| 1 |
.. _codec-registry: |
| 2 |
|
| 3 |
Codec registry and support functions |
| 4 |
==================================== |
| 5 |
|
| 6 |
.. c:function:: int PyCodec_Register(PyObject *search_function) |
| 7 |
|
| 8 |
Register a new codec search function. |
| 9 |
|
| 10 |
As a side effect, this tries to load the :mod:`!encodings` package, if not yet |
| 11 |
done, to make sure that it is always first in the list of search functions. |
| 12 |
|
| 13 |
.. c:function:: int PyCodec_Unregister(PyObject *search_function) |
| 14 |
|
| 15 |
Unregister a codec search function and clear the registry's cache. |
| 16 |
If the search function is not registered, do nothing. |
| 17 |
Return 0 on success. Raise an exception and return -1 on error. |
| 18 |
|
| 19 |
.. versionadded:: 3.10 |
| 20 |
|
| 21 |
.. c:function:: int PyCodec_KnownEncoding(const char *encoding) |
| 22 |
|
| 23 |
Return ``1`` or ``0`` depending on whether there is a registered codec for |
| 24 |
the given *encoding*. This function always succeeds. |
| 25 |
|
| 26 |
.. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors) |
| 27 |
|
| 28 |
Generic codec based encoding API. |
| 29 |
|
| 30 |
*object* is passed through the encoder function found for the given |
| 31 |
*encoding* using the error handling method defined by *errors*. *errors* may |
| 32 |
be ``NULL`` to use the default method defined for the codec. Raises a |
| 33 |
:exc:`LookupError` if no encoder can be found. |
| 34 |
|
| 35 |
.. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors) |
| 36 |
|
| 37 |
Generic codec based decoding API. |
| 38 |
|
| 39 |
*object* is passed through the decoder function found for the given |
| 40 |
*encoding* using the error handling method defined by *errors*. *errors* may |
| 41 |
be ``NULL`` to use the default method defined for the codec. Raises a |
| 42 |
:exc:`LookupError` if no decoder can be found. |
| 43 |
|
| 44 |
|
| 45 |
Codec lookup API |
| 46 |
---------------- |
| 47 |
|
| 48 |
In the following functions, the *encoding* string is looked up converted to all |
| 49 |
lower-case characters, which makes encodings looked up through this mechanism |
| 50 |
effectively case-insensitive. If no codec is found, a :exc:`KeyError` is set |
| 51 |
and ``NULL`` returned. |
| 52 |
|
| 53 |
.. c:function:: PyObject* PyCodec_Encoder(const char *encoding) |
| 54 |
|
| 55 |
Get an encoder function for the given *encoding*. |
| 56 |
|
| 57 |
.. c:function:: PyObject* PyCodec_Decoder(const char *encoding) |
| 58 |
|
| 59 |
Get a decoder function for the given *encoding*. |
| 60 |
|
| 61 |
.. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors) |
| 62 |
|
| 63 |
Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*. |
| 64 |
|
| 65 |
.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors) |
| 66 |
|
| 67 |
Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*. |
| 68 |
|
| 69 |
.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors) |
| 70 |
|
| 71 |
Get a :class:`~codecs.StreamReader` factory function for the given *encoding*. |
| 72 |
|
| 73 |
.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors) |
| 74 |
|
| 75 |
Get a :class:`~codecs.StreamWriter` factory function for the given *encoding*. |
| 76 |
|
| 77 |
|
| 78 |
Registry API for Unicode encoding error handlers |
| 79 |
------------------------------------------------ |
| 80 |
|
| 81 |
.. c:function:: int PyCodec_RegisterError(const char *name, PyObject *error) |
| 82 |
|
| 83 |
Register the error handling callback function *error* under the given *name*. |
| 84 |
This callback function will be called by a codec when it encounters |
| 85 |
unencodable characters/undecodable bytes and *name* is specified as the error |
| 86 |
parameter in the call to the encode/decode function. |
| 87 |
|
| 88 |
The callback gets a single argument, an instance of |
| 89 |
:exc:`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or |
| 90 |
:exc:`UnicodeTranslateError` that holds information about the problematic |
| 91 |
sequence of characters or bytes and their offset in the original string (see |
| 92 |
:ref:`unicodeexceptions` for functions to extract this information). The |
| 93 |
callback must either raise the given exception, or return a two-item tuple |
| 94 |
containing the replacement for the problematic sequence, and an integer |
| 95 |
giving the offset in the original string at which encoding/decoding should be |
| 96 |
resumed. |
| 97 |
|
| 98 |
Return ``0`` on success, ``-1`` on error. |
| 99 |
|
| 100 |
.. c:function:: PyObject* PyCodec_LookupError(const char *name) |
| 101 |
|
| 102 |
Lookup the error handling callback function registered under *name*. As a |
| 103 |
special case ``NULL`` can be passed, in which case the error handling callback |
| 104 |
for "strict" will be returned. |
| 105 |
|
| 106 |
.. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc) |
| 107 |
|
| 108 |
Raise *exc* as an exception. |
| 109 |
|
| 110 |
.. c:function:: PyObject* PyCodec_IgnoreErrors(PyObject *exc) |
| 111 |
|
| 112 |
Ignore the unicode error, skipping the faulty input. |
| 113 |
|
| 114 |
.. c:function:: PyObject* PyCodec_ReplaceErrors(PyObject *exc) |
| 115 |
|
| 116 |
Replace the unicode encode error with ``?`` or ``U+FFFD``. |
| 117 |
|
| 118 |
.. c:function:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc) |
| 119 |
|
| 120 |
Replace the unicode encode error with XML character references. |
| 121 |
|
| 122 |
.. c:function:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc) |
| 123 |
|
| 124 |
Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and |
| 125 |
``\U``). |
| 126 |
|
| 127 |
.. c:function:: PyObject* PyCodec_NameReplaceErrors(PyObject *exc) |
| 128 |
|
| 129 |
Replace the unicode encode error with ``\N{...}`` escapes. |
| 130 |
|
| 131 |
.. versionadded:: 3.5 |
| 132 |
|
| 133 |
|
| 134 |
Codec utility variables |
| 135 |
----------------------- |
| 136 |
|
| 137 |
.. c:var:: const char *Py_hexdigits |
| 138 |
|
| 139 |
A string constant containing the lowercase hexadecimal digits: ``"0123456789abcdef"``. |
| 140 |
|
| 141 |
.. versionadded:: 3.3 |