From 11471db48ef8f8aa219590c5cda5098f99640e38 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 1 Jul 2025 10:10:26 +0100 Subject: [PATCH 1/5] Doc --- Doc/library/codecs.rst | 46 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index 86511602fa5a60..b2072408061f7f 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -1476,6 +1476,52 @@ 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. + + +This module implements the following exception: + +.. exception:: CodecRegistryError + + Raised when a codec is invalid or incompatible. + + :mod:`encodings.idna` --- Internationalized Domain Names in Applications ------------------------------------------------------------------------ From 76a355d15a11b3551df3832a9976f0c7e2d62e5f Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 1 Jul 2025 12:25:22 +0100 Subject: [PATCH 2/5] Commit win32_code_page_search_function doc --- Doc/library/codecs.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index b2072408061f7f..dc47d53f69cdb1 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -1515,6 +1515,18 @@ This module implements the following functions: 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 From 711443c955e4aab999832d4c5f72065a50c1d8b5 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 2 Jul 2025 15:52:55 +0100 Subject: [PATCH 3/5] Add codecs.lookup to note --- Doc/library/codecs.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index dc47d53f69cdb1..33df2e14e32fa7 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -1485,7 +1485,8 @@ mapping. It is not supported by :meth:`str.encode` (which only produces This module implements the following functions: .. note:: - These functions should not be used directly, except for testing purposes. + These functions should not be used directly, except for testing purposes; + :func:`codecs.lookup` should be used instead. .. function:: normalize_encoding(encoding) From 0f90feb716fadfa220a660d828a0a0d02096789f Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 2 Jul 2025 16:19:29 +0100 Subject: [PATCH 4/5] Drop note down --- Doc/library/codecs.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index 33df2e14e32fa7..fbfc254d9a0c3e 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -1484,10 +1484,6 @@ mapping. It is not supported by :meth:`str.encode` (which only produces This module implements the following functions: -.. note:: - These functions should not be used directly, except for testing purposes; - :func:`codecs.lookup` should be used instead. - .. function:: normalize_encoding(encoding) Normalize encoding name *encoding*. @@ -1500,6 +1496,11 @@ This module implements the following functions: Note that *encoding* should be ASCII only. +.. note:: + These 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 From 221c3ba40456748bc39995fccbf1aff200547af0 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Wed, 2 Jul 2025 16:51:58 +0100 Subject: [PATCH 5/5] Reword --- Doc/library/codecs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index fbfc254d9a0c3e..cf11cb02ff0bd5 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -1497,8 +1497,8 @@ This module implements the following functions: .. note:: - These functions should not be used directly, except for testing purposes; - :func:`codecs.lookup` should be used instead. + The following functions should not be used directly, except for testing + purposes; :func:`codecs.lookup` should be used instead. .. function:: search_function(encoding)