`encodings` module is not documented · Issue #136162 · python/cpython · GitHub

Feature or enhancement

encodings contains several public and documented (at the module level) functions:

Lines 1 to 29 in 23caccf

    
           """ Standard "encodings" Package 
        
               Standard Python encoding modules are stored in this package 
        
               directory. 
        
               Codec modules must have names corresponding to normalized encoding 
        
               names as defined in the normalize_encoding() function below, e.g. 
        
               'utf-8' must be implemented by the module 'utf_8.py'. 
        
               Each codec module must export the following interface: 
        
               * getregentry() -> codecs.CodecInfo object 
        
               The getregentry() API must return a CodecInfo object with encoder, decoder, 
        
               incrementalencoder, incrementaldecoder, streamwriter and streamreader 
        
               attributes which adhere to the Python Codec Interface Standard. 
        
               In addition, a module may optionally also define the following 
        
               APIs which are then used by the package's codec search function: 
        
               * getaliases() -> sequence of encoding name strings to use as aliases 
        
               Alias names returned by getaliases() must be normalized encoding 
        
               names as defined by normalize_encoding(). 
        
           Written by Marc-Andre Lemburg (mal@lemburg.com). 
        
           (c) Copyright CNRI, All Rights Reserved. NO WARRANTY. 
        
           """#"

But, only its submodules are documented in codecs.rst:

cpython/Doc/library/codecs.rst

Lines 1487 to 1491 in 23caccf

    
           :mod:`encodings.idna` --- Internationalized Domain Names in Applications 
        
           ------------------------------------------------------------------------ 
        
           .. module:: encodings.idna 
        
              :synopsis: Internationalized Domain Names implementation

Should we add encodings itself to the docs?

Linked PRs

AFAIR, users should use codecs when possible instead of directly accessing encodings and the submodules are documented but only their name is public I think (I'm on mobile so it's hard to check).

cc @malemburg what do you recommend?

The encodings package itself provides codec search functions, which gets registered upon import and a normalization function which is used by the search functions. The search functions not only take care of mapping a codec name to codec module (within the encodings package), but also define the codec module interface which all codec modules in the encodings package have to use.

Those search functions can be used directly as well if you want to bypass the normal codecs.lookup() API for some reason.

If we document these, we should add a note that these functions should normally not be used directly, only in special cases, e.g. for testing purposes or to check whether a particular encodings codec module is available or not (the codecs.lookup() API scans all search functions, so it may well find other such modules elsewhere).

pythongh-136162: Document `encodings` package functions (python#136164)

pythongh-136162: Document `encodings` package functions (pythonGH-136164

[3.13] gh-136162: Document `encodings` package functions (GH-136164) (#…

[3.14] gh-136162: Document `encodings` package functions (GH-136164) (#…

[3.13] gh-136162: Clean up `encodings` package documentation (#136456)

pythongh-136162: Document `encodings` package functions (python#136164)

[3.14] pythongh-136162: Document `encodings` package functions (pytho…

`encodings` module is not documented · Issue #136162 · python/cpython · GitHub

Repository navigation

encodings module is not documented #136162

Feature or enhancement

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

	""" Standard "encodings" Package

	Standard Python encoding modules are stored in this package
	directory.

	Codec modules must have names corresponding to normalized encoding
	names as defined in the normalize_encoding() function below, e.g.
	'utf-8' must be implemented by the module 'utf_8.py'.

	Each codec module must export the following interface:

	* getregentry() -> codecs.CodecInfo object
	The getregentry() API must return a CodecInfo object with encoder, decoder,
	incrementalencoder, incrementaldecoder, streamwriter and streamreader
	attributes which adhere to the Python Codec Interface Standard.

	In addition, a module may optionally also define the following
	APIs which are then used by the package's codec search function:

	* getaliases() -> sequence of encoding name strings to use as aliases

	Alias names returned by getaliases() must be normalized encoding
	names as defined by normalize_encoding().

	Written by Marc-Andre Lemburg (mal@lemburg.com).

	(c) Copyright CNRI, All Rights Reserved. NO WARRANTY.

	"""#"

	:mod:`encodings.idna` --- Internationalized Domain Names in Applications
	------------------------------------------------------------------------

	.. module:: encodings.idna
	:synopsis: Internationalized Domain Names implementation

`encodings` module is not documented · Issue #136162 · python/cpython · GitHub

Repository navigation

encodings module is not documented #136162

Description

Feature or enhancement

Linked PRs

Activity

picnixz commented on Jul 1, 2025

malemburg commented on Jul 1, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions