Содержание страницы

Реестр кодеков и вспомогательные функции¶Codec registry and support functions

int PyCodec_Register(PyObject *search_function)¶

Часть Stable ABI.

Регистрирует новую функцию поиска кодека.

Попутно эта функция пытается загрузить пакет encodings, если он ещё не загружен, чтобы он всегда был первым в списке функций поиска.

int PyCodec_Unregister(PyObject *search_function)¶: Часть Stable ABI начиная с версии 3.10.
Отменяет регистрацию функции поиска кодека и очищает кеш реестра. Если функция не зарегистрирована, ничего не делает. Возвращает 0 при успехе. При ошибке возбуждает исключение и возвращает -1.

Добавлено в версии 3.10.

int PyCodec_KnownEncoding(const char *encoding)¶: Часть Stable ABI.
Возвращает 1 или 0 в зависимости от того, зарегистрирован ли кодек для заданной encoding. Эта функция всегда завершается успешно.

PyObject *PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI.

Универсальный API кодирования на основе кодеков.

object передаётся в функцию кодировщика, найденную для заданной encoding, с использованием метода обработки ошибок, определённого в errors. Значение errors может быть NULL для использования метода по умолчанию, определённого для кодека. Возбуждает LookupError, если кодировщик не найден.

PyObject *PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI.

Универсальный API декодирования на основе кодеков.

object передаётся в функцию декодера, найденную для заданной encoding, с использованием метода обработки ошибок, определённого в errors. Значение errors может быть NULL для использования метода по умолчанию, определённого для кодека. Возбуждает LookupError, если декодер не найден.

API для поиска кодеков¶Codec lookup API

В следующих функциях строка encoding при поиске приводится к нижнему регистру, что делает поиск кодировок через этот механизм нечувствительным к регистру. Если кодек не найден, устанавливается KeyError и возвращается NULL.

PyObject *PyCodec_Encoder(const char *encoding)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает функцию кодировщика для заданной encoding.

PyObject *PyCodec_Decoder(const char *encoding)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает функцию декодера для заданной encoding.

PyObject *PyCodec_IncrementalEncoder(const char *encoding, const char *errors)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Получить объект IncrementalEncoder для указанной кодировки.

PyObject *PyCodec_IncrementalDecoder(const char *encoding, const char *errors)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Получить объект IncrementalDecoder для указанной кодировки.

PyObject *PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Получить StreamReader фабричную функцию для указанной кодировки.

PyObject *PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Получить StreamWriter фабричную функцию для указанной кодировки.

API реестра обработчиков ошибок кодирования Unicode¶Registry API for Unicode encoding error handlers

int PyCodec_RegisterError(const char *name, PyObject *error)¶

Часть Stable ABI.

Зарегистрировать колбэк-функцию обработки ошибок error под указанным именем name. Эта колбэк-функция будет вызвана кодеком, когда он встретит некодируемые символы/недекодируемые байты, и name указан в качестве параметра error в вызове функции encode/decode.

Колбэк получает один аргумент – экземпляр UnicodeEncodeError, UnicodeDecodeError или UnicodeTranslateError, который содержит информацию о проблемной последовательности символов или байтов и их смещении в исходной строке (см. Объекты исключений Unicode для функций извлечения этой информации). Колбэк должен либо вызвать полученное исключение, либо вернуть кортеж из двух элементов, содержащий замену для проблемной последовательности и целое число, указывающее смещение в исходной строке, с которого следует продолжить кодирование/декодирование.

Возвращает 0 в случае успеха, -1 при ошибке.

PyObject *PyCodec_LookupError(const char *name)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Найти колбэк-функцию обработки ошибок, зарегистрированную под именем name. В частном случае можно передать NULL, и тогда будет возвращён колбэк обработки ошибок для «strict».

PyObject *PyCodec_StrictErrors(PyObject *exc)¶: Возвращаемое значение: всегда NULL. Часть Stable ABI.
Возбудить exc как исключение.

PyObject *PyCodec_IgnoreErrors(PyObject *exc)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Игнорировать ошибку Unicode, пропуская некорректный ввод.

PyObject *PyCodec_ReplaceErrors(PyObject *exc)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Заменить ошибку кодирования Unicode на ? или U+FFFD.

PyObject *PyCodec_XMLCharRefReplaceErrors(PyObject *exc)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Заменить ошибку кодирования Unicode на символьные ссылки XML.

PyObject *PyCodec_BackslashReplaceErrors(PyObject *exc)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Заменить ошибку кодирования Юникод на escape-последовательности с обратной косой чертой (\x, \u и \U).

PyObject *PyCodec_NameReplaceErrors(PyObject *exc)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI начиная с версии 3.7.
Заменить ошибку кодирования Юникод на escape-последовательности \N{...}.

Добавлено в версии 3.5.

Вспомогательные переменные кодека¶Codec utility variables

const char *Py_hexdigits¶: Строковая константа, содержащая строчные шестнадцатеричные цифры: "0123456789abcdef".

Добавлено в версии 3.3.