`codecs.md`

717 строк · 92.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.8/library/codecs.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`codecs`](https://python-all.ru/3.8/library/codecs.html#module-codecs) – Реестр кодеков и базовые классы89**Исходный код:** [Lib/codecs.py](https://python-all.ru/src/3.8/Lib/codecs.py)1011---1213Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодеков и обработки ошибок. Большинство стандартных кодеков являются [текстовыми кодировками](https://python-all.ru/3.8/glossary.html#term-text-encoding), которые кодируют текст в байты, но существуют также кодеки, которые кодируют текст в текст и байты в байты. Пользовательские кодеки могут кодировать и декодировать между произвольными типами, но некоторые возможности модуля ограничены для использования только с [текстовыми кодировками](https://python-all.ru/3.8/glossary.html#term-text-encoding) или с кодеками, которые кодируют в [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes).1415Модуль определяет следующие функции для кодирования и декодирования с помощью любого кодека:1617#### `codecs.encode(obj, encoding='utf-8', errors='strict')`1819Кодирует *obj* с помощью кодека, зарегистрированного для *encoding*.2021*Errors* may be given to set the desired error handling scheme. The default error handler is `'strict'` meaning that encoding errors raise [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError) (or a more codec specific subclass, such as [`UnicodeEncodeError`](https://python-all.ru/3.8/library/exceptions.html#UnicodeEncodeError)). Refer to [Codec Base Classes](https://python-all.ru/3.8/library/codecs.html#codec-base-classes) for more information on codec error handling.2223#### `codecs.decode(obj, encoding='utf-8', errors='strict')`2425Декодирует *obj* с помощью кодека, зарегистрированного для *encoding*.2627*Errors* may be given to set the desired error handling scheme. The default error handler is `'strict'` meaning that decoding errors raise [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError) (or a more codec specific subclass, such as [`UnicodeDecodeError`](https://python-all.ru/3.8/library/exceptions.html#UnicodeDecodeError)). Refer to [Codec Base Classes](https://python-all.ru/3.8/library/codecs.html#codec-base-classes) for more information on codec error handling.2829Полные сведения о каждом кодеке также можно получить напрямую:3031#### `codecs.lookup(encoding)`3233Ищет информацию о кодеке в реестре кодеков Python и возвращает объект [`CodecInfo`](https://python-all.ru/3.8/library/codecs.html#codecs.CodecInfo), как определено ниже.3435Сначала кодировки ищутся в кэше реестра. Если не найдены, просматривается список зарегистрированных функций поиска. Если объект [`CodecInfo`](https://python-all.ru/3.8/library/codecs.html#codecs.CodecInfo) не найден, вызывается [`LookupError`](https://python-all.ru/3.8/library/exceptions.html#LookupError). В противном случае объект [`CodecInfo`](https://python-all.ru/3.8/library/codecs.html#codecs.CodecInfo) сохраняется в кэше и возвращается вызывающему.3637#### `class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)`3839Сведения о кодеке при поиске в реестре кодеков. Аргументы конструктора хранятся в атрибутах с теми же именами:4041#### `name`4243Имя кодировки.4445#### `encode`4647#### `decode`4849Функции кодирования и декодирования без сохранения состояния. Это должны быть функции или методы с тем же интерфейсом, что и методы [`encode()`](https://python-all.ru/3.8/library/codecs.html#codecs.Codec.encode) и [`decode()`](https://python-all.ru/3.8/library/codecs.html#codecs.Codec.decode) экземпляров Codec (см. [Интерфейс Codec](https://python-all.ru/3.8/library/codecs.html#codec-objects)). Предполагается, что функции или методы работают в режиме без сохранения состояния.5051#### `incrementalencoder`5253#### `incrementaldecoder`5455Классы или фабричные функции инкрементального кодера и декодера. Они должны предоставлять интерфейс, определенный базовыми классами [`IncrementalEncoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalDecoder), соответственно. Инкрементальные кодеки могут поддерживать состояние.5657#### `streamwriter`5859#### `streamreader`6061Классы или фабричные функции записи и чтения потоков. Они должны предоставлять интерфейс, определенный базовыми классами [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader), соответственно. Потоковые кодеки могут поддерживать состояние.6263Для упрощения доступа к различным компонентам кодеков модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/3.8/library/codecs.html#codecs.lookup) для поиска кодека:6465#### `codecs.getencoder(encoding)`6667Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.6869Вызывает [`LookupError`](https://python-all.ru/3.8/library/exceptions.html#LookupError), если кодировка не найдена.7071#### `codecs.getdecoder(encoding)`7273Находит кодек для указанной кодировки и возвращает его функцию-декодер.7475Вызывает [`LookupError`](https://python-all.ru/3.8/library/exceptions.html#LookupError), если кодировка не найдена.7677#### `codecs.getincrementalencoder(encoding)`7879Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.8081Вызывает [`LookupError`](https://python-all.ru/3.8/library/exceptions.html#LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный кодировщик.8283#### `codecs.getincrementaldecoder(encoding)`8485Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.8687Вызывает [`LookupError`](https://python-all.ru/3.8/library/exceptions.html#LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный декодер.8889#### `codecs.getreader(encoding)`9091Находит кодек для указанной кодировки и возвращает его [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) класс или фабричную функцию.9293Вызывает [`LookupError`](https://python-all.ru/3.8/library/exceptions.html#LookupError), если кодировка не найдена.9495#### `codecs.getwriter(encoding)`9697Находит кодек для указанной кодировки и возвращает его [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter) класс или фабричную функцию.9899Вызывает [`LookupError`](https://python-all.ru/3.8/library/exceptions.html#LookupError), если кодировка не найдена.100101Пользовательские кодеки становятся доступными при регистрации подходящей функции поиска кодека :102103#### `codecs.register(search_function)`104105Регистрирует функцию поиска кодека. Функции поиска должны принимать один аргумент – имя кодировки строчными буквами и возвращать объект [`CodecInfo`](https://python-all.ru/3.8/library/codecs.html#codecs.CodecInfo). Если функция поиска не может найти указанную кодировку, она должна вернуть `None`.106107> **Примечание**108>109> Регистрация функции поиска в настоящее время не является обратимой, что в некоторых случаях может вызывать проблемы, например при модульном тестировании или перезагрузке модулей.110111Хотя встроенная функция [`open()`](https://python-all.ru/3.8/library/functions.html#open) и связанный с ней модуль [`io`](https://python-all.ru/3.8/library/io.html#module-io) являются рекомендуемым способом работы с закодированными текстовыми файлами, этот модуль предоставляет дополнительные вспомогательные функции и классы, позволяющие использовать более широкий набор кодеков при работе с бинарными файлами:112113#### `codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)`114115Открывает закодированный файл, используя указанный *режим*, и возвращает экземпляр [`StreamReaderWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReaderWriter), обеспечивая прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, что означает открытие файла в режиме чтения.116117> **Примечание**118>119> Базовые закодированные файлы всегда открываются в двоичном режиме. Автоматическое преобразование `'\n'` не выполняется при чтении и записи. Аргумент *mode* может быть любым двоичным режимом, приемлемым для встроенной функции [`open()`](https://python-all.ru/3.8/library/functions.html#open); `'b'` добавляется автоматически.120121*encoding* указывает кодировку, которая будет использоваться для файла. Допускается любая кодировка, которая кодирует в байты и декодирует из байтов, а типы данных, поддерживаемые методами файла, зависят от используемого кодека.122123Параметр *errors* можно задать для определения обработки ошибок. По умолчанию он равен `'strict'`, что приводит к возбуждению [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError) при возникновении ошибки кодирования.124125Параметр *buffering* имеет то же значение, что и для встроенной функции [`open()`](https://python-all.ru/3.8/library/functions.html#open). По умолчанию он равен -1, что означает использование размера буфера по умолчанию.126127#### `codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')`128129Возвращает экземпляр [`StreamRecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamRecoder), обёртку для *file*, которая обеспечивает прозрачное перекодирование. Исходный файл закрывается при закрытии обёртки.130131Данные, записываемые в обёрнутый файл, декодируются согласно заданной *data\_encoding*, а затем записываются в исходный файл в виде байтов с использованием *file\_encoding*. Байты, читаемые из исходного файла, декодируются согласно *file\_encoding*, а результат кодируется с использованием *data\_encoding*.132133Если *file\_encoding* не указан, по умолчанию используется *data\_encoding*.134135Параметр *errors* может быть задан для определения обработки ошибок. По умолчанию он равен `'strict'`, что приводит к возникновению [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError) в случае ошибки кодирования.136137#### `codecs.iterencode(iterator, encoding, errors='strict', **kwargs)`138139Использует инкрементальный кодировщик для итеративного кодирования входных данных, предоставляемых *iterator*. Эта функция является [генератором](https://python-all.ru/3.8/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному кодировщику.140141Эта функция требует, чтобы кодек принимал текстовые объекты [`str`](https://python-all.ru/3.8/library/stdtypes.html#str) для кодирования. Поэтому она не поддерживает кодировщики типа «байты-в-байты», такие как `base64_codec`.142143#### `codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)`144145Использует инкрементальный декодировщик для итеративного декодирования входных данных, предоставляемых *iterator*. Эта функция является [генератором](https://python-all.ru/3.8/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному декодировщику.146147Эта функция требует, чтобы кодек принимал объекты [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes) для декодирования. Поэтому она не поддерживает кодировщики типа «текст-в-текст», такие как `rot_13`, хотя `rot_13` может использоваться аналогично с [`iterencode()`](https://python-all.ru/3.8/library/codecs.html#codecs.iterencode).148149Модуль также предоставляет следующие константы, полезные для чтения и записи в платформенно-зависимые файлы:150151#### `codecs.BOM`152153#### `codecs.BOM_BE`154155#### `codecs.BOM_LE`156157#### `codecs.BOM_UTF8`158159#### `codecs.BOM_UTF16`160161#### `codecs.BOM_UTF16_BE`162163#### `codecs.BOM_UTF16_LE`164165#### `codecs.BOM_UTF32`166167#### `codecs.BOM_UTF32_BE`168169#### `codecs.BOM_UTF32_LE`170171Эти константы определяют различные последовательности байтов, являющиеся метками порядка байтов Unicode (BOM) для нескольких кодировок. Они используются в потоках данных UTF-16 и UTF-32 для указания используемого порядка байтов, а в UTF-8 – как сигнатура Unicode. [`BOM_UTF16`](https://python-all.ru/3.8/library/codecs.html#codecs.BOM_UTF16) это либо [`BOM_UTF16_BE`](https://python-all.ru/3.8/library/codecs.html#codecs.BOM_UTF16_BE), либо [`BOM_UTF16_LE`](https://python-all.ru/3.8/library/codecs.html#codecs.BOM_UTF16_LE) в зависимости от нативного порядка байтов платформы; [`BOM`](https://python-all.ru/3.8/library/codecs.html#codecs.BOM) – псевдоним [`BOM_UTF16`](https://python-all.ru/3.8/library/codecs.html#codecs.BOM_UTF16), [`BOM_LE`](https://python-all.ru/3.8/library/codecs.html#codecs.BOM_LE) – [`BOM_UTF16_LE`](https://python-all.ru/3.8/library/codecs.html#codecs.BOM_UTF16_LE), [`BOM_BE`](https://python-all.ru/3.8/library/codecs.html#codecs.BOM_BE) – [`BOM_UTF16_BE`](https://python-all.ru/3.8/library/codecs.html#codecs.BOM_UTF16_BE). Остальные представляют BOM в кодировках UTF-8 и UTF-32.172173## Базовые классы кодеков174175Модуль [`codecs`](https://python-all.ru/3.8/library/codecs.html#module-codecs) определяет набор базовых классов, которые задают интерфейсы для работы с объектами кодеков, а также могут использоваться как основа для реализации пользовательских кодеков.176177Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в Python: статический кодировщик, статический декодер, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно используют статический кодировщик/декодер для реализации файловых протоколов. Разработчикам кодеков также необходимо определить, как кодек будет обрабатывать ошибки кодирования и декодирования.178179### Обработчики ошибок180181Для упрощения и стандартизации обработки ошибок кодеки могут реализовывать различные схемы обработки ошибок, принимая строковый аргумент *errors*. Все стандартные кодеки Python определяют и реализуют следующие строковые значения:182183| Значение | Значение |184| --- | --- |185| `'strict'` | Вызывает [`UnicodeError`](https://python-all.ru/3.8/library/exceptions.html#UnicodeError) (или подкласс); это поведение по умолчанию. Реализовано в [`strict_errors()`](https://python-all.ru/3.8/library/codecs.html#codecs.strict_errors). |186| `'ignore'` | Игнорирует некорректные данные и продолжает без дополнительных уведомлений. Реализовано в [`ignore_errors()`](https://python-all.ru/3.8/library/codecs.html#codecs.ignore_errors). |187188Следующие обработчики ошибок применимы только к [текстовым кодировкам](https://python-all.ru/3.8/glossary.html#term-text-encoding):189190| Значение | Значение |191| --- | --- |192| `'replace'` | Заменяет подходящим маркером замены; для встроенных кодеков Python использует официальный `U+FFFD` заменяющий символ при декодировании и '?' при кодировании. Реализовано в [`replace_errors()`](https://python-all.ru/3.8/library/codecs.html#codecs.replace_errors). |193| `'xmlcharrefreplace'` | Заменяет соответствующей символьной ссылкой XML (только для кодирования). Реализовано в [`xmlcharrefreplace_errors()`](https://python-all.ru/3.8/library/codecs.html#codecs.xmlcharrefreplace_errors). |194| `'backslashreplace'` | Заменяет escape-последовательностями с обратной косой чертой. Реализовано в [`backslashreplace_errors()`](https://python-all.ru/3.8/library/codecs.html#codecs.backslashreplace_errors). |195| `'namereplace'` | Заменяет escape-последовательностями `\N{...}` (только для кодирования). Реализовано в [`namereplace_errors()`](https://python-all.ru/3.8/library/codecs.html#codecs.namereplace_errors). |196| `'surrogateescape'` | При декодировании заменяет байт на отдельный суррогатный код в диапазоне от `U+DC80` до `U+DCFF`. Этот код затем преобразуется обратно в тот же байт при использовании обработчика ошибок `'surrogateescape'` при кодировании данных. (Подробнее см. [**PEP 383**](https://python-all.ru/3.8/library/codecs.html).) |197198Кроме того, следующий обработчик ошибок специфичен для указанных кодеков:199200| Значение | Кодеки | Значение |201| --- | --- | --- |202| `'surrogatepass'` | utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le | Разрешает кодирование и декодирование суррогатных кодов. Обычно эти кодеки считают наличие суррогатов ошибкой. |203204Новое в версии 3.1: Обработчики ошибок `'surrogateescape'` и `'surrogatepass'`.205206Изменено в версии 3.4: Обработчики ошибок `'surrogatepass'` теперь работают с кодеками utf-16\* и utf-32\*.207208Новое в версии 3.5: Обработчик ошибок `'namereplace'`.209210Изменено в версии 3.5: Обработчики ошибок `'backslashreplace'` теперь работают с декодированием и транслитерацией.211212Набор допустимых значений можно расширить, зарегистрировав новый именованный обработчик ошибок:213214#### `codecs.register_error(name, error_handler)`215216Регистрирует функцию обработки ошибок *error\_handler* под именем *name*. Аргумент *error\_handler* будет вызываться во время кодирования и декодирования в случае ошибки, когда в качестве параметра errors указано *name*.217218При кодировании *error\_handler* будет вызываться с экземпляром [`UnicodeEncodeError`](https://python-all.ru/3.8/library/exceptions.html#UnicodeEncodeError), который содержит информацию о местоположении ошибки. Обработчик ошибок должен либо повторно выбросить это или другое исключение, либо вернуть кортеж с заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Замена может быть либо [`str`](https://python-all.ru/3.8/library/stdtypes.html#str), либо [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes). Если замена – bytes, кодировщик просто скопирует их в выходной буфер. Если замена – строка, кодировщик закодирует замену. Кодирование продолжается с исходных входных данных начиная с указанной позиции. Отрицательные значения позиции интерпретируются как смещение относительно конца входной строки. Если результирующая позиция выходит за границы, выбрасывается [`IndexError`](https://python-all.ru/3.8/library/exceptions.html#IndexError).219220Декодирование и трансляция работают аналогично, за исключением того, что обработчику передаётся [`UnicodeDecodeError`](https://python-all.ru/3.8/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.8/library/exceptions.html#UnicodeTranslateError), а замена от обработчика ошибок помещается в выходные данные напрямую.221222Ранее зарегистрированные обработчики ошибок (включая стандартные) можно найти по имени:223224#### `codecs.lookup_error(name)`225226Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.227228Выбрасывает [`LookupError`](https://python-all.ru/3.8/library/exceptions.html#LookupError), если обработчик не найден.229230Следующие стандартные обработчики ошибок также доступны как функции уровня модуля:231232#### `codecs.strict_errors(exception)`233234Реализует обработку ошибок `'strict'`: каждая ошибка кодирования или декодирования вызывает исключение [`UnicodeError`](https://python-all.ru/3.8/library/exceptions.html#UnicodeError).235236#### `codecs.replace_errors(exception)`237238Реализует обработку ошибок `'replace'` (только для [текстовых кодировок](https://python-all.ru/3.8/glossary.html#term-text-encoding)): заменяет ошибки кодирования на `'?'` (кодируется кодеком), а ошибки декодирования на `'\ufffd'` (символ замены Unicode).239240#### `codecs.ignore_errors(exception)`241242Реализует обработку ошибок `'ignore'`: повреждённые данные игнорируются, и кодирование или декодирование продолжается без дополнительных уведомлений.243244#### `codecs.xmlcharrefreplace_errors(exception)`245246Реализует обработку ошибок `'xmlcharrefreplace'` (только для кодирования с помощью [текстовых кодировок](https://python-all.ru/3.8/glossary.html#term-text-encoding)): некодируемый символ заменяется соответствующей символьной ссылкой XML.247248#### `codecs.backslashreplace_errors(exception)`249250Реализует обработку ошибок `'backslashreplace'` (только для [текстовых кодировок](https://python-all.ru/3.8/glossary.html#term-text-encoding)): повреждённые данные заменяются управляющей последовательностью с обратной косой чертой.251252#### `codecs.namereplace_errors(exception)`253254Реализует обработку ошибок `'namereplace'` (только для кодирования с помощью [текстовых кодировок](https://python-all.ru/3.8/glossary.html#term-text-encoding)): некодируемый символ заменяется управляющей последовательностью `\N{...}`.255256Новое в версии 3.5.257258### Кодирование и декодирование без сохранения состояния259260Базовый класс `Codec` определяет эти методы, которые также задают интерфейсы функций кодировщика и декодировщика без сохранения состояния:261262#### `Codec.encode(input[, errors])`263264Кодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Например, [текстовая кодировка](https://python-all.ru/3.8/glossary.html#term-text-encoding) преобразует строковый объект в объект bytes, используя определённую кодировку набора символов (например, `cp1252` или `iso-8859-1`).265266Аргумент *errors* задаёт применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.267268Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter) для кодеков, которым необходимо сохранять состояние для эффективного кодирования.269270Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.271272#### `Codec.decode(input[, errors])`273274Декодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Например, для [текстовой кодировки](https://python-all.ru/3.8/glossary.html#term-text-encoding) декодирование преобразует объект bytes, закодированный с использованием определённой кодировки набора символов, в строковый объект.275276Для текстовых кодировок и кодеков bytes-to-bytes *input* должен быть объектом bytes или объектом, предоставляющим интерфейс буфера только для чтения – например, буферные объекты и файлы, отображаемые в память.277278Аргумент *errors* задаёт применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.279280Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) для кодеков, которым необходимо сохранять состояние для эффективного декодирования.281282Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.283284### Инкрементальное кодирование и декодирование285286Классы [`IncrementalEncoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalDecoder) предоставляют базовый интерфейс для инкрементального кодирования и декодирования. Кодирование/декодирование входных данных выполняется не одним вызовом функции кодировщика/декодировщика без состояния, а несколькими вызовами метода [`encode()`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalDecoder.decode) инкрементального кодировщика/декодировщика. Инкрементальный кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.287288Объединённый вывод вызовов метода [`encode()`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalDecoder.decode) совпадает с тем, что получилось бы, если бы все отдельные входные данные были объединены в один, и этот вход был закодирован/декодирован кодировщиком/декодировщиком без состояния.289290#### Объекты IncrementalEncoder291292Класс [`IncrementalEncoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный кодировщик для совместимости с реестром кодеков Python.293294#### `class codecs.IncrementalEncoder(errors='strict')`295296Конструктор экземпляра [`IncrementalEncoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalEncoder).297298Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.299300Декодер [`IncrementalEncoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalEncoder) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Список возможных значений приведён в разделе [Обработчики ошибок](https://python-all.ru/3.8/library/codecs.html#error-handlers).301302Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalEncoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalEncoder).303304#### `encode(object[, final])`305306Кодирует *object* (с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов [`encode()`](https://python-all.ru/3.8/library/codecs.html#codecs.encode), *final* должен быть истинным (по умолчанию – ложь).307308#### `reset()`309310Сбрасывает кодировщик в исходное состояние. Выходные данные отбрасываются: при необходимости вызовите `.encode(object, final=True)`, передав пустую строку байтов или текстовую строку, чтобы сбросить кодировщик и получить выходные данные.311312#### `getstate()`313314Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что `0` является наиболее распространённым состоянием. (Состояния, более сложные, чем целые числа, можно преобразовать в целое число с помощью маршалинга/сериализации состояния и кодирования байтов результирующей строки в целое число.)315316#### `setstate(state)`317318Устанавливает состояние кодировщика в *state*. *state* должно быть состоянием кодировщика, возвращённым [`getstate()`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalEncoder.getstate).319320#### Объекты IncrementalDecoder321322Класс [`IncrementalDecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный декодер для совместимости с реестром кодеков Python.323324#### `class codecs.IncrementalDecoder(errors='strict')`325326Конструктор экземпляра [`IncrementalDecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalDecoder).327328Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.329330Декодер [`IncrementalDecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalDecoder) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Список возможных значений приведён в разделе [Обработчики ошибок](https://python-all.ru/3.8/library/codecs.html#error-handlers).331332Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalDecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalDecoder).333334#### `decode(object[, final])`335336Декодирует *object* (с учётом текущего состояния декодера) и возвращает результирующий декодированный объект. Если это последний вызов [`decode()`](https://python-all.ru/3.8/library/codecs.html#codecs.decode), *final* должен быть истинным (по умолчанию – ложь). Если *final* истинно, декодер должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).337338#### `reset()`339340Сбрасывает декодер в исходное состояние.341342#### `getstate()`343344Возвращает текущее состояние декодера. Это должен быть кортеж из двух элементов: первый – буфер, содержащий ещё не декодированные входные данные; второй – целое число, которое может содержать дополнительную информацию о состоянии. (Реализация должна гарантировать, что `0` является наиболее распространённой дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии равна `0`, должна быть возможность установить декодер в состояние без буферизованных входных данных и с `0` в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованных входных данных в декодер возвращала его в предыдущее состояние без вывода каких-либо данных. (Дополнительная информация о состоянии, более сложная, чем целые числа, может быть преобразована в целое число с помощью маршалинга/сериализации этой информации и кодирования байтов результирующей строки в целое число.)345346#### `setstate(state)`347348Устанавливает состояние декодера в *state*. *state* должно быть состоянием декодера, возвращённым [`getstate()`](https://python-all.ru/3.8/library/codecs.html#codecs.IncrementalDecoder.getstate).349350### Потоковое кодирование и декодирование351352Классы [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) предоставляют универсальные рабочие интерфейсы, которые можно использовать для очень простой реализации новых подмодулей кодирования. Пример см. в `encodings.utf_8`.353354#### Объекты StreamWriter355356Класс [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый писатель должен реализовать для совместимости с реестром кодеков Python.357358#### `class codecs.StreamWriter(stream, errors='strict')`359360Конструктор экземпляра [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter).361362Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.363364Аргумент *поток данных* должен быть файлоподобным объектом, открытым для записи текстовых или двоичных данных, в зависимости от конкретного кодека.365366Объект [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. См. [Обработчики ошибок](https://python-all.ru/3.8/library/codecs.html#error-handlers) для получения списка стандартных обработчиков ошибок, которые может поддерживать базовый потоковый кодек.367368Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter).369370#### `write(object)`371372Записывает в поток закодированное содержимое объекта.373374#### `writelines(list)`375376Записывает объединённый список строк в поток данных (возможно, повторно используя метод [`write()`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter.write)). Стандартные кодеки «байты в байты» не поддерживают этот метод.377378#### `reset()`379380Сбрасывает и переустанавливает буферы кодека, используемые для сохранения состояния.381382Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.383384В дополнение к приведённым выше методам, [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.385386#### Объекты StreamReader387388Класс [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый читатель должен реализовать для совместимости с реестром кодеков Python.389390#### `class codecs.StreamReader(stream, errors='strict')`391392Конструктор экземпляра [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader).393394Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.395396Аргумент *поток данных* должен быть файлоподобным объектом, открытым для чтения текстовых или двоичных данных, в зависимости от конкретного кодека.397398Объект [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. См. [Обработчики ошибок](https://python-all.ru/3.8/library/codecs.html#error-handlers) для получения списка стандартных обработчиков ошибок, которые может поддерживать базовый потоковый кодек.399400Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader).401402Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.8/library/codecs.html#codecs.register_error).403404#### `read([size[, chars[, firstline]]])`405406Декодирует данные из потока и возвращает результирующий объект.407408Аргумент *chars* указывает количество декодированных кодовых точек или байтов для возврата. Метод [`read()`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader.read) никогда не вернёт больше данных, чем запрошено, но может вернуть меньше, если доступно недостаточно.409410Аргумент *size* указывает приблизительное максимальное количество закодированных байтов или кодовых точек для чтения при декодировании. Декодер может изменять этот параметр по своему усмотрению. Значение по умолчанию -1 означает чтение и декодирование максимально возможного объёма. Этот параметр предназначен для того, чтобы не приходилось декодировать огромные файлы за один шаг.411412Флаг *firstline* указывает, что достаточно вернуть только первую строку, если на последующих строках возникают ошибки декодирования.413414Метод должен использовать жадную стратегию чтения, то есть читать столько данных, сколько допускается определением кодировки и заданным размером; например, если в потоке доступны необязательные окончания кодировки или маркеры состояния, их также следует прочитать.415416#### `readline([size[, keepends]])`417418Читает одну строку из входного потока и возвращает декодированные данные.419420*size*, если задан, передаётся как аргумент size в метод [`read()`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader.read) потока данных.421422Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.423424#### `readlines([sizehint[, keepends]])`425426Читает все строки из входного потока данных и возвращает их в виде списка строк.427428Символы конца строки обрабатываются с помощью метода [`decode()`](https://python-all.ru/3.8/library/codecs.html#codecs.decode) кодекa и включаются в элементы списка, если *keepends* равен True.429430*sizehint*, если задан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader.read) потока данных.431432#### `reset()`433434Сбрасывает буферы кодека, используемые для сохранения состояния.435436Обратите внимание, что перемещение по потоку данных не должно выполняться. Этот метод в первую очередь предназначен для восстановления после ошибок декодирования.437438В дополнение к приведённым выше методам, [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.439440#### Объекты StreamReaderWriter441442[`StreamReaderWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReaderWriter) – это удобный класс, который позволяет оборачивать потоки данных, работающие как в режиме чтения, так и в режиме записи.443444Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.8/library/codecs.html#codecs.lookup).445446#### `class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')`447448Создаёт экземпляр [`StreamReaderWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReaderWriter). *поток данных* должен быть файлоподобным объектом. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими интерфейсы [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter) соответственно. Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.449450Экземпляры [`StreamReaderWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReaderWriter) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.451452#### Объекты StreamRecoder453454[`StreamRecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamRecoder) преобразует данные из одной кодировки в другую, что иногда полезно при работе с различными кодировочными средами.455456Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.8/library/codecs.html#codecs.lookup).457458#### `class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')`459460Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamRecoder), который реализует двустороннее преобразование: *encode* и *decode* работают на внешней стороне – данные, видимые коду, вызывающему `read()` и `write()`, а *Reader* и *Writer* работают на внутренней стороне – данные в *поток данных*.461462Эти объекты можно использовать для прозрачной перекодировки, например, из Latin-1 в UTF-8 и обратно.463464Аргумент *поток данных* должен быть файлоподобным объектом.465466Аргументы *encode* и *decode* должны соответствовать интерфейсу `Codec`. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими объекты интерфейсов [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter) соответственно.467468Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.469470Экземпляры [`StreamRecoder`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamRecoder) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.8/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.471472## Кодировки и Unicode473474Строки внутри хранятся как последовательности кодовых точек в диапазоне `0x0`–`0x10FFFF`. (Подробнее об реализации см. [**PEP 393**](https://python-all.ru/3.8/library/codecs.html).) Как только строковый объект используется за пределами ЦП и памяти, порядок байтов и способ хранения этих массивов в виде байтов становятся проблемой. Как и для других кодеков, сериализация строки в последовательность байтов называется *кодированием*, а восстановление строки из последовательности байтов – *декодированием*. Существует множество различных текстовых кодеков сериализации, которые в совокупности называются [текстовыми кодировками](https://python-all.ru/3.8/glossary.html#term-text-encoding).475476Простейшая текстовая кодировка (называемая `'latin-1'` или `'iso-8859-1'`) отображает кодовые точки 0–255 на байты `0x0`–`0xff`, что означает, что строковый объект, содержащий кодовые точки больше `U+00FF`, не может быть закодирован этим кодеком. Попытка сделать это вызовет исключение [`UnicodeEncodeError`](https://python-all.ru/3.8/library/exceptions.html#UnicodeEncodeError), которое выглядит следующим образом (хотя детали сообщения об ошибке могут отличаться): `UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256)`.477478Существует ещё одна группа кодировок (так называемые charmap-кодировки), которые выбирают другое подмножество всех кодовых точек Юникода и определяют, как эти кодовые точки отображаются на байты `0x0`–`0xff`. Чтобы увидеть, как это работает, достаточно открыть, например, `encodings/cp1252.py` (кодировку, которая в основном используется в Windows). В ней есть строковая константа из 256 символов, показывающая, какой символ какому значению байта соответствует.479480Все эти кодировки могут кодировать только 256 из 1 114 112 кодовых точек, определённых в Unicode. Простой и прямой способ хранить каждую кодовую точку Unicode – хранить каждую кодовую точку в виде четырёх последовательных байтов. Есть две возможности: хранить байты в порядке big endian или little endian. Эти две кодировки называются `UTF-32-BE` и `UTF-32-LE` соответственно. Их недостаток в том, что если, например, использовать `UTF-32-BE` на машине с little endian, то при кодировании и декодировании придётся всегда менять порядок байтов. `UTF-32` избегает этой проблемы: байты всегда будут в естественном порядке байтов. Однако когда эти байты читаются процессором с другим порядком байтов, байты всё равно приходится переставлять. Чтобы можно было определить порядок байтов последовательности `UTF-16` или `UTF-32`, существует так называемая BOM («метка порядка байтов»). Это символ Unicode `U+FEFF`. Этот символ можно добавлять в начало каждой последовательности байтов `UTF-16` или `UTF-32`. Версия этого символа с переставленными байтами (`0xFFFE`) является недопустимым символом, который не может встречаться в тексте Unicode. Поэтому когда первый символ в последовательности байтов `UTF-16` или `UTF-32` оказывается символом `U+FFFE`, при декодировании байты необходимо переставить. К сожалению, символ `U+FEFF` имел второе назначение – `ZERO WIDTH NO-BREAK SPACE`: символ, не имеющий ширины и не позволяющий разбивать слово. Его можно использовать, например, для подсказок алгоритму лигатур. Начиная с Unicode 4.0 использование `U+FEFF` в качестве `ZERO WIDTH NO-BREAK SPACE` считается устаревшим (эту роль взял на себя `U+2060` (`WORD JOINER`)). Тем не менее программное обеспечение Unicode всё ещё должно уметь обрабатывать `U+FEFF` в обеих ролях: как BOM – это средство определения порядка хранения закодированных байтов, и оно исчезает после декодирования последовательности байтов в строку; как `ZERO WIDTH NO-BREAK SPACE` – это обычный символ, который будет декодирован, как любой другой.481482Существует ещё одна кодировка, способная кодировать весь диапазон символов Unicode: UTF-8. UTF-8 – это 8-битная кодировка, а это значит, что в UTF-8 нет проблем с порядком байтов. Каждый байт в последовательности UTF-8 состоит из двух частей: битов маркера (самые старшие биты) и битов полезной нагрузки. Биты маркера представляют собой последовательность от нуля до четырёх битов `1`, за которой следует бит `0`. Символы Unicode кодируются следующим образом (где x – биты полезной нагрузки, которые при объединении дают символ Unicode):483484| Диапазон | Кодировка |485| --- | --- |486| `U-00000000` … `U-0000007F` | 0xxxxxxx |487| `U-00000080` … `U-000007FF` | 110xxxxx 10xxxxxx |488| `U-00000800` … `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |489| `U-00010000` … `U-0010FFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |490491Младший значащий бит символа Unicode – это самый правый бит x.492493Поскольку UTF-8 является 8-битной кодировкой, BOM не требуется, и любой символ `U+FEFF` в декодированной строке (даже если это первый символ) рассматривается как `ZERO WIDTH NO-BREAK SPACE`.494495Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Любая кодировка charmap может декодировать любую случайную последовательность байтов. Однако с UTF-8 это невозможно, так как последовательности байтов UTF-8 имеют структуру, не допускающую произвольные последовательности. Чтобы повысить надёжность обнаружения кодировки UTF-8, Microsoft изобрела вариант UTF-8 (который Python 2.5 называет `"utf-8-sig"`) для своей программы Notepad: перед записью любого символа Unicode в файл записывается BOM в кодировке UTF-8 (которая выглядит как последовательность байтов: `0xef`, `0xbb`, `0xbf`). Поскольку маловероятно, что какой-либо файл, закодированный в charmap, начинается с этих значений байтов (которые, например, отображаются на496497> ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЭРЕЗИСОМ498>499> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА500>501> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК502503в iso-8859-1), это повышает вероятность того, что кодировка `utf-8-sig` будет правильно угадана по последовательности байтов. Таким образом, здесь BOM используется не для определения порядка байтов, использованного при генерации последовательности байтов, а как сигнатура, помогающая угадать кодировку. При кодировании кодек utf-8-sig запишет `0xef`, `0xbb`, `0xbf` в качестве первых трёх байтов в файл. При декодировании `utf-8-sig` пропустит эти три байта, если они окажутся первыми тремя байтами в файле. В UTF-8 использование BOM не рекомендуется и его обычно следует избегать.504505## Стандартные кодировки506507Python поставляется с рядом встроенных кодеков, реализованных либо как функции на C либо с использованием словарей в качестве таблиц сопоставления. В следующей таблице перечислены кодеки по имени, а также некоторые распространённые псевдонимы и языки, для которых вероятно используется данная кодировка. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что альтернативные написания, различающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами; поэтому, например, `'utf-8'` является допустимым псевдонимом для кодека `'utf_8'`.508509**Особенность реализации CPython:** Некоторые распространённые кодировки могут обходить механизм поиска кодеков для повышения производительности. Эти возможности оптимизации распознаются CPython только для ограниченного набора псевдонимов (без учёта регистра): utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (только Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32, а также те же с использованием подчёркивания вместо дефисов. Использование альтернативных псевдонимов для этих кодировок может привести к более медленному выполнению.510511Изменено в версии 3.6: Возможность оптимизации распознаётся для us-ascii.512513Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:514515- набор символов ISO 8859516- кодовая страница Microsoft Windows, которая обычно происходит из набора 8859, но заменяет управляющие символы дополнительными графическими символами517- кодовая страница IBM EBCDIC518- кодовая страница IBM PC, совместимая с ASCII519520| Кодек | Псевдонимы | Языки |521| --- | --- | --- |522| ascii | 646, us-ascii | Английский |523| big5 | big5-tw, csbig5 | Китайский традиционный |524| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |525| cp037 | IBM037, IBM039 | Английский |526| cp273 | 273, IBM273, csIBM273 | Немецкий Новое в версии 3.4. |527| cp424 | EBCDIC-CP-HE, IBM424 | Иврит |528| cp437 | 437, IBM437 | Английский |529| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Западная Европа |530| cp720 |  | Арабский |531| cp737 |  | Греческий |532| cp775 | IBM775 | Балтийские языки |533| cp850 | 850, IBM850 | Западная Европа |534| cp852 | 852, IBM852 | Центральная и Восточная Европа |535| cp855 | 855, IBM855 | болгарский, белорусский, македонский, русский, сербский |536| cp856 |  | Иврит |537| cp857 | 857, IBM857 | Турецкий |538| cp858 | 858, IBM858 | Западная Европа |539| cp860 | 860, IBM860 | португальский |540| cp861 | 861, CP-IS, IBM861 | Исландский |541| cp862 | 862, IBM862 | Иврит |542| cp863 | 863, IBM863 | канадский |543| cp864 | IBM864 | Арабский |544| cp865 | 865, IBM865 | датский, норвежский |545| cp866 | 866, IBM866 | Русский |546| cp869 | 869, CP-GR, IBM869 | Греческий |547| cp874 |  | Тайский |548| cp875 |  | Греческий |549| cp932 | 932, ms932, mskanji, ms-kanji | Японский |550| cp949 | 949, ms949, uhc | Корейский |551| cp950 | 950, ms950 | Китайский традиционный |552| cp1006 |  | Урду |553| cp1026 | ibm1026 | Турецкий |554| cp1125 | 1125, ibm1125, cp866u, ruscii | Украинский Новое в версии 3.4. |555| cp1140 | ibm1140 | Западная Европа |556| cp1250 | windows-1250 | Центральная и Восточная Европа |557| cp1251 | windows-1251 | болгарский, белорусский, македонский, русский, сербский |558| cp1252 | windows-1252 | Западная Европа |559| cp1253 | windows-1253 | Греческий |560| cp1254 | windows-1254 | Турецкий |561| cp1255 | windows-1255 | Иврит |562| cp1256 | windows-1256 | Арабский |563| cp1257 | windows-1257 | Балтийские языки |564| cp1258 | windows-1258 | вьетнамский |565| euc\_jp | eucjp, ujis, u-jis | Японский |566| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |567| euc\_jisx0213 | eucjisx0213 | Японский |568| euc\_kr | euckr, корейский, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |569| gb2312 | китайский, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58 | Упрощённый китайский |570| gbk | 936, cp936, ms936 | Унифицированный китайский |571| gb18030 | gb18030-2000 | Унифицированный китайский |572| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |573| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |574| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |575| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |576| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |577| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |578| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |579| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |580| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |581| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |582| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |583| iso8859\_4 | iso-8859-4, latin4, L4 | Балтийские языки |584| iso8859\_5 | iso-8859-5, кириллица | болгарский, белорусский, македонский, русский, сербский |585| iso8859\_6 | iso-8859-6, арабский | Арабский |586| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |587| iso8859\_8 | iso-8859-8, иврит | Иврит |588| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |589| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |590| iso8859\_11 | iso-8859-11, тайская | Тайские языки |591| iso8859\_13 | iso-8859-13, latin7, L7 | Балтийские языки |592| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |593| iso8859\_15 | iso-8859-15, latin9, L9 | Западная Европа |594| iso8859\_16 | iso-8859-16, latin10, L10 | Юго-Восточная Европа |595| johab | cp1361, ms1361 | Корейский |596| koi8\_r |  | Русский |597| koi8\_t |  | Таджикский Новое в версии 3.5. |598| koi8\_u |  | Украинский |599| kz1048 | kz\_1048, strk1048\_2002, rk1048 | Казахский Новое в версии 3.5. |600| mac\_cyrillic | maccyrillic | болгарский, белорусский, македонский, русский, сербский |601| mac\_greek | macgreek | Греческий |602| mac\_iceland | maciceland | Исландский |603| mac\_latin2 | maclatin2, maccentraleurope | Центральная и Восточная Европа |604| mac\_roman | macroman, macintosh | Западная Европа |605| mac\_turkish | macturkish | Турецкий |606| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |607| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |608| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |609| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |610| utf\_32 | U32, utf32 | все языки |611| utf\_32\_be | UTF-32BE | все языки |612| utf\_32\_le | UTF-32LE | все языки |613| utf\_16 | U16, utf16 | все языки |614| utf\_16\_be | UTF-16BE | все языки |615| utf\_16\_le | UTF-16LE | все языки |616| utf\_7 | U7, unicode-1-1-utf-7 | все языки |617| utf\_8 | U8, UTF, utf8, cp65001 | все языки |618| utf\_8\_sig |  | все языки |619620Изменено в версии 3.4: Кодировщики utf-16\* и utf-32\* больше не позволяют кодировать суррогатные кодовые точки (`U+D800`–`U+DFFF`). Декодировщики utf-32\* больше не декодируют последовательности байтов, соответствующие суррогатным кодовым точкам.621622Изменено в версии 3.8: `cp65001` теперь является псевдонимом `utf_8`.623624## Специфичные для Python кодировки625626Ряд предопределённых кодеков специфичны для Python, поэтому их имена не имеют смысла вне Python. Они перечислены в таблицах ниже на основе ожидаемых типов ввода и вывода (обратите внимание: хотя текстовые кодировки – наиболее распространённый случай использования кодеков, базовая инфраструктура кодеков поддерживает произвольные преобразования данных, а не только текстовые кодировки). Для асимметричных кодеков указанное назначение описывает направление кодирования.627628### Текстовые кодировки629630Следующие кодеки обеспечивают кодирование из [`str`](https://python-all.ru/3.8/library/stdtypes.html#str) в [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes) и декодирование из [байтоподобного объекта](https://python-all.ru/3.8/glossary.html#term-bytes-like-object) в [`str`](https://python-all.ru/3.8/library/stdtypes.html#str), аналогично текстовым кодировкам Unicode.631632| Кодек | Псевдонимы | Значение |633| --- | --- | --- |634| idna |  | Реализует [**RFC 3490**](https://python-all.ru/3.8/library/codecs.html), см. также [`encodings.idna`](https://python-all.ru/3.8/library/codecs.html#module-encodings.idna). Поддерживается только `errors='strict'`. |635| mbcs | ansi, dbcs | Только для Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |636| oem |  | Только для Windows: кодирует операнд в соответствии с кодовой страницей OEM (CP\_OEMCP). Новое в версии 3.6. |637| palmos |  | Кодировка PalmOS 3.5. |638| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/3.8/library/codecs.html). Кодеки с состоянием не поддерживаются. |639| raw\_unicode\_escape |  | Кодировка Latin-1 с `\uXXXX` и `\UXXXXXXXX` для остальных кодовых точек. Существующие обратные слеши никак не экранируются. Используется в протоколе pickle языка Python. |640| undefined |  | Вызывает исключение для всех преобразований, даже для пустых строк. Обработчик ошибок игнорируется. |641| unicode\_escape |  | Кодировка, подходящая для содержимого Unicode-литерала в исходном коде Python в кодировке ASCII, за исключением того, что кавычки не экранируются. Декодирование из исходного кода в Latin-1. Имейте в виду, что исходный код Python на самом деле по умолчанию использует UTF-8. |642643Изменено в версии 3.8: кодек «unicode\_internal» удалён.644645### Двоичные преобразования646647Следующие кодеки обеспечивают двоичные преобразования: [объект, подобный байтовой строке](https://python-all.ru/3.8/glossary.html#term-bytes-like-object) в [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes). Они не поддерживаются [`bytes.decode()`](https://python-all.ru/3.8/library/stdtypes.html#bytes.decode) (который создаёт только вывод [`str`](https://python-all.ru/3.8/library/stdtypes.html#str)).648649| Кодек | Псевдонимы | Значение | Кодировщик / декодировщик |650| --- | --- | --- | --- |651| base64\_codec [1](https://python-all.ru/3.8/library/codecs.html#b64) | base64, base\_64 | Преобразует операнд в многострочный MIME base64 (результат всегда включает завершающий `'\n'`). Изменено в версии 3.4: принимает любой [объект, подобный байтовой строке](https://python-all.ru/3.8/glossary.html#term-bytes-like-object) в качестве входных данных для кодирования и декодирования | [`base64.encodebytes()`](https://python-all.ru/3.8/library/base64.html#base64.encodebytes) / [`base64.decodebytes()`](https://python-all.ru/3.8/library/base64.html#base64.decodebytes) |652| bz2\_codec | bz2 | Сжимает операнд с помощью bz2. | [`bz2.compress()`](https://python-all.ru/3.8/library/bz2.html#bz2.compress) / [`bz2.decompress()`](https://python-all.ru/3.8/library/bz2.html#bz2.decompress) |653| hex\_codec | hex | Преобразует операнд в шестнадцатеричное представление, по два символа на байт. | [`binascii.b2a_hex()`](https://python-all.ru/3.8/library/binascii.html#binascii.b2a_hex) / [`binascii.a2b_hex()`](https://python-all.ru/3.8/library/binascii.html#binascii.a2b_hex) |654| quopri\_codec | quopri, quotedprintable, quoted\_printable | Преобразует операнд в MIME quoted printable. | [`quopri.encode()`](https://python-all.ru/3.8/library/quopri.html#quopri.encode) с `quotetabs=True` / [`quopri.decode()`](https://python-all.ru/3.8/library/quopri.html#quopri.decode) |655| uu\_codec | uu | Преобразует операнд с помощью uuencode. | [`uu.encode()`](https://python-all.ru/3.8/library/uu.html#uu.encode) / [`uu.decode()`](https://python-all.ru/3.8/library/uu.html#uu.decode) |656| zlib\_codec | zip, zlib | Сжимает операнд с помощью gzip. | [`zlib.compress()`](https://python-all.ru/3.8/library/zlib.html#zlib.compress) / [`zlib.decompress()`](https://python-all.ru/3.8/library/zlib.html#zlib.decompress) |657658**[1](https://python-all.ru/3.8/library/codecs.html#id5)**659660В дополнение к [байтоподобным объектам](https://python-all.ru/3.8/glossary.html#term-bytes-like-object), `'base64_codec'` также принимает экземпляры [`str`](https://python-all.ru/3.8/library/stdtypes.html#str) только с ASCII для декодирования661662Новое в версии 3.2: Восстановление бинарных преобразований.663664Изменено в версии 3.4: Восстановление псевдонимов для двоичных преобразований.665666### Текстовые преобразования667668Следующий кодек предоставляет текстовое преобразование: отображение [`str`](https://python-all.ru/3.8/library/stdtypes.html#str) в [`str`](https://python-all.ru/3.8/library/stdtypes.html#str). Он не поддерживается [`str.encode()`](https://python-all.ru/3.8/library/stdtypes.html#str.encode) (который создаёт только вывод [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes)).669670| Кодек | Псевдонимы | Значение |671| --- | --- | --- |672| rot\_13 | rot13 | Возвращает шифр Цезаря для операнда. |673674Новое в версии 3.2: Восстановление `rot_13` текстового преобразования.675676Изменено в версии 3.4: Восстановление псевдонима `rot13`.677678## [`encodings.idna`](https://python-all.ru/3.8/library/codecs.html#module-encodings.idna) – Интернационализированные доменные имена в приложениях679680Этот модуль реализует [**RFC 3490**](https://python-all.ru/3.8/library/codecs.html) (Internationalized Domain Names in Applications) и [**RFC 3492**](https://python-all.ru/3.8/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/3.8/library/stringprep.html#module-stringprep).681682Если требуется стандарт IDNA 2008 из [**RFC 5891**](https://python-all.ru/3.8/library/codecs.html) и [**RFC 5895**](https://python-all.ru/3.8/library/codecs.html), используйте сторонний модуль *idna \<https://pypi.org/project/idna/\>\_*.683684Эти RFC совместно определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (например, `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, такую как `www.xn--alliancefranaise-npb.nu`). Форма ACE доменного имени затем используется во всех местах, где протокол не допускает произвольных символов, таких как DNS-запросы, поля HTTP *Host* и так далее. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки доменов Unicode в IDNA при передаче по сети и преобразовывать обратно метки ACE в Unicode перед представлением их пользователю.685686Python поддерживает это преобразование несколькими способами: кодек `idna` выполняет преобразование между Unicode и ACE, разделяя входную строку на метки на основе символов-разделителей, определённых в [**раздел 3.1 RFC 3490**](https://python-all.ru/3.8/library/codecs.html), и преобразуя каждую метку в ACE по мере необходимости, и, наоборот, разделяя входную байтовую строку на метки на основе разделителя `.` и преобразуя любые найденные метки ACE в Unicode. Кроме того, модуль [`socket`](https://python-all.ru/3.8/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно беспокоиться о преобразовании имён хостов самостоятельно при передаче их в модуль socket. Вдобавок, модули, которые принимают имена хостов в качестве параметров функций, такие как [`http.client`](https://python-all.ru/3.8/library/http.client.html#module-http.client) и [`ftplib`](https://python-all.ru/3.8/library/ftplib.html#module-ftplib), принимают Unicode-имена хостов ([`http.client`](https://python-all.ru/3.8/library/http.client.html#module-http.client) затем также прозрачно отправляет IDNA-имя хоста в поле *Host*, если вообще отправляет это поле).687688При получении имён хостов из сети (например, при обратном поиске имени) никакого автоматического преобразования в Unicode не выполняется: приложения, желающие представить такие имена хостов пользователю, должны декодировать их в Unicode.689690Модуль [`encodings.idna`](https://python-all.ru/3.8/library/codecs.html#module-encodings.idna) также реализует процедуру nameprep, которая выполняет определённые нормализации имён хостов для достижения нечувствительности к регистру интернационализированных доменных имён и унификации похожих символов. Функции nameprep можно использовать напрямую, если необходимо.691692#### `encodings.idna.nameprep(label)`693694Возвращает версию *label* после обработки nameprep. В текущей реализации предполагаются строки запроса, поэтому `AllowUnassigned` имеет значение истина.695696#### `encodings.idna.ToASCII(label)`697698Преобразует метку в ASCII, как указано в [**RFC 3490**](https://python-all.ru/3.8/library/codecs.html). Предполагается, что `UseSTD3ASCIIRules` имеет значение false.699700#### `encodings.idna.ToUnicode(label)`701702Преобразует метку в Unicode, как указано в [**RFC 3490**](https://python-all.ru/3.8/library/codecs.html).703704## [`encodings.mbcs`](https://python-all.ru/3.8/library/codecs.html#module-encodings.mbcs) – кодовая страница Windows ANSI705706Этот модуль реализует кодовую страницу ANSI (CP\_ACP).707708[Доступность](https://python-all.ru/3.8/library/intro.html#availability): только в Windows.709710Изменено в версии 3.3: Поддержка любого обработчика ошибок.711712Изменено в версии 3.2: До версии 3.2 аргумент *errors* игнорировался; `'replace'` всегда использовался для кодирования, а `'ignore'` для декодирования.713714## [`encodings.utf_8_sig`](https://python-all.ru/3.8/library/codecs.html#module-encodings.utf_8_sig) – UTF-8 кодек с сигнатурой BOM715716Этот модуль реализует разновидность кодека UTF-8. При кодировании перед байтами, закодированными в UTF-8, добавляется BOM в кодировке UTF-8. Для кодера с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный BOM в кодировке UTF-8 в начале данных пропускается.717