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

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

1393

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

1394

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

1395

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

1396

decode characters.

1397

-

1398

Decoding mappings must map single string characters to single Unicode

1399


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

1400

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

1401

-

1402

Encoding mappings must map single Unicode characters to single string

1403


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

1404

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

1405

-

1406

The mapping objects provided must only support the getitem mapping

1407

interface.

1408

-

1409

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

1410

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

1411

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

1412

characters to different code points.

1396

decode characters. The mapping objects provided must support the

1397

`` +

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

1413

1398

1414

1399

`These are the mapping codec APIs:

1415

1400

1416

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

1401

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

1417

1402

` PyObject *mapping, const char *errors)

1418

1403

1419

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

1420

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

1421

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

1422

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

1423

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

1424

treated as "undefined mapping".

1404

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

1405

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

1406

by the codec.

1407

+

1408

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

1409

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

1410

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

1411


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

1412


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

1413


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

1414

an error.

1425

1415

1426

1416

1427

1417

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

1428

1418

1429

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

1430

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

1419

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

1420

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

1431

1421

` exception was raised by the codec.

1432

1422

1433

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

1434

-

1423

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

1424


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

1425

`` +

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

1426


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

1435

1427

1436

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

1437

PyObject *table, const char *errors)

1438

-

1439

`` -

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

1440

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

1441

NULL when an exception was raised by the codec.

1442

1428

1443

The mapping table must map Unicode ordinal integers to Unicode ordinal

1444


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

1429

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

1430

PyObject *mapping, const char *errors)

1445

1431

1446

`` -

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

1447

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

1448

`` -

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

1432

`` +

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

1433

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

1434

an exception was raised by the codec.

1449

1435

1450

1436

` .. deprecated-removed:: 3.3 4.0

1451

1437

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

1452

`` -

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

1453

`` -

1438

`` +

:c:func:PyUnicode_AsCharmapString or

1439

`` +

:c:func:PyUnicode_AsEncodedString.

1454

1440

1455

1441

1456

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

1442

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

1443

+

1444

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

1457

1445

` PyObject *mapping, const char *errors)

1458

1446

1459

`` -

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

1460

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

1461

exception was raised by the codec.

1447

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

1448

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

1449

codec.

1450

+

1451

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

1452


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

1453

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

1454

`` +

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

1455

+

1456

+

1457

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

1458

PyObject *mapping, const char *errors)

1459

+

1460

`` +

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

1461

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

1462

Return NULL when an exception was raised by the codec.

1462

1463

1464

` .. deprecated-removed:: 3.3 4.0

1464

1465

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

1465

`` -

:c:func:PyUnicode_AsCharmapString or

1466

`` -

:c:func:PyUnicode_AsEncodedString.

1466

`` +

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

1467

`` +

1467

1468

1469

1470

`MBCS codecs for Windows