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

---

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

Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодеков и обработки ошибок.

Он определяет следующие функции:

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

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

*Errors* may be given to set the desired error handling scheme. The default error handler is `'strict'` meaning that encoding errors raise [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (or a more codec specific subclass, such as [`UnicodeEncodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeEncodeError)). Refer to [Codec Base Classes](https://python-all.ru/2.7/library/codecs.html#codec-base-classes) for more information on codec error handling.

Новое в версии 2.4.

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

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

*Errors* may be given to set the desired error handling scheme. The default error handler is `'strict'` meaning that decoding errors raise [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (or a more codec specific subclass, such as [`UnicodeDecodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeDecodeError)). Refer to [Codec Base Classes](https://python-all.ru/2.7/library/codecs.html#codec-base-classes) for more information on codec error handling.

Новое в версии 2.4.

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

Регистрирует функцию поиска кодека. Функции поиска должны принимать один аргумент – имя кодировки строчными буквами, и возвращать объект `CodecInfo` со следующими атрибутами:

- `name` Имя кодировки;
- `encode` Функция кодирования без сохранения состояния;
- `decode` Функция декодирования без сохранения состояния;
- `incrementalencoder` Инкрементальный класс кодировщика или фабричная функция;
- `incrementaldecoder` Инкрементальный класс декодировщика или фабричная функция;
- `streamwriter` Класс потокового писателя или фабричная функция;
- `streamreader` Класс потокового читателя или фабричная функция.

Различные функции или классы принимают следующие аргументы:

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

*incrementalencoder* и *incrementaldecoder*: это должны быть фабричные функции, предоставляющие следующий интерфейс:

> `factory(errors='strict')`

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

*streamreader* и *streamwriter*: это должны быть фабричные функции, предоставляющие следующий интерфейс:

> `factory(stream, errors='strict')`

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

Возможные значения параметра errors:

- `'strict'`: возбуждать исключение в случае ошибки кодирования
- `'replace'`: заменять повреждённые данные подходящим замещающим маркером, например `'?'` или `'\ufffd'`
- `'ignore'`: игнорировать повреждённые данные и продолжать без дополнительных уведомлений
- `'xmlcharrefreplace'`: заменять соответствующей XML-ссылкой на символ (только для кодирования)
- `'backslashreplace'`: заменять экранированными последовательностями с обратной косой чертой (только для кодирования)

а также любое другое имя обработчика ошибок, определённое через [`register_error()`](https://python-all.ru/2.7/library/codecs.html#codecs.register_error).

Если функция поиска не может найти заданную кодировку, она должна вернуть `None`.

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

Ищет информацию о кодеке в реестре кодеков Python и возвращает объект `CodecInfo`, как определено выше.

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

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

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

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

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

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

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

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

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

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

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

Новое в версии 2.5.

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

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

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

Новое в версии 2.5.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Реализует обработку ошибок `replace`: повреждённые данные заменяются подходящим замещающим символом, таким как `'?'` в байтовых строках и `'\ufffd'` в строках Unicode.

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

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

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

Реализует обработку ошибок `xmlcharrefreplace` (только для кодирования): не кодируемый символ заменяется соответствующей XML-ссылкой на символ.

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

Реализует обработку ошибок `backslashreplace` (только для кодирования): не кодируемый символ заменяется управляющей последовательностью с обратной косой чертой.

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

#### `codecs.open(filename, mode[, encoding[, errors[, buffering]]])`

Открывает закодированный файл, используя заданный *режим*, и возвращает обёрнутую версию, обеспечивающую прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, то есть файл открывается в режиме чтения.

> **Примечание**
>
> Обёрнутая версия принимает только формат объектов, определённый кодеками, то есть объекты Unicode для большинства встроенных кодеков. Вывод также зависит от кодека и обычно тоже будет Unicode.

> **Примечание**
>
> Файлы всегда открываются в двоичном режиме, даже если двоичный режим не был указан. Это сделано для предотвращения потери данных из-за кодировок, использующих 8-битные значения. Это означает, что при чтении и записи не выполняется автоматическое преобразование `'\n'`.

*encoding* задаёт кодировку, которая будет использоваться для файла.

Параметр *errors* можно задать для определения обработки ошибок. По умолчанию он равен `'strict'`, что приводит к возбуждению [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) при возникновении ошибки кодирования.

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

#### `codecs.EncodedFile(file, input[, output[, errors]])`

Возвращает обёрнутую версию файла, которая обеспечивает прозрачное преобразование кодировки.

Строки, записываемые в обёрнутый файл, интерпретируются в соответствии с заданной кодировкой *input*, а затем записываются в исходный файл как строки с использованием кодировки *output*. Промежуточная кодировка обычно будет Unicode, но зависит от указанных кодеков.

Если *output* не задан, по умолчанию используется *input*.

*errors* может быть задан для определения обработки ошибок. По умолчанию `'strict'`, что приводит к возбуждению [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) в случае ошибки кодирования.

#### `codecs.iterencode(iterable, encoding[, errors])`

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

Новое в версии 2.5.

#### `codecs.iterdecode(iterable, encoding[, errors])`

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

Новое в версии 2.5.

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

#### `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`

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

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

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

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

Класс `Codec` определяет интерфейс для кодеров/декодеров без состояния.

Для упрощения и стандартизации обработки ошибок методы [`encode()`](https://python-all.ru/2.7/library/codecs.html#codecs.Codec.encode) и [`decode()`](https://python-all.ru/2.7/library/codecs.html#codecs.Codec.decode) могут реализовывать различные схемы обработки ошибок, принимая строковый аргумент *errors*. Следующие строковые значения определены и реализованы во всех стандартных кодеках Python:

| Значение | Значение |
| --- | --- |
| `'strict'` | Возбуждать [`UnicodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeError) (или подкласс); это поведение по умолчанию. |
| `'ignore'` | Игнорирует символ и продолжает со следующего. |
| `'replace'` | Заменяет подходящим заменяющим символом; для встроенных кодеков Unicode при декодировании Python будет использовать официальный U+FFFD REPLACEMENT CHARACTER, а при кодировании – '?'. |
| `'xmlcharrefreplace'` | Заменяет соответствующей символьной ссылкой XML (только для кодирования). |
| `'backslashreplace'` | Заменяет escape-последовательностями с обратной косой чертой (только для кодирования). |

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

### 7.8.1.1. Объекты кодеков

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

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

Кодирует объект *input* и возвращает кортеж (выходной объект, количество использованных символов). Хотя кодеки не ограничены использованием с Unicode, в контексте Unicode кодирование преобразует объект Unicode в простую строку с использованием определённой кодировки набора символов (например, `cp1252` или `iso-8859-1`).

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

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

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

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

Декодирует объект *input* и возвращает кортеж (выходной объект, количество использованных символов). В контексте Unicode декодирование преобразует простую строку, закодированную с использованием определённой кодировки набора символов, в объект Unicode.

*input* должен быть объектом, который предоставляет слот буфера `bf_getreadbuf`. Строки Python, буферные объекты и файлы, отображённые в память, являются примерами объектов, предоставляющих этот слот.

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

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

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

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

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

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

Новое в версии 2.5.

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

#### `class codecs.IncrementalEncoder([errors])`

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

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

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

- `'strict'` Возбуждать [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (или подкласс); это по умолчанию.
- `'ignore'` Игнорировать символ и продолжить со следующим.
- `'replace'` Заменить подходящим заменяющим символом
- `'xmlcharrefreplace'` Заменить соответствующей XML-ссылкой на символ
- `'backslashreplace'` Заменить управляющими последовательностями с обратной косой чертой.

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

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

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

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

#### `reset()`

Сбрасывает кодировщик в начальное состояние.

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

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

#### `class codecs.IncrementalDecoder([errors])`

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

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

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

- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (или подкласс); используется по умолчанию.
- `'ignore'` Пропускает символ и переходит к следующему.
- `'replace'` Заменяет подходящим символом-заменителем.

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

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

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

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

#### `reset()`

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

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

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

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

#### `class codecs.StreamWriter(stream[, errors])`

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

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

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

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

- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (или подкласс); используется по умолчанию.
- `'ignore'` Пропускает символ и переходит к следующему.
- `'replace'` Заменяет подходящим символом-заменителем
- `'xmlcharrefreplace'` Заменяет соответствующей ссылкой на символ XML
- `'backslashreplace'` Заменяет экранированными последовательностями с обратной косой чертой.

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

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

#### `write(object)`

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

#### `writelines(list)`

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

#### `reset()`

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

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

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

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

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

#### `class codecs.StreamReader(stream[, errors])`

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

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

*поток данных* должен быть файлоподобным объектом, открытым для чтения (двоичных) данных.

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

- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (или подкласс); используется по умолчанию.
- `'ignore'` Пропускает символ и переходит к следующему.
- `'replace'` Заменяет подходящим символом-заменителем.

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

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

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

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

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

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

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

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

Изменено в версии 2.4: добавлен аргумент *chars*.

Изменено в версии 2.4.2: добавлен аргумент *firstline*.

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

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

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

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

Изменено в версии 2.4: добавлен аргумент *keepends*.

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

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

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

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

#### `reset()`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

*encode* и *decode* нужны для преобразования на внешнем уровне, а *Reader* и *Writer* – на внутреннем. Используемый промежуточный формат определяется двумя наборами кодеков; например, кодеки Unicode будут использовать Unicode как промежуточную кодировку.

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

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

## 7.8.2. Кодировки и Юникод

Строки Unicode внутри хранятся как последовательности кодовых точек (если точнее, как массивы [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE)). В зависимости от того, как собран Python (через `--enable-unicode=ucs2` или `--enable-unicode=ucs4`, причём первое используется по умолчанию), [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) может быть 16-битным или 32-битным типом данных. Когда объект Unicode используется за пределами CPU и памяти, порядок байт (endianness) и способ хранения массивов в виде байтов становятся важными. Преобразование объекта Unicode в последовательность байтов называется кодированием, а восстановление объекта Unicode из последовательности байтов – декодированием. Существует много различных способов такого преобразования (они также называются кодировками). Простейший метод – сопоставить кодовые точки 0–255 байтам `0x0`–`0xff`. Это означает, что объект Unicode, содержащий кодовые точки выше `U+00FF`, нельзя закодировать этим методом (который называется `'latin-1'` или `'iso-8859-1'`). `unicode.encode()` возбудит исключение [`UnicodeEncodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeEncodeError), которое выглядит так: `UnicodeEncodeError: 'latin-1' codec can't encode character u'\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 (метка порядка байтов). Это символ 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 это средство определения порядка хранения закодированных байтов, которое исчезает после декодирования последовательности в строку Unicode; как `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` символ в dекодированной строке Unicode (даже если это первый символ) рассматривается как `ZERO WIDTH NO-BREAK SPACE`.

Без дополнительной информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки Unicode. Любая 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 С ДИЭРЕЗИСОМ
>
> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА
>
> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК

в iso-8859-1) это увеличивает вероятность того, что кодировка `utf-8-sig` может быть правильно определена по последовательности байтов. Таким образом, здесь BOM используется не для определения порядка байтов, используемого при формировании последовательности байтов, а как сигнатура, помогающая угадать кодировку. При кодировании кодек utf-8-sig запишет `0xef`, `0xbb`, `0xbf` как первые три байта в файл. При декодировании `utf-8-sig` пропустит эти три байта, если они стоят в начале файла. В UTF-8 использование BOM не рекомендуется и, как правило, его следует избегать.

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

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

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

- набор символов 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 | Английский |
| 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 | Турецкий |
| 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 | вьетнамский |
| 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 | Западная Европа |
| 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 | все языки (только BMP) |
| utf\_16\_le | UTF-16LE | все языки (только BMP) |
| utf\_7 | U7, unicode-1-1-utf-7 | все языки |
| utf\_8 | U8, UTF, utf8 | все языки |
| utf\_8\_sig |  | все языки |

## 7.8.4. Специфические кодировки Python

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

Следующие кодеки обеспечивают кодирование из Unicode в str [1](https://python-all.ru/2.7/library/codecs.html#encoding-note) и декодирование из str в Unicode [2](https://python-all.ru/2.7/library/codecs.html#decoding-note), аналогично кодировкам текста Unicode.

| Кодек | Псевдонимы | Назначение |
| --- | --- | --- |
| idna |  | Реализует [**RFC 3490**](https://python-all.ru/2.7/library/codecs.html), см. также [`encodings.idna`](https://python-all.ru/2.7/library/codecs.html#module-encodings.idna) |
| mbcs | dbcs | Только Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |
| palmos |  | Кодировка PalmOS 3.5 |
| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/2.7/library/codecs.html) |
| raw\_unicode\_escape |  | Создаёт строку, пригодную для использования в качестве сырого Unicode-литерала в исходном коде Python |
| rot\_13 | rot13 | Возвращает шифрование Цезаря операнда |
| undefined |  | Вызывает исключение для всех преобразований. Может использоваться как системная кодировка, если автоматическое [приведение](https://python-all.ru/2.7/glossary.html#term-coercion) между байтовыми строками и строками Unicode не требуется. |
| unicode\_escape |  | Создаёт строку, пригодную для использования в качестве Unicode-литерала в исходном коде Python |
| unicode\_internal |  | Возвращает внутреннее представление операнда |

Новое в версии 2.3: Кодировки `idna` и `punycode`.

Следующие кодеки обеспечивают кодирование и декодирование из строки в строку [2](https://python-all.ru/2.7/library/codecs.html#decoding-note).

| Кодек | Псевдонимы | Назначение | Кодировщик/декодировщик |
| --- | --- | --- | --- |
| base64\_codec | base64, base-64 | Преобразует операнд в многолинейный MIME base64 (результат всегда содержит завершающий `'\n'`) | [`base64.encodestring()`](https://python-all.ru/2.7/library/base64.html#base64.encodestring), [`base64.decodestring()`](https://python-all.ru/2.7/library/base64.html#base64.decodestring) |
| bz2\_codec | bz2 | Сжимает операнд с помощью bz2 | [`bz2.compress()`](https://python-all.ru/2.7/library/bz2.html#bz2.compress), [`bz2.decompress()`](https://python-all.ru/2.7/library/bz2.html#bz2.decompress) |
| hex\_codec | hex | Преобразует операнд в шестнадцатеричное представление, по два разряда на байт | [`binascii.b2a_hex()`](https://python-all.ru/2.7/library/binascii.html#binascii.b2a_hex), [`binascii.a2b_hex()`](https://python-all.ru/2.7/library/binascii.html#binascii.a2b_hex) |
| quopri\_codec | quopri, quoted-printable, quotedprintable | Преобразует операнд в MIME quoted-printable | [`quopri.encode()`](https://python-all.ru/2.7/library/quopri.html#quopri.encode) с `quotetabs=True`, [`quopri.decode()`](https://python-all.ru/2.7/library/quopri.html#quopri.decode) |
| string\_escape |  | Создаёт строку, подходящую в качестве строкового литерала в исходном коде Python |  |
| uu\_codec | uu | Преобразует операнд с помощью uuencode | [`uu.encode()`](https://python-all.ru/2.7/library/uu.html#uu.encode), [`uu.decode()`](https://python-all.ru/2.7/library/uu.html#uu.decode) |
| zlib\_codec | zip, zlib | Сжимает операнд с помощью gzip | [`zlib.compress()`](https://python-all.ru/2.7/library/zlib.html#zlib.compress), [`zlib.decompress()`](https://python-all.ru/2.7/library/zlib.html#zlib.decompress) |

**[1](https://python-all.ru/2.7/library/codecs.html#id4)**

Объекты str также принимаются в качестве входных данных вместо объектов unicode. Они неявно преобразуются в unicode путём декодирования с использованием кодировки по умолчанию. Если это преобразование не удаётся, операции кодирования могут вызвать [`UnicodeDecodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeDecodeError).

**2([1](https://python-all.ru/2.7/library/codecs.html#id5),[2](https://python-all.ru/2.7/library/codecs.html#id6))**

Объекты unicode также принимаются в качестве входных данных вместо объектов str. Они неявно преобразуются в str путём кодирования с использованием кодировки по умолчанию. Если это преобразование не удаётся, операции декодирования могут вызвать [`UnicodeEncodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeEncodeError).

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

Новое в версии 2.3.

Этот модуль реализует [**RFC 3490**](https://python-all.ru/2.7/library/codecs.html) (Internationalized Domain Names in Applications) и [**RFC 3492**](https://python-all.ru/2.7/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/2.7/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/2.7/library/codecs.html) (1) документа [**RFC 3490**](https://python-all.ru/2.7/library/codecs.html) и преобразуя каждую метку в ACE по мере необходимости, и, наоборот, разделяя входную байтовую строку на метки на основе разделителя `.` и преобразуя найденные метки ACE в Unicode. Кроме того, модуль [`socket`](https://python-all.ru/2.7/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно заботиться о преобразовании имён хостов при передаче их модулю socket. Вдобавок модули, которые принимают имена хостов в качестве параметров функций, такие как [`httplib`](https://python-all.ru/2.7/library/httplib.html#module-httplib) и [`ftplib`](https://python-all.ru/2.7/library/ftplib.html#module-ftplib), принимают Unicode-имена хостов ([`httplib`](https://python-all.ru/2.7/library/httplib.html#module-httplib) также прозрачно отправляет имя хоста в формате IDNA в поле *Host*, если оно вообще отправляет это поле).

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

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

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

Возвращает версию *label* после обработки nameprep. В текущей реализации предполагаются строки запроса, поэтому `AllowUnassigned` имеет значение истина.

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

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

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

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

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

Новое в версии 2.5.

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