`codecs.md`

691 строк · 85.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.3/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.3/library/codecs.html#module-codecs) – Реестр кодеков и базовые классы89Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодеков и обработки ошибок.1011Он определяет следующие функции:1213#### `codecs.encode(obj, encoding='utf-8', errors='strict')`1415Кодирует *obj* с помощью кодека, зарегистрированного для *encoding*.1617Параметр *Errors* может быть задан для установки желаемой схемы обработки ошибок. Обработчик ошибок по умолчанию – `strict`, что означает, что ошибки кодирования вызывают [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError) (или более специфичный подкласс кодеков, такой как [`UnicodeEncodeError`](https://python-all.ru/3.3/library/exceptions.html#UnicodeEncodeError)). Обратитесь к [*Базовым классам кодеков*](https://python-all.ru/3.3/library/codecs.html#codec-base-classes) за дополнительной информацией об обработке ошибок кодеков.1819#### `codecs.decode(obj, encoding='utf-8', errors='strict')`2021Декодирует *obj* с помощью кодека, зарегистрированного для *encoding*.2223Параметр *Errors* может быть задан для установки желаемой схемы обработки ошибок. Обработчик ошибок по умолчанию – `strict`, что означает, что ошибки декодирования вызывают [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError) (или более специфичный подкласс кодеков, такой как [`UnicodeDecodeError`](https://python-all.ru/3.3/library/exceptions.html#UnicodeDecodeError)). Обратитесь к [*Базовым классам кодеков*](https://python-all.ru/3.3/library/codecs.html#codec-base-classes) за дополнительной информацией об обработке ошибок кодеков.2425#### `codecs.register(search_function)`2627Регистрирует функцию поиска кодеков. Функции поиска должны принимать один аргумент – имя кодировки строчными буквами – и возвращать объект `CodecInfo` со следующими атрибутами:2829- `name` Имя кодировки;30- `encode` Функция кодирования без сохранения состояния;31- `decode` Функция декодирования без сохранения состояния;32- `incrementalencoder` Класс инкрементального кодировщика или фабричная функция;33- `incrementaldecoder` Класс инкрементального декодировщика или фабричная функция;34- `streamwriter` Класс потокового писателя или фабричная функция;35- `streamreader` Класс потокового читателя или фабричная функция.3637Различные функции или классы принимают следующие аргументы:3839*encode* и *decode*: это должны быть функции или методы с тем же интерфейсом, что и методы [`encode()`](https://python-all.ru/3.3/library/codecs.html#codecs.Codec.encode)/[`decode()`](https://python-all.ru/3.3/library/codecs.html#codecs.Codec.decode) экземпляров Codec (см. [*Интерфейс Codec*](https://python-all.ru/3.3/library/codecs.html#codec-objects)). Ожидается, что функции/методы работают в режиме без сохранения состояния.4041*incrementalencoder* и *incrementaldecoder*: это должны быть фабричные функции, предоставляющие следующий интерфейс:4243> `factory(errors='strict')`4445Фабричные функции должны возвращать объекты, предоставляющие интерфейсы, определённые базовыми классами [`IncrementalEncoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalDecoder), соответственно. Инкрементальные кодеки могут сохранять состояние.4647*streamreader* и *streamwriter*: это должны быть фабричные функции, предоставляющие следующий интерфейс:4849> `factory(stream, errors='strict')`5051Фабричные функции должны возвращать объекты, предоставляющие интерфейсы, определённые базовыми классами [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter), соответственно. Потоковые кодеки могут сохранять состояние.5253Возможные значения параметра errors:5455- `'strict'`: возбуждать исключение в случае ошибки кодирования56- `'replace'`: заменять повреждённые данные подходящим маркером замены, например `'?'` или `'\ufffd'`57- `'ignore'`: игнорировать повреждённые данные и продолжать без дополнительных уведомлений58- `'xmlcharrefreplace'`: заменять соответствующей символьной ссылкой XML (только для кодирования)59- `'backslashreplace'`: заменять escape-последовательностями с обратной косой чертой (только для кодирования)60- `'surrogateescape'`: при декодировании заменять кодовыми точками из частной области Unicode (Private Use Area) в диапазоне от U+DC80 до U+DCFF. Затем эти частные кодовые точки будут преобразованы обратно в те же байты при использовании обработчика ошибок `surrogateescape` при кодировании данных. (См. [**PEP 383**](https://python-all.ru/3.3/library/codecs.html).)6162а также любое другое имя обработчика ошибок, определённое через [`register_error()`](https://python-all.ru/3.3/library/codecs.html#codecs.register_error).6364Если функция поиска не может найти указанную кодировку, она должна вернуть `None`.6566#### `codecs.lookup(encoding)`6768Ищет информацию о кодеке в реестре кодеков Python и возвращает объект `CodecInfo`, как определено выше.6970Кодировки сначала ищутся в кеше реестра. Если не найдены, просматривается список зарегистрированных функций поиска. Если объект `CodecInfo` не найден, возбуждается [`LookupError`](https://python-all.ru/3.3/library/exceptions.html#LookupError). В противном случае объект `CodecInfo` сохраняется в кеш и возвращается вызывающему.7172Для упрощения доступа к различным кодекам модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/3.3/library/codecs.html#codecs.lookup) для поиска кодека:7374#### `codecs.getencoder(encoding)`7576Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.7778Вызывает [`LookupError`](https://python-all.ru/3.3/library/exceptions.html#LookupError), если кодировка не найдена.7980#### `codecs.getdecoder(encoding)`8182Находит кодек для указанной кодировки и возвращает его функцию-декодер.8384Вызывает [`LookupError`](https://python-all.ru/3.3/library/exceptions.html#LookupError), если кодировка не найдена.8586#### `codecs.getincrementalencoder(encoding)`8788Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.8990Вызывает [`LookupError`](https://python-all.ru/3.3/library/exceptions.html#LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный кодировщик.9192#### `codecs.getincrementaldecoder(encoding)`9394Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.9596Вызывает [`LookupError`](https://python-all.ru/3.3/library/exceptions.html#LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный декодировщик.9798#### `codecs.getreader(encoding)`99100Находит кодек для указанной кодировки и возвращает его класс StreamReader или фабричную функцию.101102Вызывает [`LookupError`](https://python-all.ru/3.3/library/exceptions.html#LookupError), если кодировка не найдена.103104#### `codecs.getwriter(encoding)`105106Находит кодек для указанной кодировки и возвращает его класс StreamWriter или фабричную функцию.107108Вызывает [`LookupError`](https://python-all.ru/3.3/library/exceptions.html#LookupError), если кодировка не найдена.109110#### `codecs.register_error(name, error_handler)`111112Регистрирует функцию обработки ошибок *error\_handler* под именем *name*. *error\_handler* будет вызываться при кодировании и декодировании в случае ошибки, когда *name* указан как параметр errors.113114При кодировании *error\_handler* будет вызван с экземпляром [`UnicodeEncodeError`](https://python-all.ru/3.3/library/exceptions.html#UnicodeEncodeError), который содержит информацию о месте ошибки. Обработчик ошибок должен либо возбудить это или другое исключение, либо вернуть кортеж с заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Замена может быть либо [`str`](https://python-all.ru/3.3/library/stdtypes.html#str), либо [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes). Если замена – bytes, кодировщик просто скопирует их в выходной буфер. Если замена – строка, кодировщик закодирует замену. Кодирование продолжается с исходных входных данных, начиная с указанной позиции. Отрицательные значения позиции рассматриваются как смещение от конца входной строки. Если результирующая позиция выходит за границы, будет возбуждено [`IndexError`](https://python-all.ru/3.3/library/exceptions.html#IndexError).115116Декодирование и трансляция работают аналогично, за исключением того, что обработчику будет передан [`UnicodeDecodeError`](https://python-all.ru/3.3/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.3/library/exceptions.html#UnicodeTranslateError), и что замена от обработчика ошибок будет помещена в вывод напрямую.117118#### `codecs.lookup_error(name)`119120Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.121122Возбуждает [`LookupError`](https://python-all.ru/3.3/library/exceptions.html#LookupError), если обработчик не найден.123124#### `codecs.strict_errors(exception)`125126Реализует обработку ошибок `strict`: каждая ошибка кодирования или декодирования возбуждает [`UnicodeError`](https://python-all.ru/3.3/library/exceptions.html#UnicodeError).127128#### `codecs.replace_errors(exception)`129130Реализует обработку ошибок `replace`: повреждённые данные заменяются подходящим замещающим символом, таким как `'?'` в байтовых строках и `'\ufffd'` в строках Unicode.131132#### `codecs.ignore_errors(exception)`133134Реализует обработку ошибок `ignore`: повреждённые данные игнорируются и кодирование или декодирование продолжается без дальнейших уведомлений.135136#### `codecs.xmlcharrefreplace_errors(exception)`137138Реализует обработку ошибок `xmlcharrefreplace` (только для кодирования): некодируемый символ заменяется соответствующей символьной ссылкой XML.139140#### `codecs.backslashreplace_errors(exception)`141142Реализует обработку ошибок `backslashreplace` (только для кодирования): некодируемый символ заменяется escape-последовательностью с обратной косой чертой.143144Для упрощения работы с закодированными файлами или потоками модуль также определяет следующие вспомогательные функции:145146#### `codecs.open(filename, mode[, encoding[, errors[, buffering]]])`147148Открывает закодированный файл, используя указанный *mode*, и возвращает обёрнутую версию, обеспечивающую прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, что означает открытие файла в режиме чтения.149150> **Примечание**151>152> Методы обёрнутой версии будут принимать и возвращать только строки. Аргументы типа bytes будут отклонены.153154> **Примечание**155>156> Файлы всегда открываются в двоичном режиме, даже если двоичный режим не был указан. Это сделано для предотвращения потери данных из-за кодировок, использующих 8-битные значения. Это означает, что автоматическое преобразование `b'\n'` не выполняется при чтении и записи.157158*encoding* задаёт кодировку, которая будет использоваться для файла.159160*errors* may be given to define the error handling. It defaults to `'strict'` which causes a [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError) to be raised in case an encoding error occurs.161162Параметр *buffering* имеет то же значение, что и для встроенной функции [`open()`](https://python-all.ru/3.3/library/functions.html#open). По умолчанию используется построчная буферизация.163164#### `codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')`165166Возвращает обёрнутую версию файла, которая обеспечивает прозрачное преобразование кодировки.167168Байты, записанные в обёрнутый файл, интерпретируются в соответствии с указанным *data\_encoding* и затем записываются в исходный файл как байты с использованием *file\_encoding*.169170Если *file\_encoding* не указан, по умолчанию используется *data\_encoding*.171172*errors* may be given to define the error handling. It defaults to `'strict'`, which causes [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError) to be raised in case an encoding error occurs.173174#### `codecs.iterencode(iterator, encoding, errors='strict', **kwargs)`175176Использует инкрементальный кодировщик для итеративного кодирования входных данных, предоставленных *iterator*. Эта функция является [*генератором*](https://python-all.ru/3.3/glossary.html#term-generator). *errors* (а также любые другие именованные аргументы) передаётся инкрементальному кодировщику.177178#### `codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)`179180Использует инкрементальный декодер для итеративного декодирования входных данных, предоставленных *iterator*. Эта функция является [*генератором*](https://python-all.ru/3.3/glossary.html#term-generator). Параметр *errors* (а также любые другие ключевые аргументы) передаётся инкрементальному декодеру.181182Модуль также предоставляет следующие константы, полезные для чтения и записи в платформенно-зависимые файлы:183184#### `codecs.BOM`185186#### `codecs.BOM_BE`187188#### `codecs.BOM_LE`189190#### `codecs.BOM_UTF8`191192#### `codecs.BOM_UTF16`193194#### `codecs.BOM_UTF16_BE`195196#### `codecs.BOM_UTF16_LE`197198#### `codecs.BOM_UTF32`199200#### `codecs.BOM_UTF32_BE`201202#### `codecs.BOM_UTF32_LE`203204Эти константы определяют различные кодировки метки порядка байтов Unicode (BOM), используемые в потоках данных UTF-16 и UTF-32 для указания порядка байтов, используемого в потоке или файле, а в UTF-8 – как подпись Unicode. [`BOM_UTF16`](https://python-all.ru/3.3/library/codecs.html#codecs.BOM_UTF16) – это либо [`BOM_UTF16_BE`](https://python-all.ru/3.3/library/codecs.html#codecs.BOM_UTF16_BE), либо [`BOM_UTF16_LE`](https://python-all.ru/3.3/library/codecs.html#codecs.BOM_UTF16_LE) в зависимости от родного порядка байтов платформы; [`BOM`](https://python-all.ru/3.3/library/codecs.html#codecs.BOM) является псевдонимом для [`BOM_UTF16`](https://python-all.ru/3.3/library/codecs.html#codecs.BOM_UTF16), [`BOM_LE`](https://python-all.ru/3.3/library/codecs.html#codecs.BOM_LE) – для [`BOM_UTF16_LE`](https://python-all.ru/3.3/library/codecs.html#codecs.BOM_UTF16_LE), а [`BOM_BE`](https://python-all.ru/3.3/library/codecs.html#codecs.BOM_BE) – для [`BOM_UTF16_BE`](https://python-all.ru/3.3/library/codecs.html#codecs.BOM_UTF16_BE). Остальные представляют BOM в кодировках UTF-8 и UTF-32.205206## 7.2.1. Базовые классы кодеков207208Модуль [`codecs`](https://python-all.ru/3.3/library/codecs.html#module-codecs) определяет набор базовых классов, которые задают интерфейс и также могут использоваться для простого написания собственных кодеков для использования в Python.209210Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в качестве кодека в Python: статический кодировщик без состояния, статический декодировщик без состояния, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно повторно используют статический кодировщик/декодировщик без состояния для реализации файловых протоколов.211212Класс `Codec` определяет интерфейс для кодировщиков/декодировщиков без состояния.213214Чтобы упростить и стандартизировать обработку ошибок, методы [`encode()`](https://python-all.ru/3.3/library/codecs.html#codecs.Codec.encode) и [`decode()`](https://python-all.ru/3.3/library/codecs.html#codecs.Codec.decode) могут реализовывать различные схемы обработки ошибок с помощью строкового аргумента *errors*. Следующие строковые значения определены и реализованы всеми стандартными кодеками Python:215216| Значение | Значение |217| --- | --- |218| `'strict'` | Возбуждает [`UnicodeError`](https://python-all.ru/3.3/library/exceptions.html#UnicodeError) (или подкласс); это поведение по умолчанию. |219| `'ignore'` | Игнорирует символ и продолжает со следующего. |220| `'replace'` | Заменяет подходящим заменяющим символом; для встроенных кодеков Unicode при декодировании Python будет использовать официальный U+FFFD REPLACEMENT CHARACTER, а при кодировании – '?'. |221| `'xmlcharrefreplace'` | Заменяет соответствующей символьной ссылкой XML (только для кодирования). |222| `'backslashreplace'` | Заменяет escape-последовательностями с обратной косой чертой (только для кодирования). |223| `'surrogateescape'` | Заменяет байт суррогатом U+DCxx, как определено в [**PEP 383**](https://python-all.ru/3.3/library/codecs.html). |224225Кроме того, следующие обработчики ошибок специфичны для одного кодека:226227| Значение | Кодек | Значение |228| --- | --- | --- |229| `'surrogatepass'` | utf-8 | Разрешить кодирование и декодирование суррогатных кодов в UTF-8. |230231Новое в версии 3.1: Обработчики ошибок `'surrogateescape'` и `'surrogatepass'`.232233Набор допустимых значений может быть расширен через [`register_error()`](https://python-all.ru/3.3/library/codecs.html#codecs.register_error).234235### 7.2.1.1. Объекты Codec236237Класс `Codec` определяет методы, которые также задают функциональные интерфейсы кодировщика и декодировщика без состояния:238239#### `Codec.encode(input[, errors])`240241Кодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Кодирование преобразует строковый объект в объект bytes с использованием определённой кодировки набора символов (например, `cp1252` или `iso-8859-1`).242243*errors* определяет способ обработки ошибок. По умолчанию используется `'strict'` режим.244245Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.246247Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.248249#### `Codec.decode(input[, errors])`250251Декодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Декодирование преобразует объект bytes, закодированный с помощью определённой кодировки набора символов, в строковый объект.252253*input* должен быть объектом bytes или объектом, предоставляющим интерфейс только для чтения символьного буфера – например, объекты буфера и файлы, отображаемые в память.254255*errors* определяет способ обработки ошибок. По умолчанию используется `'strict'` режим.256257Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.258259Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.260261Классы [`IncrementalEncoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalDecoder) предоставляют базовый интерфейс для пошагового кодирования и декодирования. Кодирование/декодирование входных данных выполняется не одним вызовом функции без сохранения состояния, а несколькими вызовами метода [`encode()`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalDecoder.decode) пошагового кодировщика/декодировщика. Пошаговый кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.262263Объединённый результат вызовов метода [`encode()`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalDecoder.decode) совпадает с результатом, полученным при объединении всех отдельных входных данных в один и кодировании/декодировании этого входа с помощью функции без сохранения состояния.264265### 7.2.1.2. Объекты IncrementalEncoder266267Класс [`IncrementalEncoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый кодировщик должен реализовать для совместимости с реестром кодеков Python.268269#### `class codecs.IncrementalEncoder([errors])`270271Конструктор для экземпляра [`IncrementalEncoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalEncoder).272273Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.274275[`IncrementalEncoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalEncoder) может реализовывать различные схемы обработки ошибок, передавая ключевой аргумент *errors*. Эти параметры предопределены:276277- `'strict'` Вызывает [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.278- `'ignore'` Игнорирует символ и переходит к следующему.279- `'replace'` Заменяет подходящим замещающим символом.280- `'xmlcharrefreplace'` Заменяет соответствующей символьной ссылкой XML.281- `'backslashreplace'` Заменяет управляющими последовательностями с обратной косой чертой.282283Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalEncoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalEncoder).284285Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.3/library/codecs.html#codecs.register_error).286287#### `encode(object[, final])`288289Кодирует *object* (с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов [`encode()`](https://python-all.ru/3.3/library/codecs.html#codecs.encode), *final* должен быть истинным (по умолчанию – ложь).290291#### `reset()`292293Сбрасывает кодировщик в начальное состояние. Вывод отбрасывается: вызовите `.encode('', final=True)`, чтобы сбросить кодировщик и получить вывод.294295#### `IncrementalEncoder.getstate()`296297Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что `0` – это наиболее распространённое состояние. (Состояния, которые сложнее целых чисел, можно преобразовать в целое число, замаршализовав/запиклив состояние и кодируя байты результирующей строки в целое число).298299#### `IncrementalEncoder.setstate(state)`300301Устанавливает состояние кодировщика равным *state*. *state* должно быть состоянием кодировщика, возвращённым методом [`getstate()`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalEncoder.getstate).302303### 7.2.1.3. Объекты IncrementalDecoder304305Класс [`IncrementalDecoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый декодировщик должен реализовать для совместимости с реестром кодеков Python.306307#### `class codecs.IncrementalDecoder([errors])`308309Конструктор для экземпляра [`IncrementalDecoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalDecoder).310311Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.312313[`IncrementalDecoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalDecoder) может реализовывать различные схемы обработки ошибок, передавая ключевой аргумент *errors*. Эти параметры предопределены:314315- `'strict'` Вызывает [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.316- `'ignore'` Игнорирует символ и переходит к следующему.317- `'replace'` Заменяет подходящим замещающим символом.318319Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalDecoder`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalDecoder).320321Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.3/library/codecs.html#codecs.register_error).322323#### `decode(object[, final])`324325Декодирует *object* (с учётом текущего состояния декодировщика) и возвращает результирующий декодированный объект. Если это последний вызов [`decode()`](https://python-all.ru/3.3/library/codecs.html#codecs.decode), *final* должен быть истинным (по умолчанию – ложь). Если *final* истинно, декодировщик должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).326327#### `reset()`328329Сбрасывает декодер в исходное состояние.330331#### `getstate()`332333Возвращает текущее состояние декодера. Это должен быть кортеж из двух элементов: первый – буфер, содержащий ещё не декодированные входные данные; второй – целое число, которое может содержать дополнительную информацию о состоянии. (Реализация должна гарантировать, что `0` является наиболее распространённой дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии равна `0`, должна быть возможность установить декодер в состояние без буферизованных входных данных и с `0` в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованных входных данных в декодер возвращала его в предыдущее состояние без вывода каких-либо данных. (Дополнительная информация о состоянии, более сложная, чем целые числа, может быть преобразована в целое число с помощью маршалинга/сериализации этой информации и кодирования байтов результирующей строки в целое число.)334335#### `setstate(state)`336337Устанавливает состояние декодировщика равным *state*. *state* должно быть состоянием декодировщика, возвращённым методом [`getstate()`](https://python-all.ru/3.3/library/codecs.html#codecs.IncrementalDecoder.getstate).338339Классы [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader) предоставляют общие рабочие интерфейсы, которые можно использовать для очень простой реализации новых подмодулей кодировок. Пример такой реализации можно найти в `encodings.utf_8`.340341### 7.2.1.4. Объекты StreamWriter342343Класс [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый писатель должен определить для совместимости с реестром кодеков Python.344345#### `class codecs.StreamWriter(stream[, errors])`346347Конструктор экземпляра [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter).348349Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.350351*поток данных* должен быть файлоподобным объектом, открытым для записи двоичных данных.352353Класс [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Эти параметры предопределены:354355- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.356- `'ignore'` Игнорирует символ и продолжает со следующего.357- `'replace'` Заменяет подходящим заменяющим символом358- `'xmlcharrefreplace'` Заменяет соответствующей символьной ссылкой XML359- `'backslashreplace'` Заменяет управляющими последовательностями с обратной косой чертой.360361Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter).362363Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.3/library/codecs.html#codecs.register_error).364365#### `write(object)`366367Записывает в поток закодированное содержимое объекта.368369#### `writelines(list)`370371Записывает объединённый список строк в поток данных (возможно, с повторным использованием метода [`write()`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter.write)).372373#### `reset()`374375Сбрасывает и переустанавливает буферы кодека, используемые для сохранения состояния.376377Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.378379В дополнение к указанным выше методам, [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от базового потока.380381### 7.2.1.5. Объекты StreamReader382383Класс [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый читатель должен определить для совместимости с реестром кодеков Python.384385#### `class codecs.StreamReader(stream[, errors])`386387Конструктор экземпляра [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader).388389Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.390391*поток данных* должен быть файлоподобным объектом, открытым для чтения (двоичных) данных.392393Класс [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Эти параметры определены:394395- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.396- `'ignore'` Игнорирует символ и продолжает со следующего.397- `'replace'` Заменяет подходящим заменяющим символом.398399Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader).400401Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.3/library/codecs.html#codecs.register_error).402403#### `read([size[, chars[, firstline]]])`404405Декодирует данные из потока и возвращает результирующий объект.406407*chars* указывает количество символов для чтения из потока данных. [`read()`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader.read) никогда не вернёт больше *chars* символов, но может вернуть меньше, если доступно недостаточно символов.408409*size* указывает приблизительное максимальное количество байт для чтения из потока данных в целях декодирования. Декодер может изменять этот параметр по своему усмотрению. Значение по умолчанию -1 означает, что нужно читать и декодировать как можно больше. *size* предназначен для того, чтобы избежать декодирования огромных файлов за один шаг.410411*firstline* указывает, что достаточно вернуть только первую строку, если на последующих строках возникают ошибки декодирования.412413Метод должен использовать жадную стратегию чтения, то есть читать столько данных, сколько допускается определением кодировки и заданным размером; например, если в потоке доступны необязательные окончания кодировки или маркеры состояния, их также следует прочитать.414415#### `readline([size[, keepends]])`416417Читает одну строку из входного потока и возвращает декодированные данные.418419*size*, если указан, передаётся как аргумент size в метод [`read()`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader.read) потока.420421Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.422423#### `readlines([sizehint[, keepends]])`424425Читает все строки из входного потока данных и возвращает их в виде списка строк.426427Окончания строк реализуются с помощью метода декодера кодека и включаются в элементы списка, если *keepends* имеет значение true.428429*sizehint*, если указан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader.read) потока.430431#### `reset()`432433Сбрасывает буферы кодека, используемые для сохранения состояния.434435Обратите внимание, что никакое перемещение позиции в потоке не должно выполняться. Этот метод предназначен в первую очередь для восстановления после ошибок декодирования.436437В дополнение к указанным выше методам, [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от базового потока.438439Следующие два базовых класса включены для удобства. Они не нужны реестру кодеков, но могут оказаться полезными на практике.440441### 7.2.1.6. Объекты StreamReaderWriter442443[`StreamReaderWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReaderWriter) позволяет оборачивать потоки, работающие как в режиме чтения, так и записи.444445Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.3/library/codecs.html#codecs.lookup), для создания экземпляра.446447#### `class codecs.StreamReaderWriter(stream, Reader, Writer, errors)`448449Создаёт экземпляр [`StreamReaderWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReaderWriter). *поток данных* должен быть файлоподобным объектом. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими интерфейсы [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter) соответственно. Обработка ошибок выполняется так же, как определено для потоковых читателей и писателей.450451Экземпляры [`StreamReaderWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReaderWriter) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от базового потока.452453### 7.2.1.7. Объекты StreamRecoder454455[`StreamRecoder`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamRecoder) предоставляет представление кодирования данных с разделением на фронтенд и бэкенд, что иногда полезно при работе с разными кодировками.456457Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.3/library/codecs.html#codecs.lookup), для создания экземпляра.458459#### `class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors)`460461Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamRecoder), реализующий двунаправленное преобразование: *encode* и *decode* работают на фронтенде (вход `read()` и выход `write()`), а *Reader* и *Writer* – на бэкенде (чтение и запись в поток).462463Эти объекты можно использовать для прозрачного прямого перекодирования, например, из Latin-1 в UTF-8 и обратно.464465*Поток данных* должен быть файлоподобным объектом.466467*encode*, *decode* должны соответствовать интерфейсу `Codec`. *Reader*, *Writer* должны быть фабричными функциями или классами, предоставляющими объекты интерфейсов [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter) соответственно.468469*encode* и *decode* нужны для преобразования на фронтенде, а *Reader* и *Writer* – на бэкенде.470471Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.472473Экземпляры [`StreamRecoder`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamRecoder) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.3/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока.474475## 7.2.2. Кодировки и Unicode476477Строки внутри хранятся как последовательности кодовых точек в диапазоне `0 - 10FFFF` (см. [**PEP 393**](https://python-all.ru/3.3/library/codecs.html) для подробностей реализации). Когда строковый объект используется за пределами CPU и памяти, порядок байтов CPU и способ хранения этих массивов в виде байтов становятся проблемой. Преобразование строкового объекта в последовательность байтов называется кодированием, а восстановление строкового объекта из последовательности байтов – декодированием. Существует множество различных методов для этого преобразования (эти методы также называются кодировками). Самый простой метод – сопоставить кодовые точки 0–255 байтам `0x0`–`0xff`. Это означает, что строковый объект, содержащий кодовые точки выше `U+00FF`, не может быть закодирован этим методом (который называется `'latin-1'` или `'iso-8859-1'`). [`str.encode()`](https://python-all.ru/3.3/library/stdtypes.html#str.encode) вызовет [`UnicodeEncodeError`](https://python-all.ru/3.3/library/exceptions.html#UnicodeEncodeError), который выглядит так: `UnicodeEncodeError: 'latin-1' кодек не может закодировать символ '\u1234' на позиции 3: код не в range(256)`.478479Существует ещё одна группа кодировок (так называемые charmap-кодировки), которые выбирают другое подмножество всех кодовых точек Unicode и определяют, как эти кодовые точки сопоставляются с байтами `0x0`–`0xff`. Чтобы увидеть, как это делается, достаточно открыть, например, `encodings/cp1252.py` (кодировка, используемая в основном в Windows). Там есть строковая константа из 256 символов, показывающая, какой символ какому значению байта соответствует.480481Все эти кодировки могут закодировать только 256 из 1114112 кодовых точек, определённых в Unicode. Простой и прямой способ хранить каждую кодовую точку Unicode – это хранить каждую кодовую точку как четыре последовательных байта. Есть две возможности: хранить байты в порядке big endian или little endian. Эти две кодировки называются `UTF-32-BE` и `UTF-32-LE` соответственно. Их недостаток в том, что, например, при использовании `UTF-32-BE` на машине с little endian постоянно придётся менять порядок байтов при кодировании и декодировании. `UTF-32` избегает этой проблемы: байты всегда будут в естественном порядке. Однако когда эти байты читаются CPU с другим порядком байтов, байты всё равно приходится менять. Чтобы иметь возможность определить порядок байтов последовательности байтов `UTF-16` или `UTF-32`, существует так называемый BOM (Byte Order Mark – метка порядка байтов). Это символ 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` это обычный символ, который декодируется как любой другой.482483Существует ещё одна кодировка, способная кодировать весь диапазон символов Unicode: UTF-8. UTF-8 – это 8-битная кодировка, а это значит, что в UTF-8 нет проблем с порядком байтов. Каждый байт в последовательности UTF-8 состоит из двух частей: битов маркера (самые старшие биты) и битов полезной нагрузки. Биты маркера представляют собой последовательность от нуля до четырёх битов `1`, за которой следует бит `0`. Символы Unicode кодируются следующим образом (где x – биты полезной нагрузки, которые при объединении дают символ Unicode):484485| Диапазон | Кодировка |486| --- | --- |487| `U-00000000` ... `U-0000007F` | 0xxxxxxx |488| `U-00000080` ... `U-000007FF` | 110xxxxx 10xxxxxx |489| `U-00000800` ... `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |490| `U-00010000` ... `U-0010FFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |491492Младший значащий бит символа Unicode – это самый правый бит x.493494Поскольку UTF-8 – это 8-битная кодировка, BOM не требуется, и любой символ `U+FEFF` в декодированной строке (даже если это первый символ) трактуется как `ZERO WIDTH NO-BREAK SPACE`.495496Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Любая 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-кодировке начинается с этих байтовых значений (которые, например, отображаются в497498> ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЭРЕЗИСОМ499>500> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА501>502> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК503504in iso-8859-1), this increases the probability that a `utf-8-sig` encoding can be correctly guessed from the byte sequence. So here the BOM is not used to be able to determine the byte order used for generating the byte sequence, but as a signature that helps in guessing the encoding. On encoding the utf-8-sig codec will write `0xef`, `0xbb`, `0xbf` as the first three bytes to the file. On decoding `utf-8-sig` will skip those three bytes if they appear as the first three bytes in the file. In UTF-8, the use of the BOM is discouraged and should generally be avoided.505506## 7.2.3. Стандартные кодировки507508Python поставляется с рядом встроенных кодеков, реализованных либо как функции на C, либо с помощью словарей в качестве таблиц отображения. В следующей таблице перечислены кодеки по именам, вместе с несколькими распространёнными псевдонимами и языками, для которых эта кодировка, вероятно, используется. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что варианты написания, отличающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами; поэтому, например, `'utf-8'` является допустимым псевдонимом для кодека `'utf_8'`.509510**Особенность реализации CPython:** Некоторые распространённые кодировки могут обходить механизм поиска codecs для повышения производительности. Эти возможности оптимизации распознаются CPython только для ограниченного набора псевдонимов: utf-8, utf8, latin-1, latin1, iso-8859-1, mbcs (только Windows), ascii, utf-16 и utf-32. Использование альтернативных вариантов написания этих кодировок может привести к снижению скорости выполнения.511512Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:513514- набор символов ISO 8859515- кодовая страница Microsoft Windows, обычно полученная из набора символов 8859, но заменяющая управляющие символы дополнительными графическими символами516- кодовая страница IBM EBCDIC517- кодовая страница IBM PC, совместимая с ASCII518519| Кодек | Псевдонимы | Языки |520| --- | --- | --- |521| ascii | 646, us-ascii | Английский |522| big5 | big5-tw, csbig5 | Китайский традиционный |523| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |524| cp037 | IBM037, IBM039 | Английский |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| cp1140 | ibm1140 | Западная Европа |553| cp1250 | windows-1250 | Центральная и Восточная Европа |554| cp1251 | windows-1251 | болгарский, белорусский, македонский, русский, сербский |555| cp1252 | windows-1252 | Западная Европа |556| cp1253 | windows-1253 | Греческий |557| cp1254 | windows-1254 | Турецкий |558| cp1255 | windows-1255 | Иврит |559| cp1256 | windows-1256 | Арабский |560| cp1257 | windows-1257 | Балтийские языки |561| cp1258 | windows-1258 | вьетнамский |562| cp65001 |  | Только Windows: Windows UTF-8 (`CP_UTF8`) Новое в версии 3.3. |563| euc\_jp | eucjp, ujis, u-jis | Японский |564| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |565| euc\_jisx0213 | eucjisx0213 | Японский |566| euc\_kr | euckr, корейский, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |567| gb2312 | chinese, csiso58gb231280, euc- cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso- ir-58 | Упрощённый китайский |568| gbk | 936, cp936, ms936 | Унифицированный китайский |569| gb18030 | gb18030-2000 | Унифицированный китайский |570| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |571| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |572| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |573| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |574| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |575| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |576| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |577| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |578| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |579| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |580| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |581| iso8859\_4 | iso-8859-4, latin4, L4 | Балтийские языки |582| iso8859\_5 | iso-8859-5, кириллица | болгарский, белорусский, македонский, русский, сербский |583| iso8859\_6 | iso-8859-6, арабский | Арабский |584| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |585| iso8859\_8 | iso-8859-8, иврит | Иврит |586| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |587| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |588| iso8859\_13 | iso-8859-13, latin7, L7 | Балтийские языки |589| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |590| iso8859\_15 | iso-8859-15, latin9, L9 | Западная Европа |591| iso8859\_16 | iso-8859-16, latin10, L10 | Юго-Восточная Европа |592| johab | cp1361, ms1361 | Корейский |593| koi8\_r |  | Русский |594| koi8\_u |  | Украинский |595| mac\_cyrillic | maccyrillic | болгарский, белорусский, македонский, русский, сербский |596| mac\_greek | macgreek | Греческий |597| mac\_iceland | maciceland | Исландский |598| mac\_latin2 | maclatin2, maccentraleurope | Центральная и Восточная Европа |599| mac\_roman | macroman, macintosh | Западная Европа |600| mac\_turkish | macturkish | Турецкий |601| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |602| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |603| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |604| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |605| utf\_32 | U32, utf32 | все языки |606| utf\_32\_be | UTF-32BE | все языки |607| utf\_32\_le | UTF-32LE | все языки |608| utf\_16 | U16, utf16 | все языки |609| utf\_16\_be | UTF-16BE | все языки |610| utf\_16\_le | UTF-16LE | все языки |611| utf\_7 | U7, unicode-1-1-utf-7 | все языки |612| utf\_8 | U8, UTF, utf8 | все языки |613| utf\_8\_sig |  | все языки |614615## 7.2.4. Кодировки, специфичные для Python616617Некоторые предопределенные кодеки специфичны для Python, поэтому их имена кодеков не имеют смысла за пределами Python. Они перечислены в таблицах ниже по типам ожидаемых входных и выходных данных (обратите внимание, что хотя текстовые кодировки являются наиболее распространенным вариантом использования кодеков, базовая инфраструктура кодеков поддерживает произвольные преобразования данных, а не только текстовые кодировки). Для асимметричных кодеков указанное назначение описывает направление кодирования.618619Следующие кодеки обеспечивают кодирование [`str`](https://python-all.ru/3.3/library/stdtypes.html#str) в [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes) и декодирование [*bytes-like object*](https://python-all.ru/3.3/glossary.html#term-bytes-like-object) в [`str`](https://python-all.ru/3.3/library/stdtypes.html#str), аналогично кодировкам текста Unicode.620621| Кодек | Псевдонимы | Назначение |622| --- | --- | --- |623| idna |  | Реализует [**RFC 3490**](https://python-all.ru/3.3/library/codecs.html), см. также [`encodings.idna`](https://python-all.ru/3.3/library/codecs.html#module-encodings.idna) |624| mbcs | dbcs | Только Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |625| palmos |  | Кодировка PalmOS 3.5 |626| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/3.3/library/codecs.html) |627| raw\_unicode\_escape |  | Создаёт строку, пригодную для использования в качестве сырого Unicode-литерала в исходном коде Python |628| undefined |  | Вызывает исключение для всех преобразований. Может использоваться как системная кодировка, если не требуется автоматическое приведение между байтовыми строками и строками Unicode. |629| unicode\_escape |  | Создаёт строку, пригодную для использования в качестве Unicode-литерала в исходном коде Python |630| unicode\_internal |  | Возвращает внутреннее представление операнда Устарело с версии 3.3. |631632Следующие кодеки предоставляют отображения из [*байтоподобного объекта*](https://python-all.ru/3.3/glossary.html#term-bytes-like-object) в [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes).633634| Кодек | Назначение | Кодировщик/декодировщик |635| --- | --- | --- |636| base64\_codec [\[1\]](https://python-all.ru/3.3/library/codecs.html#b64) | Преобразует операнд в MIME base64 (результат всегда содержит завершающий `'\n'`) | [`base64.b64encode()`](https://python-all.ru/3.3/library/base64.html#base64.b64encode), [`base64.b64decode()`](https://python-all.ru/3.3/library/base64.html#base64.b64decode) |637| bz2\_codec | Сжимает операнд с помощью bz2 | [`bz2.compress()`](https://python-all.ru/3.3/library/bz2.html#bz2.compress), [`bz2.decompress()`](https://python-all.ru/3.3/library/bz2.html#bz2.decompress) |638| hex\_codec | Преобразует операнд в шестнадцатеричное представление, по два разряда на байт | [`base64.b16encode()`](https://python-all.ru/3.3/library/base64.html#base64.b16encode), [`base64.b16decode()`](https://python-all.ru/3.3/library/base64.html#base64.b16decode) |639| quopri\_codec | Преобразует операнд в MIME quoted-printable | [`quopri.encodestring()`](https://python-all.ru/3.3/library/quopri.html#quopri.encodestring), [`quopri.decodestring()`](https://python-all.ru/3.3/library/quopri.html#quopri.decodestring) |640| uu\_codec | Преобразует операнд с помощью uuencode | [`uu.encode()`](https://python-all.ru/3.3/library/uu.html#uu.encode), [`uu.decode()`](https://python-all.ru/3.3/library/uu.html#uu.decode) |641| zlib\_codec | Сжимает операнд с помощью gzip | [`zlib.compress()`](https://python-all.ru/3.3/library/zlib.html#zlib.compress), [`zlib.decompress()`](https://python-all.ru/3.3/library/zlib.html#zlib.decompress) |642643| [\[1\]](https://python-all.ru/3.3/library/codecs.html#id4) | Вместо того чтобы принимать любой [*байтоподобный объект*](https://python-all.ru/3.3/glossary.html#term-bytes-like-object), `'base64_codec'` принимает только [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes) и [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray) для кодирования и только [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray) и экземпляры [`str`](https://python-all.ru/3.3/library/stdtypes.html#str), содержащие только ASCII, для декодирования |644| --- | --- |645646Следующие кодеки предоставляют отображения из [`str`](https://python-all.ru/3.3/library/stdtypes.html#str) в [`str`](https://python-all.ru/3.3/library/stdtypes.html#str).647648| Кодек | Назначение |649| --- | --- |650| rot\_13 | Возвращает шифрование Цезаря операнда |651652Новое в версии 3.2: кодеки bytes-to-bytes и str-to-str.653654## 7.2.5. [`encodings.idna`](https://python-all.ru/3.3/library/codecs.html#module-encodings.idna) – Интернационализированные доменные имена в приложениях655656Этот модуль реализует [**RFC 3490**](https://python-all.ru/3.3/library/codecs.html) (Интернационализированные доменные имена в приложениях) и [**RFC 3492**](https://python-all.ru/3.3/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/3.3/library/stringprep.html#module-stringprep).657658Вместе эти RFC определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (такое как `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, например, `www.xn--alliancefranaise-npb.nu`). Затем форма ACE доменного имени используется везде, где протокол не допускает произвольные символы, например, в DNS-запросах, полях HTTP *Host* и т.д. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки Unicode-доменов в IDNA при передаче и обратно преобразовывать метки ACE в Unicode перед отображением пользователю.659660Python поддерживает это преобразование несколькими способами: кодек `idna` выполняет преобразование между Unicode и ACE, разделяя входную строку на метки на основе символов-разделителей, определенных в [разделе 3.1](https://python-all.ru/3.3/library/codecs.html) (1) документа [**RFC 3490**](https://python-all.ru/3.3/library/codecs.html), и преобразуя каждую метку в ACE по мере необходимости, и, наоборот, разделяя входную байтовую строку на метки на основе разделителя `.` и преобразуя любые найденные метки ACE в Unicode. Кроме того, модуль [`socket`](https://python-all.ru/3.3/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно беспокоиться о преобразовании имен хостов при передаче их в модуль socket. Вдобавок, модули, которые принимают имена хостов в качестве параметров функций, такие как [`http.client`](https://python-all.ru/3.3/library/http.client.html#module-http.client) и [`ftplib`](https://python-all.ru/3.3/library/ftplib.html#module-ftplib), принимают Unicode-имена хостов (при этом [`http.client`](https://python-all.ru/3.3/library/http.client.html#module-http.client) также прозрачно отправляет IDNA-имя хоста в поле *Host*, если вообще отправляет это поле).661662При получении имён хостов из сети (например, при обратном поиске имени) автоматическое преобразование в Unicode не выполняется: приложения, желающие отобразить такие имена хостов пользователю, должны декодировать их в Unicode.663664Модуль [`encodings.idna`](https://python-all.ru/3.3/library/codecs.html#module-encodings.idna) также реализует процедуру nameprep, которая выполняет определенные нормализации имен хостов для достижения нечувствительности к регистру интернационализированных доменных имен и унификации похожих символов. Функции nameprep можно использовать напрямую при желании.665666#### `encodings.idna.nameprep(label)`667668Return the nameprepped version of *label*. The implementation currently assumes query strings, so `AllowUnassigned` is true.669670#### `encodings.idna.ToASCII(label)`671672Преобразует метку в ASCII, как указано в [**RFC 3490**](https://python-all.ru/3.3/library/codecs.html). Параметр `UseSTD3ASCIIRules` предполагается равным false.673674#### `encodings.idna.ToUnicode(label)`675676Преобразует метку в Unicode, как указано в [**RFC 3490**](https://python-all.ru/3.3/library/codecs.html).677678## 7.2.6. [`encodings.mbcs`](https://python-all.ru/3.3/library/codecs.html#module-encodings.mbcs) – Кодовая страница Windows ANSI679680Кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP).681682Доступность: только Windows.683684Изменено в версии 3.3: Поддержка любого обработчика ошибок.685686Изменено в версии 3.2: До версии 3.2 аргумент *errors* игнорировался; для кодирования всегда использовалось `'replace'`, а для декодирования – `'ignore'`.687688## 7.2.7. [`encodings.utf_8_sig`](https://python-all.ru/3.3/library/codecs.html#module-encodings.utf_8_sig) – Кодек UTF-8 с сигнатурой BOM689690Этот модуль реализует вариант кодека UTF-8: при кодировании префикс UTF-8 BOM будет добавлен перед байтами, закодированными в UTF-8. Для кодировщика с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный UTF-8 BOM в начале данных будет пропущен.691