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

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

1388

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

1389

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

1390

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

1391

decode characters.

1392

-

1393

Decoding mappings must map single string characters to single Unicode

1394


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

1395

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

1396

-

1397

Encoding mappings must map single Unicode characters to single string

1398


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

1399

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

1400

-

1401

The mapping objects provided must only support the getitem mapping

1402

interface.

1403

-

1404

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

1405

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

1406

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

1407

characters to different code points.

1391

decode characters. The mapping objects provided must support the

1392

`` +

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

1408

1393

1409

1394

`These are the mapping codec APIs:

1410

1395

1411

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

1396

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

1412

1397

` PyObject *mapping, const char *errors)

1413

1398

1414

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

1415

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

1416

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

1417

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

1418

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

1419

treated as "undefined mapping".

1399

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

1400

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

1401

by the codec.

1402

+

1403

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

1404

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

1405

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

1406


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

1407


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

1408


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

1409

an error.

1420

1410

1421

1411

1422

1412

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

1423

1413

1424

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

1425

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

1414

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

1415

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

1426

1416

` exception was raised by the codec.

1427

1417

1428

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

1429

-

1418

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

1419


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

1420

`` +

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

1421


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

1430

1422

1431

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

1432

PyObject *table, const char *errors)

1433

-

1434

`` -

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

1435

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

1436

NULL when an exception was raised by the codec.

1437

1423

1438

The mapping table must map Unicode ordinal integers to Unicode ordinal

1439


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

1424

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

1425

PyObject *mapping, const char *errors)

1440

1426

1441

`` -

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

1442

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

1443

`` -

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

1427

`` +

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

1428

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

1429

an exception was raised by the codec.

1444

1430

1445

1431

` .. deprecated-removed:: 3.3 4.0

1446

1432

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

1447

`` -

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

1448

`` -

1433

`` +

:c:func:PyUnicode_AsCharmapString or

1434

`` +

:c:func:PyUnicode_AsEncodedString.

1449

1435

1450

1436

1451

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

1437

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

1438

+

1439

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

1452

1440

` PyObject *mapping, const char *errors)

1453

1441

1454

`` -

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

1455

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

1456

exception was raised by the codec.

1442

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

1443

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

1444

codec.

1445

+

1446

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

1447


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

1448

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

1449

`` +

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

1450

+

1451

+

1452

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

1453

PyObject *mapping, const char *errors)

1454

+

1455

`` +

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

1456

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

1457

Return NULL when an exception was raised by the codec.

1457

1458

1459

` .. deprecated-removed:: 3.3 4.0

1459

1460

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

1460

`` -

:c:func:PyUnicode_AsCharmapString or

1461

`` -

:c:func:PyUnicode_AsEncodedString.

1461

`` +

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

1462

`` +

1462

1463

1464

1465

`MBCS codecs for Windows