From b9bc179abdd3dca33070bf0cf04a9d766891d2f9 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Fri, 21 Aug 2026 05:50:52 +0000 Subject: [PATCH] gh-156098: Document the str form of PyUnicode_DecodeCharmap()'s mapping argument --- Doc/c-api/unicode.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 9bf801ad608c773..66c19c074432d10 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1410,19 +1410,30 @@ This codec is special in that it can be used to implement many different codecs included in the :mod:`!encodings` package). The codec uses mappings to encode and decode characters. The mapping objects provided must support the :meth:`~object.__getitem__` mapping interface; dictionaries and sequences work well. +For decoding, a :class:`str` can also be used directly as a lookup table; see +:c:func:`PyUnicode_DecodeCharmap`. These are the mapping codec APIs: .. c:function:: PyObject* PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, \ PyObject *mapping, const char *errors) - Create a Unicode object by decoding *size* bytes of the encoded string *str* - using the given *mapping* object. Return ``NULL`` if an exception was raised - by the codec. + Create a Unicode object by decoding *length* bytes of the encoded string + *str* using the given *mapping* object. Return ``NULL`` if an exception was + raised by the codec. + + If *mapping* is ``NULL``, Latin-1 decoding will be applied. + + If *mapping* is an exact :class:`str` object (not an instance of a + subclass), it is used as a decoding table: the byte with ordinal *b* is + decoded to the character ``mapping[b]``. Bytes whose ordinal is greater + than or equal to ``len(mapping)``, as well as bytes which map to + ``'\ufffe'``, are treated as undefined mappings and cause an error. This + is the form used by the ``decoding_table`` of the modules in the + :mod:`!encodings` package. - If *mapping* is ``NULL``, Latin-1 decoding will be applied. Else - *mapping* must map bytes ordinals (integers in the range from 0 to 255) - to Unicode strings, integers (which are then interpreted as Unicode + Otherwise, *mapping* must map bytes ordinals (integers in the range from 0 + to 255) to Unicode strings, integers (which are then interpreted as Unicode ordinals) or ``None``. Unmapped data bytes -- ones which cause a :exc:`LookupError`, as well as ones which get mapped to ``None``, ``0xFFFE`` or ``'\ufffe'``, are treated as undefined mappings and cause