`codecs.md`

815 строк · 75.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/codecs.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `codecs` – реестр кодеков и базовые классы89Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодеков и обработки ошибок.1011Он определяет следующие функции:1213#### `[codecs.register]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.0/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalDecoder), соответственно. Инкрементальные кодеки могут сохранять состояние.3435*streamreader* и *streamwriter*: это должны быть фабричные функции, предоставляющие следующий интерфейс:3637`factory(поток данных, errors='strict')`3839Фабричные функции должны возвращать объекты, предоставляющие интерфейсы, определённые базовыми классами [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader) соответственно. Потоковые кодеки могут поддерживать состояние.4041Возможные значения для errors: `'strict'` (возбуждает исключение при ошибке кодирования), `'replace'` (заменяет некорректные данные подходящим замещающим маркером, например `'?'`), `'ignore'` (игнорирует некорректные данные и продолжает без уведомления), `'xmlcharrefreplace'` (заменяет на соответствующий символьный XML-код (только для кодирования)) и `'backslashreplace'` (заменяет на escape-последовательности с обратными слешами (только для кодирования)), а также любые другие методы обработки ошибок, определённые через [`register_error()`](https://python-all.ru/3.0/library/codecs.html#codecs.register_error).4243Если функция поиска не может найти указанную кодировку, она должна вернуть `None`.4445#### `[codecs.lookup]codecs.lookup(encoding)`4647Ищет информацию о кодеке в реестре кодеков Python и возвращает объект `CodecInfo`, как определено выше.4849Кодировки сначала ищутся в кеше реестра. Если не найдены, просматривается список зарегистрированных функций поиска. Если объект `CodecInfo` не найден, возбуждается [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError). В противном случае объект `CodecInfo` сохраняется в кеш и возвращается вызывающему.5051Для упрощения доступа к различным кодекам модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/3.0/library/codecs.html#codecs.lookup) для поиска кодека:5253#### `[codecs.getencoder]codecs.getencoder(encoding)`5455Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.5657Вызывает [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError), если кодировка не найдена.5859#### `[codecs.getdecoder]codecs.getdecoder(encoding)`6061Находит кодек для указанной кодировки и возвращает его функцию-декодер.6263Вызывает [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError), если кодировка не найдена.6465#### `[codecs.getincrementalencoder]codecs.getincrementalencoder(encoding)`6667Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.6869Вызывает [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный кодировщик.7071#### `[codecs.getincrementaldecoder]codecs.getincrementaldecoder(encoding)`7273Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.7475Вызывает [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError), если кодировка не может быть найдена или кодек не поддерживает инкрементальный декодировщик.7677#### `[codecs.getreader]codecs.getreader(encoding)`7879Находит кодек для указанной кодировки и возвращает его класс StreamReader или фабричную функцию.8081Вызывает [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError), если кодировка не найдена.8283#### `[codecs.getwriter]codecs.getwriter(encoding)`8485Находит кодек для указанной кодировки и возвращает его класс StreamWriter или фабричную функцию.8687Вызывает [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError), если кодировка не найдена.8889#### `[codecs.register_error]codecs.register_error(name, error_handler)`9091Регистрирует функцию обработки ошибок *error\_handler* под именем *name*. *error\_handler* будет вызываться при кодировании и декодировании в случае ошибки, когда *name* указан как параметр errors.9293При кодировании *error\_handler* будет вызван с экземпляром [`UnicodeEncodeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeEncodeError), который содержит информацию о месте ошибки. Обработчик ошибок должен либо снова вызывать это исключение, либо другое, либо вернуть кортеж с заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Кодировщик закодирует замену и продолжит кодирование исходных данных с указанной позиции. Отрицательные значения позиции считаются относительно конца входной строки. Если результирующая позиция выходит за пределы, будет возбуждено [`IndexError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.IndexError).9495Декодирование и трансляция работают аналогично, за исключением того, что обработчику будет передан [`UnicodeDecodeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeTranslateError), и что замена от обработчика ошибок будет помещена в вывод напрямую.9697#### `[codecs.lookup_error]codecs.lookup_error(name)`9899Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.100101Возбуждает [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError), если обработчик не найден.102103#### `[codecs.strict_errors]codecs.strict_errors(exception)`104105Реализует обработку ошибок106107`strict`108109.110111#### `[codecs.replace_errors]codecs.replace_errors(exception)`112113Реализует обработку ошибок114115`replace`116117.118119#### `[codecs.ignore_errors]codecs.ignore_errors(exception)`120121Реализует обработку ошибок122123`ignore`124125.126127#### `[codecs.xmlcharrefreplace_errors]codecs.xmlcharrefreplace_errors(exception)`128129Реализует обработку ошибок130131`xmlcharrefreplace`132133.134135#### `[codecs.backslashreplace_errors]codecs.backslashreplace_errors(exception)`136137Реализует обработку ошибок138139`backslashreplace`140141.142143Для упрощения работы с закодированными файлами или потоками модуль также определяет следующие вспомогательные функции:144145#### `[codecs.open]codecs.open(filename, mode[, encoding[, errors[, buffering]]])`146147Открывает закодированный файл, используя указанный *mode*, и возвращает обёрнутую версию, обеспечивающую прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, что означает открытие файла в режиме чтения.148149> **Примечание**150>151> Методы обёрнутой версии будут принимать и возвращать только строки. Аргументы типа bytes будут отклонены.152153> **Примечание**154>155> Файлы всегда открываются в двоичном режиме, даже если двоичный режим не был указан. Это сделано для предотвращения потери данных из-за кодировок, использующих 8-битные значения. Это означает, что автоматическое преобразование `b'\n'` не выполняется при чтении и записи.156157*encoding* задаёт кодировку, которая будет использоваться для файла.158159*errors* may be given to define the error handling. It defaults to `'strict'` which causes a [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) to be raised in case an encoding error occurs.160161Параметр *buffering* имеет то же значение, что и для встроенной функции [`open()`](https://python-all.ru/3.0/library/functions.html#open). По умолчанию используется построчная буферизация.162163#### `[codecs.EncodedFile]codecs.EncodedFile(file, input[, output[, errors]])`164165Возвращает обёрнутую версию файла, которая обеспечивает прозрачное преобразование кодировки.166167Байты, записанные в обёрнутый файл, интерпретируются в соответствии с кодировкой *input* и затем записываются в исходный файл как байты с использованием кодировки *output*.168169Если *output* не задан, по умолчанию используется *input*.170171Параметр *errors* может быть задан для определения обработки ошибок. По умолчанию `'strict'`, что вызывает [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) при возникновении ошибки кодирования.172173#### `[codecs.iterencode]codecs.iterencode(iterable, encoding[, errors])`174175Использует инкрементальный кодировщик для последовательного кодирования входных данных из176177*iterable*178179. Эта функция является180181[*генератором*](https://python-all.ru/3.0/glossary.html#term-generator)182183. Параметр184185*errors*186187(а также любые другие именованные аргументы) передаётся инкрементальному кодировщику.188189#### `[codecs.iterdecode]codecs.iterdecode(iterable, encoding[, errors])`190191Использует инкрементальный декодировщик для последовательного декодирования входных данных из192193*iterable*194195. Эта функция является196197[*генератором*](https://python-all.ru/3.0/glossary.html#term-generator)198199. Параметр200201*errors*202203(а также любые другие именованные аргументы) передаётся инкрементальному декодировщику.204205Модуль также предоставляет следующие константы, полезные для чтения и записи в платформенно-зависимые файлы:206207#### `[codecs.BOM]codecs.BOM`208209#### `codecs.BOM_BE`210211#### `codecs.BOM_LE`212213#### `codecs.BOM_UTF8`214215#### `codecs.BOM_UTF16`216217#### `codecs.BOM_UTF16_BE`218219#### `codecs.BOM_UTF16_LE`220221#### `codecs.BOM_UTF32`222223#### `codecs.BOM_UTF32_BE`224225#### `codecs.BOM_UTF32_LE`226227Эти константы определяют различные кодировки метки порядка байтов Unicode (BOM), используемые в потоках данных UTF-16 и UTF-32 для указания порядка байтов, используемого в потоке или файле, а в UTF-8 – как подпись Unicode.228229[`BOM_UTF16`](https://python-all.ru/3.0/library/codecs.html#codecs.BOM_UTF16)230231– это либо232233[`BOM_UTF16_BE`](https://python-all.ru/3.0/library/codecs.html#codecs.BOM_UTF16_BE)234235, либо236237[`BOM_UTF16_LE`](https://python-all.ru/3.0/library/codecs.html#codecs.BOM_UTF16_LE)238239в зависимости от родного порядка байтов платформы;240241[`BOM`](https://python-all.ru/3.0/library/codecs.html#codecs.BOM)242243является псевдонимом для244245[`BOM_UTF16`](https://python-all.ru/3.0/library/codecs.html#codecs.BOM_UTF16)246247,248249[`BOM_LE`](https://python-all.ru/3.0/library/codecs.html#codecs.BOM_LE)250251– для252253[`BOM_UTF16_LE`](https://python-all.ru/3.0/library/codecs.html#codecs.BOM_UTF16_LE)254255, а256257[`BOM_BE`](https://python-all.ru/3.0/library/codecs.html#codecs.BOM_BE)258259– для260261[`BOM_UTF16_BE`](https://python-all.ru/3.0/library/codecs.html#codecs.BOM_UTF16_BE)262263. Остальные представляют BOM в кодировках UTF-8 и UTF-32.264265## Базовые классы кодеков266267Модуль `codecs` определяет набор базовых классов, которые задают интерфейс и могут также использоваться для простого написания собственных кодеков для применения в Python.268269Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в качестве кодека в Python: статический кодировщик без состояния, статический декодировщик без состояния, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно повторно используют статический кодировщик/декодировщик без состояния для реализации файловых протоколов.270271Класс `Codec` определяет интерфейс для кодировщиков/декодировщиков без состояния.272273Для упрощения и стандартизации обработки ошибок методы `encode()` и `decode()` могут реализовывать различные схемы обработки ошибок с помощью строкового аргумента *errors*. Определены и реализованы следующие строковые значения для всех стандартных кодеков Python:274275| Значение | Значение |276| --- | --- |277| `'strict'` | Возбуждает [`UnicodeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeError) (или подкласс); это поведение по умолчанию. |278| `'ignore'` | Игнорирует символ и продолжает со следующего. |279| `'replace'` | Заменяет подходящим заменяющим символом; для встроенных кодеков Unicode при декодировании Python будет использовать официальный U+FFFD REPLACEMENT CHARACTER, а при кодировании – '?'. |280| `'xmlcharrefreplace'` | Заменяет соответствующей символьной ссылкой XML (только для кодирования). |281| `'backslashreplace'` | Заменяет escape-последовательностями с обратной косой чертой (только для кодирования). |282283Набор допустимых значений может быть расширен через [`register_error()`](https://python-all.ru/3.0/library/codecs.html#codecs.register_error).284285### Объекты Codec286287Класс `Codec` определяет методы, которые также задают функциональные интерфейсы кодировщика и декодировщика без состояния:288289#### `[codecs.Codec.encode]Codec.encode(input[, errors])`290291Кодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Кодирование преобразует строковый объект в объект bytes с использованием определённой кодировки набора символов (например, `cp1252` или `iso-8859-1`).292293*errors* определяет способ обработки ошибок. По умолчанию используется `'strict'` режим.294295Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.296297Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.298299#### `[codecs.Codec.decode]Codec.decode(input[, errors])`300301Декодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Декодирование преобразует объект bytes, закодированный с помощью определённой кодировки набора символов, в строковый объект.302303*input* должен быть объектом bytes или объектом, предоставляющим интерфейс только для чтения символьного буфера – например, объекты буфера и файлы, отображаемые в память.304305*errors* определяет способ обработки ошибок. По умолчанию используется `'strict'` режим.306307Метод не должен хранить состояние в экземпляре `Codec`. Используйте `StreamCodec` для кодеков, которым необходимо сохранять состояние, чтобы обеспечить эффективное кодирование/декодирование.308309Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.310311Классы [`IncrementalEncoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalDecoder) предоставляют базовый интерфейс для инкрементального кодирования и декодирования. Кодирование/декодирование входных данных выполняется не одним вызовом функции кодировщика/декодировщика без сохранения состояния, а несколькими вызовами метода `encode()`/`decode()` инкрементального кодировщика/декодировщика. Инкрементальный кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.312313Объединённый результат вызовов метода `encode()`/`decode()` совпадает с тем, который получился бы, если бы все отдельные входные данные были объединены в один и этот вход был закодирован/декодирован кодировщиком/декодировщиком без состояния.314315### Объекты IncrementalEncoder316317Класс [`IncrementalEncoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый кодировщик должен реализовать для совместимости с реестром кодеков Python.318319#### `[codecs.IncrementalEncoder]class codecs.IncrementalEncoder([errors])`320321Конструктор для экземпляра [`IncrementalEncoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalEncoder).322323Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.324325[`IncrementalEncoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalEncoder) может реализовывать различные схемы обработки ошибок, передавая ключевой аргумент *errors*. Эти параметры предопределены:326327- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) (или подкласс); это значение по умолчанию.328- `'ignore'` Игнорирует символ и продолжает со следующего.329- `'replace'` Заменяет подходящим заменяющим символом330- `'xmlcharrefreplace'` Заменяет соответствующей символьной ссылкой XML331- `'backslashreplace'` Заменяет управляющими последовательностями с обратной косой чертой.332333Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalEncoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalEncoder).334335Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.0/library/codecs.html#codecs.register_error).336337#### `[codecs.IncrementalEncoder.encode]encode(object[, final])`338339Кодирует340341*object*342343(с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов344345[`encode()`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalEncoder.encode)346347,348349*final*350351должен быть истинным (по умолчанию – ложь).352353#### `[codecs.IncrementalEncoder.reset]reset()`354355Сбрасывает кодировщик в начальное состояние.356357#### `[codecs.IncrementalEncoder.getstate]IncrementalEncoder.getstate()`358359Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что360361`0`362363– это наиболее распространённое состояние. (Состояния, которые сложнее целых чисел, можно преобразовать в целое число, замаршализовав/запиклив состояние и кодируя байты результирующей строки в целое число).364365#### `[codecs.IncrementalEncoder.setstate]IncrementalEncoder.setstate(state)`366367Устанавливает состояние кодировщика равным368369*state*370371.372373*state*374375должно быть состоянием кодировщика, возвращённым методом376377[`getstate()`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalEncoder.getstate)378379.380381### Объекты IncrementalDecoder382383Класс [`IncrementalDecoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных в несколько шагов. Он определяет следующие методы, которые каждый пошаговый декодировщик должен реализовать для совместимости с реестром кодеков Python.384385#### `[codecs.IncrementalDecoder]class codecs.IncrementalDecoder([errors])`386387Конструктор для экземпляра [`IncrementalDecoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalDecoder).388389Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.390391[`IncrementalDecoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalDecoder) может реализовывать различные схемы обработки ошибок, передавая ключевой аргумент *errors*. Эти параметры предопределены:392393- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) (или подкласс); это значение по умолчанию.394- `'ignore'` Игнорирует символ и продолжает со следующего.395- `'replace'` Заменяет подходящим заменяющим символом.396397Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalDecoder`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalDecoder).398399Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.0/library/codecs.html#codecs.register_error).400401#### `[codecs.IncrementalDecoder.decode]decode(object[, final])`402403Декодирует404405*object*406407(с учётом текущего состояния декодировщика) и возвращает результирующий декодированный объект. Если это последний вызов408409[`decode()`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalDecoder.decode)410411,412413*final*414415должен быть истинным (по умолчанию – ложь). Если416417*final*418419истинно, декодировщик должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).420421#### `[codecs.IncrementalDecoder.reset]reset()`422423Сбрасывает декодер в исходное состояние.424425#### `[codecs.IncrementalDecoder.getstate]getstate()`426427Возвращает текущее состояние декодера. Это должен быть кортеж из двух элементов: первый – буфер, содержащий ещё не декодированные входные данные; второй – целое число, которое может содержать дополнительную информацию о состоянии. (Реализация должна гарантировать, что428429`0`430431является наиболее распространённой дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии равна432433`0`434435, должна быть возможность установить декодер в состояние без буферизованных входных данных и с436437`0`438439в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованных входных данных в декодер возвращала его в предыдущее состояние без вывода каких-либо данных. (Дополнительная информация о состоянии, более сложная, чем целые числа, может быть преобразована в целое число с помощью маршалинга/сериализации этой информации и кодирования байтов результирующей строки в целое число.)440441#### `[codecs.IncrementalDecoder.setstate]setstate(state)`442443Устанавливает состояние декодировщика равным444445*state*446447.448449*state*450451должно быть состоянием декодировщика, возвращённым методом452453[`getstate()`](https://python-all.ru/3.0/library/codecs.html#codecs.IncrementalDecoder.getstate)454455.456457Классы [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader) предоставляют общие рабочие интерфейсы, которые можно использовать для очень простой реализации новых подмодулей кодировок. Пример такой реализации можно найти в `encodings.utf_8`.458459### Объекты StreamWriter460461Класс [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый писатель должен определить для совместимости с реестром кодеков Python.462463#### `[codecs.StreamWriter]class codecs.StreamWriter(stream[, errors])`464465Конструктор экземпляра [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter).466467Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.468469*поток данных* должен быть файлоподобным объектом, открытым для записи двоичных данных.470471Класс [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Эти параметры предопределены:472473- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) (или подкласс); это значение по умолчанию.474- `'ignore'` Игнорирует символ и продолжает со следующего.475- `'replace'` Заменяет подходящим заменяющим символом476- `'xmlcharrefreplace'` Заменяет соответствующей символьной ссылкой XML477- `'backslashreplace'` Заменяет управляющими последовательностями с обратной косой чертой.478479Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter).480481Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.0/library/codecs.html#codecs.register_error).482483#### `[codecs.StreamWriter.write]write(object)`484485Записывает в поток закодированное содержимое объекта.486487#### `[codecs.StreamWriter.writelines]writelines(list)`488489Записывает объединённый список строк в поток данных (возможно, с повторным использованием метода490491[`write()`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter.write)492493).494495#### `[codecs.StreamWriter.reset]reset()`496497Сбрасывает и переустанавливает буферы кодека, используемые для сохранения состояния.498499Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.500501В дополнение к указанным выше методам, [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от базового потока.502503### Объекты StreamReader504505Класс [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый читатель должен определить для совместимости с реестром кодеков Python.506507#### `[codecs.StreamReader]class codecs.StreamReader(stream[, errors])`508509Конструктор экземпляра [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader).510511Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.512513*поток данных* должен быть файлоподобным объектом, открытым для чтения (двоичных) данных.514515Класс [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Эти параметры определены:516517- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) (или подкласс); это значение по умолчанию.518- `'ignore'` Игнорирует символ и продолжает со следующего.519- `'replace'` Заменяет подходящим заменяющим символом.520521Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader).522523Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.0/library/codecs.html#codecs.register_error).524525#### `[codecs.StreamReader.read]read([size[, chars[, firstline]]])`526527Декодирует данные из потока и возвращает результирующий объект.528529*chars* указывает количество символов для чтения из потока данных. [`read()`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader.read) никогда не вернёт больше *chars* символов, но может вернуть меньше, если доступно недостаточно символов.530531*size* указывает приблизительное максимальное количество байт для чтения из потока данных в целях декодирования. Декодер может изменять этот параметр по своему усмотрению. Значение по умолчанию -1 означает, что нужно читать и декодировать как можно больше. *size* предназначен для того, чтобы избежать декодирования огромных файлов за один шаг.532533*firstline* указывает, что достаточно вернуть только первую строку, если на последующих строках возникают ошибки декодирования.534535Метод должен использовать жадную стратегию чтения, то есть читать столько данных, сколько допускается определением кодировки и заданным размером; например, если в потоке доступны необязательные окончания кодировки или маркеры состояния, их также следует прочитать.536537#### `[codecs.StreamReader.readline]readline([size[, keepends]])`538539Читает одну строку из входного потока и возвращает декодированные данные.540541*size*, если задан, передаётся как аргумент size методу [`readline()`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader.readline) потока.542543Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.544545#### `[codecs.StreamReader.readlines]readlines([sizehint[, keepends]])`546547Читает все строки из входного потока данных и возвращает их в виде списка строк.548549Окончания строк реализуются с помощью метода декодера кодека и включаются в элементы списка, если *keepends* имеет значение true.550551*sizehint*, если указан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader.read) потока.552553#### `[codecs.StreamReader.reset]reset()`554555Сбрасывает буферы кодека, используемые для сохранения состояния.556557Обратите внимание, что никакое перемещение позиции в потоке не должно выполняться. Этот метод предназначен в первую очередь для восстановления после ошибок декодирования.558559В дополнение к указанным выше методам, [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от базового потока.560561Следующие два базовых класса включены для удобства. Они не нужны реестру кодеков, но могут оказаться полезными на практике.562563### Объекты StreamReaderWriter564565[`StreamReaderWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReaderWriter) позволяет оборачивать потоки, работающие как в режиме чтения, так и записи.566567Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.0/library/codecs.html#codecs.lookup), для создания экземпляра.568569#### `[codecs.StreamReaderWriter]class codecs.StreamReaderWriter(stream, Reader, Writer, errors)`570571Создаёт экземпляр572573[`StreamReaderWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReaderWriter)574575.576577*поток данных*578579должен быть файлоподобным объектом.580581*Reader*582583и584585*Writer*586587должны быть фабричными функциями или классами, предоставляющими интерфейсы588589[`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader)590591и592593[`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter)594595соответственно. Обработка ошибок выполняется так же, как определено для потоковых читателей и писателей.596597Экземпляры [`StreamReaderWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReaderWriter) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от базового потока.598599### Объекты StreamRecoder600601[`StreamRecoder`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamRecoder) предоставляет представление кодирования данных с разделением на фронтенд и бэкенд, что иногда полезно при работе с разными кодировками.602603Конструкция такова, что можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.0/library/codecs.html#codecs.lookup), для создания экземпляра.604605#### `[codecs.StreamRecoder]class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors)`606607Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamRecoder), реализующий двунаправленное преобразование: *encode* и *decode* работают на фронтенде (вход `read()` и выход `write()`), а *Reader* и *Writer* – на бэкенде (чтение и запись в поток).608609Эти объекты можно использовать для прозрачного прямого перекодирования, например, из Latin-1 в UTF-8 и обратно.610611*Поток данных* должен быть файлоподобным объектом.612613*encode*, *decode* должны соответствовать интерфейсу `Codec`. *Reader*, *Writer* должны быть фабричными функциями или классами, предоставляющими объекты интерфейсов [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter) соответственно.614615*encode* и *decode* нужны для преобразования на фронтенде, а *Reader* и *Writer* – на бэкенде.616617Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.618619Экземпляры [`StreamRecoder`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamRecoder) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.0/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока.620621## Кодировки и Unicode622623Строки внутренне хранятся как последовательности кодовых точек (если быть точным, как массивы [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)). В зависимости от того, как скомпилирован Python (через *--without-wide-unicode* или *--with-wide-unicode*, причём первый вариант используется по умолчанию), [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) является 16-битным или 32-битным типом данных. Когда строковый объект используется за пределами CPU и памяти, порядок байтов CPU и способ хранения этих массивов в виде байтов становятся проблемой. Преобразование строкового объекта в последовательность байтов называется кодированием (encoding), а восстановление строкового объекта из последовательности байтов – декодированием (decoding). Существует много различных способов выполнить это преобразование (эти способы также называются кодировками). Самый простой способ – сопоставить кодовые точки 0–255 байтам `0x0`–`0xff`. Это означает, что строковый объект, содержащий кодовые точки выше `U+00FF`, не может быть закодирован этим способом (который называется `'latin-1'` или `'iso-8859-1'`). [`str.encode()`](https://python-all.ru/3.0/library/stdtypes.html#str.encode) вызовет исключение [`UnicodeEncodeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeEncodeError), которое выглядит так: `UnicodeEncodeError: 'latin-1' кодек не может закодировать символ '\u1234' на позиции 3: порядковый номер не входит в range(256)`.624625Существует ещё одна группа кодировок (так называемые charmap-кодировки), которые выбирают другое подмножество всех кодовых точек Unicode и определяют, как эти кодовые точки сопоставляются с байтами `0x0`–`0xff`. Чтобы увидеть, как это делается, достаточно открыть, например, `encodings/cp1252.py` (кодировка, используемая в основном в Windows). Там есть строковая константа из 256 символов, показывающая, какой символ какому значению байта соответствует.626627Все эти кодировки могут кодировать только 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 это средство определения порядка хранения закодированных байтов, которое исчезает после декодирования последовательности байтов в строку; как `НУЛЕВОЙ ШИРИНЫ НЕРАЗРЫВНЫЙ ПРОБЕЛ` это обычный символ, который декодируется как любой другой.628629Существует ещё одна кодировка, способная кодировать полный диапазон символов Unicode: UTF-8. UTF-8 – это 8-битная кодировка, поэтому в UTF-8 нет проблем с порядком байтов. Каждый байт в последовательности UTF-8 состоит из двух частей: битов маркера (самые старшие биты) и битов полезной нагрузки. Биты маркера представляют собой последовательность от нуля до шести единичных битов, за которыми следует нулевой бит. Символы Unicode кодируются так (где x – биты полезной нагрузки, которые при соединении дают символ Unicode):630631| Диапазон | Кодировка |632| --- | --- |633| `U-00000000` ... `U-0000007F` | 0xxxxxxx |634| `U-00000080` ... `U-000007FF` | 110xxxxx 10xxxxxx |635| `U-00000800` ... `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |636| `U-00010000` ... `U-001FFFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |637| `U-00200000` ... `U-03FFFFFF` | 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |638| `U-04000000` ... `U-7FFFFFFF` | 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |639640Младший значащий бит символа Unicode – это самый правый бит x.641642Поскольку UTF-8 – это 8-битная кодировка, BOM не требуется, и любой символ `U+FEFF` в декодированной строке (даже если это первый символ) трактуется как `ZERO WIDTH NO-BREAK SPACE`.643644Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Любая 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-кодировке начинается с этих байтовых значений (которые, например, отображаются в645646> ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЭРЕЗИСОМ647>648> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА649>650> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК651652в iso-8859-1), это увеличивает вероятность того, что кодировку utf-8-sig можно правильно угадать по последовательности байтов. Таким образом, здесь BOM используется не для определения порядка байтов, использованного при генерации последовательности, а как сигнатура, помогающая угадать кодировку. При кодировании кодек utf-8-sig запишет `0xef`, `0xbb`, `0xbf` в качестве первых трёх байтов в файл. При декодировании utf-8-sig пропустит эти три байта, если они окажутся первыми тремя байтами в файле.653654## Стандартные кодировки655656Python поставляется с рядом встроенных кодеков, реализованных либо в виде функций на C, либо в виде словарей, используемых как таблицы соответствия. В следующей таблице перечислены кодеки по именам, а также несколько распространённых псевдонимов и языки, для которых эта кодировка, вероятно, используется. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что варианты написания, отличающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами.657658Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:659660- набор символов ISO 8859661- кодовая страница Microsoft Windows, обычно полученная из набора символов 8859, но заменяющая управляющие символы дополнительными графическими символами662- кодовая страница IBM EBCDIC663- кодовая страница IBM PC, совместимая с ASCII664665| Кодек | Псевдонимы | Языки |666| --- | --- | --- |667| ascii | 646, us-ascii | Английский |668| big5 | big5-tw, csbig5 | Китайский традиционный |669| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |670| cp037 | IBM037, IBM039 | Английский |671| cp424 | EBCDIC-CP-HE, IBM424 | Иврит |672| cp437 | 437, IBM437 | Английский |673| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Западная Европа |674| cp737 |  | Греческий |675| cp775 | IBM775 | Балтийские языки |676| cp850 | 850, IBM850 | Западная Европа |677| cp852 | 852, IBM852 | Центральная и Восточная Европа |678| cp855 | 855, IBM855 | болгарский, белорусский, македонский, русский, сербский |679| cp856 |  | Иврит |680| cp857 | 857, IBM857 | Турецкий |681| cp860 | 860, IBM860 | португальский |682| cp861 | 861, CP-IS, IBM861 | Исландский |683| cp862 | 862, IBM862 | Иврит |684| cp863 | 863, IBM863 | канадский |685| cp864 | IBM864 | Арабский |686| cp865 | 865, IBM865 | датский, норвежский |687| cp866 | 866, IBM866 | Русский |688| cp869 | 869, CP-GR, IBM869 | Греческий |689| cp874 |  | Тайский |690| cp875 |  | Греческий |691| cp932 | 932, ms932, mskanji, ms-kanji | Японский |692| cp949 | 949, ms949, uhc | Корейский |693| cp950 | 950, ms950 | Китайский традиционный |694| cp1006 |  | Урду |695| cp1026 | ibm1026 | Турецкий |696| cp1140 | ibm1140 | Западная Европа |697| cp1250 | windows-1250 | Центральная и Восточная Европа |698| cp1251 | windows-1251 | болгарский, белорусский, македонский, русский, сербский |699| cp1252 | windows-1252 | Западная Европа |700| cp1253 | windows-1253 | Греческий |701| cp1254 | windows-1254 | Турецкий |702| cp1255 | windows-1255 | Иврит |703| cp1256 | windows1256 | Арабский |704| cp1257 | windows-1257 | Балтийские языки |705| cp1258 | windows-1258 | вьетнамский |706| euc\_jp | eucjp, ujis, u-jis | Японский |707| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |708| euc\_jisx0213 | eucjisx0213 | Японский |709| euc\_kr | euckr, корейский, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |710| gb2312 | chinese, csiso58gb231280, euc- cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso- ir-58 | Упрощённый китайский |711| gbk | 936, cp936, ms936 | Унифицированный китайский |712| gb18030 | gb18030-2000 | Унифицированный китайский |713| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |714| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |715| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |716| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |717| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |718| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |719| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |720| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |721| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |722| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |723| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |724| iso8859\_4 | iso-8859-4, latin4, L4 | Балтийские языки |725| iso8859\_5 | iso-8859-5, кириллица | болгарский, белорусский, македонский, русский, сербский |726| iso8859\_6 | iso-8859-6, арабский | Арабский |727| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |728| iso8859\_8 | iso-8859-8, иврит | Иврит |729| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |730| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |731| iso8859\_13 | iso-8859-13 | Балтийские языки |732| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |733| iso8859\_15 | iso-8859-15 | Западная Европа |734| johab | cp1361, ms1361 | Корейский |735| koi8\_r |  | Русский |736| koi8\_u |  | Украинский |737| mac\_cyrillic | maccyrillic | болгарский, белорусский, македонский, русский, сербский |738| mac\_greek | macgreek | Греческий |739| mac\_iceland | maciceland | Исландский |740| mac\_latin2 | maclatin2, maccentraleurope | Центральная и Восточная Европа |741| mac\_roman | macroman | Западная Европа |742| mac\_turkish | macturkish | Турецкий |743| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |744| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |745| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |746| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |747| utf\_32 | U32, utf32 | все языки |748| utf\_32\_be | UTF-32BE | все языки |749| utf\_32\_le | UTF-32LE | все языки |750| utf\_16 | U16, utf16 | все языки |751| utf\_16\_be | UTF-16BE | все языки (только BMP) |752| utf\_16\_le | UTF-16LE | все языки (только BMP) |753| utf\_7 | U7, unicode-1-1-utf-7 | все языки |754| utf\_8 | U8, UTF, utf8 | все языки |755| utf\_8\_sig |  | все языки |756757| Кодек | Псевдонимы | Назначение |758| --- | --- | --- |759| idna |  | Реализует [**RFC 3490**](https://python-all.ru/3.0/library/codecs.html), см. также `encodings.idna` |760| mbcs | dbcs | Только Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |761| palmos |  | Кодировка PalmOS 3.5 |762| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/3.0/library/codecs.html) |763| raw\_unicode\_escape |  | Создаёт строку, пригодную для использования в качестве сырого Unicode-литерала в исходном коде Python |764| undefined |  | Вызывает исключение для всех преобразований. Может использоваться как системная кодировка, если не требуется автоматическое приведение между байтовыми строками и строками Unicode. |765| unicode\_escape |  | Создаёт строку, пригодную для использования в качестве Unicode-литерала в исходном коде Python |766| unicode\_internal |  | Возвращает внутреннее представление операнда |767768## `encodings.idna` – Интернационализированные доменные имена в приложениях769770Этот модуль реализует [**RFC 3490**](https://python-all.ru/3.0/library/codecs.html) (Интернационализированные доменные имена в приложениях) и [**RFC 3492**](https://python-all.ru/3.0/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/3.0/library/stringprep.html#module-stringprep).771772Вместе эти RFC определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (такое как `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, например, `www.xn--alliancefranaise-npb.nu`). Затем форма ACE доменного имени используется везде, где протокол не допускает произвольные символы, например, в DNS-запросах, полях HTTP *Host* и т.д. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки Unicode-доменов в IDNA при передаче и обратно преобразовывать метки ACE в Unicode перед отображением пользователю.773774Python поддерживает это преобразование несколькими способами: кодек `idna` позволяет преобразовывать между Unicode и ACE. Кроме того, модуль [`socket`](https://python-all.ru/3.0/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно заботиться о преобразовании имён хостов при передаче их в модуль socket. Вдобавок, модули, которые принимают имена хостов в качестве параметров функций, например [`http.client`](https://python-all.ru/3.0/library/http.client.html#module-http.client) и [`ftplib`](https://python-all.ru/3.0/library/ftplib.html#module-ftplib), принимают Unicode-имена хостов ([`http.client`](https://python-all.ru/3.0/library/http.client.html#module-http.client) затем также прозрачно отправляет IDNA-имя хоста в поле *Host*, если вообще отправляет это поле).775776При получении имён хостов из сети (например, при обратном поиске имени) автоматическое преобразование в Unicode не выполняется: приложения, желающие отобразить такие имена хостов пользователю, должны декодировать их в Unicode.777778Модуль `encodings.idna` также реализует процедуру nameprep, которая выполняет определённые нормализации имён хостов для достижения нечувствительности к регистру интернационализированных доменных имён и унификации похожих символов. Функции nameprep можно использовать напрямую при необходимости.779780#### `[encodings.idna.nameprep]encodings.idna.nameprep(label)`781782Return the nameprepped version of783784*label*785786. The implementation currently assumes query strings, so787788`AllowUnassigned`789790is true.791792#### `[encodings.idna.ToASCII]encodings.idna.ToASCII(label)`793794Преобразует метку в ASCII, как указано в795796[**RFC 3490**](https://python-all.ru/3.0/library/codecs.html)797798. Параметр799800`UseSTD3ASCIIRules`801802предполагается равным false.803804#### `[encodings.idna.ToUnicode]encodings.idna.ToUnicode(label)`805806Преобразует метку в Unicode, как указано в807808[**RFC 3490**](https://python-all.ru/3.0/library/codecs.html)809810.811812## `encodings.utf_8_sig` – кодек UTF-8 с сигнатурой BOM813814Этот модуль реализует вариант кодека UTF-8: при кодировании префикс UTF-8 BOM будет добавлен перед байтами, закодированными в UTF-8. Для кодировщика с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный UTF-8 BOM в начале данных будет пропущен.815