codec.md

1> **Источник:** https://python-all.ru/3.9/c-api/codec.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Реестр кодеков и вспомогательные функции89#### `int PyCodec_Register(PyObject *search_function)`1011Регистрирует новую функцию поиска кодека.1213В качестве побочного эффекта эта функция пытается загрузить пакет `encodings`, если он ещё не загружен, чтобы гарантировать, что он всегда будет первым в списке функций поиска.1415#### `int PyCodec_KnownEncoding(const char *encoding)`1617Возвращает `1` или `0` в зависимости от того, зарегистрирован ли кодек для заданной *encoding*. Эта функция всегда завершается успешно.1819#### `PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)`2021*Возвращаемое значение: новая ссылка.*2223Универсальный API кодирования на основе кодеков.2425*object* передаётся в функцию кодировщика, найденную для заданной *encoding*, с использованием метода обработки ошибок, определённого в *errors*. Значение *errors* может быть `NULL` для использования метода по умолчанию, определённого для кодека. Возбуждает [`LookupError`](https://python-all.ru/3.9/library/exceptions.html#LookupError), если кодировщик не найден.2627#### `PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)`2829*Возвращаемое значение: новая ссылка.*3031Универсальный API декодирования на основе кодеков.3233Объект *object* передаётся в функцию декодера, найденную для заданной *encoding*, с использованием метода обработки ошибок, определённого параметром *errors*. Параметр *errors* может быть `NULL`, чтобы использовать метод по умолчанию, определённый для кодека. Вызывает [`LookupError`](https://python-all.ru/3.9/library/exceptions.html#LookupError), если кодировщик не найден.3435## API для поиска кодеков3637В следующих функциях строка *encoding* при поиске приводится к нижнему регистру, что делает поиск кодировок через этот механизм нечувствительным к регистру. Если кодек не найден, устанавливается [`KeyError`](https://python-all.ru/3.9/library/exceptions.html#KeyError) и возвращается `NULL`.3839#### `PyObject* PyCodec_Encoder(const char *encoding)`4041*Возвращаемое значение: новая ссылка.*4243Возвращает функцию кодировщика для заданной *encoding*.4445#### `PyObject* PyCodec_Decoder(const char *encoding)`4647*Возвращаемое значение: новая ссылка.*4849Возвращает функцию декодера для заданной *encoding*.5051#### `PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)`5253*Возвращаемое значение: новая ссылка.*5455Получить объект [`IncrementalEncoder`](https://python-all.ru/3.9/library/codecs.html#codecs.IncrementalEncoder) для указанной *кодировки*.5657#### `PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)`5859*Возвращаемое значение: новая ссылка.*6061Получить объект [`IncrementalDecoder`](https://python-all.ru/3.9/library/codecs.html#codecs.IncrementalDecoder) для указанной *кодировки*.6263#### `PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)`6465*Возвращаемое значение: новая ссылка.*6667Получить [`StreamReader`](https://python-all.ru/3.9/library/codecs.html#codecs.StreamReader) фабричную функцию для указанной *кодировки*.6869#### `PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)`7071*Возвращаемое значение: новая ссылка.*7273Получить [`StreamWriter`](https://python-all.ru/3.9/library/codecs.html#codecs.StreamWriter) фабричную функцию для указанной *кодировки*.7475## API реестра обработчиков ошибок кодирования Unicode7677#### `int PyCodec_RegisterError(const char *name, PyObject *error)`7879Зарегистрировать колбэк-функцию обработки ошибок *error* под указанным именем *name*. Эта колбэк-функция будет вызвана кодеком, когда он встретит некодируемые символы/недекодируемые байты, и *name* указан в качестве параметра error в вызове функции encode/decode.8081Колбэк получает один аргумент – экземпляр [`UnicodeEncodeError`](https://python-all.ru/3.9/library/exceptions.html#UnicodeEncodeError), [`UnicodeDecodeError`](https://python-all.ru/3.9/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.9/library/exceptions.html#UnicodeTranslateError), который содержит информацию о проблемной последовательности символов или байтов и их смещении в исходной строке (см. [Объекты исключений Unicode](https://python-all.ru/3.9/c-api/exceptions.html#unicodeexceptions) для функций извлечения этой информации). Колбэк должен либо вызвать полученное исключение, либо вернуть кортеж из двух элементов, содержащий замену для проблемной последовательности и целое число, указывающее смещение в исходной строке, с которого следует продолжить кодирование/декодирование.8283Возвращает `0` в случае успеха, `-1` при ошибке.8485#### `PyObject* PyCodec_LookupError(const char *name)`8687*Возвращаемое значение: новая ссылка.*8889Найти колбэк-функцию обработки ошибок, зарегистрированную под именем *name*. В частном случае можно передать `NULL`, и тогда будет возвращён колбэк обработки ошибок для «strict».9091#### `PyObject* PyCodec_StrictErrors(PyObject *exc)`9293*Возвращаемое значение: всегда NULL.*9495Возбудить *exc* как исключение.9697#### `PyObject* PyCodec_IgnoreErrors(PyObject *exc)`9899*Возвращаемое значение: новая ссылка.*100101Игнорировать ошибку Unicode, пропуская некорректный ввод.102103#### `PyObject* PyCodec_ReplaceErrors(PyObject *exc)`104105*Возвращаемое значение: новая ссылка.*106107Заменить ошибку кодирования Unicode на `?` или `U+FFFD`.108109#### `PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)`110111*Возвращаемое значение: новая ссылка.*112113Заменить ошибку кодирования Unicode на символьные ссылки XML.114115#### `PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)`116117*Возвращаемое значение: новая ссылка.*118119Заменить ошибку кодирования Юникод на escape-последовательности с обратной косой чертой (`\x`, `\u` и `\U`).120121#### `PyObject* PyCodec_NameReplaceErrors(PyObject *exc)`122123*Возвращаемое значение: новая ссылка.*124125Заменить ошибку кодирования Юникод на escape-последовательности `\N{...}`.126127Новое в версии 3.5.128