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

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.