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

Реестр кодеков и вспомогательные функции¶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.