mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-25 21:11:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

gh-136162: Document encodings package functions (#136164)

Browse source 
Closes #136162.
This commit is contained in:
Stan Ulbrych 2025-07-08 23:34:48 +02:00 • committed by GitHub
parent b6b99bf7f1
commit ffd7f2f231
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 61 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

60
Doc/library/codecs.rst
View file

@ -1484,6 +1484,66 @@ 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:
.. 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.
.. note::
The following functions should not be used directly, except for testing
purposes; :func:`codecs.lookup` should be used instead.
.. 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
------------------------------------------------------------------------

2
Doc/whatsnew/3.9.rst
View file

@ -1139,7 +1139,7 @@ Changes in the Python API
(Contributed by Christian Heimes in :issue:`36384`).
* :func:`codecs.lookup` now normalizes the encoding name the same way as
:func:`!encodings.normalize_encoding`, except that :func:`codecs.lookup` also
:func:`encodings.normalize_encoding`, except that :func:`codecs.lookup` also
converts the name to lower case. For example, ``"latex+latin1"`` encoding
name is now normalized to ``"latex_latin1"``.
(Contributed by Jordon Xu in :issue:`37751`.)