`encodings` module is not documented

[sobolevn]

Feature or enhancement

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

cpython/Lib/encodings/__init__.py

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

• gh-136162: Document encodings #136164
• [3.13] gh-136162: Document encodings package functions (GH-136164) #136453
• [3.14] gh-136162: Document encodings package functions (GH-136164) #136454
• [3.13] gh-136162: Clean up encodings package documentation #136456

[picnixz]

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?

[malemburg]

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).