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

---

# 7.6. `codecs` – Реестр кодеков и базовые классы

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

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

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

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

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

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

*encode* и *decode*: это должны быть функции или методы с тем же интерфейсом, что и методы `encode()`/`decode()` экземпляров Codec (см. Codec Interface). Функции/методы должны работать в режиме без сохранения состояния.

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

> `factory(errors='strict')`

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

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

> `factory(поток данных, errors='strict')`

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

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

- `'strict'`: возбуждать исключение в случае ошибки кодирования
- `'replace'`: заменять повреждённые данные подходящим маркером замены, например `'?'` или `'\ufffd'`
- `'ignore'`: игнорировать повреждённые данные и продолжать без дополнительных уведомлений
- `'xmlcharrefreplace'`: заменять соответствующей символьной ссылкой XML (только для кодирования)
- `'backslashreplace'`: заменять escape-последовательностями с обратной косой чертой (только для кодирования)
- `'surrogateescape'`: заменить на суррогат U+DCxx, см. [**PEP 383**](https://python-all.ru/3.1/library/codecs.html)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Реализует обработку ошибок

`strict`

: каждая ошибка кодирования или декодирования возбуждает

[`UnicodeError`](https://python-all.ru/3.1/library/exceptions.html#UnicodeError)

.

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

Реализует обработку ошибок

`replace`

: повреждённые данные заменяются подходящим замещающим символом, таким как

`'?'`

в байтовых строках и

`'\ufffd'`

в строках Unicode.

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

Реализует обработку ошибок

`ignore`

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

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

Реализует обработку ошибок

`xmlcharrefreplace`

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

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

Реализует обработку ошибок

`backslashreplace`

(только для кодирования): некодируемый символ заменяется escape-последовательностью с обратной косой чертой.

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

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

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

> **Примечание**
>
> Методы обёрнутой версии будут принимать и возвращать только строки. Аргументы типа bytes будут отклонены.

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

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

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

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

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

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

Байты, записанные в обёрнутый файл, интерпретируются в соответствии с указанным *data\_encoding* и затем записываются в исходный файл как байты с использованием *file\_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.1/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.1/glossary.html#term-generator)

.

*errors*

(а также любые другие именованные аргументы) передаётся инкрементальному кодировщику.

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

Использует инкрементальный декодер для итеративного декодирования входных данных, предоставленных

*iterator*

. Эта функция является

[*генератором*](https://python-all.ru/3.1/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.1/library/codecs.html#codecs.BOM_UTF16)

– это либо

[`BOM_UTF16_BE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16_BE)

, либо

[`BOM_UTF16_LE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16_LE)

в зависимости от родного порядка байтов платформы;

[`BOM`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM)

является псевдонимом для

[`BOM_UTF16`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16)

,

[`BOM_LE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_LE)

– для

[`BOM_UTF16_LE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16_LE)

, а

[`BOM_BE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_BE)

– для

[`BOM_UTF16_BE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16_BE)

. Остальные представляют BOM в кодировках UTF-8 и UTF-32.

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

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

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

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

Для упрощения и стандартизации обработки ошибок методы `encode()` и `decode()` могут реализовывать различные схемы обработки ошибок с помощью строкового аргумента *errors*. Определены и реализованы следующие строковые значения для всех стандартных кодеков Python:

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

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

| Значение | Кодек | Значение |
| --- | --- | --- |
| `'surrogatepass'` | utf-8 | Разрешить кодирование и декодирование суррогатных кодов в UTF-8. |

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

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

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

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

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

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

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

Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.

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

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

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

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

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

Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.

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

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

Объединённый результат вызовов метода `encode()`/`decode()` совпадает с тем, который получился бы, если бы все отдельные входные данные были объединены в один и этот вход был закодирован/декодирован кодировщиком/декодировщиком без состояния.

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

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

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

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

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

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

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

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

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

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

Кодирует

*object*

(с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов

[`encode()`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalEncoder.encode)

,

*final*

должен быть истинным (по умолчанию – ложь).

#### `reset()`

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

#### `IncrementalEncoder.getstate()`

Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что

`0`

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

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

Устанавливает состояние кодировщика равным

*state*

.

*state*

должно быть состоянием кодировщика, возвращённым методом

[`getstate()`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalEncoder.getstate)

.

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

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

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

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

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

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

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

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

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

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

Декодирует

*object*

(с учётом текущего состояния декодировщика) и возвращает результирующий декодированный объект. Если это последний вызов

[`decode()`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder.decode)

,

*final*

должен быть истинным (по умолчанию – ложь). Если

*final*

истинно, декодировщик должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).

#### `reset()`

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

#### `getstate()`

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

`0`

является наиболее распространённой дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии равна

`0`

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

`0`

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

#### `setstate(state)`

Устанавливает состояние декодировщика равным

*state*

.

*state*

должно быть состоянием декодировщика, возвращённым методом

[`getstate()`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder.getstate)

.

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

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

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

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

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

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

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

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

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

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

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

#### `write(object)`

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

#### `writelines(list)`

Записывает объединённый список строк в поток данных (возможно, с повторным использованием метода

[`write()`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter.write)

).

#### `reset()`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#### `reset()`

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

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

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

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

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

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

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

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

Создаёт экземпляр

[`StreamReaderWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReaderWriter)

.

*поток данных*

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

*Reader*

и

*Writer*

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

[`StreamReader`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader)

и

[`StreamWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter)

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

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

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

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

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

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

Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/3.1/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/3.1/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter) соответственно.

*encode* и *decode* нужны для преобразования на фронтенде, а *Reader* и *Writer* – на бэкенде.

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

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

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

Строки внутренне хранятся как последовательности кодовых точек (точнее, как массивы [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)). В зависимости от того, как скомпилирован Python (с помощью `--without-wide-unicode` или `--with-wide-unicode`, и по умолчанию используется первый вариант) [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) является 16- или 32-битным типом данных. Как только строковый объект выходит за пределы CPU и памяти, порядок байтов CPU и то, как эти массивы хранятся в виде байтов, становится проблемой. Преобразование строкового объекта в последовательность байтов называется кодированием, а восстановление строкового объекта из последовательности байтов – декодированием. Существует множество различных методов выполнения этого преобразования (эти методы также называются кодировками). Простейший метод – сопоставить кодовым точкам 0-255 байты `0x0`-`0xff`. Это означает, что строковый объект, содержащий кодовые точки выше `U+00FF`, не может быть закодирован этим методом (который называется `'latin-1'` или `'iso-8859-1'`). [`str.encode()`](https://python-all.ru/3.1/library/stdtypes.html#str.encode) вызовет исключение [`UnicodeEncodeError`](https://python-all.ru/3.1/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 из 65536 (или 1114111) кодовых точек, определённых в Unicode. Простой и понятный способ хранить каждую кодовую точку Unicode – хранить её как два последовательных байта. Есть две возможности: хранить байты в порядке от старшего к младшему (big endian) или от младшего к старшему (little endian). Эти две кодировки называются UTF-16-BE и UTF-16-LE соответственно. Их недостаток в том, что если, например, использовать UTF-16-BE на машине с little endian, то при кодировании и декодировании придётся постоянно переставлять байты. UTF-16 позволяет избежать этой проблемы: байты всегда будут в естественном порядке. Однако, когда эти байты считываются процессором с другим порядком байт, их всё равно придётся переставлять. Чтобы можно было определить порядок байт последовательности UTF-16, существует так называемая метка порядка байт (BOM – Byte Order Mark). Это символ Unicode `U+FEFF`. Этот символ добавляется в начало каждой последовательности байт UTF-16. Версия этого символа с переставленными байтами (`0xFFFE`) является недопустимым символом и не может встречаться в тексте Unicode. Поэтому если первый символ в последовательности байт UTF-16 оказывается `U+FFFE`, то при декодировании байты нужно переставить. К сожалению, вплоть до Unicode 4.0 символ `U+FEFF` имел второе назначение – `НУЛЕВОЙ ШИРИНЫ НЕРАЗРЫВНЫЙ ПРОБЕЛ`: символ, не имеющий ширины и не допускающий разрыва слова. Его можно было использовать, например, для подсказок алгоритму лигатур. Начиная с Unicode 4.0 использование `U+FEFF` в качестве `НУЛЕВОЙ ШИРИНЫ НЕРАЗРЫВНЫЙ ПРОБЕЛ` устарело (эту роль взял на себя `U+2060` (`СЛОВ СОЕДИНИТЕЛЬ`)). Тем не менее, программное обеспечение Unicode всё ещё должно уметь обрабатывать `U+FEFF` в обеих ролях: как BOM это средство определения порядка хранения закодированных байтов, которое исчезает после декодирования последовательности байтов в строку; как `НУЛЕВОЙ ШИРИНЫ НЕРАЗРЫВНЫЙ ПРОБЕЛ` это обычный символ, который декодируется как любой другой.

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

| Диапазон | Кодировка |
| --- | --- |
| `U-00000000` ... `U-0000007F` | 0xxxxxxx |
| `U-00000080` ... `U-000007FF` | 110xxxxx 10xxxxxx |
| `U-00000800` ... `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |
| `U-00010000` ... `U-001FFFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |
| `U-00200000` ... `U-03FFFFFF` | 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |
| `U-04000000` ... `U-7FFFFFFF` | 1111110x 10xxxxxx 10xxxxxx 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 С ДИЭРЕЗИСОМ
>
> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА
>
> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК

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

## 7.6.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 | Западная Европа |
| cp737 |  | Греческий |
| cp775 | IBM775 | Балтийские языки |
| cp850 | 850, IBM850 | Западная Европа |
| cp852 | 852, IBM852 | Центральная и Восточная Европа |
| cp855 | 855, IBM855 | болгарский, белорусский, македонский, русский, сербский |
| cp856 |  | Иврит |
| cp857 | 857, IBM857 | Турецкий |
| 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\_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 |  | все языки |

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

## 7.6.4. `encodings.idna` – Интернационализированные доменные имена в приложениях

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

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

Модуль `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.1/library/codecs.html)

. Параметр

`UseSTD3ASCIIRules`

предполагается равным false.

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

Преобразует метку в Unicode, как указано в

[**RFC 3490**](https://python-all.ru/3.1/library/codecs.html)

.

## 7.6.5. `encodings.utf_8_sig` – UTF-8 кодек с сигнатурой BOM

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