`codecs.md`

846 строк · 76.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/codecs.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 7.6. `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.1/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder), соответственно. Инкрементальные кодеки могут сохранять состояние.3435*streamreader* и *streamwriter*: это должны быть фабричные функции, предоставляющие следующий интерфейс:3637> `factory(поток данных, errors='strict')`3839Фабричные функции должны возвращать объекты, предоставляющие интерфейсы, определённые базовыми классами [`StreamWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.1/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.1/library/codecs.html)4950а также любое другое имя обработчика ошибок, определённое через [`register_error()`](https://python-all.ru/3.1/library/codecs.html#codecs.register_error).5152Если функция поиска не может найти указанную кодировку, она должна вернуть `None`.5354#### `codecs.lookup(encoding)`5556Ищет информацию о кодеке в реестре кодеков Python и возвращает объект `CodecInfo`, как определено выше.5758Кодировки сначала ищутся в кеше реестра. Если не найдены, просматривается список зарегистрированных функций поиска. Если объект `CodecInfo` не найден, возбуждается [`LookupError`](https://python-all.ru/3.1/library/exceptions.html#LookupError). В противном случае объект `CodecInfo` сохраняется в кеш и возвращается вызывающему.5960Для упрощения доступа к различным кодекам модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/3.1/library/codecs.html#codecs.lookup) для поиска кодека:6162#### `codecs.getencoder(encoding)`6364Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.6566Вызывает [`LookupError`](https://python-all.ru/3.1/library/exceptions.html#LookupError), если кодировка не найдена.6768#### `codecs.getdecoder(encoding)`6970Находит кодек для указанной кодировки и возвращает его функцию-декодер.7172Вызывает [`LookupError`](https://python-all.ru/3.1/library/exceptions.html#LookupError), если кодировка не найдена.7374#### `codecs.getincrementalencoder(encoding)`7576Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.7778Вызывает [`LookupError`](https://python-all.ru/3.1/library/exceptions.html#LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный кодировщик.7980#### `codecs.getincrementaldecoder(encoding)`8182Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.8384Вызывает [`LookupError`](https://python-all.ru/3.1/library/exceptions.html#LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный декодировщик.8586#### `codecs.getreader(encoding)`8788Находит кодек для указанной кодировки и возвращает его класс StreamReader или фабричную функцию.8990Вызывает [`LookupError`](https://python-all.ru/3.1/library/exceptions.html#LookupError), если кодировка не найдена.9192#### `codecs.getwriter(encoding)`9394Находит кодек для указанной кодировки и возвращает его класс StreamWriter или фабричную функцию.9596Вызывает [`LookupError`](https://python-all.ru/3.1/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.1/library/exceptions.html#UnicodeEncodeError), который содержит информацию о месте ошибки. Обработчик ошибок должен либо снова вызывать это исключение, либо другое, либо вернуть кортеж с заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Кодировщик закодирует замену и продолжит кодирование исходных данных с указанной позиции. Отрицательные значения позиции считаются относительно конца входной строки. Если результирующая позиция выходит за пределы, будет возбуждено [`IndexError`](https://python-all.ru/3.1/library/exceptions.html#IndexError).103104Декодирование и трансляция работают аналогично, за исключением того, что обработчику будет передан [`UnicodeDecodeError`](https://python-all.ru/3.1/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.1/library/exceptions.html#UnicodeTranslateError), и что замена от обработчика ошибок будет помещена в вывод напрямую.105106#### `codecs.lookup_error(name)`107108Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.109110Возбуждает [`LookupError`](https://python-all.ru/3.1/library/exceptions.html#LookupError), если обработчик не найден.111112#### `codecs.strict_errors(exception)`113114Реализует обработку ошибок115116`strict`117118: каждая ошибка кодирования или декодирования возбуждает119120[`UnicodeError`](https://python-all.ru/3.1/library/exceptions.html#UnicodeError)121122.123124#### `codecs.replace_errors(exception)`125126Реализует обработку ошибок127128`replace`129130: повреждённые данные заменяются подходящим замещающим символом, таким как131132`'?'`133134в байтовых строках и135136`'\ufffd'`137138в строках Unicode.139140#### `codecs.ignore_errors(exception)`141142Реализует обработку ошибок143144`ignore`145146: повреждённые данные игнорируются и кодирование или декодирование продолжается без дальнейших уведомлений.147148#### `codecs.xmlcharrefreplace_errors(exception)`149150Реализует обработку ошибок151152`xmlcharrefreplace`153154(только для кодирования): некодируемый символ заменяется соответствующей символьной ссылкой XML.155156#### `codecs.backslashreplace_errors(exception)`157158Реализует обработку ошибок159160`backslashreplace`161162(только для кодирования): некодируемый символ заменяется escape-последовательностью с обратной косой чертой.163164Для упрощения работы с закодированными файлами или потоками модуль также определяет следующие вспомогательные функции:165166#### `codecs.open(filename, mode[, encoding[, errors[, buffering]]])`167168Открывает закодированный файл, используя указанный *mode*, и возвращает обёрнутую версию, обеспечивающую прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, что означает открытие файла в режиме чтения.169170> **Примечание**171>172> Методы обёрнутой версии будут принимать и возвращать только строки. Аргументы типа bytes будут отклонены.173174> **Примечание**175>176> Файлы всегда открываются в двоичном режиме, даже если двоичный режим не был указан. Это сделано для предотвращения потери данных из-за кодировок, использующих 8-битные значения. Это означает, что автоматическое преобразование `b'\n'` не выполняется при чтении и записи.177178*encoding* задаёт кодировку, которая будет использоваться для файла.179180*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.181182Параметр *buffering* имеет то же значение, что и для встроенной функции [`open()`](https://python-all.ru/3.1/library/functions.html#open). По умолчанию используется построчная буферизация.183184#### `codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')`185186Возвращает обёрнутую версию файла, которая обеспечивает прозрачное преобразование кодировки.187188Байты, записанные в обёрнутый файл, интерпретируются в соответствии с указанным *data\_encoding* и затем записываются в исходный файл как байты с использованием *file\_encoding*.189190Если *file\_encoding* не указан, по умолчанию используется *data\_encoding*.191192*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.193194#### `codecs.iterencode(iterator, encoding, errors='strict', **kwargs)`195196Использует инкрементальный кодировщик для итеративного кодирования входных данных, предоставленных197198*iterator*199200. Эта функция является201202[*генератором*](https://python-all.ru/3.1/glossary.html#term-generator)203204.205206*errors*207208(а также любые другие именованные аргументы) передаётся инкрементальному кодировщику.209210#### `codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)`211212Использует инкрементальный декодер для итеративного декодирования входных данных, предоставленных213214*iterator*215216. Эта функция является217218[*генератором*](https://python-all.ru/3.1/glossary.html#term-generator)219220. Параметр221222*errors*223224(а также любые другие ключевые аргументы) передаётся инкрементальному декодеру.225226Модуль также предоставляет следующие константы, полезные для чтения и записи в платформенно-зависимые файлы:227228#### `codecs.BOM`229230#### `codecs.BOM_BE`231232#### `codecs.BOM_LE`233234#### `codecs.BOM_UTF8`235236#### `codecs.BOM_UTF16`237238#### `codecs.BOM_UTF16_BE`239240#### `codecs.BOM_UTF16_LE`241242#### `codecs.BOM_UTF32`243244#### `codecs.BOM_UTF32_BE`245246#### `codecs.BOM_UTF32_LE`247248Эти константы определяют различные кодировки метки порядка байтов Unicode (BOM), используемые в потоках данных UTF-16 и UTF-32 для указания порядка байтов, используемого в потоке или файле, а в UTF-8 – как подпись Unicode.249250[`BOM_UTF16`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16)251252– это либо253254[`BOM_UTF16_BE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16_BE)255256, либо257258[`BOM_UTF16_LE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16_LE)259260в зависимости от родного порядка байтов платформы;261262[`BOM`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM)263264является псевдонимом для265266[`BOM_UTF16`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16)267268,269270[`BOM_LE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_LE)271272– для273274[`BOM_UTF16_LE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16_LE)275276, а277278[`BOM_BE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_BE)279280– для281282[`BOM_UTF16_BE`](https://python-all.ru/3.1/library/codecs.html#codecs.BOM_UTF16_BE)283284. Остальные представляют BOM в кодировках UTF-8 и UTF-32.285286## 7.6.1. Базовые классы кодеков287288Модуль `codecs` определяет набор базовых классов, которые задают интерфейс и могут также использоваться для простого написания собственных кодеков для применения в Python.289290Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в качестве кодека в Python: статический кодировщик без состояния, статический декодировщик без состояния, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно повторно используют статический кодировщик/декодировщик без состояния для реализации файловых протоколов.291292Класс `Codec` определяет интерфейс для кодировщиков/декодировщиков без состояния.293294Для упрощения и стандартизации обработки ошибок методы `encode()` и `decode()` могут реализовывать различные схемы обработки ошибок с помощью строкового аргумента *errors*. Определены и реализованы следующие строковые значения для всех стандартных кодеков Python:295296| Значение | Значение |297| --- | --- |298| `'strict'` | Возбуждает [`UnicodeError`](https://python-all.ru/3.1/library/exceptions.html#UnicodeError) (или подкласс); это поведение по умолчанию. |299| `'ignore'` | Игнорирует символ и продолжает со следующего. |300| `'replace'` | Заменяет подходящим заменяющим символом; для встроенных кодеков Unicode при декодировании Python будет использовать официальный U+FFFD REPLACEMENT CHARACTER, а при кодировании – '?'. |301| `'xmlcharrefreplace'` | Заменяет соответствующей символьной ссылкой XML (только для кодирования). |302| `'backslashreplace'` | Заменяет escape-последовательностями с обратной косой чертой (только для кодирования). |303| `'surrogateescape'` | Заменяет байт суррогатом U+DCxx, как определено в [**PEP 383**](https://python-all.ru/3.1/library/codecs.html). |304305Кроме того, следующие обработчики ошибок специфичны для одного кодека:306307| Значение | Кодек | Значение |308| --- | --- | --- |309| `'surrogatepass'` | utf-8 | Разрешить кодирование и декодирование суррогатных кодов в UTF-8. |310311Новое в версии 3.1: Обработчики ошибок `'surrogateescape'` и `'surrogatepass'`.312313Набор допустимых значений может быть расширен через [`register_error()`](https://python-all.ru/3.1/library/codecs.html#codecs.register_error).314315### 7.6.1.1. Объекты кодеков316317Класс `Codec` определяет методы, которые также задают функциональные интерфейсы кодировщика и декодировщика без состояния:318319#### `Codec.encode(input[, errors])`320321Кодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Кодирование преобразует строковый объект в объект bytes с использованием определённой кодировки набора символов (например, `cp1252` или `iso-8859-1`).322323*errors* определяет способ обработки ошибок. По умолчанию используется `'strict'` режим.324325Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.326327Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.328329#### `Codec.decode(input[, errors])`330331Декодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Декодирование преобразует объект bytes, закодированный с помощью определённой кодировки набора символов, в строковый объект.332333*input* должен быть объектом bytes или объектом, предоставляющим интерфейс только для чтения символьного буфера – например, объекты буфера и файлы, отображаемые в память.334335*errors* определяет способ обработки ошибок. По умолчанию используется `'strict'` режим.336337Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.338339Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.340341Классы [`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()` инкрементального кодировщика/декодировщика. Инкрементальный кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.342343Объединённый результат вызовов метода `encode()`/`decode()` совпадает с тем, который получился бы, если бы все отдельные входные данные были объединены в один и этот вход был закодирован/декодирован кодировщиком/декодировщиком без состояния.344345### 7.6.1.2. Объекты IncrementalEncoder346347Класс [`IncrementalEncoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый кодировщик должен реализовать для совместимости с реестром кодеков Python.348349#### `class codecs.IncrementalEncoder([errors])`350351Конструктор для экземпляра [`IncrementalEncoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalEncoder).352353Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.354355[`IncrementalEncoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalEncoder) может реализовывать различные схемы обработки ошибок, передавая ключевой аргумент *errors*. Эти параметры предопределены:356357- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.358- `'ignore'` Игнорирует символ и продолжает со следующего.359- `'replace'` Заменяет подходящим заменяющим символом360- `'xmlcharrefreplace'` Заменяет соответствующей символьной ссылкой XML361- `'backslashreplace'` Заменяет управляющими последовательностями с обратной косой чертой.362363Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalEncoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalEncoder).364365Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.1/library/codecs.html#codecs.register_error).366367#### `encode(object[, final])`368369Кодирует370371*object*372373(с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов374375[`encode()`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalEncoder.encode)376377,378379*final*380381должен быть истинным (по умолчанию – ложь).382383#### `reset()`384385Сбрасывает кодировщик в начальное состояние.386387#### `IncrementalEncoder.getstate()`388389Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что390391`0`392393– это наиболее распространённое состояние. (Состояния, которые сложнее целых чисел, можно преобразовать в целое число, замаршализовав/запиклив состояние и кодируя байты результирующей строки в целое число).394395#### `IncrementalEncoder.setstate(state)`396397Устанавливает состояние кодировщика равным398399*state*400401.402403*state*404405должно быть состоянием кодировщика, возвращённым методом406407[`getstate()`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalEncoder.getstate)408409.410411### 7.6.1.3. Объекты IncrementalDecoder412413Класс [`IncrementalDecoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый декодировщик должен реализовать для совместимости с реестром кодеков Python.414415#### `class codecs.IncrementalDecoder([errors])`416417Конструктор для экземпляра [`IncrementalDecoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder).418419Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.420421[`IncrementalDecoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder) может реализовывать различные схемы обработки ошибок, передавая ключевой аргумент *errors*. Эти параметры предопределены:422423- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.424- `'ignore'` Игнорирует символ и продолжает со следующего.425- `'replace'` Заменяет подходящим заменяющим символом.426427Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalDecoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder).428429Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.1/library/codecs.html#codecs.register_error).430431#### `decode(object[, final])`432433Декодирует434435*object*436437(с учётом текущего состояния декодировщика) и возвращает результирующий декодированный объект. Если это последний вызов438439[`decode()`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder.decode)440441,442443*final*444445должен быть истинным (по умолчанию – ложь). Если446447*final*448449истинно, декодировщик должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).450451#### `reset()`452453Сбрасывает декодер в исходное состояние.454455#### `getstate()`456457Возвращает текущее состояние декодера. Это должен быть кортеж из двух элементов: первый – буфер, содержащий ещё не декодированные входные данные; второй – целое число, которое может содержать дополнительную информацию о состоянии. (Реализация должна гарантировать, что458459`0`460461является наиболее распространённой дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии равна462463`0`464465, должна быть возможность установить декодер в состояние без буферизованных входных данных и с466467`0`468469в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованных входных данных в декодер возвращала его в предыдущее состояние без вывода каких-либо данных. (Дополнительная информация о состоянии, более сложная, чем целые числа, может быть преобразована в целое число с помощью маршалинга/сериализации этой информации и кодирования байтов результирующей строки в целое число.)470471#### `setstate(state)`472473Устанавливает состояние декодировщика равным474475*state*476477.478479*state*480481должно быть состоянием декодировщика, возвращённым методом482483[`getstate()`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder.getstate)484485.486487Классы [`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`.488489### 7.6.1.4. Объекты StreamWriter490491Класс [`StreamWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый писатель должен определить для совместимости с реестром кодеков Python.492493#### `class codecs.StreamWriter(stream[, errors])`494495Конструктор экземпляра [`StreamWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter).496497Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.498499*поток данных* должен быть файлоподобным объектом, открытым для записи двоичных данных.500501Класс [`StreamWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Эти параметры предопределены:502503- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.504- `'ignore'` Игнорирует символ и продолжает со следующего.505- `'replace'` Заменяет подходящим заменяющим символом506- `'xmlcharrefreplace'` Заменяет соответствующей символьной ссылкой XML507- `'backslashreplace'` Заменяет управляющими последовательностями с обратной косой чертой.508509Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter).510511Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.1/library/codecs.html#codecs.register_error).512513#### `write(object)`514515Записывает в поток закодированное содержимое объекта.516517#### `writelines(list)`518519Записывает объединённый список строк в поток данных (возможно, с повторным использованием метода520521[`write()`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter.write)522523).524525#### `reset()`526527Сбрасывает и переустанавливает буферы кодека, используемые для сохранения состояния.528529Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.530531В дополнение к указанным выше методам, [`StreamWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от базового потока.532533### 7.6.1.5. Объекты StreamReader534535Класс [`StreamReader`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый читатель должен определить для совместимости с реестром кодеков Python.536537#### `class codecs.StreamReader(stream[, errors])`538539Конструктор экземпляра [`StreamReader`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader).540541Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.542543*поток данных* должен быть файлоподобным объектом, открытым для чтения (двоичных) данных.544545Класс [`StreamReader`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Эти параметры определены:546547- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError) (или подкласс); это значение по умолчанию.548- `'ignore'` Игнорирует символ и продолжает со следующего.549- `'replace'` Заменяет подходящим заменяющим символом.550551Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamReader`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader).552553Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.1/library/codecs.html#codecs.register_error).554555#### `read([size[, chars[, firstline]]])`556557Декодирует данные из потока и возвращает результирующий объект.558559*chars* указывает количество символов для чтения из потока данных. [`read()`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader.read) никогда не вернёт больше *chars* символов, но может вернуть меньше, если доступно недостаточно символов.560561*size* указывает приблизительное максимальное количество байт для чтения из потока данных в целях декодирования. Декодер может изменять этот параметр по своему усмотрению. Значение по умолчанию -1 означает, что нужно читать и декодировать как можно больше. *size* предназначен для того, чтобы избежать декодирования огромных файлов за один шаг.562563*firstline* указывает, что достаточно вернуть только первую строку, если на последующих строках возникают ошибки декодирования.564565Метод должен использовать жадную стратегию чтения, то есть читать столько данных, сколько допускается определением кодировки и заданным размером; например, если в потоке доступны необязательные окончания кодировки или маркеры состояния, их также следует прочитать.566567#### `readline([size[, keepends]])`568569Читает одну строку из входного потока и возвращает декодированные данные.570571*size*, если задан, передаётся как аргумент size методу [`readline()`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader.readline) потока.572573Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.574575#### `readlines([sizehint[, keepends]])`576577Читает все строки из входного потока данных и возвращает их в виде списка строк.578579Окончания строк реализуются с помощью метода декодера кодека и включаются в элементы списка, если *keepends* имеет значение true.580581*sizehint*, если указан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader.read) потока.582583#### `reset()`584585Сбрасывает буферы кодека, используемые для сохранения состояния.586587Обратите внимание, что никакое перемещение позиции в потоке не должно выполняться. Этот метод предназначен в первую очередь для восстановления после ошибок декодирования.588589В дополнение к указанным выше методам, [`StreamReader`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от базового потока.590591Следующие два базовых класса включены для удобства. Они не нужны реестру кодеков, но могут оказаться полезными на практике.592593### 7.6.1.6. Объекты StreamReaderWriter594595[`StreamReaderWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReaderWriter) позволяет оборачивать потоки, работающие как в режиме чтения, так и записи.596597Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.1/library/codecs.html#codecs.lookup), для создания экземпляра.598599#### `class codecs.StreamReaderWriter(stream, Reader, Writer, errors)`600601Создаёт экземпляр602603[`StreamReaderWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReaderWriter)604605.606607*поток данных*608609должен быть файлоподобным объектом.610611*Reader*612613и614615*Writer*616617должны быть фабричными функциями или классами, предоставляющими интерфейсы618619[`StreamReader`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamReader)620621и622623[`StreamWriter`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamWriter)624625соответственно. Обработка ошибок выполняется так же, как определено для потоковых читателей и писателей.626627Экземпляры [`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). Они наследуют все остальные методы и атрибуты от базового потока.628629### 7.6.1.7. Объекты StreamRecoder630631[`StreamRecoder`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamRecoder) предоставляет представление кодирования данных с разделением на фронтенд и бэкенд, что иногда полезно при работе с разными кодировками.632633Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.1/library/codecs.html#codecs.lookup), для создания экземпляра.634635#### `class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors)`636637Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/3.1/library/codecs.html#codecs.StreamRecoder), реализующий двунаправленное преобразование: *encode* и *decode* работают на фронтенде (вход `read()` и выход `write()`), а *Reader* и *Writer* – на бэкенде (чтение и запись в поток).638639Эти объекты можно использовать для прозрачного прямого перекодирования, например, из Latin-1 в UTF-8 и обратно.640641*Поток данных* должен быть файлоподобным объектом.642643*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) соответственно.644645*encode* и *decode* нужны для преобразования на фронтенде, а *Reader* и *Writer* – на бэкенде.646647Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.648649Экземпляры [`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). Они наследуют все остальные методы и атрибуты от нижележащего потока.650651## 7.6.2. Кодировки и Unicode652653Строки внутренне хранятся как последовательности кодовых точек (точнее, как массивы [`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)`.654655Существует ещё одна группа кодировок (так называемые charmap-кодировки), которые выбирают другое подмножество всех кодовых точек Unicode и определяют, как эти кодовые точки сопоставляются с байтами `0x0`–`0xff`. Чтобы увидеть, как это делается, достаточно открыть, например, `encodings/cp1252.py` (кодировка, используемая в основном в Windows). Там есть строковая константа из 256 символов, показывающая, какой символ какому значению байта соответствует.656657Все эти кодировки могут кодировать только 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 это средство определения порядка хранения закодированных байтов, которое исчезает после декодирования последовательности байтов в строку; как `НУЛЕВОЙ ШИРИНЫ НЕРАЗРЫВНЫЙ ПРОБЕЛ` это обычный символ, который декодируется как любой другой.658659Существует ещё одна кодировка, способная кодировать полный диапазон символов Unicode: UTF-8. UTF-8 – это 8-битная кодировка, поэтому в UTF-8 нет проблем с порядком байтов. Каждый байт в последовательности UTF-8 состоит из двух частей: битов маркера (самые старшие биты) и битов полезной нагрузки. Биты маркера представляют собой последовательность от нуля до шести единичных битов, за которыми следует нулевой бит. Символы Unicode кодируются так (где x – биты полезной нагрузки, которые при соединении дают символ Unicode):660661| Диапазон | Кодировка |662| --- | --- |663| `U-00000000` ... `U-0000007F` | 0xxxxxxx |664| `U-00000080` ... `U-000007FF` | 110xxxxx 10xxxxxx |665| `U-00000800` ... `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |666| `U-00010000` ... `U-001FFFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |667| `U-00200000` ... `U-03FFFFFF` | 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |668| `U-04000000` ... `U-7FFFFFFF` | 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |669670Младший значащий бит символа Unicode – это самый правый бит x.671672Поскольку UTF-8 – это 8-битная кодировка, BOM не требуется, и любой символ `U+FEFF` в декодированной строке (даже если это первый символ) трактуется как `ZERO WIDTH NO-BREAK SPACE`.673674Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Любая 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-кодировке начинается с этих байтовых значений (которые, например, отображаются в675676> ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЭРЕЗИСОМ677>678> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА679>680> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК681682в iso-8859-1), это увеличивает вероятность того, что кодировку utf-8-sig можно правильно угадать по последовательности байтов. Таким образом, здесь BOM используется не для определения порядка байтов, использованного при генерации последовательности, а как сигнатура, помогающая угадать кодировку. При кодировании кодек utf-8-sig запишет `0xef`, `0xbb`, `0xbf` в качестве первых трёх байтов в файл. При декодировании utf-8-sig пропустит эти три байта, если они окажутся первыми тремя байтами в файле.683684## 7.6.3. Стандартные кодировки685686Python поставляется с рядом встроенных кодеков, реализованных либо как функции на C, либо с помощью словарей в качестве таблиц отображения. В следующей таблице перечислены кодеки по именам, вместе с несколькими распространёнными псевдонимами и языками, для которых эта кодировка, вероятно, используется. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что варианты написания, отличающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами; поэтому, например, `'utf-8'` является допустимым псевдонимом для кодека `'utf_8'`.687688Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:689690- набор символов ISO 8859691- кодовая страница Microsoft Windows, обычно полученная из набора символов 8859, но заменяющая управляющие символы дополнительными графическими символами692- кодовая страница IBM EBCDIC693- кодовая страница IBM PC, совместимая с ASCII694695| Кодек | Псевдонимы | Языки |696| --- | --- | --- |697| ascii | 646, us-ascii | Английский |698| big5 | big5-tw, csbig5 | Китайский традиционный |699| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |700| cp037 | IBM037, IBM039 | Английский |701| cp424 | EBCDIC-CP-HE, IBM424 | Иврит |702| cp437 | 437, IBM437 | Английский |703| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Западная Европа |704| cp737 |  | Греческий |705| cp775 | IBM775 | Балтийские языки |706| cp850 | 850, IBM850 | Западная Европа |707| cp852 | 852, IBM852 | Центральная и Восточная Европа |708| cp855 | 855, IBM855 | болгарский, белорусский, македонский, русский, сербский |709| cp856 |  | Иврит |710| cp857 | 857, IBM857 | Турецкий |711| cp860 | 860, IBM860 | португальский |712| cp861 | 861, CP-IS, IBM861 | Исландский |713| cp862 | 862, IBM862 | Иврит |714| cp863 | 863, IBM863 | канадский |715| cp864 | IBM864 | Арабский |716| cp865 | 865, IBM865 | датский, норвежский |717| cp866 | 866, IBM866 | Русский |718| cp869 | 869, CP-GR, IBM869 | Греческий |719| cp874 |  | Тайский |720| cp875 |  | Греческий |721| cp932 | 932, ms932, mskanji, ms-kanji | Японский |722| cp949 | 949, ms949, uhc | Корейский |723| cp950 | 950, ms950 | Китайский традиционный |724| cp1006 |  | Урду |725| cp1026 | ibm1026 | Турецкий |726| cp1140 | ibm1140 | Западная Европа |727| cp1250 | windows-1250 | Центральная и Восточная Европа |728| cp1251 | windows-1251 | болгарский, белорусский, македонский, русский, сербский |729| cp1252 | windows-1252 | Западная Европа |730| cp1253 | windows-1253 | Греческий |731| cp1254 | windows-1254 | Турецкий |732| cp1255 | windows-1255 | Иврит |733| cp1256 | windows-1256 | Арабский |734| cp1257 | windows-1257 | Балтийские языки |735| cp1258 | windows-1258 | вьетнамский |736| euc\_jp | eucjp, ujis, u-jis | Японский |737| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |738| euc\_jisx0213 | eucjisx0213 | Японский |739| euc\_kr | euckr, корейский, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |740| gb2312 | chinese, csiso58gb231280, euc- cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso- ir-58 | Упрощённый китайский |741| gbk | 936, cp936, ms936 | Унифицированный китайский |742| gb18030 | gb18030-2000 | Унифицированный китайский |743| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |744| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |745| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |746| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |747| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |748| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |749| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |750| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |751| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |752| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |753| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |754| iso8859\_4 | iso-8859-4, latin4, L4 | Балтийские языки |755| iso8859\_5 | iso-8859-5, кириллица | болгарский, белорусский, македонский, русский, сербский |756| iso8859\_6 | iso-8859-6, арабский | Арабский |757| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |758| iso8859\_8 | iso-8859-8, иврит | Иврит |759| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |760| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |761| iso8859\_13 | iso-8859-13, latin7, L7 | Балтийские языки |762| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |763| iso8859\_15 | iso-8859-15, latin9, L9 | Западная Европа |764| iso8859\_16 | iso-8859-16, latin10, L10 | Юго-Восточная Европа |765| johab | cp1361, ms1361 | Корейский |766| koi8\_r |  | Русский |767| koi8\_u |  | Украинский |768| mac\_cyrillic | maccyrillic | болгарский, белорусский, македонский, русский, сербский |769| mac\_greek | macgreek | Греческий |770| mac\_iceland | maciceland | Исландский |771| mac\_latin2 | maclatin2, maccentraleurope | Центральная и Восточная Европа |772| mac\_roman | macroman | Западная Европа |773| mac\_turkish | macturkish | Турецкий |774| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |775| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |776| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |777| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |778| utf\_32 | U32, utf32 | все языки |779| utf\_32\_be | UTF-32BE | все языки |780| utf\_32\_le | UTF-32LE | все языки |781| utf\_16 | U16, utf16 | все языки |782| utf\_16\_be | UTF-16BE | все языки (только BMP) |783| utf\_16\_le | UTF-16LE | все языки (только BMP) |784| utf\_7 | U7, unicode-1-1-utf-7 | все языки |785| utf\_8 | U8, UTF, utf8 | все языки |786| utf\_8\_sig |  | все языки |787788| Кодек | Псевдонимы | Назначение |789| --- | --- | --- |790| idna |  | Реализует [**RFC 3490**](https://python-all.ru/3.1/library/codecs.html), см. также `encodings.idna` |791| mbcs | dbcs | Только Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |792| palmos |  | Кодировка PalmOS 3.5 |793| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/3.1/library/codecs.html) |794| raw\_unicode\_escape |  | Создаёт строку, пригодную для использования в качестве сырого Unicode-литерала в исходном коде Python |795| undefined |  | Вызывает исключение для всех преобразований. Может использоваться как системная кодировка, если не требуется автоматическое приведение между байтовыми строками и строками Unicode. |796| unicode\_escape |  | Создаёт строку, пригодную для использования в качестве Unicode-литерала в исходном коде Python |797| unicode\_internal |  | Возвращает внутреннее представление операнда |798799## 7.6.4. `encodings.idna` – Интернационализированные доменные имена в приложениях800801Этот модуль реализует [**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).802803Вместе эти RFC определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (такое как `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, например, `www.xn--alliancefranaise-npb.nu`). Затем форма ACE доменного имени используется везде, где протокол не допускает произвольные символы, например, в DNS-запросах, полях HTTP *Host* и т.д. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки Unicode-доменов в IDNA при передаче и обратно преобразовывать метки ACE в Unicode перед отображением пользователю.804805Python поддерживает это преобразование несколькими способами: кодек `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*, если вообще отправляет это поле).806807При получении имён хостов из сети (например, при обратном поиске имени) автоматическое преобразование в Unicode не выполняется: приложения, желающие отобразить такие имена хостов пользователю, должны декодировать их в Unicode.808809Модуль `encodings.idna` также реализует процедуру nameprep, которая выполняет определённые нормализации имён хостов для достижения нечувствительности к регистру интернационализированных доменных имён и унификации похожих символов. Функции nameprep можно использовать напрямую при необходимости.810811#### `encodings.idna.nameprep(label)`812813Return the nameprepped version of814815*label*816817. The implementation currently assumes query strings, so818819`AllowUnassigned`820821is true.822823#### `encodings.idna.ToASCII(label)`824825Преобразует метку в ASCII, как указано в826827[**RFC 3490**](https://python-all.ru/3.1/library/codecs.html)828829. Параметр830831`UseSTD3ASCIIRules`832833предполагается равным false.834835#### `encodings.idna.ToUnicode(label)`836837Преобразует метку в Unicode, как указано в838839[**RFC 3490**](https://python-all.ru/3.1/library/codecs.html)840841.842843## 7.6.5. `encodings.utf_8_sig` – UTF-8 кодек с сигнатурой BOM844845Этот модуль реализует вариант кодека UTF-8: при кодировании префикс UTF-8 BOM будет добавлен перед байтами, закодированными в UTF-8. Для кодировщика с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный UTF-8 BOM в начале данных будет пропущен.846