bpo-28749: Fixed the documentation of the mapping codec APIs. (#487) · python/cpython@c85a266 (original) (raw)

`@@ -1399,77 +1399,78 @@ Character Map Codecs

1399

`This codec is special in that it can be used to implement many different codecs

1400

`(and this is in fact what was done to obtain most of the standard codecs

1401

`` included in the :mod:encodings package). The codec uses mapping to encode and

1402

decode characters.

1403

-

1404

Decoding mappings must map single string characters to single Unicode

1405


characters, integers (which are then interpreted as Unicode ordinals) or ``None``

1406

(meaning "undefined mapping" and causing an error).

1407

-

1408

Encoding mappings must map single Unicode characters to single string

1409


characters, integers (which are then interpreted as Latin-1 ordinals) or ``None``

1410

(meaning "undefined mapping" and causing an error).

1411

-

1412

The mapping objects provided must only support the getitem mapping

1413

interface.

1414

-

1415

If a character lookup fails with a LookupError, the character is copied as-is

1416

meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal

1417

resp. Because of this, mappings only need to contain those mappings which map

1418

characters to different code points.

1402

decode characters. The mapping objects provided must support the

1403

`` +

:meth:__getitem__ mapping interface; dictionaries and sequences work well.

1419

1404

1420

1405

`These are the mapping codec APIs:

1421

1406

1422

.. c:function:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, \

1407

.. c:function:: PyObject* PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, \

1423

1408

` PyObject *mapping, const char *errors)

1424

1409

1425

Create a Unicode object by decoding size bytes of the encoded string s using

1426

the given mapping object. Return NULL if an exception was raised by the

1427

codec. If mapping is NULL latin-1 decoding will be done. Else it can be a

1428

dictionary mapping byte or a unicode string, which is treated as a lookup table.

1429

Byte values greater that the length of the string and U+FFFE "characters" are

1430

treated as "undefined mapping".

1410

Create a Unicode object by decoding size bytes of the encoded string s

1411

using the given mapping object. Return NULL if an exception was raised

1412

by the codec.

1413

+

1414

If mapping is NULL, Latin-1 decoding will be applied. Else

1415

mapping must map bytes ordinals (integers in the range from 0 to 255)

1416

to Unicode strings, integers (which are then interpreted as Unicode

1417


 ordinals) or ``None``. Unmapped data bytes -- ones which cause a

1418


 :exc:`LookupError`, as well as ones which get mapped to ``None``,

1419


 ``0xFFFE`` or ``'\ufffe'``, are treated as undefined mappings and cause

1420

an error.

1431

1421

1432

1422

1433

1423

`.. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)

1434

1424

1435

Encode a Unicode object using the given mapping object and return the result

1436

as Python string object. Error handling is "strict". Return NULL if an

1425

Encode a Unicode object using the given mapping object and return the

1426

result as a bytes object. Error handling is "strict". Return NULL if an

1437

1427

` exception was raised by the codec.

1438

1428

1439

The following codec API is special in that maps Unicode to Unicode.

1440

-

1429

The mapping object must map Unicode ordinal integers to bytes objects,

1430


 integers in the range from 0 to 255 or ``None``. Unmapped character

1431

`` +

ordinals (ones which cause a :exc:LookupError) as well as mapped to

1432


 ``None`` are treated as "undefined mapping" and cause an error.

1441

1433

1442

.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, \

1443

PyObject *table, const char *errors)

1444

-

1445

`` -

Translate a :c:type:Py_UNICODE buffer of the given size by applying a

1446

character mapping table to it and return the resulting Unicode object. Return

1447

NULL when an exception was raised by the codec.

1448

1434

1449

The mapping table must map Unicode ordinal integers to Unicode ordinal

1450


integers or ``None`` (causing deletion of the character).

1435

.. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, \

1436

PyObject *mapping, const char *errors)

1451

1437

1452

`` -

Mapping tables need only provide the :meth:__getitem__ interface; dictionaries

1453

and sequences work well. Unmapped character ordinals (ones which cause a

1454

`` -

:exc:LookupError) are left untouched and are copied as-is.

1438

`` +

Encode the :c:type:Py_UNICODE buffer of the given size using the given

1439

mapping object and return the result as a bytes object. Return NULL if

1440

an exception was raised by the codec.

1455

1441

1456

1442

` .. deprecated-removed:: 3.3 4.0

1457

1443

`` Part of the old-style :c:type:Py_UNICODE API; please migrate to using

1458

`` -

:c:func:PyUnicode_Translate. or :ref:`generic codec based API

1459

`` -

1444

`` +

:c:func:PyUnicode_AsCharmapString or

1445

`` +

:c:func:PyUnicode_AsEncodedString.

1460

1446

1461

1447

1462

.. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, \

1448

The following codec API is special in that maps Unicode to Unicode.

1449

+

1450

.. c:function:: PyObject* PyUnicode_Translate(PyObject *unicode, \

1463

1451

` PyObject *mapping, const char *errors)

1464

1452

1465

`` -

Encode the :c:type:Py_UNICODE buffer of the given size using the given

1466

mapping object and return a Python string object. Return NULL if an

1467

exception was raised by the codec.

1453

Translate a Unicode object using the given mapping object and return the

1454

resulting Unicode object. Return NULL if an exception was raised by the

1455

codec.

1456

+

1457

The mapping object must map Unicode ordinal integers to Unicode strings,

1458


 integers (which are then interpreted as Unicode ordinals) or ``None``

1459

(causing deletion of the character). Unmapped character ordinals (ones

1460

`` +

which cause a :exc:LookupError) are left untouched and are copied as-is.

1461

+

1462

+

1463

.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, \

1464

PyObject *mapping, const char *errors)

1465

+

1466

`` +

Translate a :c:type:Py_UNICODE buffer of the given size by applying a

1467

character mapping table to it and return the resulting Unicode object.

1468

Return NULL when an exception was raised by the codec.

1468

1469

1470

` .. deprecated-removed:: 3.3 4.0

1470

1471

`` Part of the old-style :c:type:Py_UNICODE API; please migrate to using

1471

`` -

:c:func:PyUnicode_AsCharmapString or

1472

`` -

:c:func:PyUnicode_AsEncodedString.

1472

`` +

:c:func:PyUnicode_Translate. or :ref:`generic codec based API

1473

`` +

1473

1474

1475

1476

`MBCS codecs for Windows