`codecs.md`

665 строк · 77.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.2/library/codecs.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 6.6. [`codecs`](https://python-all.ru/3.2/library/codecs.html#module-codecs) – Реестр кодеков и базовые классы89Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодеков и обработки ошибок.1011Он определяет следующие функции:1213#### `codecs.register(search_function)`1415Регистрирует функцию поиска кодеков. Функции поиска должны принимать один аргумент – имя кодировки строчными буквами – и возвращать объект `CodecInfo` со следующими атрибутами:1617- `name` Имя кодировки;18- `encode` Функция кодирования без сохранения состояния;19- `decode` Функция декодирования без сохранения состояния;20- `incrementalencoder` Класс инкрементального кодировщика или фабричная функция;21- `incrementaldecoder` Класс инкрементального декодировщика или фабричная функция;22- `streamwriter` Класс потокового писателя или фабричная функция;23- `streamreader` Класс потокового читателя или фабричная функция.2425Различные функции или классы принимают следующие аргументы:2627*encode* и *decode*: это должны быть функции или методы с тем же интерфейсом, что и методы `encode()`/`decode()` экземпляров Codec (см. Codec Interface). Функции/методы должны работать в режиме без сохранения состояния.2829*incrementalencoder* и *incrementaldecoder*: это должны быть фабричные функции, предоставляющие следующий интерфейс:3031> `factory(errors='strict')`3233Фабричные функции должны возвращать объекты, предоставляющие интерфейсы, определённые базовыми классами [`IncrementalEncoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalDecoder), соответственно. Инкрементальные кодеки могут сохранять состояние.3435*streamreader* и *streamwriter*: это должны быть фабричные функции, предоставляющие следующий интерфейс:3637> `factory(поток данных, errors='strict')`3839Фабричные функции должны возвращать объекты, предоставляющие интерфейсы, определённые базовыми классами [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader) соответственно. Потоковые кодеки могут поддерживать состояние.4041Возможные значения параметра errors:4243- `'strict'`: возбуждать исключение в случае ошибки кодирования44- `'replace'`: заменять повреждённые данные подходящим маркером замены, например `'?'` или `'\ufffd'`45- `'ignore'`: игнорировать повреждённые данные и продолжать без дополнительных уведомлений46- `'xmlcharrefreplace'`: заменять соответствующей символьной ссылкой XML (только для кодирования)47- `'backslashreplace'`: заменять escape-последовательностями с обратной косой чертой (только для кодирования)48- `'surrogateescape'`: заменить на суррогат U+DCxx, см. [**PEP 383**](https://python-all.ru/3.2/library/codecs.html)4950а также любое другое имя обработчика ошибок, определённое через [`register_error()`](https://python-all.ru/3.2/library/codecs.html#codecs.register_error).5152Если функция поиска не может найти указанную кодировку, она должна вернуть `None`.5354#### `codecs.lookup(encoding)`5556Ищет информацию о кодеке в реестре кодеков Python и возвращает объект `CodecInfo`, как определено выше.5758Кодировки сначала ищутся в кеше реестра. Если не найдены, просматривается список зарегистрированных функций поиска. Если объект `CodecInfo` не найден, возбуждается [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError). В противном случае объект `CodecInfo` сохраняется в кеш и возвращается вызывающему.5960Для упрощения доступа к различным кодекам модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/3.2/library/codecs.html#codecs.lookup) для поиска кодека:6162#### `codecs.getencoder(encoding)`6364Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.6566Вызывает [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError), если кодировка не найдена.6768#### `codecs.getdecoder(encoding)`6970Находит кодек для указанной кодировки и возвращает его функцию-декодер.7172Вызывает [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError), если кодировка не найдена.7374#### `codecs.getincrementalencoder(encoding)`7576Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.7778Вызывает [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный кодировщик.7980#### `codecs.getincrementaldecoder(encoding)`8182Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.8384Вызывает [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный декодировщик.8586#### `codecs.getreader(encoding)`8788Находит кодек для указанной кодировки и возвращает его класс StreamReader или фабричную функцию.8990Вызывает [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError), если кодировка не найдена.9192#### `codecs.getwriter(encoding)`9394Находит кодек для указанной кодировки и возвращает его класс StreamWriter или фабричную функцию.9596Вызывает [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError), если кодировка не найдена.9798#### `codecs.register_error(name, error_handler)`99100Регистрирует функцию обработки ошибок *error\_handler* под именем *name*. *error\_handler* будет вызываться при кодировании и декодировании в случае ошибки, когда *name* указан как параметр errors.101102При кодировании *error\_handler* будет вызван с экземпляром [`UnicodeEncodeError`](https://python-all.ru/3.2/library/exceptions.html#UnicodeEncodeError), который содержит информацию о месте ошибки. Обработчик ошибок должен либо снова вызывать это исключение, либо другое, либо вернуть кортеж с заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Кодировщик закодирует замену и продолжит кодирование исходных данных с указанной позиции. Отрицательные значения позиции считаются относительно конца входной строки. Если результирующая позиция выходит за пределы, будет возбуждено [`IndexError`](https://python-all.ru/3.2/library/exceptions.html#IndexError).103104Декодирование и трансляция работают аналогично, за исключением того, что обработчику будет передан [`UnicodeDecodeError`](https://python-all.ru/3.2/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.2/library/exceptions.html#UnicodeTranslateError), и что замена от обработчика ошибок будет помещена в вывод напрямую.105106#### `codecs.lookup_error(name)`107108Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.109110Возбуждает [`LookupError`](https://python-all.ru/3.2/library/exceptions.html#LookupError), если обработчик не найден.111112#### `codecs.strict_errors(exception)`113114Реализует обработку ошибок `strict`: каждая ошибка кодирования или декодирования возбуждает [`UnicodeError`](https://python-all.ru/3.2/library/exceptions.html#UnicodeError).115116#### `codecs.replace_errors(exception)`117118Реализует обработку ошибок `replace`: повреждённые данные заменяются подходящим замещающим символом, таким как `'?'` в байтовых строках и `'\ufffd'` в строках Unicode.119120#### `codecs.ignore_errors(exception)`121122Реализует обработку ошибок `ignore`: повреждённые данные игнорируются и кодирование или декодирование продолжается без дальнейших уведомлений.123124#### `codecs.xmlcharrefreplace_errors(exception)`125126Реализует обработку ошибок `xmlcharrefreplace` (только для кодирования): некодируемый символ заменяется соответствующей символьной ссылкой XML.127128#### `codecs.backslashreplace_errors(exception)`129130Реализует обработку ошибок `backslashreplace` (только для кодирования): некодируемый символ заменяется escape-последовательностью с обратной косой чертой.131132Для упрощения работы с закодированными файлами или потоками модуль также определяет следующие вспомогательные функции:133134#### `codecs.open(filename, mode[, encoding[, errors[, buffering]]])`135136Открывает закодированный файл, используя указанный *mode*, и возвращает обёрнутую версию, обеспечивающую прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, что означает открытие файла в режиме чтения.137138> **Примечание**139>140> Методы обёрнутой версии будут принимать и возвращать только строки. Аргументы типа bytes будут отклонены.141142> **Примечание**143>144> Файлы всегда открываются в двоичном режиме, даже если двоичный режим не был указан. Это сделано для предотвращения потери данных из-за кодировок, использующих 8-битные значения. Это означает, что автоматическое преобразование `b'\n'` не выполняется при чтении и записи.145146*encoding* задаёт кодировку, которая будет использоваться для файла.147148*errors* may be given to define the error handling. It defaults to `'strict'` which causes a [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError) to be raised in case an encoding error occurs.149150Параметр *buffering* имеет то же значение, что и для встроенной функции [`open()`](https://python-all.ru/3.2/library/functions.html#open). По умолчанию используется построчная буферизация.151152#### `codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')`153154Возвращает обёрнутую версию файла, которая обеспечивает прозрачное преобразование кодировки.155156Байты, записанные в обёрнутый файл, интерпретируются в соответствии с указанным *data\_encoding* и затем записываются в исходный файл как байты с использованием *file\_encoding*.157158Если *file\_encoding* не указан, по умолчанию используется *data\_encoding*.159160*errors* may be given to define the error handling. It defaults to `'strict'`, which causes [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError) to be raised in case an encoding error occurs.161162#### `codecs.iterencode(iterator, encoding, errors='strict', **kwargs)`163164Использует инкрементальный кодировщик для итеративного кодирования входных данных, предоставленных *iterator*. Эта функция является [*генератором*](https://python-all.ru/3.2/glossary.html#term-generator). *errors* (а также любые другие именованные аргументы) передаётся инкрементальному кодировщику.165166#### `codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)`167168Использует инкрементальный декодер для итеративного декодирования входных данных, предоставленных *iterator*. Эта функция является [*генератором*](https://python-all.ru/3.2/glossary.html#term-generator). Параметр *errors* (а также любые другие ключевые аргументы) передаётся инкрементальному декодеру.169170Модуль также предоставляет следующие константы, полезные для чтения и записи в платформенно-зависимые файлы:171172#### `codecs.BOM`173174#### `codecs.BOM_BE`175176#### `codecs.BOM_LE`177178#### `codecs.BOM_UTF8`179180#### `codecs.BOM_UTF16`181182#### `codecs.BOM_UTF16_BE`183184#### `codecs.BOM_UTF16_LE`185186#### `codecs.BOM_UTF32`187188#### `codecs.BOM_UTF32_BE`189190#### `codecs.BOM_UTF32_LE`191192Эти константы определяют различные кодировки метки порядка байтов Unicode (BOM), используемые в потоках данных UTF-16 и UTF-32 для указания порядка байтов, используемого в потоке или файле, а в UTF-8 – как подпись Unicode. [`BOM_UTF16`](https://python-all.ru/3.2/library/codecs.html#codecs.BOM_UTF16) – это либо [`BOM_UTF16_BE`](https://python-all.ru/3.2/library/codecs.html#codecs.BOM_UTF16_BE), либо [`BOM_UTF16_LE`](https://python-all.ru/3.2/library/codecs.html#codecs.BOM_UTF16_LE) в зависимости от родного порядка байтов платформы; [`BOM`](https://python-all.ru/3.2/library/codecs.html#codecs.BOM) является псевдонимом для [`BOM_UTF16`](https://python-all.ru/3.2/library/codecs.html#codecs.BOM_UTF16), [`BOM_LE`](https://python-all.ru/3.2/library/codecs.html#codecs.BOM_LE) – для [`BOM_UTF16_LE`](https://python-all.ru/3.2/library/codecs.html#codecs.BOM_UTF16_LE), а [`BOM_BE`](https://python-all.ru/3.2/library/codecs.html#codecs.BOM_BE) – для [`BOM_UTF16_BE`](https://python-all.ru/3.2/library/codecs.html#codecs.BOM_UTF16_BE). Остальные представляют BOM в кодировках UTF-8 и UTF-32.193194## 6.6.1. Базовые классы кодеков195196Модуль [`codecs`](https://python-all.ru/3.2/library/codecs.html#module-codecs) определяет набор базовых классов, которые задают интерфейс и также могут использоваться для простого написания собственных кодеков для использования в Python.197198Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в качестве кодека в Python: статический кодировщик без состояния, статический декодировщик без состояния, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно повторно используют статический кодировщик/декодировщик без состояния для реализации файловых протоколов.199200Класс `Codec` определяет интерфейс для кодировщиков/декодировщиков без состояния.201202Для упрощения и стандартизации обработки ошибок методы `encode()` и `decode()` могут реализовывать различные схемы обработки ошибок с помощью строкового аргумента *errors*. Определены и реализованы следующие строковые значения для всех стандартных кодеков Python:203204| Значение | Значение |205| --- | --- |206| `'strict'` | Возбуждает [`UnicodeError`](https://python-all.ru/3.2/library/exceptions.html#UnicodeError) (или подкласс); это поведение по умолчанию. |207| `'ignore'` | Игнорирует символ и продолжает со следующего. |208| `'replace'` | Заменяет подходящим заменяющим символом; для встроенных кодеков Unicode при декодировании Python будет использовать официальный U+FFFD REPLACEMENT CHARACTER, а при кодировании – '?'. |209| `'xmlcharrefreplace'` | Заменяет соответствующей символьной ссылкой XML (только для кодирования). |210| `'backslashreplace'` | Заменяет escape-последовательностями с обратной косой чертой (только для кодирования). |211| `'surrogateescape'` | Заменяет байт суррогатом U+DCxx, как определено в [**PEP 383**](https://python-all.ru/3.2/library/codecs.html). |212213Кроме того, следующие обработчики ошибок специфичны для одного кодека:214215| Значение | Кодек | Значение |216| --- | --- | --- |217| `'surrogatepass'` | utf-8 | Разрешить кодирование и декодирование суррогатных кодов в UTF-8. |218219Новое в версии 3.1: Обработчики ошибок `'surrogateescape'` и `'surrogatepass'`.220221Набор допустимых значений может быть расширен через [`register_error()`](https://python-all.ru/3.2/library/codecs.html#codecs.register_error).222223### 6.6.1.1. Объекты кодеков224225Класс `Codec` определяет методы, которые также задают функциональные интерфейсы кодировщика и декодировщика без состояния:226227#### `Codec.encode(input[, errors])`228229Кодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Кодирование преобразует строковый объект в объект bytes с использованием определённой кодировки набора символов (например, `cp1252` или `iso-8859-1`).230231*errors* определяет способ обработки ошибок. По умолчанию используется `'strict'` режим.232233Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.234235Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.236237#### `Codec.decode(input[, errors])`238239Декодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Декодирование преобразует объект bytes, закодированный с помощью определённой кодировки набора символов, в строковый объект.240241*input* должен быть объектом bytes или объектом, предоставляющим интерфейс только для чтения символьного буфера – например, объекты буфера и файлы, отображаемые в память.242243*errors* определяет способ обработки ошибок. По умолчанию используется `'strict'` режим.244245Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.246247Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.248249Классы [`IncrementalEncoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalDecoder) предоставляют базовый интерфейс для инкрементального кодирования и декодирования. Кодирование/декодирование входных данных выполняется не одним вызовом функции кодировщика/декодировщика без сохранения состояния, а несколькими вызовами метода `encode()`/`decode()` инкрементального кодировщика/декодировщика. Инкрементальный кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.250251Объединённый результат вызовов метода `encode()`/`decode()` совпадает с тем, который получился бы, если бы все отдельные входные данные были объединены в один и этот вход был закодирован/декодирован кодировщиком/декодировщиком без состояния.252253### 6.6.1.2. Объекты IncrementalEncoder254255Класс [`IncrementalEncoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый кодировщик должен реализовать для совместимости с реестром кодеков Python.256257#### `class codecs.IncrementalEncoder([errors])`258259Конструктор для экземпляра [`IncrementalEncoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalEncoder).260261Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.262263[`IncrementalEncoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalEncoder) может реализовывать различные схемы обработки ошибок, передавая ключевой аргумент *errors*. Эти параметры предопределены:264265- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.266- `'ignore'` Игнорирует символ и продолжает со следующего.267- `'replace'` Заменяет подходящим заменяющим символом268- `'xmlcharrefreplace'` Заменяет соответствующей символьной ссылкой XML269- `'backslashreplace'` Заменяет управляющими последовательностями с обратной косой чертой.270271Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalEncoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalEncoder).272273Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.2/library/codecs.html#codecs.register_error).274275#### `encode(object[, final])`276277Кодирует *object* (с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов [`encode()`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalEncoder.encode), *final* должен быть истинным (по умолчанию – ложь).278279#### `reset()`280281Сбрасывает кодировщик в начальное состояние.282283#### `IncrementalEncoder.getstate()`284285Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что `0` – это наиболее распространённое состояние. (Состояния, которые сложнее целых чисел, можно преобразовать в целое число, замаршализовав/запиклив состояние и кодируя байты результирующей строки в целое число).286287#### `IncrementalEncoder.setstate(state)`288289Устанавливает состояние кодировщика равным *state*. *state* должно быть состоянием кодировщика, возвращённым методом [`getstate()`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalEncoder.getstate).290291### 6.6.1.3. Объекты IncrementalDecoder292293Класс [`IncrementalDecoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый декодировщик должен реализовать для совместимости с реестром кодеков Python.294295#### `class codecs.IncrementalDecoder([errors])`296297Конструктор для экземпляра [`IncrementalDecoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalDecoder).298299Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.300301[`IncrementalDecoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalDecoder) может реализовывать различные схемы обработки ошибок, передавая ключевой аргумент *errors*. Эти параметры предопределены:302303- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.304- `'ignore'` Игнорирует символ и продолжает со следующего.305- `'replace'` Заменяет подходящим заменяющим символом.306307Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalDecoder`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalDecoder).308309Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.2/library/codecs.html#codecs.register_error).310311#### `decode(object[, final])`312313Декодирует *object* (с учётом текущего состояния декодировщика) и возвращает результирующий декодированный объект. Если это последний вызов [`decode()`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalDecoder.decode), *final* должен быть истинным (по умолчанию – ложь). Если *final* истинно, декодировщик должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).314315#### `reset()`316317Сбрасывает декодер в исходное состояние.318319#### `getstate()`320321Возвращает текущее состояние декодера. Это должен быть кортеж из двух элементов: первый – буфер, содержащий ещё не декодированные входные данные; второй – целое число, которое может содержать дополнительную информацию о состоянии. (Реализация должна гарантировать, что `0` является наиболее распространённой дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии равна `0`, должна быть возможность установить декодер в состояние без буферизованных входных данных и с `0` в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованных входных данных в декодер возвращала его в предыдущее состояние без вывода каких-либо данных. (Дополнительная информация о состоянии, более сложная, чем целые числа, может быть преобразована в целое число с помощью маршалинга/сериализации этой информации и кодирования байтов результирующей строки в целое число.)322323#### `setstate(state)`324325Устанавливает состояние декодировщика равным *state*. *state* должно быть состоянием декодировщика, возвращённым методом [`getstate()`](https://python-all.ru/3.2/library/codecs.html#codecs.IncrementalDecoder.getstate).326327Классы [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader) предоставляют общие рабочие интерфейсы, которые можно использовать для очень простой реализации новых подмодулей кодировок. Пример такой реализации можно найти в `encodings.utf_8`.328329### 6.6.1.4. Объекты StreamWriter330331Класс [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый писатель должен определить для совместимости с реестром кодеков Python.332333#### `class codecs.StreamWriter(stream[, errors])`334335Конструктор экземпляра [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter).336337Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.338339*поток данных* должен быть файлоподобным объектом, открытым для записи двоичных данных.340341Класс [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Эти параметры предопределены:342343- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.344- `'ignore'` Игнорирует символ и продолжает со следующего.345- `'replace'` Заменяет подходящим заменяющим символом346- `'xmlcharrefreplace'` Заменяет соответствующей символьной ссылкой XML347- `'backslashreplace'` Заменяет управляющими последовательностями с обратной косой чертой.348349Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter).350351Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.2/library/codecs.html#codecs.register_error).352353#### `write(object)`354355Записывает в поток закодированное содержимое объекта.356357#### `writelines(list)`358359Записывает объединённый список строк в поток данных (возможно, с повторным использованием метода [`write()`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter.write)).360361#### `reset()`362363Сбрасывает и переустанавливает буферы кодека, используемые для сохранения состояния.364365Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.366367В дополнение к указанным выше методам, [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от базового потока.368369### 6.6.1.5. Объекты StreamReader370371Класс [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый читатель должен определить для совместимости с реестром кодеков Python.372373#### `class codecs.StreamReader(stream[, errors])`374375Конструктор экземпляра [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader).376377Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.378379*поток данных* должен быть файлоподобным объектом, открытым для чтения (двоичных) данных.380381Класс [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Эти параметры определены:382383- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.384- `'ignore'` Игнорирует символ и продолжает со следующего.385- `'replace'` Заменяет подходящим заменяющим символом.386387Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader).388389Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.2/library/codecs.html#codecs.register_error).390391#### `read([size[, chars[, firstline]]])`392393Декодирует данные из потока и возвращает результирующий объект.394395*chars* указывает количество символов для чтения из потока данных. [`read()`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader.read) никогда не вернёт больше *chars* символов, но может вернуть меньше, если доступно недостаточно символов.396397*size* указывает приблизительное максимальное количество байт для чтения из потока данных в целях декодирования. Декодер может изменять этот параметр по своему усмотрению. Значение по умолчанию -1 означает, что нужно читать и декодировать как можно больше. *size* предназначен для того, чтобы избежать декодирования огромных файлов за один шаг.398399*firstline* указывает, что достаточно вернуть только первую строку, если на последующих строках возникают ошибки декодирования.400401Метод должен использовать жадную стратегию чтения, то есть читать столько данных, сколько допускается определением кодировки и заданным размером; например, если в потоке доступны необязательные окончания кодировки или маркеры состояния, их также следует прочитать.402403#### `readline([size[, keepends]])`404405Читает одну строку из входного потока и возвращает декодированные данные.406407*size*, если задан, передаётся как аргумент size методу [`readline()`](https://python-all.ru/3.2/library/readline.html#module-readline) потока.408409Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.410411#### `readlines([sizehint[, keepends]])`412413Читает все строки из входного потока данных и возвращает их в виде списка строк.414415Окончания строк реализуются с помощью метода декодера кодека и включаются в элементы списка, если *keepends* имеет значение true.416417*sizehint*, если указан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader.read) потока.418419#### `reset()`420421Сбрасывает буферы кодека, используемые для сохранения состояния.422423Обратите внимание, что никакое перемещение позиции в потоке не должно выполняться. Этот метод предназначен в первую очередь для восстановления после ошибок декодирования.424425В дополнение к указанным выше методам, [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от базового потока.426427Следующие два базовых класса включены для удобства. Они не нужны реестру кодеков, но могут оказаться полезными на практике.428429### 6.6.1.6. Объекты StreamReaderWriter430431[`StreamReaderWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReaderWriter) позволяет оборачивать потоки, работающие как в режиме чтения, так и записи.432433Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.2/library/codecs.html#codecs.lookup), для создания экземпляра.434435#### `class codecs.StreamReaderWriter(stream, Reader, Writer, errors)`436437Создаёт экземпляр [`StreamReaderWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReaderWriter). *поток данных* должен быть файлоподобным объектом. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими интерфейсы [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter) соответственно. Обработка ошибок выполняется так же, как определено для потоковых читателей и писателей.438439Экземпляры [`StreamReaderWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReaderWriter) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от базового потока.440441### 6.6.1.7. Объекты StreamRecoder442443[`StreamRecoder`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamRecoder) предоставляет представление кодирования данных с разделением на фронтенд и бэкенд, что иногда полезно при работе с разными кодировками.444445Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.2/library/codecs.html#codecs.lookup), для создания экземпляра.446447#### `class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors)`448449Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamRecoder), реализующий двунаправленное преобразование: *encode* и *decode* работают на фронтенде (вход `read()` и выход `write()`), а *Reader* и *Writer* – на бэкенде (чтение и запись в поток).450451Эти объекты можно использовать для прозрачного прямого перекодирования, например, из Latin-1 в UTF-8 и обратно.452453*Поток данных* должен быть файлоподобным объектом.454455*encode*, *decode* должны соответствовать интерфейсу `Codec`. *Reader*, *Writer* должны быть фабричными функциями или классами, предоставляющими объекты интерфейсов [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter) соответственно.456457*encode* и *decode* нужны для преобразования на фронтенде, а *Reader* и *Writer* – на бэкенде.458459Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.460461Экземпляры [`StreamRecoder`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamRecoder) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.2/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока.462463## 6.6.2. Кодировки и Unicode464465Строки внутренне хранятся как последовательности кодовых точек (точнее, как массивы [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE)). В зависимости от того, как скомпилирован Python (с помощью `--without-wide-unicode` или `--with-wide-unicode`, и по умолчанию используется первый вариант) [`Py_UNICODE`](https://python-all.ru/3.2/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.2/library/stdtypes.html#str.encode) вызовет исключение [`UnicodeEncodeError`](https://python-all.ru/3.2/library/exceptions.html#UnicodeEncodeError), которое выглядит так: `UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256)`.466467Существует ещё одна группа кодировок (так называемые charmap-кодировки), которые выбирают другое подмножество всех кодовых точек Unicode и определяют, как эти кодовые точки сопоставляются с байтами `0x0`–`0xff`. Чтобы увидеть, как это делается, достаточно открыть, например, `encodings/cp1252.py` (кодировка, используемая в основном в Windows). Там есть строковая константа из 256 символов, показывающая, какой символ какому значению байта соответствует.468469Все эти кодировки могут закодировать только 256 из 1114112 кодовых точек, определённых в Unicode. Простой и прямой способ хранить каждую кодовую точку Unicode – это хранить каждую кодовую точку как четыре последовательных байта. Есть две возможности: хранить байты в порядке big endian или little endian. Эти две кодировки называются `UTF-32-BE` и `UTF-32-LE` соответственно. Их недостаток в том, что, например, при использовании `UTF-32-BE` на машине с little endian постоянно придётся менять порядок байтов при кодировании и декодировании. `UTF-32` избегает этой проблемы: байты всегда будут в естественном порядке. Однако когда эти байты читаются CPU с другим порядком байтов, байты всё равно приходится менять. Чтобы иметь возможность определить порядок байтов последовательности байтов `UTF-16` или `UTF-32`, существует так называемый BOM (Byte Order Mark – метка порядка байтов). Это символ Unicode `U+FEFF`. Этот символ может быть добавлен в начало любой последовательности байтов `UTF-16` или `UTF-32`. Символ с переставленными байтами (`0xFFFE`) является недопустимым символом, который не может встречаться в тексте Unicode. Таким образом, если первый символ в последовательности байтов `UTF-16` или `UTF-32` оказывается `U+FFFE`, байты необходимо менять местами при декодировании. К сожалению, символ `U+FEFF` имел и второе назначение – как `ZERO WIDTH NO-BREAK SPACE`: символ без ширины, не позволяющий разбивать слово. Он может использоваться, например, для подсказок алгоритму лигатур. Начиная с Unicode 4.0 использование `U+FEFF` в качестве `ZERO WIDTH NO-BREAK SPACE` устарело (эту роль принял `U+2060` (`WORD JOINER`)). Тем не менее программное обеспечение Unicode всё ещё должно уметь обрабатывать `U+FEFF` в обеих ролях: как BOM это устройство для определения порядка хранения закодированных байтов, и оно исчезает после декодирования последовательности байтов в строку; как `ZERO WIDTH NO-BREAK SPACE` это обычный символ, который декодируется как любой другой.470471Существует ещё одна кодировка, способная кодировать весь диапазон символов Unicode: UTF-8. UTF-8 – это 8-битная кодировка, а это значит, что в UTF-8 нет проблем с порядком байтов. Каждый байт в последовательности UTF-8 состоит из двух частей: битов маркера (самые старшие биты) и битов полезной нагрузки. Биты маркера представляют собой последовательность от нуля до четырёх битов `1`, за которой следует бит `0`. Символы Unicode кодируются следующим образом (где x – биты полезной нагрузки, которые при объединении дают символ Unicode):472473| Диапазон | Кодировка |474| --- | --- |475| `U-00000000` ... `U-0000007F` | 0xxxxxxx |476| `U-00000080` ... `U-000007FF` | 110xxxxx 10xxxxxx |477| `U-00000800` ... `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |478| `U-00010000` ... `U-0010FFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |479480Младший значащий бит символа Unicode – это самый правый бит x.481482Поскольку UTF-8 – это 8-битная кодировка, BOM не требуется, и любой символ `U+FEFF` в декодированной строке (даже если это первый символ) трактуется как `ZERO WIDTH NO-BREAK SPACE`.483484Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Любая 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-кодировке начинается с этих байтовых значений (которые, например, отображаются в485486> ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЭРЕЗИСОМ487>488> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА489>490> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК491492in iso-8859-1), this increases the probability that a `utf-8-sig` encoding can be correctly guessed from the byte sequence. So here the BOM is not used to be able to determine the byte order used for generating the byte sequence, but as a signature that helps in guessing the encoding. On encoding the utf-8-sig codec will write `0xef`, `0xbb`, `0xbf` as the first three bytes to the file. On decoding `utf-8-sig` will skip those three bytes if they appear as the first three bytes in the file. In UTF-8, the use of the BOM is discouraged and should generally be avoided.493494## 6.6.3. Стандартные кодировки495496Python поставляется с рядом встроенных кодеков, реализованных либо как функции на C, либо с помощью словарей в качестве таблиц отображения. В следующей таблице перечислены кодеки по именам, вместе с несколькими распространёнными псевдонимами и языками, для которых эта кодировка, вероятно, используется. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что варианты написания, отличающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами; поэтому, например, `'utf-8'` является допустимым псевдонимом для кодека `'utf_8'`.497498Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:499500- набор символов ISO 8859501- кодовая страница Microsoft Windows, обычно полученная из набора символов 8859, но заменяющая управляющие символы дополнительными графическими символами502- кодовая страница IBM EBCDIC503- кодовая страница IBM PC, совместимая с ASCII504505| Кодек | Псевдонимы | Языки |506| --- | --- | --- |507| ascii | 646, us-ascii | Английский |508| big5 | big5-tw, csbig5 | Китайский традиционный |509| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |510| cp037 | IBM037, IBM039 | Английский |511| cp424 | EBCDIC-CP-HE, IBM424 | Иврит |512| cp437 | 437, IBM437 | Английский |513| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Западная Европа |514| cp720 |  | Арабский |515| cp737 |  | Греческий |516| cp775 | IBM775 | Балтийские языки |517| cp850 | 850, IBM850 | Западная Европа |518| cp852 | 852, IBM852 | Центральная и Восточная Европа |519| cp855 | 855, IBM855 | болгарский, белорусский, македонский, русский, сербский |520| cp856 |  | Иврит |521| cp857 | 857, IBM857 | Турецкий |522| cp858 | 858, IBM858 | Западная Европа |523| cp860 | 860, IBM860 | португальский |524| cp861 | 861, CP-IS, IBM861 | Исландский |525| cp862 | 862, IBM862 | Иврит |526| cp863 | 863, IBM863 | канадский |527| cp864 | IBM864 | Арабский |528| cp865 | 865, IBM865 | датский, норвежский |529| cp866 | 866, IBM866 | Русский |530| cp869 | 869, CP-GR, IBM869 | Греческий |531| cp874 |  | Тайский |532| cp875 |  | Греческий |533| cp932 | 932, ms932, mskanji, ms-kanji | Японский |534| cp949 | 949, ms949, uhc | Корейский |535| cp950 | 950, ms950 | Китайский традиционный |536| cp1006 |  | Урду |537| cp1026 | ibm1026 | Турецкий |538| cp1140 | ibm1140 | Западная Европа |539| cp1250 | windows-1250 | Центральная и Восточная Европа |540| cp1251 | windows-1251 | болгарский, белорусский, македонский, русский, сербский |541| cp1252 | windows-1252 | Западная Европа |542| cp1253 | windows-1253 | Греческий |543| cp1254 | windows-1254 | Турецкий |544| cp1255 | windows-1255 | Иврит |545| cp1256 | windows-1256 | Арабский |546| cp1257 | windows-1257 | Балтийские языки |547| cp1258 | windows-1258 | вьетнамский |548| euc\_jp | eucjp, ujis, u-jis | Японский |549| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |550| euc\_jisx0213 | eucjisx0213 | Японский |551| euc\_kr | euckr, корейский, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |552| gb2312 | chinese, csiso58gb231280, euc- cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso- ir-58 | Упрощённый китайский |553| gbk | 936, cp936, ms936 | Унифицированный китайский |554| gb18030 | gb18030-2000 | Унифицированный китайский |555| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |556| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |557| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |558| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |559| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |560| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |561| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |562| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |563| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |564| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |565| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |566| iso8859\_4 | iso-8859-4, latin4, L4 | Балтийские языки |567| iso8859\_5 | iso-8859-5, кириллица | болгарский, белорусский, македонский, русский, сербский |568| iso8859\_6 | iso-8859-6, арабский | Арабский |569| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |570| iso8859\_8 | iso-8859-8, иврит | Иврит |571| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |572| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |573| iso8859\_13 | iso-8859-13, latin7, L7 | Балтийские языки |574| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |575| iso8859\_15 | iso-8859-15, latin9, L9 | Западная Европа |576| iso8859\_16 | iso-8859-16, latin10, L10 | Юго-Восточная Европа |577| johab | cp1361, ms1361 | Корейский |578| koi8\_r |  | Русский |579| koi8\_u |  | Украинский |580| mac\_cyrillic | maccyrillic | болгарский, белорусский, македонский, русский, сербский |581| mac\_greek | macgreek | Греческий |582| mac\_iceland | maciceland | Исландский |583| mac\_latin2 | maclatin2, maccentraleurope | Центральная и Восточная Европа |584| mac\_roman | macroman, macintosh | Западная Европа |585| mac\_turkish | macturkish | Турецкий |586| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |587| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |588| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |589| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |590| utf\_32 | U32, utf32 | все языки |591| utf\_32\_be | UTF-32BE | все языки |592| utf\_32\_le | UTF-32LE | все языки |593| utf\_16 | U16, utf16 | все языки |594| utf\_16\_be | UTF-16BE | все языки |595| utf\_16\_le | UTF-16LE | все языки |596| utf\_7 | U7, unicode-1-1-utf-7 | все языки |597| utf\_8 | U8, UTF, utf8 | все языки |598| utf\_8\_sig |  | все языки |599600| Кодек | Псевдонимы | Назначение |601| --- | --- | --- |602| idna |  | Реализует [**RFC 3490**](https://python-all.ru/3.2/library/codecs.html), см. также [`encodings.idna`](https://python-all.ru/3.2/library/codecs.html#module-encodings.idna) |603| mbcs | dbcs | Только Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |604| palmos |  | Кодировка PalmOS 3.5 |605| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/3.2/library/codecs.html) |606| raw\_unicode\_escape |  | Создаёт строку, пригодную для использования в качестве сырого Unicode-литерала в исходном коде Python |607| undefined |  | Вызывает исключение для всех преобразований. Может использоваться как системная кодировка, если не требуется автоматическое приведение между байтовыми строками и строками Unicode. |608| unicode\_escape |  | Создаёт строку, пригодную для использования в качестве Unicode-литерала в исходном коде Python |609| unicode\_internal |  | Возвращает внутреннее представление операнда |610611Следующие кодеки преобразуют байты в байты.612613| Кодек | Псевдонимы | Назначение |614| --- | --- | --- |615| base64\_codec | base64, base-64 | Преобразует операнд в MIME base64 |616| bz2\_codec | bz2 | Сжимает операнд с помощью bz2 |617| hex\_codec | hex | Преобразует операнд в шестнадцатеричное представление, по два разряда на байт |618| quopri\_codec | quopri, quoted-printable, quotedprintable | Преобразует операнд в MIME quoted-printable |619| uu\_codec | uu | Преобразует операнд с помощью uuencode |620| zlib\_codec | zip, zlib | Сжимает операнд с помощью gzip |621622Следующие кодеки преобразуют строки в строки.623624| Кодек | Псевдонимы | Назначение |625| --- | --- | --- |626| rot\_13 | rot13 | Возвращает шифрование Цезаря операнда |627628Новое в версии 3.2: кодеки преобразования байтов в байты и строк в строки.629630## 6.6.4. [`encodings.idna`](https://python-all.ru/3.2/library/codecs.html#module-encodings.idna) – Интернационализированные доменные имена в приложениях631632Этот модуль реализует [**RFC 3490**](https://python-all.ru/3.2/library/codecs.html) (Интернационализированные доменные имена в приложениях) и [**RFC 3492**](https://python-all.ru/3.2/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/3.2/library/stringprep.html#module-stringprep).633634Вместе эти RFC определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (такое как `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, например, `www.xn--alliancefranaise-npb.nu`). Затем форма ACE доменного имени используется везде, где протокол не допускает произвольные символы, например, в DNS-запросах, полях HTTP *Host* и т.д. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки Unicode-доменов в IDNA при передаче и обратно преобразовывать метки ACE в Unicode перед отображением пользователю.635636Python поддерживает это преобразование несколькими способами: кодек `idna` выполняет преобразование между Unicode и ACE, разделяя входную строку на метки на основе символов-разделителей, определенных в [разделе 3.1](https://python-all.ru/3.2/library/codecs.html) (1) документа [**RFC 3490**](https://python-all.ru/3.2/library/codecs.html), и преобразуя каждую метку в ACE по мере необходимости, и, наоборот, разделяя входную байтовую строку на метки на основе разделителя `.` и преобразуя любые найденные метки ACE в Unicode. Кроме того, модуль [`socket`](https://python-all.ru/3.2/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно беспокоиться о преобразовании имен хостов при передаче их в модуль socket. Вдобавок, модули, которые принимают имена хостов в качестве параметров функций, такие как [`http.client`](https://python-all.ru/3.2/library/http.client.html#module-http.client) и [`ftplib`](https://python-all.ru/3.2/library/ftplib.html#module-ftplib), принимают Unicode-имена хостов (при этом [`http.client`](https://python-all.ru/3.2/library/http.client.html#module-http.client) также прозрачно отправляет IDNA-имя хоста в поле *Host*, если вообще отправляет это поле).637638При получении имён хостов из сети (например, при обратном поиске имени) автоматическое преобразование в Unicode не выполняется: приложения, желающие отобразить такие имена хостов пользователю, должны декодировать их в Unicode.639640Модуль [`encodings.idna`](https://python-all.ru/3.2/library/codecs.html#module-encodings.idna) также реализует процедуру nameprep, которая выполняет определенные нормализации имен хостов для достижения нечувствительности к регистру интернационализированных доменных имен и унификации похожих символов. Функции nameprep можно использовать напрямую при желании.641642#### `encodings.idna.nameprep(label)`643644Return the nameprepped version of *label*. The implementation currently assumes query strings, so `AllowUnassigned` is true.645646#### `encodings.idna.ToASCII(label)`647648Преобразует метку в ASCII, как указано в [**RFC 3490**](https://python-all.ru/3.2/library/codecs.html). Параметр `UseSTD3ASCIIRules` предполагается равным false.649650#### `encodings.idna.ToUnicode(label)`651652Преобразует метку в Unicode, как указано в [**RFC 3490**](https://python-all.ru/3.2/library/codecs.html).653654## 6.6.5. [`encodings.mbcs`](https://python-all.ru/3.2/library/codecs.html#module-encodings.mbcs) – кодовая страница Windows ANSI655656Кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). Этот кодек поддерживает только обработчики ошибок `'strict'` и `'replace'` для кодирования и `'strict'` и `'ignore'` для декодирования.657658Доступность: только Windows.659660Изменено в версии 3.2: До версии 3.2 аргумент *errors* игнорировался; для кодирования всегда использовалось `'replace'`, а для декодирования – `'ignore'`.661662## 6.6.6. [`encodings.utf_8_sig`](https://python-all.ru/3.2/library/codecs.html#module-encodings.utf_8_sig) – кодек UTF-8 с сигнатурой BOM663664Этот модуль реализует вариант кодека UTF-8: при кодировании префикс UTF-8 BOM будет добавлен перед байтами, закодированными в UTF-8. Для кодировщика с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный UTF-8 BOM в начале данных будет пропущен.665