> **Источник:** https://python-all.ru/3.4/library/codecs.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# 7.2. [`codecs`](https://python-all.ru/3.4/library/codecs.html#module-codecs) – Реестр кодеков и базовые классы

Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет поиском кодеков и обработкой ошибок. Большинство стандартных кодеков – это [*текстовые кодировки*](https://python-all.ru/3.4/glossary.html#term-text-encoding), которые кодируют текст в байты, но существуют также кодеки, кодирующие текст в текст и байты в байты. Пользовательские кодеки могут кодировать и декодировать данные произвольных типов, однако некоторые возможности модуля ограничены использованием только с [*текстовыми кодировками*](https://python-all.ru/3.4/glossary.html#term-text-encoding), или с кодеками, которые кодируют в [`байты`](https://python-all.ru/3.4/library/functions.html#bytes).

Модуль определяет следующие функции для кодирования и декодирования с помощью любого кодека:

#### `codecs.encode(obj[, encoding[, errors]])`

Кодирует *obj* с помощью кодека, зарегистрированного для *encoding*. Кодировка по умолчанию – `utf-8`.

Параметр *Errors* может быть задан для выбора желаемой схемы обработки ошибок. Обработчик ошибок по умолчанию – `'strict'`, то есть ошибки кодирования вызывают [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError) (или более специфичный подкласс, например [`UnicodeEncodeError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeEncodeError)). Обратитесь к разделу [*Базовые классы кодеков*](https://python-all.ru/3.4/library/codecs.html#codec-base-classes) для получения дополнительной информации об обработке ошибок кодеков.

#### `codecs.decode(obj[, encoding[, errors]])`

Декодирует *obj* с помощью кодека, зарегистрированного для *encoding*. Кодировка по умолчанию – `utf-8`.

Параметр *Errors* может быть задан для выбора желаемой схемы обработки ошибок. Обработчик ошибок по умолчанию – `'strict'`, то есть ошибки декодирования вызывают [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError) (или более специфичный подкласс, например [`UnicodeDecodeError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeDecodeError)). Обратитесь к разделу [*Базовые классы кодеков*](https://python-all.ru/3.4/library/codecs.html#codec-base-classes) для получения дополнительной информации об обработке ошибок кодеков.

Полные сведения о каждом кодеке также можно получить напрямую:

#### `codecs.lookup(encoding)`

Ищет информацию о кодеке в реестре кодеков Python и возвращает объект [`CodecInfo`](https://python-all.ru/3.4/library/codecs.html#codecs.CodecInfo), как определено ниже.

Сначала кодировки ищутся в кеше реестра. Если не найдены, сканируется список зарегистрированных функций поиска. Если объект [`CodecInfo`](https://python-all.ru/3.4/library/codecs.html#codecs.CodecInfo) не найден, вызывается [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError). В противном случае объект [`CodecInfo`](https://python-all.ru/3.4/library/codecs.html#codecs.CodecInfo) сохраняется в кеше и возвращается вызывающему.

#### `class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)`

Сведения о кодеке при поиске в реестре кодеков. Аргументы конструктора хранятся в атрибутах с теми же именами:

#### `name`

Имя кодировки.

#### `encode`

#### `decode`

Функции кодирования и декодирования без сохранения состояния. Это должны быть функции или методы с тем же интерфейсом, что и методы [`encode()`](https://python-all.ru/3.4/library/codecs.html#codecs.Codec.encode) и [`decode()`](https://python-all.ru/3.4/library/codecs.html#codecs.Codec.decode) экземпляров Codec (см. [*Интерфейс Codec*](https://python-all.ru/3.4/library/codecs.html#codec-objects)). Ожидается, что функции или методы работают в режиме без сохранения состояния.

#### `incrementalencoder`

#### `incrementaldecoder`

Классы или функции-фабрики инкрементального кодировщика и декодировщика. Они должны предоставлять интерфейс, определенный базовыми классами [`IncrementalEncoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalDecoder), соответственно. Инкрементальные кодеки могут сохранять состояние.

#### `streamwriter`

#### `streamreader`

Классы или функции-фабрики потокового писателя и читателя. Они должны предоставлять интерфейс, определенный базовыми классами [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader), соответственно. Потоковые кодеки могут сохранять состояние.

Для упрощения доступа к различным компонентам кодеков модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/3.4/library/codecs.html#codecs.lookup) для поиска кодека:

#### `codecs.getencoder(encoding)`

Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.

Вызывает [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError), если кодировка не может быть найдена.

#### `codecs.getdecoder(encoding)`

Находит кодек для указанной кодировки и возвращает его функцию-декодер.

Вызывает [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError), если кодировка не может быть найдена.

#### `codecs.getincrementalencoder(encoding)`

Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.

Вызывает [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный кодировщик.

#### `codecs.getincrementaldecoder(encoding)`

Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.

Вызывает [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный декодировщик.

#### `codecs.getreader(encoding)`

Находит кодек для указанной кодировки и возвращает его класс StreamReader или фабричную функцию.

Вызывает [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError), если кодировка не найдена.

#### `codecs.getwriter(encoding)`

Находит кодек для указанной кодировки и возвращает его класс StreamWriter или фабричную функцию.

Вызывает [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError), если кодировка не найдена.

Пользовательские кодеки становятся доступными при регистрации подходящей функции поиска кодека :

#### `codecs.register(search_function)`

Регистрирует функцию поиска кодека. Функции поиска должны принимать один аргумент – имя кодировки строчными буквами – и возвращать объект [`CodecInfo`](https://python-all.ru/3.4/library/codecs.html#codecs.CodecInfo). Если функция поиска не может найти указанную кодировку, она должна вернуть `None`.

> **Примечание**
>
> Регистрация функции поиска в настоящее время не является обратимой, что в некоторых случаях может вызывать проблемы, например при модульном тестировании или перезагрузке модулей.

Хотя встроенная функция [`open()`](https://python-all.ru/3.4/library/functions.html#open) и соответствующий модуль [`io`](https://python-all.ru/3.4/library/io.html#module-io) являются рекомендуемым подходом для работы с закодированными текстовыми файлами, этот модуль предоставляет дополнительные вспомогательные функции и классы, которые позволяют использовать более широкий набор кодеков при работе с бинарными файлами:

#### `codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=1)`

Открывает закодированный файл, используя указанный *mode*, и возвращает экземпляр [`StreamReaderWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReaderWriter), обеспечивающий прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, что означает открытие файла в режиме чтения.

> **Примечание**
>
> Базовые закодированные файлы всегда открываются в бинарном режиме. Автоматическое преобразование `'\n'` при чтении и записи не выполняется. Аргумент *mode* может быть любым бинарным режимом, допустимым для встроенной функции [`open()`](https://python-all.ru/3.4/library/functions.html#open); `'b'` добавляется автоматически.

*encoding* указывает кодировку, которая будет использоваться для файла. Допускается любая кодировка, которая кодирует в байты и декодирует из байтов, а типы данных, поддерживаемые методами файла, зависят от используемого кодека.

*errors* may be given to define the error handling. It defaults to `'strict'` which causes a [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError) to be raised in case an encoding error occurs.

Параметр *buffering* имеет то же значение, что и для встроенной функции [`open()`](https://python-all.ru/3.4/library/functions.html#open). По умолчанию используется построчная буферизация.

#### `codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')`

Возвращает экземпляр [`StreamRecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamRecoder), обёртку для *file*, которая обеспечивает прозрачное перекодирование. Исходный файл закрывается при закрытии обёртки.

Данные, записываемые в обёрнутый файл, декодируются согласно заданной *data\_encoding*, а затем записываются в исходный файл в виде байтов с использованием *file\_encoding*. Байты, читаемые из исходного файла, декодируются согласно *file\_encoding*, а результат кодируется с использованием *data\_encoding*.

Если *file\_encoding* не указан, по умолчанию используется *data\_encoding*.

*errors* may be given to define the error handling. It defaults to `'strict'`, which causes [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError) to be raised in case an encoding error occurs.

#### `codecs.iterencode(iterator, encoding, errors='strict', **kwargs)`

Использует инкрементальный кодировщик для итеративного кодирования входных данных, предоставляемых *iterator*. Эта функция является [*генератором*](https://python-all.ru/3.4/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному кодировщику.

#### `codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)`

Использует инкрементальный декодировщик для итеративного декодирования входных данных, предоставляемых *iterator*. Эта функция является [*генератором*](https://python-all.ru/3.4/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному декодировщику.

Модуль также предоставляет следующие константы, полезные для чтения и записи в платформенно-зависимые файлы:

#### `codecs.BOM`

#### `codecs.BOM_BE`

#### `codecs.BOM_LE`

#### `codecs.BOM_UTF8`

#### `codecs.BOM_UTF16`

#### `codecs.BOM_UTF16_BE`

#### `codecs.BOM_UTF16_LE`

#### `codecs.BOM_UTF32`

#### `codecs.BOM_UTF32_BE`

#### `codecs.BOM_UTF32_LE`

Эти константы определяют различные последовательности байтов, являющиеся метками порядка байтов Unicode (BOM) для нескольких кодировок. Они используются в потоках данных UTF-16 и UTF-32 для указания используемого порядка байтов, а в UTF-8 – как сигнатура Unicode. [`BOM_UTF16`](https://python-all.ru/3.4/library/codecs.html#codecs.BOM_UTF16) может быть [`BOM_UTF16_BE`](https://python-all.ru/3.4/library/codecs.html#codecs.BOM_UTF16_BE) или [`BOM_UTF16_LE`](https://python-all.ru/3.4/library/codecs.html#codecs.BOM_UTF16_LE) в зависимости от родного порядка байтов платформы, [`BOM`](https://python-all.ru/3.4/library/codecs.html#codecs.BOM) – псевдоним для [`BOM_UTF16`](https://python-all.ru/3.4/library/codecs.html#codecs.BOM_UTF16), [`BOM_LE`](https://python-all.ru/3.4/library/codecs.html#codecs.BOM_LE) для [`BOM_UTF16_LE`](https://python-all.ru/3.4/library/codecs.html#codecs.BOM_UTF16_LE), а [`BOM_BE`](https://python-all.ru/3.4/library/codecs.html#codecs.BOM_BE) для [`BOM_UTF16_BE`](https://python-all.ru/3.4/library/codecs.html#codecs.BOM_UTF16_BE). Остальные представляют BOM в кодировках UTF-8 и UTF-32.

## 7.2.1. Базовые классы кодеков

Модуль [`codecs`](https://python-all.ru/3.4/library/codecs.html#module-codecs) определяет набор базовых классов, которые задают интерфейсы для работы с объектами кодеков, и также может использоваться в качестве основы для пользовательских реализаций кодеков.

Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в Python: статический кодировщик, статический декодер, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно используют статический кодировщик/декодер для реализации файловых протоколов. Разработчикам кодеков также необходимо определить, как кодек будет обрабатывать ошибки кодирования и декодирования.

### 7.2.1.1. Обработчики ошибок

Для упрощения и стандартизации обработки ошибок кодеки могут реализовывать различные схемы обработки ошибок, принимая строковый аргумент *errors*. Следующие строковые значения определены и реализованы всеми стандартными кодеками Python:

| Значение | Значение |
| --- | --- |
| `'strict'` | Возбуждает [`UnicodeError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeError) (или подкласс); это поведение по умолчанию. Реализовано в [`strict_errors()`](https://python-all.ru/3.4/library/codecs.html#codecs.strict_errors). |
| `'ignore'` | Игнорировать повреждённые данные и продолжить без дополнительных уведомлений. Реализовано в [`ignore_errors()`](https://python-all.ru/3.4/library/codecs.html#codecs.ignore_errors). |

Следующие обработчики ошибок применимы только к [*текстовым кодировкам*](https://python-all.ru/3.4/glossary.html#term-text-encoding):

| Значение | Значение |
| --- | --- |
| `'replace'` | Заменять подходящим замещающим символом; Python использует официальный `U+FFFD` REPLACEMENT CHARACTER для встроенных кодеков при декодировании и '?' при кодировании. Реализовано в [`replace_errors()`](https://python-all.ru/3.4/library/codecs.html#codecs.replace_errors). |
| `'xmlcharrefreplace'` | Заменять соответствующей XML-ссылкой на символ (только для кодирования). Реализовано в [`xmlcharrefreplace_errors()`](https://python-all.ru/3.4/library/codecs.html#codecs.xmlcharrefreplace_errors). |
| `'backslashreplace'` | Заменять escape-последовательностями с обратной косой чертой (только для кодирования). Реализовано в [`backslashreplace_errors()`](https://python-all.ru/3.4/library/codecs.html#codecs.backslashreplace_errors). |
| `'surrogateescape'` | При декодировании заменять байт на отдельный суррогатный код в диапазоне от `U+DC80` до `U+DCFF`. Затем этот код будет преобразован обратно в тот же байт, когда обработчик ошибок `'surrogateescape'` используется при кодировании данных. (Подробнее см. [**PEP 383**](https://python-all.ru/3.4/library/codecs.html).) |

Кроме того, следующий обработчик ошибок специфичен для указанных кодеков:

| Значение | Кодеки | Значение |
| --- | --- | --- |
| `'surrogatepass'` | utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le | Разрешить кодирование и декодирование суррогатных кодов. Обычно эти кодеки рассматривают наличие суррогатов как ошибку. |

Новое в версии 3.1: Обработчики ошибок `'surrogateescape'` и `'surrogatepass'`.

Изменено в версии 3.4: Обработчик ошибок `'surrogatepass'` теперь работает с кодеками utf-16\* и utf-32\*.

Набор допустимых значений можно расширить, зарегистрировав новый именованный обработчик ошибок:

#### `codecs.register_error(name, error_handler)`

Регистрирует функцию обработки ошибок *error\_handler* под именем *name*. Аргумент *error\_handler* будет вызываться во время кодирования и декодирования в случае ошибки, когда в качестве параметра errors указано *name*.

При кодировании *error\_handler* будет вызван с экземпляром [`UnicodeEncodeError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeEncodeError), содержащим информацию о местоположении ошибки. Обработчик ошибок должен либо возбудить это или другое исключение, либо вернуть кортеж с заменой для некодируемой части ввода и позицией, с которой следует продолжить кодирование. Замена может быть либо [`str`](https://python-all.ru/3.4/library/stdtypes.html#str), либо [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes). Если замена – bytes, кодировщик просто скопирует их в выходной буфер. Если замена – строка, кодировщик закодирует замену. Кодирование продолжается с исходного ввода на указанной позиции. Отрицательные значения позиции обрабатываются как относительные относительно конца входной строки. Если результирующая позиция выходит за границы, будет возбуждено [`IndexError`](https://python-all.ru/3.4/library/exceptions.html#IndexError).

Декодирование и трансляция работают аналогично, за исключением того, что обработчику будет передан [`UnicodeDecodeError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeTranslateError), и что замена от обработчика ошибок будет помещена в выходные данные напрямую.

Ранее зарегистрированные обработчики ошибок (включая стандартные) можно найти по имени:

#### `codecs.lookup_error(name)`

Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.

Возбуждает [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError), если обработчик не найден.

Следующие стандартные обработчики ошибок также доступны как функции уровня модуля:

#### `codecs.strict_errors(exception)`

Реализует обработку ошибок `'strict'`: каждая ошибка кодирования или декодирования возбуждает [`UnicodeError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeError).

#### `codecs.replace_errors(exception)`

Реализует обработку ошибок `'replace'` (только для [*текстовых кодировок*](https://python-all.ru/3.4/glossary.html#term-text-encoding)): подставляет `'?'` для ошибок кодирования (кодируется кодеком), и `'\ufffd'` (символ замены Unicode) для ошибок декодирования.

#### `codecs.ignore_errors(exception)`

Реализует обработку ошибок `'ignore'`: повреждённые данные игнорируются и кодирование или декодирование продолжается без дополнительных уведомлений.

#### `codecs.xmlcharrefreplace_errors(exception)`

Реализует обработку ошибок `'xmlcharrefreplace'` (только для кодирования с [*текстовыми кодировками*](https://python-all.ru/3.4/glossary.html#term-text-encoding)): некодируемый символ заменяется соответствующей XML-ссылкой на символ.

#### `codecs.backslashreplace_errors(exception)`

Реализует обработку ошибок `'backslashreplace'` (только для кодирования с [*текстовыми кодировками*](https://python-all.ru/3.4/glossary.html#term-text-encoding)): некодируемый символ заменяется escape-последовательностью с обратной косой чертой.

### 7.2.1.2. Кодирование и декодирование без состояния

Базовый класс `Codec` определяет следующие методы, которые также задают функциональные интерфейсы кодировщика и декодировщика без состояния:

#### `Codec.encode(input[, errors])`

Кодирует объект *input* и возвращает кортеж (выходной объект, длина потреблённых данных). Например, [*кодирование текста*](https://python-all.ru/3.4/glossary.html#term-text-encoding) преобразует строковый объект в объект bytes, используя определённую кодировку символов (например, `cp1252` или `iso-8859-1`).

Аргумент *errors* определяет применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.

Этот метод не должен сохранять состояние в экземпляре `Codec`. Для кодеков, которым необходимо хранить состояние для эффективного кодирования, используйте [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter).

Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.

#### `Codec.decode(input[, errors])`

Декодирует объект *input* и возвращает кортеж (объект вывода, длина потреблённых данных). Например, для [*текстовой кодировки*](https://python-all.ru/3.4/glossary.html#term-text-encoding) декодирование преобразует объект bytes, закодированный с использованием определённой кодировки набора символов, в объект строки.

Для текстовых кодировок и кодеков bytes-to-bytes *input* должен быть объектом bytes или объектом, предоставляющим интерфейс буфера только для чтения – например, буферные объекты и файлы, отображаемые в память.

Аргумент *errors* определяет применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.

Этот метод не должен сохранять состояние в экземпляре `Codec`. Для кодеков, которым необходимо хранить состояние для эффективного декодирования, используйте [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader).

Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.

### 7.2.1.3. Инкрементальное кодирование и декодирование

Классы [`IncrementalEncoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalDecoder) предоставляют базовый интерфейс для пошагового кодирования и декодирования. Кодирование/декодирование входных данных выполняется не одним вызовом функции без сохранения состояния, а несколькими вызовами метода [`encode()`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalDecoder.decode) пошагового кодировщика/декодировщика. Пошаговый кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.

Объединённый результат вызовов метода [`encode()`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalDecoder.decode) совпадает с результатом, полученным при объединении всех отдельных входных данных в один и кодировании/декодировании этого входа с помощью функции без сохранения состояния.

#### 7.2.1.3.1. Объекты IncrementalEncoder

Класс [`IncrementalEncoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый кодировщик должен реализовать для совместимости с реестром кодеков Python.

#### `class codecs.IncrementalEncoder(errors='strict')`

Конструктор для экземпляра [`IncrementalEncoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalEncoder).

Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.

[`IncrementalEncoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalEncoder) может реализовывать различные схемы обработки ошибок, передавая аргумент *errors*. Допустимые значения перечислены в разделе [*Обработчики ошибок*](https://python-all.ru/3.4/library/codecs.html#error-handlers).

Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalEncoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalEncoder).

#### `encode(object[, final])`

Кодирует *object* (с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов [`encode()`](https://python-all.ru/3.4/library/codecs.html#codecs.encode), *final* должен быть истинным (по умолчанию – ложь).

#### `reset()`

Сбрасывает кодировщик в начальное состояние. Выходные данные отбрасываются: вызовите `.encode(object, final=True)`, передав при необходимости пустую байтовую строку или пустой текст, чтобы сбросить кодировщик и получить выходные данные.

#### `IncrementalEncoder.getstate()`

Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что `0` – это наиболее распространённое состояние. (Состояния, которые сложнее целых чисел, можно преобразовать в целое число, замаршализовав/запиклив состояние и кодируя байты результирующей строки в целое число).

#### `IncrementalEncoder.setstate(state)`

Устанавливает состояние кодировщика равным *state*. *state* должно быть состоянием кодировщика, возвращённым методом [`getstate()`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalEncoder.getstate).

#### 7.2.1.3.2. Объекты IncrementalDecoder

Класс [`IncrementalDecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый декодировщик должен реализовать для совместимости с реестром кодеков Python.

#### `class codecs.IncrementalDecoder(errors='strict')`

Конструктор для экземпляра [`IncrementalDecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalDecoder).

Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.

[`IncrementalDecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalDecoder) может реализовывать различные схемы обработки ошибок, передавая аргумент *errors*. Допустимые значения перечислены в разделе [*Обработчики ошибок*](https://python-all.ru/3.4/library/codecs.html#error-handlers).

Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalDecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalDecoder).

#### `decode(object[, final])`

Декодирует *object* (с учётом текущего состояния декодировщика) и возвращает результирующий декодированный объект. Если это последний вызов [`decode()`](https://python-all.ru/3.4/library/codecs.html#codecs.decode), *final* должен быть истинным (по умолчанию – ложь). Если *final* истинно, декодировщик должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).

#### `reset()`

Сбрасывает декодер в исходное состояние.

#### `getstate()`

Возвращает текущее состояние декодера. Это должен быть кортеж из двух элементов: первый – буфер, содержащий ещё не декодированные входные данные; второй – целое число, которое может содержать дополнительную информацию о состоянии. (Реализация должна гарантировать, что `0` является наиболее распространённой дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии равна `0`, должна быть возможность установить декодер в состояние без буферизованных входных данных и с `0` в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованных входных данных в декодер возвращала его в предыдущее состояние без вывода каких-либо данных. (Дополнительная информация о состоянии, более сложная, чем целые числа, может быть преобразована в целое число с помощью маршалинга/сериализации этой информации и кодирования байтов результирующей строки в целое число.)

#### `setstate(state)`

Устанавливает состояние декодировщика равным *state*. *state* должно быть состоянием декодировщика, возвращённым методом [`getstate()`](https://python-all.ru/3.4/library/codecs.html#codecs.IncrementalDecoder.getstate).

### 7.2.1.4. Потоковое кодирование и декодирование

Классы [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader) предоставляют общие рабочие интерфейсы, которые можно использовать для очень простой реализации новых подмодулей кодировок. Пример такой реализации можно найти в `encodings.utf_8`.

#### 7.2.1.4.1. Объекты StreamWriter

Класс [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый писатель должен определить для совместимости с реестром кодеков Python.

#### `class codecs.StreamWriter(stream, errors='strict')`

Конструктор экземпляра [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter).

Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.

Аргумент *поток данных* должен быть файлоподобным объектом, открытым для записи текстовых или двоичных данных, в зависимости от конкретного кодека.

[`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter) может реализовывать различные схемы обработки ошибок, передавая именованный аргумент *errors*. Обратитесь к разделу [*Обработчики ошибок*](https://python-all.ru/3.4/library/codecs.html#error-handlers), чтобы узнать о стандартных обработчиках ошибок, которые может поддерживать базовый потоковый кодек.

Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter).

#### `write(object)`

Записывает в поток закодированное содержимое объекта.

#### `writelines(list)`

Записывает объединённый список строк в поток (возможно, используя метод [`write()`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter.write)). Стандартные кодеки типа «байты-в-байты» не поддерживают этот метод.

#### `reset()`

Сбрасывает и переустанавливает буферы кодека, используемые для сохранения состояния.

Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.

В дополнение к указанным выше методам, [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от базового потока.

#### 7.2.1.4.2. Объекты StreamReader

Класс [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый читатель должен определить для совместимости с реестром кодеков Python.

#### `class codecs.StreamReader(stream, errors='strict')`

Конструктор экземпляра [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader).

Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.

Аргумент *поток данных* должен быть файлоподобным объектом, открытым для чтения текстовых или двоичных данных, в зависимости от конкретного кодека.

[`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader) может реализовывать различные схемы обработки ошибок, передавая именованный аргумент *errors*. Обратитесь к разделу [*Обработчики ошибок*](https://python-all.ru/3.4/library/codecs.html#error-handlers), чтобы узнать о стандартных обработчиках ошибок, которые может поддерживать базовый потоковый кодек.

Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader).

Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.4/library/codecs.html#codecs.register_error).

#### `read([size[, chars[, firstline]]])`

Декодирует данные из потока и возвращает результирующий объект.

Аргумент *chars* указывает количество декодированных кодовых точек или байтов для возврата. Метод [`read()`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader.read) никогда не вернёт больше данных, чем запрошено, но может вернуть меньше, если доступно недостаточно.

Аргумент *size* указывает примерное максимальное количество закодированных байт или кодовых точек для чтения при декодировании. Декодер может изменять этот параметр по своему усмотрению. Значение по умолчанию -1 означает чтение и декодирование максимально возможного объёма. Данный параметр предназначен для предотвращения необходимости декодировать огромные файлы за один шаг.

Флаг *firstline* указывает, что достаточно вернуть только первую строку, если на последующих строках возникают ошибки декодирования.

Метод должен использовать жадную стратегию чтения, то есть читать столько данных, сколько допускается определением кодировки и заданным размером; например, если в потоке доступны необязательные окончания кодировки или маркеры состояния, их также следует прочитать.

#### `readline([size[, keepends]])`

Читает одну строку из входного потока и возвращает декодированные данные.

*size*, если указан, передаётся как аргумент size в метод [`read()`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader.read) потока.

Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.

#### `readlines([sizehint[, keepends]])`

Читает все строки из входного потока данных и возвращает их в виде списка строк.

Окончания строк реализуются с помощью метода декодера кодека и включаются в элементы списка, если *keepends* имеет значение true.

*sizehint*, если указан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader.read) потока.

#### `reset()`

Сбрасывает буферы кодека, используемые для сохранения состояния.

Обратите внимание, что никакое перемещение позиции в потоке не должно выполняться. Этот метод предназначен в первую очередь для восстановления после ошибок декодирования.

В дополнение к указанным выше методам, [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от базового потока.

#### 7.2.1.4.3. Объекты StreamReaderWriter

[`StreamReaderWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReaderWriter) – это вспомогательный класс, который позволяет оборачивать потоки, работающие как в режиме чтения, так и в режиме записи.

Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.4/library/codecs.html#codecs.lookup), для создания экземпляра.

#### `class codecs.StreamReaderWriter(stream, Reader, Writer, errors)`

Создаёт экземпляр [`StreamReaderWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReaderWriter). *поток данных* должен быть файлоподобным объектом. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими интерфейсы [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter) соответственно. Обработка ошибок выполняется так же, как определено для потоковых читателей и писателей.

Экземпляры [`StreamReaderWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReaderWriter) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от базового потока.

#### 7.2.1.4.4. Объекты StreamRecoder

[`StreamRecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamRecoder) преобразует данные из одной кодировки в другую, что иногда полезно при работе с различными кодировочными средами.

Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.4/library/codecs.html#codecs.lookup), для создания экземпляра.

#### `class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors)`

Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamRecoder), реализующий двустороннее преобразование: *encode* и *decode* работают с внешним интерфейсом – данными, видимыми для кода, вызывающего `read()` и `write()`, а *Reader* и *Writer* работают с внутренним интерфейсом – данными в *stream*.

Эти объекты можно использовать для прозрачного перекодирования, например, из Latin-1 в UTF-8 и обратно.

Аргумент *поток данных* должен быть файлоподобным объектом.

Аргументы *encode* и *decode* должны соответствовать интерфейсу `Codec`. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими объекты, соответствующие интерфейсам [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter) соответственно.

Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.

Экземпляры [`StreamRecoder`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamRecoder) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.4/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока.

## 7.2.2. Кодировки и Unicode

Строки внутренне хранятся как последовательности кодовых точек в диапазоне `0x0`-`0x10FFFF`. (См. [**PEP 393**](https://python-all.ru/3.4/library/codecs.html) для подробностей реализации.) Когда строковый объект используется вне CPU и памяти, порядок байт (endianness) и то, как эти массивы хранятся в виде байтов, становится важным. Как и для других кодеков, сериализация строки в последовательность байтов называется *кодированием*, а восстановление строки из последовательности байтов – *декодированием*. Существует множество различных кодеков текстовой сериализации, которые в совокупности называются [*текстовыми кодировками*](https://python-all.ru/3.4/glossary.html#term-text-encoding).

Простейшая текстовая кодировка (называемая `'latin-1'` или `'iso-8859-1'`) сопоставляет кодовые точки 0-255 байтам `0x0`-`0xff`, что означает, что строковый объект, содержащий кодовые точки выше `U+00FF`, не может быть закодирован этим кодеком. Попытка вызовет [`UnicodeEncodeError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeEncodeError), который выглядит следующим образом (хотя детали сообщения об ошибке могут отличаться): `UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256)`.

Существует ещё одна группа кодировок (так называемые charmap-кодировки), которые выбирают другое подмножество всех кодовых точек Unicode и определяют, как эти кодовые точки сопоставляются байтам `0x0`-`0xff`. Чтобы увидеть, как это делается, просто откройте, например, `encodings/cp1252.py` (кодировку, которая в основном используется в Windows). Там есть строковая константа из 256 символов, показывающая, какой символ сопоставляется какому значению байта.

Все эти кодировки могут закодировать только 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` это обычный символ, который декодируется как любой другой.

Существует ещё одна кодировка, способная кодировать весь диапазон символов Unicode: UTF-8. UTF-8 – это 8-битная кодировка, а это значит, что в UTF-8 нет проблем с порядком байтов. Каждый байт в последовательности UTF-8 состоит из двух частей: битов маркера (самые старшие биты) и битов полезной нагрузки. Биты маркера представляют собой последовательность от нуля до четырёх битов `1`, за которой следует бит `0`. Символы Unicode кодируются следующим образом (где x – биты полезной нагрузки, которые при объединении дают символ Unicode):

| Диапазон | Кодировка |
| --- | --- |
| `U-00000000` ... `U-0000007F` | 0xxxxxxx |
| `U-00000080` ... `U-000007FF` | 110xxxxx 10xxxxxx |
| `U-00000800` ... `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |
| `U-00010000` ... `U-0010FFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |

Младший значащий бит символа Unicode – это самый правый бит x.

Поскольку UTF-8 – это 8-битная кодировка, BOM не требуется, и любой символ `U+FEFF` в декодированной строке (даже если это первый символ) трактуется как `ZERO WIDTH NO-BREAK SPACE`.

Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Любая 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-кодировке начинается с этих байтовых значений (которые, например, отображаются в

> ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЭРЕЗИСОМ
>
> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА
>
> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК

in 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.

## 7.2.3. Стандартные кодировки

Python поставляется с рядом встроенных кодеков, реализованных либо как функции на C, либо с помощью словарей в качестве таблиц отображения. В следующей таблице перечислены кодеки по именам, вместе с несколькими распространёнными псевдонимами и языками, для которых эта кодировка, вероятно, используется. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что варианты написания, отличающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами; поэтому, например, `'utf-8'` является допустимым псевдонимом для кодека `'utf_8'`.

**Особенность реализации CPython:** Некоторые распространённые кодировки могут обходить механизм поиска codecs для повышения производительности. Эти возможности оптимизации распознаются CPython только для ограниченного набора псевдонимов: utf-8, utf8, latin-1, latin1, iso-8859-1, mbcs (только Windows), ascii, utf-16 и utf-32. Использование альтернативных вариантов написания этих кодировок может привести к снижению скорости выполнения.

Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:

- набор символов ISO 8859
- кодовая страница Microsoft Windows, обычно полученная из набора символов 8859, но заменяющая управляющие символы дополнительными графическими символами
- кодовая страница IBM EBCDIC
- кодовая страница IBM PC, совместимая с ASCII

| Кодек | Псевдонимы | Языки |
| --- | --- | --- |
| ascii | 646, us-ascii | Английский |
| big5 | big5-tw, csbig5 | Китайский традиционный |
| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |
| cp037 | IBM037, IBM039 | Английский |
| cp273 | 273, IBM273, csIBM273 | Немецкий Новое в версии 3.4. |
| cp424 | EBCDIC-CP-HE, IBM424 | Иврит |
| cp437 | 437, IBM437 | Английский |
| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Западная Европа |
| cp720 |  | Арабский |
| cp737 |  | Греческий |
| cp775 | IBM775 | Балтийские языки |
| cp850 | 850, IBM850 | Западная Европа |
| cp852 | 852, IBM852 | Центральная и Восточная Европа |
| cp855 | 855, IBM855 | болгарский, белорусский, македонский, русский, сербский |
| cp856 |  | Иврит |
| cp857 | 857, IBM857 | Турецкий |
| cp858 | 858, IBM858 | Западная Европа |
| cp860 | 860, IBM860 | португальский |
| cp861 | 861, CP-IS, IBM861 | Исландский |
| cp862 | 862, IBM862 | Иврит |
| cp863 | 863, IBM863 | канадский |
| cp864 | IBM864 | Арабский |
| cp865 | 865, IBM865 | датский, норвежский |
| cp866 | 866, IBM866 | Русский |
| cp869 | 869, CP-GR, IBM869 | Греческий |
| cp874 |  | Тайский |
| cp875 |  | Греческий |
| cp932 | 932, ms932, mskanji, ms-kanji | Японский |
| cp949 | 949, ms949, uhc | Корейский |
| cp950 | 950, ms950 | Китайский традиционный |
| cp1006 |  | Урду |
| cp1026 | ibm1026 | Турецкий |
| cp1125 | 1125, ibm1125, cp866u, ruscii | Украинский Новое в версии 3.4. |
| cp1140 | ibm1140 | Западная Европа |
| cp1250 | windows-1250 | Центральная и Восточная Европа |
| cp1251 | windows-1251 | болгарский, белорусский, македонский, русский, сербский |
| cp1252 | windows-1252 | Западная Европа |
| cp1253 | windows-1253 | Греческий |
| cp1254 | windows-1254 | Турецкий |
| cp1255 | windows-1255 | Иврит |
| cp1256 | windows-1256 | Арабский |
| cp1257 | windows-1257 | Балтийские языки |
| cp1258 | windows-1258 | вьетнамский |
| cp65001 |  | Только Windows: Windows UTF-8 (`CP_UTF8`) Новое в версии 3.3. |
| euc\_jp | eucjp, ujis, u-jis | Японский |
| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |
| euc\_jisx0213 | eucjisx0213 | Японский |
| euc\_kr | euckr, корейский, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |
| gb2312 | chinese, csiso58gb231280, euc- cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso- ir-58 | Упрощённый китайский |
| gbk | 936, cp936, ms936 | Унифицированный китайский |
| gb18030 | gb18030-2000 | Унифицированный китайский |
| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |
| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |
| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |
| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |
| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |
| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |
| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |
| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |
| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |
| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |
| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |
| iso8859\_4 | iso-8859-4, latin4, L4 | Балтийские языки |
| iso8859\_5 | iso-8859-5, кириллица | болгарский, белорусский, македонский, русский, сербский |
| iso8859\_6 | iso-8859-6, арабский | Арабский |
| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |
| iso8859\_8 | iso-8859-8, иврит | Иврит |
| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |
| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |
| iso8859\_11 | iso-8859-11, тайская | Тайские языки |
| iso8859\_13 | iso-8859-13, latin7, L7 | Балтийские языки |
| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |
| iso8859\_15 | iso-8859-15, latin9, L9 | Западная Европа |
| iso8859\_16 | iso-8859-16, latin10, L10 | Юго-Восточная Европа |
| johab | cp1361, ms1361 | Корейский |
| koi8\_r |  | Русский |
| koi8\_u |  | Украинский |
| mac\_cyrillic | maccyrillic | болгарский, белорусский, македонский, русский, сербский |
| mac\_greek | macgreek | Греческий |
| mac\_iceland | maciceland | Исландский |
| mac\_latin2 | maclatin2, maccentraleurope | Центральная и Восточная Европа |
| mac\_roman | macroman, macintosh | Западная Европа |
| mac\_turkish | macturkish | Турецкий |
| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |
| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |
| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |
| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |
| utf\_32 | U32, utf32 | все языки |
| utf\_32\_be | UTF-32BE | все языки |
| utf\_32\_le | UTF-32LE | все языки |
| utf\_16 | U16, utf16 | все языки |
| utf\_16\_be | UTF-16BE | все языки |
| utf\_16\_le | UTF-16LE | все языки |
| utf\_7 | U7, unicode-1-1-utf-7 | все языки |
| utf\_8 | U8, UTF, utf8 | все языки |
| utf\_8\_sig |  | все языки |

Изменено в версии 3.4: Кодировщики utf-16\* и utf-32\* больше не допускают кодирования суррогатных кодовых точек (`U+D800`–`U+DFFF`). Декодеры utf-32\* больше не декодируют последовательности байтов, соответствующие суррогатным кодовым точкам.

## 7.2.4. Кодировки, специфичные для Python

Некоторые предопределенные кодеки специфичны для Python, поэтому их имена кодеков не имеют смысла за пределами Python. Они перечислены в таблицах ниже по типам ожидаемых входных и выходных данных (обратите внимание, что хотя текстовые кодировки являются наиболее распространенным вариантом использования кодеков, базовая инфраструктура кодеков поддерживает произвольные преобразования данных, а не только текстовые кодировки). Для асимметричных кодеков указанное назначение описывает направление кодирования.

### 7.2.4.1. Текстовые кодировки

Следующие кодеки обеспечивают кодирование [`str`](https://python-all.ru/3.4/library/stdtypes.html#str) в [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) и декодирование [*bytes-like object*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object) в [`str`](https://python-all.ru/3.4/library/stdtypes.html#str), аналогично кодировкам текста Unicode.

| Кодек | Псевдонимы | Назначение |
| --- | --- | --- |
| idna |  | Реализует [**RFC 3490**](https://python-all.ru/3.4/library/codecs.html), см. также [`encodings.idna`](https://python-all.ru/3.4/library/codecs.html#module-encodings.idna). Поддерживается только `errors='strict'`. |
| mbcs | dbcs | Только Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |
| palmos |  | Кодировка PalmOS 3.5 |
| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/3.4/library/codecs.html). Кодеки с состоянием не поддерживаются. |
| raw\_unicode\_escape |  | Кодировка Latin-1 с `\uXXXX` и `\UXXXXXXXX` для других кодовых точек. Существующие обратные косые черты никак не экранируются. Используется в протоколе pickle Python. |
| undefined |  | Вызывает исключение для всех преобразований, даже для пустых строк. Обработчик ошибок игнорируется. |
| unicode\_escape |  | Кодировка, подходящая для содержимого строкового литерала Unicode в исходном коде Python в кодировке ASCII, за исключением того, что кавычки не экранируются. Декодирует из исходного кода Latin-1. Имейте в виду, что исходный код Python на самом деле по умолчанию использует UTF-8. |
| unicode\_internal |  | Возвращает внутреннее представление операнда. Кодеки с состоянием не поддерживаются. Устарело с версии 3.3: Это представление устарело с появлением [**PEP 393**](https://python-all.ru/3.4/library/codecs.html). |

### 7.2.4.2. Двоичные преобразования

Следующие кодеки предоставляют двоичные преобразования: отображения [*bytes-like object*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object) в [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes). Они не поддерживаются [`bytes.decode()`](https://python-all.ru/3.4/library/stdtypes.html#bytes.decode) (который выдает только выход [`str`](https://python-all.ru/3.4/library/stdtypes.html#str)).

| Кодек | Псевдонимы | Назначение | Кодировщик / декодировщик |
| --- | --- | --- | --- |
| base64\_codec [\[1\]](https://python-all.ru/3.4/library/codecs.html#b64) | base64, base\_64 | Преобразует операнд в многострочный MIME base64 (результат всегда включает завершающий `'\n'`) Изменено в версии 3.4: принимает любой [*объект, подобный байтовой строке*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object) в качестве входных данных для кодирования и декодирования | [`base64.encodebytes()`](https://python-all.ru/3.4/library/base64.html#base64.encodebytes) / [`base64.decodebytes()`](https://python-all.ru/3.4/library/base64.html#base64.decodebytes) |
| bz2\_codec | bz2 | Сжимает операнд с помощью bz2 | [`bz2.compress()`](https://python-all.ru/3.4/library/bz2.html#bz2.compress) / [`bz2.decompress()`](https://python-all.ru/3.4/library/bz2.html#bz2.decompress) |
| hex\_codec | hex | Преобразует операнд в шестнадцатеричное представление, по два разряда на байт | [`binascii.b2a_hex()`](https://python-all.ru/3.4/library/binascii.html#binascii.b2a_hex) / [`binascii.a2b_hex()`](https://python-all.ru/3.4/library/binascii.html#binascii.a2b_hex) |
| quopri\_codec | quopri, quotedprintable, quoted\_printable | Преобразует операнд в MIME quoted-printable | [`quopri.encode()`](https://python-all.ru/3.4/library/quopri.html#quopri.encode) с `quotetabs=True` / [`quopri.decode()`](https://python-all.ru/3.4/library/quopri.html#quopri.decode) |
| uu\_codec | uu | Преобразует операнд с помощью uuencode | [`uu.encode()`](https://python-all.ru/3.4/library/uu.html#uu.encode) /\\n[`uu.decode()`](https://python-all.ru/3.4/library/uu.html#uu.decode) |
| zlib\_codec | zip, zlib | Сжимает операнд с помощью gzip | [`zlib.compress()`](https://python-all.ru/3.4/library/zlib.html#zlib.compress) /\\n[`zlib.decompress()`](https://python-all.ru/3.4/library/zlib.html#zlib.decompress) |

| [\[1\]](https://python-all.ru/3.4/library/codecs.html#id5) | Помимо [*байтоподобных объектов*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object),\\n`'base64_codec'` также принимает для декодирования экземпляры [`str`](https://python-all.ru/3.4/library/stdtypes.html#str), содержащие только ASCII |
| --- | --- |

Новое в версии 3.2: Восстановление бинарных преобразований.

Изменено в версии 3.4: Восстановление псевдонимов для двоичных преобразований.

### 7.2.4.3. Текстовые преобразования

Следующий кодек предоставляет текстовое преобразование: отображение [`str`](https://python-all.ru/3.4/library/stdtypes.html#str) в [`str`](https://python-all.ru/3.4/library/stdtypes.html#str).\\nОно не поддерживается [`str.encode()`](https://python-all.ru/3.4/library/stdtypes.html#str.encode) (который выдает только [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes))

| Кодек | Псевдонимы | Назначение |
| --- | --- | --- |
| rot\_13 | rot13 | Возвращает шифрование Цезаря операнда |

Новое в версии 3.2: Восстановление текстового преобразования `rot_13`.

Изменено в версии 3.4: Восстановление псевдонима `rot13`.

## 7.2.5. [`encodings.idna`](https://python-all.ru/3.4/library/codecs.html#module-encodings.idna) – Интернационализированные доменные имена в приложениях

Этот модуль реализует [**RFC 3490**](https://python-all.ru/3.4/library/codecs.html) (Интернационализированные доменные имена в приложениях) и [**RFC 3492**](https://python-all.ru/3.4/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/3.4/library/stringprep.html#module-stringprep).

Вместе эти RFC определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (такое как `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, например, `www.xn--alliancefranaise-npb.nu`). Затем форма ACE доменного имени используется везде, где протокол не допускает произвольные символы, например, в DNS-запросах, полях HTTP *Host* и т.д. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки Unicode-доменов в IDNA при передаче и обратно преобразовывать метки ACE в Unicode перед отображением пользователю.

Python поддерживает это преобразование несколькими способами: кодек `idna` выполняет преобразование между Unicode и ACE, разделяя входную строку на метки на основе символов-разделителей, определенных в [разделе 3.1](https://python-all.ru/3.4/library/codecs.html) (1) документа [**RFC 3490**](https://python-all.ru/3.4/library/codecs.html), и преобразуя каждую метку в ACE по мере необходимости, и, наоборот, разделяя входную байтовую строку на метки на основе разделителя `.` и преобразуя любые найденные метки ACE в Unicode. Кроме того, модуль [`socket`](https://python-all.ru/3.4/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно беспокоиться о преобразовании имен хостов при передаче их в модуль socket. Вдобавок, модули, которые принимают имена хостов в качестве параметров функций, такие как [`http.client`](https://python-all.ru/3.4/library/http.client.html#module-http.client) и [`ftplib`](https://python-all.ru/3.4/library/ftplib.html#module-ftplib), принимают Unicode-имена хостов (при этом [`http.client`](https://python-all.ru/3.4/library/http.client.html#module-http.client) также прозрачно отправляет IDNA-имя хоста в поле *Host*, если вообще отправляет это поле).

При получении имён хостов из сети (например, при обратном поиске имени) автоматическое преобразование в Unicode не выполняется: приложения, желающие отобразить такие имена хостов пользователю, должны декодировать их в Unicode.

Модуль [`encodings.idna`](https://python-all.ru/3.4/library/codecs.html#module-encodings.idna) также реализует процедуру nameprep, которая выполняет определенные нормализации имен хостов для достижения нечувствительности к регистру интернационализированных доменных имен и унификации похожих символов. Функции nameprep можно использовать напрямую при желании.

#### `encodings.idna.nameprep(label)`

Return the nameprepped version of *label*. The implementation currently assumes query strings, so `AllowUnassigned` is true.

#### `encodings.idna.ToASCII(label)`

Преобразует метку в ASCII, как указано в [**RFC 3490**](https://python-all.ru/3.4/library/codecs.html). Параметр `UseSTD3ASCIIRules` предполагается равным false.

#### `encodings.idna.ToUnicode(label)`

Преобразует метку в Unicode, как указано в [**RFC 3490**](https://python-all.ru/3.4/library/codecs.html).

## 7.2.6. [`encodings.mbcs`](https://python-all.ru/3.4/library/codecs.html#module-encodings.mbcs) – Кодовая страница Windows ANSI

Кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP).

Доступность: только Windows.

Изменено в версии 3.3: Поддержка любого обработчика ошибок.

Изменено в версии 3.2: До версии 3.2 аргумент *errors* игнорировался; для кодирования всегда использовалось `'replace'`, а для декодирования – `'ignore'`.

## 7.2.7. [`encodings.utf_8_sig`](https://python-all.ru/3.4/library/codecs.html#module-encodings.utf_8_sig) – Кодек UTF-8 с сигнатурой BOM

Этот модуль реализует вариант кодека UTF-8: при кодировании префикс UTF-8 BOM будет добавлен перед байтами, закодированными в UTF-8. Для кодировщика с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный UTF-8 BOM в начале данных будет пропущен.