17db96d56Sopenharmony_ci.. _codec-registry: 27db96d56Sopenharmony_ci 37db96d56Sopenharmony_ciCodec registry and support functions 47db96d56Sopenharmony_ci==================================== 57db96d56Sopenharmony_ci 67db96d56Sopenharmony_ci.. c:function:: int PyCodec_Register(PyObject *search_function) 77db96d56Sopenharmony_ci 87db96d56Sopenharmony_ci Register a new codec search function. 97db96d56Sopenharmony_ci 107db96d56Sopenharmony_ci As side effect, this tries to load the :mod:`encodings` package, if not yet 117db96d56Sopenharmony_ci done, to make sure that it is always first in the list of search functions. 127db96d56Sopenharmony_ci 137db96d56Sopenharmony_ci.. c:function:: int PyCodec_Unregister(PyObject *search_function) 147db96d56Sopenharmony_ci 157db96d56Sopenharmony_ci Unregister a codec search function and clear the registry's cache. 167db96d56Sopenharmony_ci If the search function is not registered, do nothing. 177db96d56Sopenharmony_ci Return 0 on success. Raise an exception and return -1 on error. 187db96d56Sopenharmony_ci 197db96d56Sopenharmony_ci .. versionadded:: 3.10 207db96d56Sopenharmony_ci 217db96d56Sopenharmony_ci.. c:function:: int PyCodec_KnownEncoding(const char *encoding) 227db96d56Sopenharmony_ci 237db96d56Sopenharmony_ci Return ``1`` or ``0`` depending on whether there is a registered codec for 247db96d56Sopenharmony_ci the given *encoding*. This function always succeeds. 257db96d56Sopenharmony_ci 267db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors) 277db96d56Sopenharmony_ci 287db96d56Sopenharmony_ci Generic codec based encoding API. 297db96d56Sopenharmony_ci 307db96d56Sopenharmony_ci *object* is passed through the encoder function found for the given 317db96d56Sopenharmony_ci *encoding* using the error handling method defined by *errors*. *errors* may 327db96d56Sopenharmony_ci be ``NULL`` to use the default method defined for the codec. Raises a 337db96d56Sopenharmony_ci :exc:`LookupError` if no encoder can be found. 347db96d56Sopenharmony_ci 357db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors) 367db96d56Sopenharmony_ci 377db96d56Sopenharmony_ci Generic codec based decoding API. 387db96d56Sopenharmony_ci 397db96d56Sopenharmony_ci *object* is passed through the decoder function found for the given 407db96d56Sopenharmony_ci *encoding* using the error handling method defined by *errors*. *errors* may 417db96d56Sopenharmony_ci be ``NULL`` to use the default method defined for the codec. Raises a 427db96d56Sopenharmony_ci :exc:`LookupError` if no encoder can be found. 437db96d56Sopenharmony_ci 447db96d56Sopenharmony_ci 457db96d56Sopenharmony_ciCodec lookup API 467db96d56Sopenharmony_ci---------------- 477db96d56Sopenharmony_ci 487db96d56Sopenharmony_ciIn the following functions, the *encoding* string is looked up converted to all 497db96d56Sopenharmony_cilower-case characters, which makes encodings looked up through this mechanism 507db96d56Sopenharmony_cieffectively case-insensitive. If no codec is found, a :exc:`KeyError` is set 517db96d56Sopenharmony_ciand ``NULL`` returned. 527db96d56Sopenharmony_ci 537db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_Encoder(const char *encoding) 547db96d56Sopenharmony_ci 557db96d56Sopenharmony_ci Get an encoder function for the given *encoding*. 567db96d56Sopenharmony_ci 577db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_Decoder(const char *encoding) 587db96d56Sopenharmony_ci 597db96d56Sopenharmony_ci Get a decoder function for the given *encoding*. 607db96d56Sopenharmony_ci 617db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors) 627db96d56Sopenharmony_ci 637db96d56Sopenharmony_ci Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*. 647db96d56Sopenharmony_ci 657db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors) 667db96d56Sopenharmony_ci 677db96d56Sopenharmony_ci Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*. 687db96d56Sopenharmony_ci 697db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors) 707db96d56Sopenharmony_ci 717db96d56Sopenharmony_ci Get a :class:`~codecs.StreamReader` factory function for the given *encoding*. 727db96d56Sopenharmony_ci 737db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors) 747db96d56Sopenharmony_ci 757db96d56Sopenharmony_ci Get a :class:`~codecs.StreamWriter` factory function for the given *encoding*. 767db96d56Sopenharmony_ci 777db96d56Sopenharmony_ci 787db96d56Sopenharmony_ciRegistry API for Unicode encoding error handlers 797db96d56Sopenharmony_ci------------------------------------------------ 807db96d56Sopenharmony_ci 817db96d56Sopenharmony_ci.. c:function:: int PyCodec_RegisterError(const char *name, PyObject *error) 827db96d56Sopenharmony_ci 837db96d56Sopenharmony_ci Register the error handling callback function *error* under the given *name*. 847db96d56Sopenharmony_ci This callback function will be called by a codec when it encounters 857db96d56Sopenharmony_ci unencodable characters/undecodable bytes and *name* is specified as the error 867db96d56Sopenharmony_ci parameter in the call to the encode/decode function. 877db96d56Sopenharmony_ci 887db96d56Sopenharmony_ci The callback gets a single argument, an instance of 897db96d56Sopenharmony_ci :exc:`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or 907db96d56Sopenharmony_ci :exc:`UnicodeTranslateError` that holds information about the problematic 917db96d56Sopenharmony_ci sequence of characters or bytes and their offset in the original string (see 927db96d56Sopenharmony_ci :ref:`unicodeexceptions` for functions to extract this information). The 937db96d56Sopenharmony_ci callback must either raise the given exception, or return a two-item tuple 947db96d56Sopenharmony_ci containing the replacement for the problematic sequence, and an integer 957db96d56Sopenharmony_ci giving the offset in the original string at which encoding/decoding should be 967db96d56Sopenharmony_ci resumed. 977db96d56Sopenharmony_ci 987db96d56Sopenharmony_ci Return ``0`` on success, ``-1`` on error. 997db96d56Sopenharmony_ci 1007db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_LookupError(const char *name) 1017db96d56Sopenharmony_ci 1027db96d56Sopenharmony_ci Lookup the error handling callback function registered under *name*. As a 1037db96d56Sopenharmony_ci special case ``NULL`` can be passed, in which case the error handling callback 1047db96d56Sopenharmony_ci for "strict" will be returned. 1057db96d56Sopenharmony_ci 1067db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc) 1077db96d56Sopenharmony_ci 1087db96d56Sopenharmony_ci Raise *exc* as an exception. 1097db96d56Sopenharmony_ci 1107db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_IgnoreErrors(PyObject *exc) 1117db96d56Sopenharmony_ci 1127db96d56Sopenharmony_ci Ignore the unicode error, skipping the faulty input. 1137db96d56Sopenharmony_ci 1147db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_ReplaceErrors(PyObject *exc) 1157db96d56Sopenharmony_ci 1167db96d56Sopenharmony_ci Replace the unicode encode error with ``?`` or ``U+FFFD``. 1177db96d56Sopenharmony_ci 1187db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc) 1197db96d56Sopenharmony_ci 1207db96d56Sopenharmony_ci Replace the unicode encode error with XML character references. 1217db96d56Sopenharmony_ci 1227db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc) 1237db96d56Sopenharmony_ci 1247db96d56Sopenharmony_ci Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and 1257db96d56Sopenharmony_ci ``\U``). 1267db96d56Sopenharmony_ci 1277db96d56Sopenharmony_ci.. c:function:: PyObject* PyCodec_NameReplaceErrors(PyObject *exc) 1287db96d56Sopenharmony_ci 1297db96d56Sopenharmony_ci Replace the unicode encode error with ``\N{...}`` escapes. 1307db96d56Sopenharmony_ci 1317db96d56Sopenharmony_ci .. versionadded:: 3.5 132