`codec.md`

172 строк · 11.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.10/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*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*1213Регистрирует новую функцию поиска кодека.1415В качестве побочного эффекта эта функция пытается загрузить пакет `encodings`, если он ещё не загружен, чтобы гарантировать, что он всегда будет первым в списке функций поиска.1617#### `int PyCodec_Unregister(PyObject *search_function)`1819*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.10.*2021Отменяет регистрацию функции поиска кодека и очищает кеш реестра. Если функция не зарегистрирована, ничего не делает. Возвращает 0 при успехе. При ошибке возбуждает исключение и возвращает -1.2223Новое в версии 3.10.2425#### `int PyCodec_KnownEncoding(const char *encoding)`2627*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*2829Возвращает `1` или `0` в зависимости от того, зарегистрирован ли кодек для заданной *encoding*. Эта функция всегда завершается успешно.3031#### `PyObject *PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)`3233*Возвращаемое значение: новая ссылка.*3435*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*3637Универсальный API кодирования на основе кодеков.3839*object* передаётся в функцию кодировщика, найденную для заданной *encoding*, с использованием метода обработки ошибок, определённого в *errors*. Значение *errors* может быть `NULL` для использования метода по умолчанию, определённого для кодека. Возбуждает [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), если кодировщик не найден.4041#### `PyObject *PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)`4243*Возвращаемое значение: новая ссылка.*4445*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*4647Универсальный API декодирования на основе кодеков.4849Объект *object* передаётся в функцию декодера, найденную для заданной *encoding*, с использованием метода обработки ошибок, определённого параметром *errors*. Параметр *errors* может быть `NULL`, чтобы использовать метод по умолчанию, определённый для кодека. Вызывает [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), если кодировщик не найден.5051## API для поиска кодеков5253В следующих функциях строка *encoding* при поиске приводится к нижнему регистру, что делает поиск кодировок через этот механизм нечувствительным к регистру. Если кодек не найден, устанавливается [`KeyError`](https://python-all.ru/3.10/library/exceptions.html#KeyError) и возвращается `NULL`.5455#### `PyObject *PyCodec_Encoder(const char *encoding)`5657*Возвращаемое значение: новая ссылка.*5859*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*6061Возвращает функцию кодировщика для заданной *encoding*.6263#### `PyObject *PyCodec_Decoder(const char *encoding)`6465*Возвращаемое значение: новая ссылка.*6667*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*6869Возвращает функцию декодера для заданной *encoding*.7071#### `PyObject *PyCodec_IncrementalEncoder(const char *encoding, const char *errors)`7273*Возвращаемое значение: новая ссылка.*7475*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*7677Получить объект [`IncrementalEncoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder) для указанной *кодировки*.7879#### `PyObject *PyCodec_IncrementalDecoder(const char *encoding, const char *errors)`8081*Возвращаемое значение: новая ссылка.*8283*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*8485Получить объект [`IncrementalDecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder) для указанной *кодировки*.8687#### `PyObject *PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)`8889*Возвращаемое значение: новая ссылка.*9091*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*9293Получить [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) фабричную функцию для указанной *кодировки*.9495#### `PyObject *PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)`9697*Возвращаемое значение: новая ссылка.*9899*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*100101Получить [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) фабричную функцию для указанной *кодировки*.102103## API реестра обработчиков ошибок кодирования Unicode104105#### `int PyCodec_RegisterError(const char *name, PyObject *error)`106107*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*108109Зарегистрировать колбэк-функцию обработки ошибок *error* под указанным именем *name*. Эта колбэк-функция будет вызвана кодеком, когда он встретит некодируемые символы/недекодируемые байты, и *name* указан в качестве параметра error в вызове функции encode/decode.110111Колбэк получает один аргумент – экземпляр [`UnicodeEncodeError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeEncodeError), [`UnicodeDecodeError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeTranslateError), который содержит информацию о проблемной последовательности символов или байтов и их смещении в исходной строке (см. [Объекты исключений Unicode](https://python-all.ru/3.10/c-api/exceptions.html#unicodeexceptions) для функций извлечения этой информации). Колбэк должен либо вызвать полученное исключение, либо вернуть кортеж из двух элементов, содержащий замену для проблемной последовательности и целое число, указывающее смещение в исходной строке, с которого следует продолжить кодирование/декодирование.112113Возвращает `0` в случае успеха, `-1` при ошибке.114115#### `PyObject *PyCodec_LookupError(const char *name)`116117*Возвращаемое значение: новая ссылка.*118119*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*120121Найти колбэк-функцию обработки ошибок, зарегистрированную под именем *name*. В частном случае можно передать `NULL`, и тогда будет возвращён колбэк обработки ошибок для «strict».122123#### `PyObject *PyCodec_StrictErrors(PyObject *exc)`124125*Возвращаемое значение: всегда NULL.*126127*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*128129Возбудить *exc* как исключение.130131#### `PyObject *PyCodec_IgnoreErrors(PyObject *exc)`132133*Возвращаемое значение: новая ссылка.*134135*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*136137Игнорировать ошибку Unicode, пропуская некорректный ввод.138139#### `PyObject *PyCodec_ReplaceErrors(PyObject *exc)`140141*Возвращаемое значение: новая ссылка.*142143*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*144145Заменить ошибку кодирования Unicode на `?` или `U+FFFD`.146147#### `PyObject *PyCodec_XMLCharRefReplaceErrors(PyObject *exc)`148149*Возвращаемое значение: новая ссылка.*150151*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*152153Заменить ошибку кодирования Unicode на символьные ссылки XML.154155#### `PyObject *PyCodec_BackslashReplaceErrors(PyObject *exc)`156157*Возвращаемое значение: новая ссылка.*158159*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*160161Заменить ошибку кодирования Юникод на escape-последовательности с обратной косой чертой (`\x`, `\u` и `\U`).162163#### `PyObject *PyCodec_NameReplaceErrors(PyObject *exc)`164165*Возвращаемое значение: новая ссылка.*166167*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.7.*168169Заменить ошибку кодирования Юникод на escape-последовательности `\N{...}`.170171Новое в версии 3.5.172