`codecs.md`

709 строк · 92.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.5/library/codecs.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 7.2. [`codecs`](https://python-all.ru/3.5/library/codecs.html#module-codecs) – Реестр кодеков и базовые классы89**Исходный код:** [Lib/codecs.py](https://python-all.ru/src/3.5/Lib/codecs.py)1011---1213Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодеков и обработки ошибок. Большинство стандартных кодеков являются [текстовыми кодировками](https://python-all.ru/3.5/glossary.html#term-text-encoding), которые кодируют текст в байты, но существуют также кодеки, которые кодируют текст в текст и байты в байты. Пользовательские кодеки могут кодировать и декодировать между произвольными типами, но некоторые возможности модуля ограничены для использования только с [текстовыми кодировками](https://python-all.ru/3.5/glossary.html#term-text-encoding) или с кодеками, которые кодируют в [`bytes`](https://python-all.ru/3.5/library/functions.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.5/library/exceptions.html#ValueError) (or a more codec specific subclass, such as [`UnicodeEncodeError`](https://python-all.ru/3.5/library/exceptions.html#UnicodeEncodeError)). Refer to [Codec Base Classes](https://python-all.ru/3.5/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.5/library/exceptions.html#ValueError) (or a more codec specific subclass, such as [`UnicodeDecodeError`](https://python-all.ru/3.5/library/exceptions.html#UnicodeDecodeError)). Refer to [Codec Base Classes](https://python-all.ru/3.5/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.5/library/codecs.html#codecs.CodecInfo), как определено ниже.3435Сначала кодировки ищутся в кэше реестра. Если не найдены, просматривается список зарегистрированных функций поиска. Если объект [`CodecInfo`](https://python-all.ru/3.5/library/codecs.html#codecs.CodecInfo) не найден, вызывается [`LookupError`](https://python-all.ru/3.5/library/exceptions.html#LookupError). В противном случае объект [`CodecInfo`](https://python-all.ru/3.5/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.5/library/codecs.html#codecs.Codec.encode) и [`decode()`](https://python-all.ru/3.5/library/codecs.html#codecs.Codec.decode) экземпляров Codec (см. [Интерфейс Codec](https://python-all.ru/3.5/library/codecs.html#codec-objects)). Предполагается, что функции или методы работают в режиме без сохранения состояния.5051#### `incrementalencoder`5253#### `incrementaldecoder`5455Классы или фабричные функции инкрементального кодера и декодера. Они должны предоставлять интерфейс, определенный базовыми классами [`IncrementalEncoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalDecoder), соответственно. Инкрементальные кодеки могут поддерживать состояние.5657#### `streamwriter`5859#### `streamreader`6061Классы или фабричные функции записи и чтения потоков. Они должны предоставлять интерфейс, определенный базовыми классами [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader), соответственно. Потоковые кодеки могут поддерживать состояние.6263Для упрощения доступа к различным компонентам кодеков модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/3.5/library/codecs.html#codecs.lookup) для поиска кодека:6465#### `codecs.getencoder(encoding)`6667Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.6869Вызывает [`LookupError`](https://python-all.ru/3.5/library/exceptions.html#LookupError), если кодировка не найдена.7071#### `codecs.getdecoder(encoding)`7273Находит кодек для указанной кодировки и возвращает его функцию-декодер.7475Вызывает [`LookupError`](https://python-all.ru/3.5/library/exceptions.html#LookupError), если кодировка не найдена.7677#### `codecs.getincrementalencoder(encoding)`7879Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.8081Вызывает [`LookupError`](https://python-all.ru/3.5/library/exceptions.html#LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный кодировщик.8283#### `codecs.getincrementaldecoder(encoding)`8485Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.8687Вызывает [`LookupError`](https://python-all.ru/3.5/library/exceptions.html#LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный декодер.8889#### `codecs.getreader(encoding)`9091Находит кодек для указанной кодировки и возвращает его [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader) класс или фабричную функцию.9293Вызывает [`LookupError`](https://python-all.ru/3.5/library/exceptions.html#LookupError), если кодировка не найдена.9495#### `codecs.getwriter(encoding)`9697Находит кодек для указанной кодировки и возвращает его [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter) класс или фабричную функцию.9899Вызывает [`LookupError`](https://python-all.ru/3.5/library/exceptions.html#LookupError), если кодировка не найдена.100101Пользовательские кодеки становятся доступными при регистрации подходящей функции поиска кодека :102103#### `codecs.register(search_function)`104105Регистрирует функцию поиска кодека. Функции поиска должны принимать один аргумент – имя кодировки строчными буквами и возвращать объект [`CodecInfo`](https://python-all.ru/3.5/library/codecs.html#codecs.CodecInfo). Если функция поиска не может найти указанную кодировку, она должна вернуть `None`.106107> **Примечание**108>109> Регистрация функции поиска в настоящее время не является обратимой, что в некоторых случаях может вызывать проблемы, например при модульном тестировании или перезагрузке модулей.110111Хотя встроенная функция [`open()`](https://python-all.ru/3.5/library/functions.html#open) и связанный с ней модуль [`io`](https://python-all.ru/3.5/library/io.html#module-io) являются рекомендуемым способом работы с закодированными текстовыми файлами, этот модуль предоставляет дополнительные вспомогательные функции и классы, позволяющие использовать более широкий набор кодеков при работе с бинарными файлами:112113#### `codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=1)`114115Открывает закодированный файл, используя указанный *режим*, и возвращает экземпляр [`StreamReaderWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReaderWriter), обеспечивая прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, что означает открытие файла в режиме чтения.116117> **Примечание**118>119> Базовые закодированные файлы всегда открываются в двоичном режиме. Автоматическое преобразование `'\n'` не выполняется при чтении и записи. Аргумент *mode* может быть любым двоичным режимом, приемлемым для встроенной функции [`open()`](https://python-all.ru/3.5/library/functions.html#open); `'b'` добавляется автоматически.120121*encoding* указывает кодировку, которая будет использоваться для файла. Допускается любая кодировка, которая кодирует в байты и декодирует из байтов, а типы данных, поддерживаемые методами файла, зависят от используемого кодека.122123Параметр *errors* можно задать для определения обработки ошибок. По умолчанию он равен `'strict'`, что приводит к возбуждению [`ValueError`](https://python-all.ru/3.5/library/exceptions.html#ValueError) при возникновении ошибки кодирования.124125*buffering* имеет то же значение, что и для встроенной функции [`open()`](https://python-all.ru/3.5/library/functions.html#open). По умолчанию используется построчная буферизация.126127#### `codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')`128129Возвращает экземпляр [`StreamRecoder`](https://python-all.ru/3.5/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.5/library/exceptions.html#ValueError) в случае ошибки кодирования.136137#### `codecs.iterencode(iterator, encoding, errors='strict', **kwargs)`138139Использует инкрементальный кодировщик для итеративного кодирования входных данных, предоставляемых *iterator*. Эта функция является [генератором](https://python-all.ru/3.5/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному кодировщику.140141Эта функция требует, чтобы кодек принимал текстовые объекты [`str`](https://python-all.ru/3.5/library/stdtypes.html#str) для кодирования. Поэтому она не поддерживает кодировщики типа «байты-в-байты», такие как `base64_codec`.142143#### `codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)`144145Использует инкрементальный декодировщик для итеративного декодирования входных данных, предоставляемых *iterator*. Эта функция является [генератором](https://python-all.ru/3.5/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному декодировщику.146147Эта функция требует, чтобы кодек принимал объекты [`bytes`](https://python-all.ru/3.5/library/functions.html#bytes) для декодирования. Поэтому она не поддерживает кодировщики типа «текст-в-текст», такие как `rot_13`, хотя `rot_13` может использоваться аналогично с [`iterencode()`](https://python-all.ru/3.5/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.5/library/codecs.html#codecs.BOM_UTF16) это либо [`BOM_UTF16_BE`](https://python-all.ru/3.5/library/codecs.html#codecs.BOM_UTF16_BE), либо [`BOM_UTF16_LE`](https://python-all.ru/3.5/library/codecs.html#codecs.BOM_UTF16_LE) в зависимости от нативного порядка байтов платформы; [`BOM`](https://python-all.ru/3.5/library/codecs.html#codecs.BOM) – псевдоним [`BOM_UTF16`](https://python-all.ru/3.5/library/codecs.html#codecs.BOM_UTF16), [`BOM_LE`](https://python-all.ru/3.5/library/codecs.html#codecs.BOM_LE) – [`BOM_UTF16_LE`](https://python-all.ru/3.5/library/codecs.html#codecs.BOM_UTF16_LE), [`BOM_BE`](https://python-all.ru/3.5/library/codecs.html#codecs.BOM_BE) – [`BOM_UTF16_BE`](https://python-all.ru/3.5/library/codecs.html#codecs.BOM_UTF16_BE). Остальные представляют BOM в кодировках UTF-8 и UTF-32.172173## 7.2.1. Базовые классы кодеков174175Модуль [`codecs`](https://python-all.ru/3.5/library/codecs.html#module-codecs) определяет набор базовых классов, которые задают интерфейсы для работы с объектами кодеков, а также могут использоваться как основа для реализации пользовательских кодеков.176177Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в Python: статический кодировщик, статический декодер, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно используют статический кодировщик/декодер для реализации файловых протоколов. Разработчикам кодеков также необходимо определить, как кодек будет обрабатывать ошибки кодирования и декодирования.178179### 7.2.1.1. Обработчики ошибок180181Для упрощения и стандартизации обработки ошибок кодеки могут реализовывать различные схемы обработки ошибок, принимая строковый аргумент *errors*. Следующие строковые значения определены и реализованы всеми стандартными кодеками Python:182183| Значение | Значение |184| --- | --- |185| `'strict'` | Возбуждается [`UnicodeError`](https://python-all.ru/3.5/library/exceptions.html#UnicodeError) (или подкласс); это поведение по умолчанию. Реализовано в [`strict_errors()`](https://python-all.ru/3.5/library/codecs.html#codecs.strict_errors). |186| `'ignore'` | Игнорировать поврежденные данные и продолжить без дополнительных уведомлений. Реализовано в [`ignore_errors()`](https://python-all.ru/3.5/library/codecs.html#codecs.ignore_errors). |187188Следующие обработчики ошибок применимы только к [текстовым кодировкам](https://python-all.ru/3.5/glossary.html#term-text-encoding):189190| Значение | Значение |191| --- | --- |192| `'replace'` | Замена подходящим замещающим символом; Python использует официальный `U+FFFD` замещающий символ для встроенных кодеков при декодировании, и «?» при кодировании. Реализовано в [`replace_errors()`](https://python-all.ru/3.5/library/codecs.html#codecs.replace_errors). |193| `'xmlcharrefreplace'` | Замена подходящей ссылкой на символ XML (только для кодирования). Реализовано в [`xmlcharrefreplace_errors()`](https://python-all.ru/3.5/library/codecs.html#codecs.xmlcharrefreplace_errors). |194| `'backslashreplace'` | Заменяет escape-последовательностями с обратной косой чертой. Реализовано в [`backslashreplace_errors()`](https://python-all.ru/3.5/library/codecs.html#codecs.backslashreplace_errors). |195| `'namereplace'` | Замена escape-последовательностями `\N{...}` (только для кодирования). Реализовано в [`namereplace_errors()`](https://python-all.ru/3.5/library/codecs.html#codecs.namereplace_errors). |196| `'surrogateescape'` | При декодировании заменять байт на отдельный суррогатный код в диапазоне от `U+DC80` до `U+DCFF`. Затем этот код будет преобразован обратно в тот же байт, когда используется обработчик ошибок `'surrogateescape'` при кодировании данных. (Подробнее см. [**PEP 383**](https://python-all.ru/3.5/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.5/library/exceptions.html#UnicodeEncodeError), который содержит информацию о местоположении ошибки. Обработчик ошибок должен либо возбудить это исключение (или другое), либо вернуть кортеж с заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Замена может быть либо [`str`](https://python-all.ru/3.5/library/stdtypes.html#str), либо [`bytes`](https://python-all.ru/3.5/library/functions.html#bytes). Если замена – байты, кодировщик просто скопирует их в выходной буфер. Если замена – строка, кодировщик закодирует замену. Кодирование продолжается с исходных входных данных на указанной позиции. Отрицательные значения позиции рассматриваются как относительные от конца входной строки. Если результирующая позиция выходит за границы, возбуждается [`IndexError`](https://python-all.ru/3.5/library/exceptions.html#IndexError).219220Декодирование и трансляция работают аналогично, за исключением того, что обработчику передаётся [`UnicodeDecodeError`](https://python-all.ru/3.5/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.5/library/exceptions.html#UnicodeTranslateError), а замена от обработчика ошибок помещается в выходные данные напрямую.221222Ранее зарегистрированные обработчики ошибок (включая стандартные) можно найти по имени:223224#### `codecs.lookup_error(name)`225226Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.227228Выбрасывает [`LookupError`](https://python-all.ru/3.5/library/exceptions.html#LookupError), если обработчик не найден.229230Следующие стандартные обработчики ошибок также доступны как функции уровня модуля:231232#### `codecs.strict_errors(exception)`233234Реализует обработку ошибок `'strict'`: каждая ошибка кодирования или декодирования вызывает исключение [`UnicodeError`](https://python-all.ru/3.5/library/exceptions.html#UnicodeError).235236#### `codecs.replace_errors(exception)`237238Реализует обработку ошибок `'replace'` (только для [текстовых кодировок](https://python-all.ru/3.5/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.5/glossary.html#term-text-encoding)): некодируемый символ заменяется соответствующей символьной ссылкой XML.247248#### `codecs.backslashreplace_errors(exception)`249250Реализует обработку ошибок `'backslashreplace'` (только для [текстовых кодировок](https://python-all.ru/3.5/glossary.html#term-text-encoding)): повреждённые данные заменяются управляющей последовательностью с обратной косой чертой.251252#### `codecs.namereplace_errors(exception)`253254Реализует обработку ошибок `'namereplace'` (только для кодирования с помощью [текстовых кодировок](https://python-all.ru/3.5/glossary.html#term-text-encoding)): некодируемый символ заменяется управляющей последовательностью `\N{...}`.255256Новое в версии 3.5.257258### 7.2.1.2. Кодирование и декодирование без состояния259260Базовый класс `Codec` определяет эти методы, которые также задают интерфейсы функций кодировщика и декодировщика без сохранения состояния:261262#### `Codec.encode(input[, errors])`263264Кодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Например, [текстовая кодировка](https://python-all.ru/3.5/glossary.html#term-text-encoding) преобразует строковый объект в объект bytes, используя определённую кодировку набора символов (например, `cp1252` или `iso-8859-1`).265266Аргумент *errors* задаёт применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.267268Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter) для кодеков, которым необходимо сохранять состояние для эффективного кодирования.269270Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.271272#### `Codec.decode(input[, errors])`273274Декодирует объект *input* и возвращает кортеж (объект вывода, длина потреблённых данных). Например, для [текстовой кодировки](https://python-all.ru/3.5/glossary.html#term-text-encoding) декодирование преобразует объект bytes, закодированный с использованием определённой кодировки набора символов, в объект строки.275276Для текстовых кодировок и кодеков bytes-to-bytes *input* должен быть объектом bytes или объектом, предоставляющим интерфейс буфера только для чтения – например, буферные объекты и файлы, отображаемые в память.277278Аргумент *errors* задаёт применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.279280Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader) для кодеков, которым необходимо сохранять состояние для эффективного декодирования.281282Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.283284### 7.2.1.3. Инкрементальное кодирование и декодирование285286Классы [`IncrementalEncoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalDecoder) предоставляют базовый интерфейс для инкрементального кодирования и декодирования. Кодирование/декодирование входных данных выполняется не одним вызовом функции кодировщика/декодировщика без состояния, а несколькими вызовами метода [`encode()`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalDecoder.decode) инкрементального кодировщика/декодировщика. Инкрементальный кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.287288Объединённый вывод вызовов метода [`encode()`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalDecoder.decode) совпадает с тем, что получилось бы, если бы все отдельные входные данные были объединены в один, и этот вход был закодирован/декодирован кодировщиком/декодировщиком без состояния.289290#### 7.2.1.3.1. Объекты IncrementalEncoder291292Класс [`IncrementalEncoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный кодировщик для совместимости с реестром кодеков Python.293294#### `class codecs.IncrementalEncoder(errors='strict')`295296Конструктор экземпляра [`IncrementalEncoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalEncoder).297298Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.299300Декодер [`IncrementalEncoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalEncoder) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Список возможных значений приведён в разделе [Обработчики ошибок](https://python-all.ru/3.5/library/codecs.html#error-handlers).301302Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalEncoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalEncoder).303304#### `encode(object[, final])`305306Кодирует *object* (с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов [`encode()`](https://python-all.ru/3.5/library/codecs.html#codecs.encode), *final* должен быть истинным (по умолчанию – ложь).307308#### `reset()`309310Сбрасывает кодировщик в исходное состояние. Выходные данные отбрасываются: при необходимости вызовите `.encode(object, final=True)`, передав пустую строку байтов или текстовую строку, чтобы сбросить кодировщик и получить выходные данные.311312#### `IncrementalEncoder.getstate()`313314Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что `0` – это наиболее распространённое состояние. (Состояния, которые сложнее целых чисел, можно преобразовать в целое число, замаршализовав/запиклив состояние и кодируя байты результирующей строки в целое число).315316#### `IncrementalEncoder.setstate(state)`317318Устанавливает состояние кодировщика в *state*. *state* должно быть состоянием кодировщика, возвращённым [`getstate()`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalEncoder.getstate).319320#### 7.2.1.3.2. Объекты IncrementalDecoder321322Класс [`IncrementalDecoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный декодер для совместимости с реестром кодеков Python.323324#### `class codecs.IncrementalDecoder(errors='strict')`325326Конструктор экземпляра [`IncrementalDecoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalDecoder).327328Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.329330Декодер [`IncrementalDecoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalDecoder) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Список возможных значений приведён в разделе [Обработчики ошибок](https://python-all.ru/3.5/library/codecs.html#error-handlers).331332Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalDecoder`](https://python-all.ru/3.5/library/codecs.html#codecs.IncrementalDecoder).333334#### `decode(object[, final])`335336Декодирует *object* (с учётом текущего состояния декодера) и возвращает результирующий декодированный объект. Если это последний вызов [`decode()`](https://python-all.ru/3.5/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.5/library/codecs.html#codecs.IncrementalDecoder.getstate).349350### 7.2.1.4. Потоковое кодирование и декодирование351352Классы [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader) предоставляют универсальные рабочие интерфейсы, которые можно использовать для очень простой реализации новых подмодулей кодирования. Пример см. в `encodings.utf_8`.353354#### 7.2.1.4.1. Объекты StreamWriter355356Класс [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый писатель должен реализовать для совместимости с реестром кодеков Python.357358#### `class codecs.StreamWriter(stream, errors='strict')`359360Конструктор экземпляра [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter).361362Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.363364Аргумент *поток данных* должен быть файлоподобным объектом, открытым для записи текстовых или двоичных данных, в зависимости от конкретного кодека.365366Объект [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. См. [Обработчики ошибок](https://python-all.ru/3.5/library/codecs.html#error-handlers) для получения списка стандартных обработчиков ошибок, которые может поддерживать базовый потоковый кодек.367368Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter).369370#### `write(object)`371372Записывает в поток закодированное содержимое объекта.373374#### `writelines(list)`375376Записывает объединённый список строк в поток данных (возможно, повторно используя метод [`write()`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter.write)). Стандартные кодеки «байты в байты» не поддерживают этот метод.377378#### `reset()`379380Сбрасывает и переустанавливает буферы кодека, используемые для сохранения состояния.381382Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.383384В дополнение к приведённым выше методам, [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.385386#### 7.2.1.4.2. Объекты StreamReader387388Класс [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый читатель должен реализовать для совместимости с реестром кодеков Python.389390#### `class codecs.StreamReader(stream, errors='strict')`391392Конструктор экземпляра [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader).393394Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.395396Аргумент *поток данных* должен быть файлоподобным объектом, открытым для чтения текстовых или двоичных данных, в зависимости от конкретного кодека.397398Объект [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. См. [Обработчики ошибок](https://python-all.ru/3.5/library/codecs.html#error-handlers) для получения списка стандартных обработчиков ошибок, которые может поддерживать базовый потоковый кодек.399400Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader).401402Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.5/library/codecs.html#codecs.register_error).403404#### `read([size[, chars[, firstline]]])`405406Декодирует данные из потока и возвращает результирующий объект.407408Аргумент *chars* указывает количество декодированных кодовых точек или байтов для возврата. Метод [`read()`](https://python-all.ru/3.5/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.5/library/codecs.html#codecs.StreamReader.read) потока данных.421422Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.423424#### `readlines([sizehint[, keepends]])`425426Читает все строки из входного потока данных и возвращает их в виде списка строк.427428Окончания строк реализуются с помощью метода декодера кодека и включаются в элементы списка, если *keepends* имеет значение true.429430*sizehint*, если задан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader.read) потока данных.431432#### `reset()`433434Сбрасывает буферы кодека, используемые для сохранения состояния.435436Обратите внимание, что никакое перемещение позиции в потоке не должно выполняться. Этот метод предназначен в первую очередь для восстановления после ошибок декодирования.437438В дополнение к приведённым выше методам, [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.439440#### 7.2.1.4.3. Объекты StreamReaderWriter441442[`StreamReaderWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReaderWriter) – это удобный класс, который позволяет оборачивать потоки данных, работающие как в режиме чтения, так и в режиме записи.443444Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.5/library/codecs.html#codecs.lookup).445446#### `class codecs.StreamReaderWriter(stream, Reader, Writer, errors)`447448Создаёт экземпляр [`StreamReaderWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReaderWriter). *поток данных* должен быть файлоподобным объектом. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими интерфейсы [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter) соответственно. Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.449450Экземпляры [`StreamReaderWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReaderWriter) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.451452#### 7.2.1.4.4. Объекты StreamRecoder453454[`StreamRecoder`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamRecoder) преобразует данные из одной кодировки в другую, что иногда полезно при работе с различными кодировочными средами.455456Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.5/library/codecs.html#codecs.lookup).457458#### `class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors)`459460Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/3.5/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.5/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter) соответственно.467468Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.469470Экземпляры [`StreamRecoder`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamRecoder) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.5/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.471472## 7.2.2. Кодировки и Unicode473474Строки хранятся внутри как последовательности кодовых точек в диапазоне `0x0`–`0x10FFFF`. (См. [**PEP 393**](https://python-all.ru/3.5/library/codecs.html) для получения более подробной информации о реализации.) Как только строковый объект используется за пределами ЦП и памяти, порядок байтов (endianness) и способ хранения этих массивов в виде байтов становятся важными. Как и в случае с другими кодеками, сериализация строки в последовательность байтов известна как *кодирование*, а воссоздание строки из последовательности байтов – как *декодирование*. Существует множество различных текстовых кодеков сериализации, которые в совокупности называются [текстовыми кодировками](https://python-all.ru/3.5/glossary.html#term-text-encoding).475476Простейшая текстовая кодировка (называемая `'latin-1'` или `'iso-8859-1'`) отображает кодовые точки 0–255 на байты `0x0`–`0xff`, что означает, что строковый объект, содержащий кодовые точки больше `U+00FF`, не может быть закодирован этим кодеком. Попытка сделать это вызовет исключение [`UnicodeEncodeError`](https://python-all.ru/3.5/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## 7.2.3. Стандартные кодировки506507Python поставляется с рядом встроенных кодеков, реализованных либо как функции на C либо с использованием словарей в качестве таблиц сопоставления. В следующей таблице перечислены кодеки по имени, а также некоторые распространённые псевдонимы и языки, для которых вероятно используется данная кодировка. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что альтернативные написания, различающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами; поэтому, например, `'utf-8'` является допустимым псевдонимом для кодека `'utf_8'`.508509**Особенность реализации CPython:** Некоторые распространённые кодировки могут обходить механизм поиска codecs для повышения производительности. Эти возможности оптимизации распознаются CPython только для ограниченного набора псевдонимов: utf-8, utf8, latin-1, latin1, iso-8859-1, mbcs (только Windows), ascii, utf-16 и utf-32. Использование альтернативных вариантов написания этих кодировок может привести к снижению скорости выполнения.510511Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:512513- набор символов ISO 8859514- кодовая страница Microsoft Windows, которая обычно происходит из набора 8859, но заменяет управляющие символы дополнительными графическими символами515- кодовая страница IBM EBCDIC516- кодовая страница IBM PC, совместимая с ASCII517518| Кодек | Псевдонимы | Языки |519| --- | --- | --- |520| ascii | 646, us-ascii | Английский |521| big5 | big5-tw, csbig5 | Китайский традиционный |522| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |523| cp037 | IBM037, IBM039 | Английский |524| cp273 | 273, IBM273, csIBM273 | Немецкий Новое в версии 3.4. |525| cp424 | EBCDIC-CP-HE, IBM424 | Иврит |526| cp437 | 437, IBM437 | Английский |527| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Западная Европа |528| cp720 |  | Арабский |529| cp737 |  | Греческий |530| cp775 | IBM775 | Балтийские языки |531| cp850 | 850, IBM850 | Западная Европа |532| cp852 | 852, IBM852 | Центральная и Восточная Европа |533| cp855 | 855, IBM855 | болгарский, белорусский, македонский, русский, сербский |534| cp856 |  | Иврит |535| cp857 | 857, IBM857 | Турецкий |536| cp858 | 858, IBM858 | Западная Европа |537| cp860 | 860, IBM860 | португальский |538| cp861 | 861, CP-IS, IBM861 | Исландский |539| cp862 | 862, IBM862 | Иврит |540| cp863 | 863, IBM863 | канадский |541| cp864 | IBM864 | Арабский |542| cp865 | 865, IBM865 | датский, норвежский |543| cp866 | 866, IBM866 | Русский |544| cp869 | 869, CP-GR, IBM869 | Греческий |545| cp874 |  | Тайский |546| cp875 |  | Греческий |547| cp932 | 932, ms932, mskanji, ms-kanji | Японский |548| cp949 | 949, ms949, uhc | Корейский |549| cp950 | 950, ms950 | Китайский традиционный |550| cp1006 |  | Урду |551| cp1026 | ibm1026 | Турецкий |552| cp1125 | 1125, ibm1125, cp866u, ruscii | Украинский Новое в версии 3.4. |553| cp1140 | ibm1140 | Западная Европа |554| cp1250 | windows-1250 | Центральная и Восточная Европа |555| cp1251 | windows-1251 | болгарский, белорусский, македонский, русский, сербский |556| cp1252 | windows-1252 | Западная Европа |557| cp1253 | windows-1253 | Греческий |558| cp1254 | windows-1254 | Турецкий |559| cp1255 | windows-1255 | Иврит |560| cp1256 | windows-1256 | Арабский |561| cp1257 | windows-1257 | Балтийские языки |562| cp1258 | windows-1258 | вьетнамский |563| cp65001 |  | Только для Windows: Windows UTF-8 (`CP_UTF8`) Новое в версии 3.3. |564| euc\_jp | eucjp, ujis, u-jis | Японский |565| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |566| euc\_jisx0213 | eucjisx0213 | Японский |567| euc\_kr | euckr, корейский, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |568| gb2312 | chinese, csiso58gb231280, euc- cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso- ir-58 | Упрощённый китайский |569| gbk | 936, cp936, ms936 | Унифицированный китайский |570| gb18030 | gb18030-2000 | Унифицированный китайский |571| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |572| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |573| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |574| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |575| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |576| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |577| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |578| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |579| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |580| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |581| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |582| iso8859\_4 | iso-8859-4, latin4, L4 | Балтийские языки |583| iso8859\_5 | iso-8859-5, кириллица | болгарский, белорусский, македонский, русский, сербский |584| iso8859\_6 | iso-8859-6, арабский | Арабский |585| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |586| iso8859\_8 | iso-8859-8, иврит | Иврит |587| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |588| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |589| iso8859\_11 | iso-8859-11, тайская | Тайские языки |590| iso8859\_13 | iso-8859-13, latin7, L7 | Балтийские языки |591| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |592| iso8859\_15 | iso-8859-15, latin9, L9 | Западная Европа |593| iso8859\_16 | iso-8859-16, latin10, L10 | Юго-Восточная Европа |594| johab | cp1361, ms1361 | Корейский |595| koi8\_r |  | Русский |596| koi8\_t |  | Таджикский Новое в версии 3.5. |597| koi8\_u |  | Украинский |598| kz1048 | kz\_1048, strk1048\_2002, rk1048 | Казахский Новое в версии 3.5. |599| mac\_cyrillic | maccyrillic | болгарский, белорусский, македонский, русский, сербский |600| mac\_greek | macgreek | Греческий |601| mac\_iceland | maciceland | Исландский |602| mac\_latin2 | maclatin2, maccentraleurope | Центральная и Восточная Европа |603| mac\_roman | macroman, macintosh | Западная Европа |604| mac\_turkish | macturkish | Турецкий |605| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |606| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |607| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |608| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |609| utf\_32 | U32, utf32 | все языки |610| utf\_32\_be | UTF-32BE | все языки |611| utf\_32\_le | UTF-32LE | все языки |612| utf\_16 | U16, utf16 | все языки |613| utf\_16\_be | UTF-16BE | все языки |614| utf\_16\_le | UTF-16LE | все языки |615| utf\_7 | U7, unicode-1-1-utf-7 | все языки |616| utf\_8 | U8, UTF, utf8 | все языки |617| utf\_8\_sig |  | все языки |618619Изменено в версии 3.4: Кодировщики utf-16\* и utf-32\* больше не позволяют кодировать суррогатные кодовые точки (`U+D800`–`U+DFFF`). Декодировщики utf-32\* больше не декодируют последовательности байтов, соответствующие суррогатным кодовым точкам.620621## 7.2.4. Кодировки, специфичные для Python622623Некоторые предопределенные кодеки специфичны для Python, поэтому их имена кодеков не имеют смысла за пределами Python. Они перечислены в таблицах ниже по типам ожидаемых входных и выходных данных (обратите внимание, что хотя текстовые кодировки являются наиболее распространенным вариантом использования кодеков, базовая инфраструктура кодеков поддерживает произвольные преобразования данных, а не только текстовые кодировки). Для асимметричных кодеков указанное назначение описывает направление кодирования.624625### 7.2.4.1. Текстовые кодировки626627Следующие кодеки обеспечивают кодирование из [`str`](https://python-all.ru/3.5/library/stdtypes.html#str) в [`bytes`](https://python-all.ru/3.5/library/functions.html#bytes) и декодирование из [байтоподобного объекта](https://python-all.ru/3.5/glossary.html#term-bytes-like-object) в [`str`](https://python-all.ru/3.5/library/stdtypes.html#str), аналогично текстовым кодировкам Unicode.628629| Кодек | Псевдонимы | Назначение |630| --- | --- | --- |631| idna |  | Реализует [**RFC 3490**](https://python-all.ru/3.5/library/codecs.html), см. также [`encodings.idna`](https://python-all.ru/3.5/library/codecs.html#module-encodings.idna). Поддерживается только `errors='strict'`. |632| mbcs | dbcs | Только Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |633| palmos |  | Кодировка PalmOS 3.5 |634| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/3.5/library/codecs.html). Кодеки с состоянием не поддерживаются. |635| raw\_unicode\_escape |  | Кодировка Latin-1 с `\uXXXX` и `\UXXXXXXXX` для остальных кодовых точек. Существующие обратные слеши никак не экранируются. Используется в протоколе pickle языка Python. |636| undefined |  | Вызывает исключение для всех преобразований, даже для пустых строк. Обработчик ошибок игнорируется. |637| unicode\_escape |  | Кодировка, подходящая для содержимого строкового литерала Unicode в исходном коде Python в кодировке ASCII, за исключением того, что кавычки не экранируются. Декодирует из исходного кода Latin-1. Имейте в виду, что исходный код Python на самом деле по умолчанию использует UTF-8. |638| unicode\_internal |  | Возвращает внутреннее представление операнда. Кодеки с состоянием не поддерживаются. Устарело с версии 3.3: Это представление устарело с появлением [**PEP 393**](https://python-all.ru/3.5/library/codecs.html). |639640### 7.2.4.2. Двоичные преобразования641642Следующие кодеки обеспечивают двоичные преобразования: отображения [байтово-подобный объект](https://python-all.ru/3.5/glossary.html#term-bytes-like-object) в [`bytes`](https://python-all.ru/3.5/library/functions.html#bytes). Они не поддерживаются [`bytes.decode()`](https://python-all.ru/3.5/library/stdtypes.html#bytes.decode) (который выдает только [`str`](https://python-all.ru/3.5/library/stdtypes.html#str)).643644| Кодек | Псевдонимы | Назначение | Кодировщик / декодировщик |645| --- | --- | --- | --- |646| base64\_codec [\[1\]](https://python-all.ru/3.5/library/codecs.html#b64) | base64, base\_64 | Преобразует операнд в многострочный MIME base64 (результат всегда включает завершающий `'\n'`). Изменено в версии 3.4: принимает любой [объект, подобный байтовой строке](https://python-all.ru/3.5/glossary.html#term-bytes-like-object) в качестве входных данных для кодирования и декодирования | [`base64.encodebytes()`](https://python-all.ru/3.5/library/base64.html#base64.encodebytes) / [`base64.decodebytes()`](https://python-all.ru/3.5/library/base64.html#base64.decodebytes) |647| bz2\_codec | bz2 | Сжимает операнд с помощью bz2 | [`bz2.compress()`](https://python-all.ru/3.5/library/bz2.html#bz2.compress) / [`bz2.decompress()`](https://python-all.ru/3.5/library/bz2.html#bz2.decompress) |648| hex\_codec | hex | Преобразует операнд в шестнадцатеричное представление, по два разряда на байт | [`binascii.b2a_hex()`](https://python-all.ru/3.5/library/binascii.html#binascii.b2a_hex) / [`binascii.a2b_hex()`](https://python-all.ru/3.5/library/binascii.html#binascii.a2b_hex) |649| quopri\_codec | quopri, quotedprintable, quoted\_printable | Преобразует операнд в MIME quoted-printable | [`quopri.encode()`](https://python-all.ru/3.5/library/quopri.html#quopri.encode) с `quotetabs=True` / [`quopri.decode()`](https://python-all.ru/3.5/library/quopri.html#quopri.decode) |650| uu\_codec | uu | Преобразует операнд с помощью uuencode | [`uu.encode()`](https://python-all.ru/3.5/library/uu.html#uu.encode) / [`uu.decode()`](https://python-all.ru/3.5/library/uu.html#uu.decode) |651| zlib\_codec | zip, zlib | Сжимает операнд с помощью gzip | [`zlib.compress()`](https://python-all.ru/3.5/library/zlib.html#zlib.compress) / [`zlib.decompress()`](https://python-all.ru/3.5/library/zlib.html#zlib.decompress) |652653| [\[1\]](https://python-all.ru/3.5/library/codecs.html#id5) | В дополнение к [байтоподобным объектам](https://python-all.ru/3.5/glossary.html#term-bytes-like-object), `'base64_codec'` также принимает экземпляры [`str`](https://python-all.ru/3.5/library/stdtypes.html#str) только с ASCII для декодирования |654| --- | --- |655656Новое в версии 3.2: Восстановление бинарных преобразований.657658Изменено в версии 3.4: Восстановление псевдонимов для двоичных преобразований.659660### 7.2.4.3. Текстовые преобразования661662Следующий кодек предоставляет текстовое преобразование: отображение [`str`](https://python-all.ru/3.5/library/stdtypes.html#str) в [`str`](https://python-all.ru/3.5/library/stdtypes.html#str). Он не поддерживается [`str.encode()`](https://python-all.ru/3.5/library/stdtypes.html#str.encode) (который создаёт только вывод [`bytes`](https://python-all.ru/3.5/library/functions.html#bytes)).663664| Кодек | Псевдонимы | Назначение |665| --- | --- | --- |666| rot\_13 | rot13 | Возвращает шифрование Цезаря операнда |667668Новое в версии 3.2: Восстановление `rot_13` текстового преобразования.669670Изменено в версии 3.4: Восстановление псевдонима `rot13`.671672## 7.2.5. [`encodings.idna`](https://python-all.ru/3.5/library/codecs.html#module-encodings.idna) – Интернационализированные доменные имена в приложениях673674Этот модуль реализует [**RFC 3490**](https://python-all.ru/3.5/library/codecs.html) (Internationalized Domain Names in Applications) и [**RFC 3492**](https://python-all.ru/3.5/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/3.5/library/stringprep.html#module-stringprep).675676Эти RFC совместно определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (например, `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, такую как `www.xn--alliancefranaise-npb.nu`). Форма ACE доменного имени затем используется во всех местах, где протокол не допускает произвольных символов, таких как DNS-запросы, поля HTTP *Host* и так далее. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки доменов Unicode в IDNA при передаче по сети и преобразовывать обратно метки ACE в Unicode перед представлением их пользователю.677678Python поддерживает это преобразование несколькими способами: кодек `idna` выполняет преобразование между Unicode и ACE, разбивая входную строку на метки на основе разделителей, определённых в [разделе 3.1](https://python-all.ru/3.5/library/codecs.html) (1) документа [**RFC 3490**](https://python-all.ru/3.5/library/codecs.html), и преобразуя каждую метку в ACE по необходимости; и наоборот, разбивает входную байтовую строку на метки на основе разделителя `.` и преобразует найденные метки ACE в Unicode. Кроме того, модуль [`socket`](https://python-all.ru/3.5/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно беспокоиться о преобразовании имён хостов при передаче их в модуль socket. Более того, модули, которые принимают имена хостов в качестве параметров функций, такие как [`http.client`](https://python-all.ru/3.5/library/http.client.html#module-http.client) и [`ftplib`](https://python-all.ru/3.5/library/ftplib.html#module-ftplib), поддерживают Unicode-имена хостов (при этом [`http.client`](https://python-all.ru/3.5/library/http.client.html#module-http.client) также прозрачно отправляет IDNA-имя хоста в поле *Host*, если оно вообще отправляет это поле).679680При получении имён хостов из сети (например, при обратном поиске имени) автоматическое преобразование в Unicode не выполняется: приложения, желающие отобразить такие имена хостов пользователю, должны декодировать их в Unicode.681682Модуль [`encodings.idna`](https://python-all.ru/3.5/library/codecs.html#module-encodings.idna) также реализует процедуру nameprep, которая выполняет определённые нормализации имён хостов для достижения нечувствительности к регистру интернационализированных доменных имён и унификации похожих символов. Функции nameprep можно использовать напрямую, если необходимо.683684#### `encodings.idna.nameprep(label)`685686Возвращает версию *label* после обработки nameprep. В текущей реализации предполагаются строки запроса, поэтому `AllowUnassigned` имеет значение истина.687688#### `encodings.idna.ToASCII(label)`689690Преобразует метку в ASCII, как указано в [**RFC 3490**](https://python-all.ru/3.5/library/codecs.html). Предполагается, что `UseSTD3ASCIIRules` имеет значение false.691692#### `encodings.idna.ToUnicode(label)`693694Преобразует метку в Unicode, как указано в [**RFC 3490**](https://python-all.ru/3.5/library/codecs.html).695696## 7.2.6. [`encodings.mbcs`](https://python-all.ru/3.5/library/codecs.html#module-encodings.mbcs) – Кодовая страница Windows ANSI697698Кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP).699700Доступность: только Windows.701702Изменено в версии 3.3: Поддержка любого обработчика ошибок.703704Изменено в версии 3.2: До версии 3.2 аргумент *errors* игнорировался; `'replace'` всегда использовался для кодирования, а `'ignore'` для декодирования.705706## 7.2.7. [`encodings.utf_8_sig`](https://python-all.ru/3.5/library/codecs.html#module-encodings.utf_8_sig) – Кодек UTF-8 с сигнатурой BOM707708Этот модуль реализует вариант кодека UTF-8: при кодировании префикс UTF-8 BOM будет добавлен перед байтами, закодированными в UTF-8. Для кодировщика с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный UTF-8 BOM в начале данных будет пропущен.709