Реестр кодеков и вспомогательные функции

int PyCodec_Register(PyObject *search_function)

Часть стабильного ABI.

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

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

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

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

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

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

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

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

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

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

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

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

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

API поиска кодеков

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

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

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

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

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

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

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

API реестра обработчиков ошибок кодирования Unicode

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

Часть стабильного ABI.

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

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

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

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

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

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

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

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

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

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

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

Вспомогательные переменные кодеков

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

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