bpo-28749: Fixed the documentation of the mapping codec APIs. (#487) (#714)
Added the documentation for PyUnicode_Translate().
(cherry picked from commit c85a26628ceb9624c96c3064e8b99033c026d8a3)
diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h
index 587cf03..2d0d77e 100644
--- a/Include/unicodeobject.h
+++ b/Include/unicodeobject.h
@@ -1609,50 +1609,41 @@
This codec uses mappings to encode and decode characters.
- Decoding mappings must map single string characters to single
- Unicode characters, integers (which are then interpreted as Unicode
- ordinals) or None (meaning "undefined mapping" and causing an
- error).
+ Decoding mappings must map byte 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 LookupError)
+ as well as mapped to None, 0xFFFE or '\ufffe' are treated as "undefined
+ mapping" and cause an error.
- Encoding mappings must map single Unicode characters to single
- string characters, integers (which are then interpreted as Latin-1
- ordinals) or None (meaning "undefined mapping" and causing an
- error).
-
- If a character lookup fails with a LookupError, the character is
- copied as-is meaning that its ordinal value will be interpreted as
- Unicode or Latin-1 ordinal resp. Because of this mappings only need
- to contain those mappings which map characters to different code
- points.
+ Encoding mappings must map Unicode ordinal integers to bytes objects,
+ integers in the range from 0 to 255 or None. Unmapped character
+ ordinals (ones which cause a LookupError) as well as mapped to
+ None are treated as "undefined mapping" and cause an error.
*/
PyAPI_FUNC(PyObject*) PyUnicode_DecodeCharmap(
const char *string, /* Encoded string */
Py_ssize_t length, /* size of string */
- PyObject *mapping, /* character mapping
- (char ordinal -> unicode ordinal) */
+ PyObject *mapping, /* decoding mapping */
const char *errors /* error handling */
);
PyAPI_FUNC(PyObject*) PyUnicode_AsCharmapString(
PyObject *unicode, /* Unicode object */
- PyObject *mapping /* character mapping
- (unicode ordinal -> char ordinal) */
+ PyObject *mapping /* encoding mapping */
);
#ifndef Py_LIMITED_API
PyAPI_FUNC(PyObject*) PyUnicode_EncodeCharmap(
const Py_UNICODE *data, /* Unicode char buffer */
Py_ssize_t length, /* Number of Py_UNICODE chars to encode */
- PyObject *mapping, /* character mapping
- (unicode ordinal -> char ordinal) */
+ PyObject *mapping, /* encoding mapping */
const char *errors /* error handling */
);
PyAPI_FUNC(PyObject*) _PyUnicode_EncodeCharmap(
PyObject *unicode, /* Unicode object */
- PyObject *mapping, /* character mapping
- (unicode ordinal -> char ordinal) */
+ PyObject *mapping, /* encoding mapping */
const char *errors /* error handling */
);
#endif
@@ -1661,8 +1652,8 @@
character mapping table to it and return the resulting Unicode
object.
- The mapping table must map Unicode ordinal integers to Unicode
- ordinal integers or None (causing deletion of the character).
+ The mapping table must map Unicode ordinal integers to Unicode strings,
+ Unicode ordinal integers or None (causing deletion of the character).
Mapping tables may be dictionaries or sequences. Unmapped character
ordinals (ones which cause a LookupError) are left untouched and
@@ -1960,8 +1951,8 @@
/* Translate a string by applying a character mapping table to it and
return the resulting Unicode object.
- The mapping table must map Unicode ordinal integers to Unicode
- ordinal integers or None (causing deletion of the character).
+ The mapping table must map Unicode ordinal integers to Unicode strings,
+ Unicode ordinal integers or None (causing deletion of the character).
Mapping tables may be dictionaries or sequences. Unmapped character
ordinals (ones which cause a LookupError) are left untouched and