Skip to content

gh-136162: Document encodings #136164

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+58 −0
Open

gh-136162: Document encodings #136164

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
11471db
Doc
StanFromIreland Jul 1, 2025
76a355d
Commit win32_code_page_search_function doc
StanFromIreland Jul 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions Doc/library/codecs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1476,6 +1476,64 @@ mapping. It is not supported by :meth:`str.encode` (which only produces
Restoration of the ``rot13`` alias.


:mod:`encodings` --- Encodings package
--------------------------------------

.. module:: encodings
:synopsis: Encodings package

This module implements the following functions:

.. note::
These functions should not be used directly, except for testing purposes.

.. function:: normalize_encoding(encoding)

Normalize encoding name *encoding*.

Normalization works as follows: all non-alphanumeric characters except the
dot used for Python package names are collapsed and replaced with a single
underscore, leading and trailing underscores are removed.
For example, ``' -;#'`` becomes ``'_'``.

Note that *encoding* should be ASCII only.


.. function:: search_function(encoding)

Search for the codec module corresponding to the given encoding name
*encoding*.

This function first normalizes the *encoding* using
:func:`normalize_encoding`, then looks for a corresponding alias.
It attempts to import a codec module from the encodings package using either
the alias or the normalized name. If the module is found and defines a valid
``getregentry()`` function that returns a :class:`codecs.CodecInfo` object,
the codec is cached and returned.

If the codec module defines a ``getaliases()`` function any returned aliases
are registered for future use.


.. function:: win32_code_page_search_function(encoding)

Search for a Windows code page encoding *encoding* of the form ``cpXXXX``.

If the code page is valid and supported, return a :class:`codecs.CodecInfo`
object for it.

.. availability:: Windows.

.. versionadded:: 3.14


This module implements the following exception:

.. exception:: CodecRegistryError

Raised when a codec is invalid or incompatible.


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

Expand Down
Loading