`codecs.md`

678 строк · 81.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/library/codecs.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 7.8. [`codecs`](https://python-all.ru/2.7/library/codecs.html#module-codecs) – Реестр кодеков и базовые классы89Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодеков и обработки ошибок.1011Он определяет следующие функции:1213#### `codecs.encode(obj[, encoding[, errors]])`1415Кодирует *obj* с помощью кодека, зарегистрированного для *encoding*. Кодировка по умолчанию – `'ascii'`.1617*Errors* may be given to set the desired error handling scheme. The default error handler is `'strict'` meaning that encoding errors raise [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (or a more codec specific subclass, such as [`UnicodeEncodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeEncodeError)). Refer to [Codec Base Classes](https://python-all.ru/2.7/library/codecs.html#codec-base-classes) for more information on codec error handling.1819Новое в версии 2.4.2021#### `codecs.decode(obj[, encoding[, errors]])`2223Декодирует *obj* с помощью кодека, зарегистрированного для *encoding*. Кодировка по умолчанию – `'ascii'`.2425*Errors* may be given to set the desired error handling scheme. The default error handler is `'strict'` meaning that decoding errors raise [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (or a more codec specific subclass, such as [`UnicodeDecodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeDecodeError)). Refer to [Codec Base Classes](https://python-all.ru/2.7/library/codecs.html#codec-base-classes) for more information on codec error handling.2627Новое в версии 2.4.2829#### `codecs.register(search_function)`3031Регистрирует функцию поиска кодека. Функции поиска должны принимать один аргумент – имя кодировки строчными буквами, и возвращать объект `CodecInfo` со следующими атрибутами:3233- `name` Имя кодировки;34- `encode` Функция кодирования без сохранения состояния;35- `decode` Функция декодирования без сохранения состояния;36- `incrementalencoder` Инкрементальный класс кодировщика или фабричная функция;37- `incrementaldecoder` Инкрементальный класс декодировщика или фабричная функция;38- `streamwriter` Класс потокового писателя или фабричная функция;39- `streamreader` Класс потокового читателя или фабричная функция.4041Различные функции или классы принимают следующие аргументы:4243*encode* и *decode*: это должны быть функции или методы с тем же интерфейсом, что и методы [`encode()`](https://python-all.ru/2.7/library/codecs.html#codecs.Codec.encode)/[`decode()`](https://python-all.ru/2.7/library/codecs.html#codecs.Codec.decode) экземпляров Codec (см. [Интерфейс Codec](https://python-all.ru/2.7/library/codecs.html#codec-objects)). Ожидается, что функции/методы работают в режиме без сохранения состояния.4445*incrementalencoder* и *incrementaldecoder*: это должны быть фабричные функции, предоставляющие следующий интерфейс:4647> `factory(errors='strict')`4849Фабричные функции должны возвращать объекты, предоставляющие интерфейсы, определённые базовыми классами [`IncrementalEncoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalDecoder) соответственно. Инкрементальные кодеки могут поддерживать состояние.5051*streamreader* и *streamwriter*: это должны быть фабричные функции, предоставляющие следующий интерфейс:5253> `factory(stream, errors='strict')`5455Фабричные функции должны возвращать объекты, предоставляющие интерфейсы, определённые базовыми классами [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter) соответственно. Потоковые кодеки могут поддерживать состояние.5657Возможные значения параметра errors:5859- `'strict'`: возбуждать исключение в случае ошибки кодирования60- `'replace'`: заменять повреждённые данные подходящим замещающим маркером, например `'?'` или `'\ufffd'`61- `'ignore'`: игнорировать повреждённые данные и продолжать без дополнительных уведомлений62- `'xmlcharrefreplace'`: заменять соответствующей XML-ссылкой на символ (только для кодирования)63- `'backslashreplace'`: заменять экранированными последовательностями с обратной косой чертой (только для кодирования)6465а также любое другое имя обработчика ошибок, определённое через [`register_error()`](https://python-all.ru/2.7/library/codecs.html#codecs.register_error).6667Если функция поиска не может найти заданную кодировку, она должна вернуть `None`.6869#### `codecs.lookup(encoding)`7071Ищет информацию о кодеке в реестре кодеков Python и возвращает объект `CodecInfo`, как определено выше.7273Сначала кодировки ищутся в кэше реестра. Если не найдены, просматривается список зарегистрированных функций поиска. Если объект `CodecInfo` не найден, вызывается [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError). В противном случае объект `CodecInfo` сохраняется в кэше и возвращается вызывающему.7475Для упрощения доступа к различным кодекам модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/2.7/library/codecs.html#codecs.lookup) для поиска кодека:7677#### `codecs.getencoder(encoding)`7879Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.8081Вызывает [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError), если кодировка не найдена.8283#### `codecs.getdecoder(encoding)`8485Находит кодек для указанной кодировки и возвращает его функцию-декодер.8687Вызывает [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError), если кодировка не найдена.8889#### `codecs.getincrementalencoder(encoding)`9091Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.9293Вызывает [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный кодировщик.9495Новое в версии 2.5.9697#### `codecs.getincrementaldecoder(encoding)`9899Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.100101Вызывает [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный декодер.102103Новое в версии 2.5.104105#### `codecs.getreader(encoding)`106107Находит кодек для указанной кодировки и возвращает его класс StreamReader или фабричную функцию.108109Вызывает [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError), если кодировка не найдена.110111#### `codecs.getwriter(encoding)`112113Находит кодек для указанной кодировки и возвращает его класс StreamWriter или фабричную функцию.114115Вызывает [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError), если кодировка не найдена.116117#### `codecs.register_error(name, error_handler)`118119Регистрирует функцию обработки ошибок *error\_handler* под именем *name*. *error\_handler* будет вызываться при кодировании и декодировании в случае ошибки, когда *name* указан как параметр errors.120121При кодировании *error\_handler* будет вызван с экземпляром [`UnicodeEncodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeEncodeError), который содержит информацию о местоположении ошибки. Обработчик ошибок должен либо возбудить это же или другое исключение, либо вернуть кортеж с заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Кодировщик закодирует замену и продолжит кодирование исходного ввода с указанной позиции. Отрицательные значения позиции трактуются как относительные от конца входной строки. Если результирующая позиция выходит за границы, будет возбуждено [`IndexError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.IndexError).122123Декодирование и трансляция работают аналогично, за исключением того, что обработчику будет передан [`UnicodeDecodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeTranslateError), и что замена от обработчика ошибок будет помещена в вывод напрямую.124125#### `codecs.lookup_error(name)`126127Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.128129Выбрасывает [`LookupError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.LookupError), если обработчик не найден.130131#### `codecs.strict_errors(exception)`132133Реализует обработку ошибок `strict`: каждая ошибка кодирования или декодирования возбуждает [`UnicodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeError).134135#### `codecs.replace_errors(exception)`136137Реализует обработку ошибок `replace`: повреждённые данные заменяются подходящим замещающим символом, таким как `'?'` в байтовых строках и `'\ufffd'` в строках Unicode.138139#### `codecs.ignore_errors(exception)`140141Реализует обработку ошибок `ignore`: повреждённые данные игнорируются, и кодирование или декодирование продолжается без дополнительных уведомлений.142143#### `codecs.xmlcharrefreplace_errors(exception)`144145Реализует обработку ошибок `xmlcharrefreplace` (только для кодирования): не кодируемый символ заменяется соответствующей XML-ссылкой на символ.146147#### `codecs.backslashreplace_errors(exception)`148149Реализует обработку ошибок `backslashreplace` (только для кодирования): не кодируемый символ заменяется управляющей последовательностью с обратной косой чертой.150151Для упрощения работы с закодированными файлами или потоками модуль также определяет следующие вспомогательные функции:152153#### `codecs.open(filename, mode[, encoding[, errors[, buffering]]])`154155Открывает закодированный файл, используя заданный *режим*, и возвращает обёрнутую версию, обеспечивающую прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, то есть файл открывается в режиме чтения.156157> **Примечание**158>159> Обёрнутая версия принимает только формат объектов, определённый кодеками, то есть объекты Unicode для большинства встроенных кодеков. Вывод также зависит от кодека и обычно тоже будет Unicode.160161> **Примечание**162>163> Файлы всегда открываются в двоичном режиме, даже если двоичный режим не был указан. Это сделано для предотвращения потери данных из-за кодировок, использующих 8-битные значения. Это означает, что при чтении и записи не выполняется автоматическое преобразование `'\n'`.164165*encoding* задаёт кодировку, которая будет использоваться для файла.166167Параметр *errors* можно задать для определения обработки ошибок. По умолчанию он равен `'strict'`, что приводит к возбуждению [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) при возникновении ошибки кодирования.168169*buffering* имеет то же значение, что и для встроенной функции [`open()`](https://python-all.ru/2.7/library/functions.html#open). По умолчанию используется построчная буферизация.170171#### `codecs.EncodedFile(file, input[, output[, errors]])`172173Возвращает обёрнутую версию файла, которая обеспечивает прозрачное преобразование кодировки.174175Строки, записываемые в обёрнутый файл, интерпретируются в соответствии с заданной кодировкой *input*, а затем записываются в исходный файл как строки с использованием кодировки *output*. Промежуточная кодировка обычно будет Unicode, но зависит от указанных кодеков.176177Если *output* не задан, по умолчанию используется *input*.178179*errors* может быть задан для определения обработки ошибок. По умолчанию `'strict'`, что приводит к возбуждению [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) в случае ошибки кодирования.180181#### `codecs.iterencode(iterable, encoding[, errors])`182183Использует инкрементальный кодировщик для последовательного кодирования входных данных из *iterable*. Эта функция является [генератором](https://python-all.ru/2.7/glossary.html#term-generator). Параметр *errors* (а также любые другие именованные аргументы) передаётся инкрементальному кодировщику.184185Новое в версии 2.5.186187#### `codecs.iterdecode(iterable, encoding[, errors])`188189Использует инкрементальный декодировщик для последовательного декодирования входных данных из *iterable*. Эта функция является [генератором](https://python-all.ru/2.7/glossary.html#term-generator). Параметр *errors* (а также любые другие именованные аргументы) передаётся инкрементальному декодировщику.190191Новое в версии 2.5.192193Модуль также предоставляет следующие константы, полезные для чтения и записи в платформенно-зависимые файлы:194195#### `codecs.BOM`196197#### `codecs.BOM_BE`198199#### `codecs.BOM_LE`200201#### `codecs.BOM_UTF8`202203#### `codecs.BOM_UTF16`204205#### `codecs.BOM_UTF16_BE`206207#### `codecs.BOM_UTF16_LE`208209#### `codecs.BOM_UTF32`210211#### `codecs.BOM_UTF32_BE`212213#### `codecs.BOM_UTF32_LE`214215Эти константы определяют различные кодировки метки порядка байтов (BOM) Unicode, используемые в потоках данных UTF-16 и UTF-32 для указания порядка байтов в потоке или файле, а в UTF-8 – как сигнатура Unicode. [`BOM_UTF16`](https://python-all.ru/2.7/library/codecs.html#codecs.BOM_UTF16) – это либо [`BOM_UTF16_BE`](https://python-all.ru/2.7/library/codecs.html#codecs.BOM_UTF16_BE), либо [`BOM_UTF16_LE`](https://python-all.ru/2.7/library/codecs.html#codecs.BOM_UTF16_LE) в зависимости от нативного порядка байтов платформы, [`BOM`](https://python-all.ru/2.7/library/codecs.html#codecs.BOM) – псевдоним для [`BOM_UTF16`](https://python-all.ru/2.7/library/codecs.html#codecs.BOM_UTF16), [`BOM_LE`](https://python-all.ru/2.7/library/codecs.html#codecs.BOM_LE) – для [`BOM_UTF16_LE`](https://python-all.ru/2.7/library/codecs.html#codecs.BOM_UTF16_LE) и [`BOM_BE`](https://python-all.ru/2.7/library/codecs.html#codecs.BOM_BE) – для [`BOM_UTF16_BE`](https://python-all.ru/2.7/library/codecs.html#codecs.BOM_UTF16_BE). Остальные представляют BOM в кодировках UTF-8 и UTF-32.216217## 7.8.1. Базовые классы кодеков218219Модуль [`codecs`](https://python-all.ru/2.7/library/codecs.html#module-codecs) определяет набор базовых классов, которые задают интерфейс и могут также использоваться для простого написания собственных кодеков для использования в Python.220221Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в качестве кодека в Python: статический кодировщик без состояния, статический декодировщик без состояния, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно повторно используют статический кодировщик/декодировщик без состояния для реализации файловых протоколов.222223Класс `Codec` определяет интерфейс для кодеров/декодеров без состояния.224225Для упрощения и стандартизации обработки ошибок методы [`encode()`](https://python-all.ru/2.7/library/codecs.html#codecs.Codec.encode) и [`decode()`](https://python-all.ru/2.7/library/codecs.html#codecs.Codec.decode) могут реализовывать различные схемы обработки ошибок, принимая строковый аргумент *errors*. Следующие строковые значения определены и реализованы во всех стандартных кодеках Python:226227| Значение | Значение |228| --- | --- |229| `'strict'` | Возбуждать [`UnicodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeError) (или подкласс); это поведение по умолчанию. |230| `'ignore'` | Игнорирует символ и продолжает со следующего. |231| `'replace'` | Заменяет подходящим заменяющим символом; для встроенных кодеков Unicode при декодировании Python будет использовать официальный U+FFFD REPLACEMENT CHARACTER, а при кодировании – '?'. |232| `'xmlcharrefreplace'` | Заменяет соответствующей символьной ссылкой XML (только для кодирования). |233| `'backslashreplace'` | Заменяет escape-последовательностями с обратной косой чертой (только для кодирования). |234235Набор допустимых значений может быть расширен с помощью [`register_error()`](https://python-all.ru/2.7/library/codecs.html#codecs.register_error).236237### 7.8.1.1. Объекты кодеков238239Класс `Codec` определяет следующие методы, которые также задают функциональные интерфейсы кодера и декодера без состояния:240241#### `Codec.encode(input[, errors])`242243Кодирует объект *input* и возвращает кортеж (выходной объект, количество использованных символов). Хотя кодеки не ограничены использованием с Unicode, в контексте Unicode кодирование преобразует объект Unicode в простую строку с использованием определённой кодировки набора символов (например, `cp1252` или `iso-8859-1`).244245*errors* определяет применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.246247Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter) для кодеков, которым необходимо сохранять состояние для эффективного кодирования.248249Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.250251#### `Codec.decode(input[, errors])`252253Декодирует объект *input* и возвращает кортеж (выходной объект, количество использованных символов). В контексте Unicode декодирование преобразует простую строку, закодированную с использованием определённой кодировки набора символов, в объект Unicode.254255*input* должен быть объектом, который предоставляет слот буфера `bf_getreadbuf`. Строки Python, буферные объекты и файлы, отображённые в память, являются примерами объектов, предоставляющих этот слот.256257*errors* определяет применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.258259Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) для кодеков, которым необходимо сохранять состояние для эффективного декодирования.260261Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.262263Классы [`IncrementalEncoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalDecoder) предоставляют базовый интерфейс для инкрементального кодирования и декодирования. Кодирование/декодирование входных данных выполняется не одним вызовом функции кодировщика/декодировщика без состояния, а несколькими вызовами метода [`encode()`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalDecoder.decode) инкрементального кодировщика/декодировщика. Инкрементальный кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.264265Объединённый вывод вызовов метода [`encode()`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalDecoder.decode) совпадает с тем, что получилось бы, если бы все отдельные входные данные были объединены в один, и этот вход был закодирован/декодирован кодировщиком/декодировщиком без состояния.266267### 7.8.1.2. Объекты IncrementalEncoder268269Новое в версии 2.5.270271Класс [`IncrementalEncoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный кодировщик для совместимости с реестром кодеков Python.272273#### `class codecs.IncrementalEncoder([errors])`274275Конструктор экземпляра [`IncrementalEncoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalEncoder).276277Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.278279[`IncrementalEncoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalEncoder) может реализовывать различные схемы обработки ошибок, предоставляя именованный аргумент *errors*. Эти параметры предопределены:280281- `'strict'` Возбуждать [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (или подкласс); это по умолчанию.282- `'ignore'` Игнорировать символ и продолжить со следующим.283- `'replace'` Заменить подходящим заменяющим символом284- `'xmlcharrefreplace'` Заменить соответствующей XML-ссылкой на символ285- `'backslashreplace'` Заменить управляющими последовательностями с обратной косой чертой.286287Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalEncoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalEncoder).288289Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/2.7/library/codecs.html#codecs.register_error).290291#### `encode(object[, final])`292293Кодирует *object* (с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов [`encode()`](https://python-all.ru/2.7/library/codecs.html#codecs.encode), *final* должен быть истинным (по умолчанию – ложь).294295#### `reset()`296297Сбрасывает кодировщик в начальное состояние.298299### 7.8.1.3. Объекты IncrementalDecoder300301Класс [`IncrementalDecoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный декодер для совместимости с реестром кодеков Python.302303#### `class codecs.IncrementalDecoder([errors])`304305Конструктор экземпляра [`IncrementalDecoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalDecoder).306307Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.308309[`IncrementalDecoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalDecoder) может реализовывать разные схемы обработки ошибок с помощью ключевого аргумента *errors*. Доступны следующие параметры:310311- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (или подкласс); используется по умолчанию.312- `'ignore'` Пропускает символ и переходит к следующему.313- `'replace'` Заменяет подходящим символом-заменителем.314315Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalDecoder`](https://python-all.ru/2.7/library/codecs.html#codecs.IncrementalDecoder).316317Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/2.7/library/codecs.html#codecs.register_error).318319#### `decode(object[, final])`320321Декодирует *object* (с учётом текущего состояния декодера) и возвращает результирующий декодированный объект. Если это последний вызов [`decode()`](https://python-all.ru/2.7/library/codecs.html#codecs.decode), *final* должен быть истинным (по умолчанию – ложь). Если *final* истинно, декодер должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).322323#### `reset()`324325Сбрасывает декодер в исходное состояние.326327Классы [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) предоставляют универсальные рабочие интерфейсы, которые можно использовать для очень простой реализации новых подмодулей кодирования. Пример см. в `encodings.utf_8`.328329### 7.8.1.4. Объекты StreamWriter330331Класс [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый писатель должен реализовать для совместимости с реестром кодеков Python.332333#### `class codecs.StreamWriter(stream[, errors])`334335Конструктор экземпляра [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter).336337Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.338339*поток данных* должен быть файлоподобным объектом, открытым для записи двоичных данных.340341[`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter) может реализовывать разные схемы обработки ошибок, указывая ключевой аргумент *errors*. Доступны следующие параметры:342343- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (или подкласс); используется по умолчанию.344- `'ignore'` Пропускает символ и переходит к следующему.345- `'replace'` Заменяет подходящим символом-заменителем346- `'xmlcharrefreplace'` Заменяет соответствующей ссылкой на символ XML347- `'backslashreplace'` Заменяет экранированными последовательностями с обратной косой чертой.348349Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter).350351Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/2.7/library/codecs.html#codecs.register_error).352353#### `write(object)`354355Записывает в поток закодированное содержимое объекта.356357#### `writelines(list)`358359Записывает в поток объединённый список строк (возможно, переиспользуя метод [`write()`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter.write)).360361#### `reset()`362363Сбрасывает и переустанавливает буферы кодека, используемые для сохранения состояния.364365Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.366367В дополнение к приведённым выше методам, [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.368369### 7.8.1.5. Объекты StreamReader370371Класс [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый читатель должен реализовать для совместимости с реестром кодеков Python.372373#### `class codecs.StreamReader(stream[, errors])`374375Конструктор экземпляра [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader).376377Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.378379*поток данных* должен быть файлоподобным объектом, открытым для чтения (двоичных) данных.380381[`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) может реализовывать разные схемы обработки ошибок, указывая ключевой аргумент *errors*. Определены следующие параметры:382383- `'strict'` Возбуждает [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError) (или подкласс); используется по умолчанию.384- `'ignore'` Пропускает символ и переходит к следующему.385- `'replace'` Заменяет подходящим символом-заменителем.386387Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader).388389Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/2.7/library/codecs.html#codecs.register_error).390391#### `read([size[, chars[, firstline]]])`392393Декодирует данные из потока и возвращает результирующий объект.394395*chars* указывает количество читаемых из потока символов. [`read()`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader.read) никогда не вернёт больше *chars* символов, но может вернуть меньше, если доступно недостаточно символов.396397*size* указывает приблизительное максимальное количество байт для чтения из потока данных в целях декодирования. Декодер может изменять этот параметр по своему усмотрению. Значение по умолчанию -1 означает, что нужно читать и декодировать как можно больше. *size* предназначен для того, чтобы избежать декодирования огромных файлов за один шаг.398399*firstline* указывает, что достаточно вернуть только первую строку, если на последующих строках возникают ошибки декодирования.400401Метод должен использовать жадную стратегию чтения, то есть читать столько данных, сколько допускается определением кодировки и заданным размером; например, если в потоке доступны необязательные окончания кодировки или маркеры состояния, их также следует прочитать.402403Изменено в версии 2.4: добавлен аргумент *chars*.404405Изменено в версии 2.4.2: добавлен аргумент *firstline*.406407#### `readline([size[, keepends]])`408409Читает одну строку из входного потока и возвращает декодированные данные.410411*size*, если задан, передаётся как аргумент size в метод [`read()`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader.read) потока данных.412413Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.414415Изменено в версии 2.4: добавлен аргумент *keepends*.416417#### `readlines([sizehint[, keepends]])`418419Читает все строки из входного потока данных и возвращает их в виде списка строк.420421Окончания строк реализуются с помощью метода декодера кодека и включаются в элементы списка, если *keepends* имеет значение true.422423*sizehint*, если задан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader.read) потока данных.424425#### `reset()`426427Сбрасывает буферы кодека, используемые для сохранения состояния.428429Обратите внимание, что никакое перемещение позиции в потоке не должно выполняться. Этот метод предназначен в первую очередь для восстановления после ошибок декодирования.430431В дополнение к приведённым выше методам, [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.432433Следующие два базовых класса включены для удобства. Они не нужны реестру кодеков, но могут оказаться полезными на практике.434435### 7.8.1.6. Объекты StreamReaderWriter436437[`StreamReaderWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReaderWriter) позволяет оборачивать потоки, работающие в режиме как чтения, так и записи.438439Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/2.7/library/codecs.html#codecs.lookup).440441#### `class codecs.StreamReaderWriter(stream, Reader, Writer, errors)`442443Создаёт экземпляр [`StreamReaderWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReaderWriter). *поток данных* должен быть файлоподобным объектом. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими интерфейсы [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter) соответственно. Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.444445Экземпляры [`StreamReaderWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReaderWriter) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.446447### 7.8.1.7. Объекты StreamRecoder448449[`StreamRecoder`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamRecoder) предоставляют представление данных кодирования с разделением на внешний и внутренний уровни, что иногда полезно при работе с разными средами кодирования.450451Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/2.7/library/codecs.html#codecs.lookup).452453#### `class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors)`454455Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamRecoder), реализующий двунаправленное преобразование: *encode* и *decode* работают на внешнем уровне (вход `read()` и выход `write()`), а *Reader* и *Writer* – на внутреннем (чтение и запись в поток).456457Эти объекты можно использовать для прозрачного прямого перекодирования, например, из Latin-1 в UTF-8 и обратно.458459*Поток данных* должен быть файлоподобным объектом.460461*encode* и *decode* должны соответствовать интерфейсу `Codec`. *Reader*, *Writer* должны быть фабричными функциями или классами, предоставляющими объекты интерфейсов [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter) соответственно.462463*encode* и *decode* нужны для преобразования на внешнем уровне, а *Reader* и *Writer* – на внутреннем. Используемый промежуточный формат определяется двумя наборами кодеков; например, кодеки Unicode будут использовать Unicode как промежуточную кодировку.464465Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.466467Экземпляры [`StreamRecoder`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamRecoder) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/2.7/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.468469## 7.8.2. Кодировки и Юникод470471Строки Unicode внутри хранятся как последовательности кодовых точек (если точнее, как массивы [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE)). В зависимости от того, как собран Python (через `--enable-unicode=ucs2` или `--enable-unicode=ucs4`, причём первое используется по умолчанию), [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE) может быть 16-битным или 32-битным типом данных. Когда объект Unicode используется за пределами CPU и памяти, порядок байт (endianness) и способ хранения массивов в виде байтов становятся важными. Преобразование объекта Unicode в последовательность байтов называется кодированием, а восстановление объекта Unicode из последовательности байтов – декодированием. Существует много различных способов такого преобразования (они также называются кодировками). Простейший метод – сопоставить кодовые точки 0–255 байтам `0x0`–`0xff`. Это означает, что объект Unicode, содержащий кодовые точки выше `U+00FF`, нельзя закодировать этим методом (который называется `'latin-1'` или `'iso-8859-1'`). `unicode.encode()` возбудит исключение [`UnicodeEncodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeEncodeError), которое выглядит так: `UnicodeEncodeError: 'latin-1' codec can't encode character u'\u1234' in position 3: ordinal not in range(256)`.472473Существует ещё одна группа кодировок (так называемые charmap-кодировки), которые выбирают другое подмножество всех кодовых точек Unicode и определяют, как эти кодовые точки сопоставляются байтам `0x0`–`0xff`. Чтобы увидеть, как это работает, достаточно открыть, например, `encodings/cp1252.py` (это кодировка, используемая в основном в Windows). Там есть строковая константа из 256 символов, показывающая, какой символ какому значению байта соответствует.474475Все эти кодировки могут закодировать лишь 256 из 1114112 кодовых точек, определённых в Unicode. Простой и прямой способ, позволяющий хранить каждую кодовую точку Unicode, – хранить каждую кодовую точку как четыре последовательных байта. Есть две возможности: хранить байты в порядке big endian или little endian. Эти две кодировки называются `UTF-32-BE` и `UTF-32-LE` соответственно. Их недостаток в том, что если, например, использовать `UTF-32-BE` на little endian-машине, то всегда придётся менять порядок байтов при кодировании и декодировании. `UTF-32` избегает этой проблемы: байты всегда будут располагаться в естественном порядке. Однако при чтении этих байтов CPU с другим порядком байтов их придётся переставлять. Чтобы иметь возможность определить порядок байтов последовательности `UTF-16` или `UTF-32`, существует так называемая BOM (метка порядка байтов). Это символ Unicode `U+FEFF`. Этот символ может добавляться в начало каждой последовательности байтов `UTF-16` или `UTF-32`. Версия этого символа с переставленными байтами (`0xFFFE`) является недопустимым символом, который не должен встречаться в тексте Unicode. Таким образом, когда первый символ в последовательности `UTF-16` или `UTF-32` оказывается `U+FFFE`, байты необходимо переставить при декодировании. К сожалению, символ `U+FEFF` имел и второе назначение как `ZERO WIDTH NO-BREAK SPACE`: символ, не имеющий ширины и не позволяющий разбивать слово. Его можно использовать, например, для подсказок алгоритму лигатур. Начиная с Unicode 4.0 использование `U+FEFF` в качестве `ZERO WIDTH NO-BREAK SPACE` считается устаревшим (эту роль взял на себя `U+2060` (`WORD JOINER`)). Тем не менее, программное обеспечение Unicode по-прежнему должно уметь обрабатывать `U+FEFF` в обеих ролях: как BOM это средство определения порядка хранения закодированных байтов, которое исчезает после декодирования последовательности в строку Unicode; как `ZERO WIDTH NO-BREAK SPACE` это обычный символ, который декодируется как любой другой.476477Существует ещё одна кодировка, способная кодировать весь диапазон символов Unicode: UTF-8. UTF-8 – это 8-битная кодировка, а это значит, что в UTF-8 нет проблем с порядком байтов. Каждый байт в последовательности UTF-8 состоит из двух частей: битов маркера (самые старшие биты) и битов полезной нагрузки. Биты маркера представляют собой последовательность от нуля до четырёх битов `1`, за которой следует бит `0`. Символы Unicode кодируются следующим образом (где x – биты полезной нагрузки, которые при объединении дают символ Unicode):478479| Диапазон | Кодировка |480| --- | --- |481| `U-00000000` … `U-0000007F` | 0xxxxxxx |482| `U-00000080` … `U-000007FF` | 110xxxxx 10xxxxxx |483| `U-00000800` … `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |484| `U-00010000` … `U-0010FFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |485486Младший значащий бит символа Unicode – это самый правый бит x.487488Поскольку UTF-8 – это 8-битная кодировка, BOM не требуется, и любой `U+FEFF` символ в dекодированной строке Unicode (даже если это первый символ) рассматривается как `ZERO WIDTH NO-BREAK SPACE`.489490Без дополнительной информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки Unicode. Любая charmap-кодировка может декодировать любую произвольную последовательность байт. Однако с UTF-8 это невозможно, так как байтовые последовательности UTF-8 имеют структуру, не допускающую произвольных последовательностей. Чтобы повысить надёжность определения кодировки UTF-8, Microsoft изобрела вариант UTF-8 (который Python 2.5 называет `"utf-8-sig"`) для своей программы Notepad: перед тем как любой символ Unicode записывается в файл, записывается BOM в кодировке UTF-8 (который выглядит как последовательность байт: `0xef`, `0xbb`, `0xbf`). Поскольку маловероятно, что какой-либо файл в charmap-кодировке начинается с таких значений байт (которые, например, отображаются в491492> ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЭРЕЗИСОМ493>494> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА495>496> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК497498в iso-8859-1) это увеличивает вероятность того, что кодировка `utf-8-sig` может быть правильно определена по последовательности байтов. Таким образом, здесь BOM используется не для определения порядка байтов, используемого при формировании последовательности байтов, а как сигнатура, помогающая угадать кодировку. При кодировании кодек utf-8-sig запишет `0xef`, `0xbb`, `0xbf` как первые три байта в файл. При декодировании `utf-8-sig` пропустит эти три байта, если они стоят в начале файла. В UTF-8 использование BOM не рекомендуется и, как правило, его следует избегать.499500## 7.8.3. Стандартные кодировки501502Python поставляется с рядом встроенных кодеков, реализованных либо как функции на C либо с использованием словарей в качестве таблиц сопоставления. В следующей таблице перечислены кодеки по имени, а также некоторые распространённые псевдонимы и языки, для которых вероятно используется данная кодировка. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что альтернативные написания, различающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами; поэтому, например, `'utf-8'` является допустимым псевдонимом для кодека `'utf_8'`.503504Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:505506- набор символов ISO 8859507- кодовая страница Microsoft Windows, которая обычно происходит из набора 8859, но заменяет управляющие символы дополнительными графическими символами508- кодовая страница IBM EBCDIC509- кодовая страница IBM PC, совместимая с ASCII510511| Кодек | Псевдонимы | Языки |512| --- | --- | --- |513| ascii | 646, us-ascii | Английский |514| big5 | big5-tw, csbig5 | Китайский традиционный |515| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |516| cp037 | IBM037, IBM039 | Английский |517| cp424 | EBCDIC-CP-HE, IBM424 | Иврит |518| cp437 | 437, IBM437 | Английский |519| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Западная Европа |520| cp720 |  | Арабский |521| cp737 |  | Греческий |522| cp775 | IBM775 | Балтийские языки |523| cp850 | 850, IBM850 | Западная Европа |524| cp852 | 852, IBM852 | Центральная и Восточная Европа |525| cp855 | 855, IBM855 | болгарский, белорусский, македонский, русский, сербский |526| cp856 |  | Иврит |527| cp857 | 857, IBM857 | Турецкий |528| cp858 | 858, IBM858 | Западная Европа |529| cp860 | 860, IBM860 | португальский |530| cp861 | 861, CP-IS, IBM861 | Исландский |531| cp862 | 862, IBM862 | Иврит |532| cp863 | 863, IBM863 | канадский |533| cp864 | IBM864 | Арабский |534| cp865 | 865, IBM865 | датский, норвежский |535| cp866 | 866, IBM866 | Русский |536| cp869 | 869, CP-GR, IBM869 | Греческий |537| cp874 |  | Тайский |538| cp875 |  | Греческий |539| cp932 | 932, ms932, mskanji, ms-kanji | Японский |540| cp949 | 949, ms949, uhc | Корейский |541| cp950 | 950, ms950 | Китайский традиционный |542| cp1006 |  | Урду |543| cp1026 | ibm1026 | Турецкий |544| cp1140 | ibm1140 | Западная Европа |545| cp1250 | windows-1250 | Центральная и Восточная Европа |546| cp1251 | windows-1251 | болгарский, белорусский, македонский, русский, сербский |547| cp1252 | windows-1252 | Западная Европа |548| cp1253 | windows-1253 | Греческий |549| cp1254 | windows-1254 | Турецкий |550| cp1255 | windows-1255 | Иврит |551| cp1256 | windows-1256 | Арабский |552| cp1257 | windows-1257 | Балтийские языки |553| cp1258 | windows-1258 | вьетнамский |554| euc\_jp | eucjp, ujis, u-jis | Японский |555| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |556| euc\_jisx0213 | eucjisx0213 | Японский |557| euc\_kr | euckr, корейский, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |558| gb2312 | chinese, csiso58gb231280, euc- cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso- ir-58 | Упрощённый китайский |559| gbk | 936, cp936, ms936 | Унифицированный китайский |560| gb18030 | gb18030-2000 | Унифицированный китайский |561| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |562| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |563| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |564| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |565| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |566| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |567| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |568| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |569| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |570| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |571| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |572| iso8859\_4 | iso-8859-4, latin4, L4 | Балтийские языки |573| iso8859\_5 | iso-8859-5, кириллица | болгарский, белорусский, македонский, русский, сербский |574| iso8859\_6 | iso-8859-6, арабский | Арабский |575| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |576| iso8859\_8 | iso-8859-8, иврит | Иврит |577| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |578| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |579| iso8859\_11 | iso-8859-11, тайская | Тайские языки |580| iso8859\_13 | iso-8859-13, latin7, L7 | Балтийские языки |581| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |582| iso8859\_15 | iso-8859-15, latin9, L9 | Западная Европа |583| iso8859\_16 | iso-8859-16, latin10, L10 | Юго-Восточная Европа |584| johab | cp1361, ms1361 | Корейский |585| koi8\_r |  | Русский |586| koi8\_u |  | Украинский |587| mac\_cyrillic | maccyrillic | болгарский, белорусский, македонский, русский, сербский |588| mac\_greek | macgreek | Греческий |589| mac\_iceland | maciceland | Исландский |590| mac\_latin2 | maclatin2, maccentraleurope | Центральная и Восточная Европа |591| mac\_roman | macroman | Западная Европа |592| mac\_turkish | macturkish | Турецкий |593| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |594| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |595| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |596| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |597| utf\_32 | U32, utf32 | все языки |598| utf\_32\_be | UTF-32BE | все языки |599| utf\_32\_le | UTF-32LE | все языки |600| utf\_16 | U16, utf16 | все языки |601| utf\_16\_be | UTF-16BE | все языки (только BMP) |602| utf\_16\_le | UTF-16LE | все языки (только BMP) |603| utf\_7 | U7, unicode-1-1-utf-7 | все языки |604| utf\_8 | U8, UTF, utf8 | все языки |605| utf\_8\_sig |  | все языки |606607## 7.8.4. Специфические кодировки Python608609Некоторые предопределенные кодеки специфичны для Python, поэтому их имена кодеков не имеют смысла за пределами Python. Они перечислены в таблицах ниже по типам ожидаемых входных и выходных данных (обратите внимание, что хотя текстовые кодировки являются наиболее распространенным вариантом использования кодеков, базовая инфраструктура кодеков поддерживает произвольные преобразования данных, а не только текстовые кодировки). Для асимметричных кодеков указанное назначение описывает направление кодирования.610611Следующие кодеки обеспечивают кодирование из Unicode в str [1](https://python-all.ru/2.7/library/codecs.html#encoding-note) и декодирование из str в Unicode [2](https://python-all.ru/2.7/library/codecs.html#decoding-note), аналогично кодировкам текста Unicode.612613| Кодек | Псевдонимы | Назначение |614| --- | --- | --- |615| idna |  | Реализует [**RFC 3490**](https://python-all.ru/2.7/library/codecs.html), см. также [`encodings.idna`](https://python-all.ru/2.7/library/codecs.html#module-encodings.idna) |616| mbcs | dbcs | Только Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |617| palmos |  | Кодировка PalmOS 3.5 |618| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/2.7/library/codecs.html) |619| raw\_unicode\_escape |  | Создаёт строку, пригодную для использования в качестве сырого Unicode-литерала в исходном коде Python |620| rot\_13 | rot13 | Возвращает шифрование Цезаря операнда |621| undefined |  | Вызывает исключение для всех преобразований. Может использоваться как системная кодировка, если автоматическое [приведение](https://python-all.ru/2.7/glossary.html#term-coercion) между байтовыми строками и строками Unicode не требуется. |622| unicode\_escape |  | Создаёт строку, пригодную для использования в качестве Unicode-литерала в исходном коде Python |623| unicode\_internal |  | Возвращает внутреннее представление операнда |624625Новое в версии 2.3: Кодировки `idna` и `punycode`.626627Следующие кодеки обеспечивают кодирование и декодирование из строки в строку [2](https://python-all.ru/2.7/library/codecs.html#decoding-note).628629| Кодек | Псевдонимы | Назначение | Кодировщик/декодировщик |630| --- | --- | --- | --- |631| base64\_codec | base64, base-64 | Преобразует операнд в многолинейный MIME base64 (результат всегда содержит завершающий `'\n'`) | [`base64.encodestring()`](https://python-all.ru/2.7/library/base64.html#base64.encodestring), [`base64.decodestring()`](https://python-all.ru/2.7/library/base64.html#base64.decodestring) |632| bz2\_codec | bz2 | Сжимает операнд с помощью bz2 | [`bz2.compress()`](https://python-all.ru/2.7/library/bz2.html#bz2.compress), [`bz2.decompress()`](https://python-all.ru/2.7/library/bz2.html#bz2.decompress) |633| hex\_codec | hex | Преобразует операнд в шестнадцатеричное представление, по два разряда на байт | [`binascii.b2a_hex()`](https://python-all.ru/2.7/library/binascii.html#binascii.b2a_hex), [`binascii.a2b_hex()`](https://python-all.ru/2.7/library/binascii.html#binascii.a2b_hex) |634| quopri\_codec | quopri, quoted-printable, quotedprintable | Преобразует операнд в MIME quoted-printable | [`quopri.encode()`](https://python-all.ru/2.7/library/quopri.html#quopri.encode) с `quotetabs=True`, [`quopri.decode()`](https://python-all.ru/2.7/library/quopri.html#quopri.decode) |635| string\_escape |  | Создаёт строку, подходящую в качестве строкового литерала в исходном коде Python |  |636| uu\_codec | uu | Преобразует операнд с помощью uuencode | [`uu.encode()`](https://python-all.ru/2.7/library/uu.html#uu.encode), [`uu.decode()`](https://python-all.ru/2.7/library/uu.html#uu.decode) |637| zlib\_codec | zip, zlib | Сжимает операнд с помощью gzip | [`zlib.compress()`](https://python-all.ru/2.7/library/zlib.html#zlib.compress), [`zlib.decompress()`](https://python-all.ru/2.7/library/zlib.html#zlib.decompress) |638639**[1](https://python-all.ru/2.7/library/codecs.html#id4)**640641Объекты str также принимаются в качестве входных данных вместо объектов unicode. Они неявно преобразуются в unicode путём декодирования с использованием кодировки по умолчанию. Если это преобразование не удаётся, операции кодирования могут вызвать [`UnicodeDecodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeDecodeError).642643**2([1](https://python-all.ru/2.7/library/codecs.html#id5),[2](https://python-all.ru/2.7/library/codecs.html#id6))**644645Объекты unicode также принимаются в качестве входных данных вместо объектов str. Они неявно преобразуются в str путём кодирования с использованием кодировки по умолчанию. Если это преобразование не удаётся, операции декодирования могут вызвать [`UnicodeEncodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeEncodeError).646647## 7.8.5. [`encodings.idna`](https://python-all.ru/2.7/library/codecs.html#module-encodings.idna) – Интернационализированные доменные имена в приложениях648649Новое в версии 2.3.650651Этот модуль реализует [**RFC 3490**](https://python-all.ru/2.7/library/codecs.html) (Internationalized Domain Names in Applications) и [**RFC 3492**](https://python-all.ru/2.7/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/2.7/library/stringprep.html#module-stringprep).652653Эти RFC совместно определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (например, `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, такую как `www.xn--alliancefranaise-npb.nu`). Форма ACE доменного имени затем используется во всех местах, где протокол не допускает произвольных символов, таких как DNS-запросы, поля HTTP *Host* и так далее. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки доменов Unicode в IDNA при передаче по сети и преобразовывать обратно метки ACE в Unicode перед представлением их пользователю.654655Python поддерживает это преобразование несколькими способами: кодек `idna` выполняет преобразование между Unicode и ACE, разделяя входную строку на метки на основе символов-разделителей, определённых в [разделе 3.1](https://python-all.ru/2.7/library/codecs.html) (1) документа [**RFC 3490**](https://python-all.ru/2.7/library/codecs.html) и преобразуя каждую метку в ACE по мере необходимости, и, наоборот, разделяя входную байтовую строку на метки на основе разделителя `.` и преобразуя найденные метки ACE в Unicode. Кроме того, модуль [`socket`](https://python-all.ru/2.7/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно заботиться о преобразовании имён хостов при передаче их модулю socket. Вдобавок модули, которые принимают имена хостов в качестве параметров функций, такие как [`httplib`](https://python-all.ru/2.7/library/httplib.html#module-httplib) и [`ftplib`](https://python-all.ru/2.7/library/ftplib.html#module-ftplib), принимают Unicode-имена хостов ([`httplib`](https://python-all.ru/2.7/library/httplib.html#module-httplib) также прозрачно отправляет имя хоста в формате IDNA в поле *Host*, если оно вообще отправляет это поле).656657При получении имён хостов из сети (например, при обратном поиске имени) автоматическое преобразование в Unicode не выполняется: приложения, желающие отобразить такие имена хостов пользователю, должны декодировать их в Unicode.658659Модуль [`encodings.idna`](https://python-all.ru/2.7/library/codecs.html#module-encodings.idna) также реализует процедуру nameprep, которая выполняет определённые нормализации имён хостов для достижения нечувствительности к регистру интернационализированных доменных имён и унификации похожих символов. Функции nameprep можно использовать напрямую, если необходимо.660661#### `encodings.idna.nameprep(label)`662663Возвращает версию *label* после обработки nameprep. В текущей реализации предполагаются строки запроса, поэтому `AllowUnassigned` имеет значение истина.664665#### `encodings.idna.ToASCII(label)`666667Преобразует метку в ASCII, как указано в [**RFC 3490**](https://python-all.ru/2.7/library/codecs.html). Предполагается, что `UseSTD3ASCIIRules` имеет значение false.668669#### `encodings.idna.ToUnicode(label)`670671Преобразует метку в Unicode, как указано в [**RFC 3490**](https://python-all.ru/2.7/library/codecs.html).672673## 7.8.6. [`encodings.utf_8_sig`](https://python-all.ru/2.7/library/codecs.html#module-encodings.utf_8_sig) – Кодек UTF-8 с сигнатурой BOM674675Новое в версии 2.5.676677Этот модуль реализует вариант кодека UTF-8: при кодировании префикс UTF-8 BOM будет добавлен перед байтами, закодированными в UTF-8. Для кодировщика с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный UTF-8 BOM в начале данных будет пропущен.678