`codecs.md`

744 строк · 95.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.10/library/codecs.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`codecs`](https://python-all.ru/3.10/library/codecs.html#module-codecs) – Реестр кодеков и базовые классы89**Исходный код:** [Lib/codecs.py](https://python-all.ru/src/3.10/Lib/codecs.py)1011---1213Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодека и обработки ошибок. Большинство стандартных кодеков – это [текстовые кодировки](https://python-all.ru/3.10/glossary.html#term-text-encoding), которые кодируют текст в байты (и декодируют байты в текст), но есть также кодеки, которые кодируют текст в текст и байты в байты. Пользовательские кодеки могут кодировать и декодировать между произвольными типами, но некоторые возможности модуля ограничены для использования только с [текстовыми кодировками](https://python-all.ru/3.10/glossary.html#term-text-encoding) или с кодеками, которые кодируют в [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes).1415Модуль определяет следующие функции для кодирования и декодирования с помощью любого кодека:1617#### `codecs.encode(obj, encoding='utf-8', errors='strict')`1819Кодирует *obj* с помощью кодека, зарегистрированного для *encoding*.2021*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/3.10/library/exceptions.html#ValueError) (or a more codec specific subclass, such as [`UnicodeEncodeError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeEncodeError)). Refer to [Codec Base Classes](https://python-all.ru/3.10/library/codecs.html#codec-base-classes) for more information on codec error handling.2223#### `codecs.decode(obj, encoding='utf-8', errors='strict')`2425Декодирует *obj* с помощью кодека, зарегистрированного для *encoding*.2627*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/3.10/library/exceptions.html#ValueError) (or a more codec specific subclass, such as [`UnicodeDecodeError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeDecodeError)). Refer to [Codec Base Classes](https://python-all.ru/3.10/library/codecs.html#codec-base-classes) for more information on codec error handling.2829Полные сведения о каждом кодеке также можно получить напрямую:3031#### `codecs.lookup(encoding)`3233Ищет информацию о кодеке в реестре кодеков Python и возвращает объект [`CodecInfo`](https://python-all.ru/3.10/library/codecs.html#codecs.CodecInfo), как определено ниже.3435Сначала кодировки ищутся в кэше реестра. Если не найдены, просматривается список зарегистрированных функций поиска. Если объект [`CodecInfo`](https://python-all.ru/3.10/library/codecs.html#codecs.CodecInfo) не найден, вызывается [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError). В противном случае объект [`CodecInfo`](https://python-all.ru/3.10/library/codecs.html#codecs.CodecInfo) сохраняется в кэше и возвращается вызывающему.3637#### `class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)`3839Сведения о кодеке при поиске в реестре кодеков. Аргументы конструктора хранятся в атрибутах с теми же именами:4041#### `name`4243Имя кодировки.4445#### `encode`4647#### `decode`4849Функции кодирования и декодирования без сохранения состояния. Это должны быть функции или методы с тем же интерфейсом, что и методы [`encode()`](https://python-all.ru/3.10/library/codecs.html#codecs.Codec.encode) и [`decode()`](https://python-all.ru/3.10/library/codecs.html#codecs.Codec.decode) экземпляров Codec (см. [Интерфейс Codec](https://python-all.ru/3.10/library/codecs.html#codec-objects)). Предполагается, что функции или методы работают в режиме без сохранения состояния.5051#### `incrementalencoder`5253#### `incrementaldecoder`5455Классы или фабричные функции инкрементального кодера и декодера. Они должны предоставлять интерфейс, определенный базовыми классами [`IncrementalEncoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder), соответственно. Инкрементальные кодеки могут поддерживать состояние.5657#### `streamwriter`5859#### `streamreader`6061Классы или фабричные функции записи и чтения потоков. Они должны предоставлять интерфейс, определенный базовыми классами [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader), соответственно. Потоковые кодеки могут поддерживать состояние.6263Для упрощения доступа к различным компонентам кодеков модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/3.10/library/codecs.html#codecs.lookup) для поиска кодека:6465#### `codecs.getencoder(encoding)`6667Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.6869Вызывает [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), если кодировка не найдена.7071#### `codecs.getdecoder(encoding)`7273Находит кодек для указанной кодировки и возвращает его функцию-декодер.7475Вызывает [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), если кодировка не найдена.7677#### `codecs.getincrementalencoder(encoding)`7879Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.8081Вызывает [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный кодировщик.8283#### `codecs.getincrementaldecoder(encoding)`8485Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.8687Вызывает [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный декодер.8889#### `codecs.getreader(encoding)`9091Находит кодек для указанной кодировки и возвращает его [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) класс или фабричную функцию.9293Вызывает [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), если кодировка не найдена.9495#### `codecs.getwriter(encoding)`9697Находит кодек для указанной кодировки и возвращает его [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) класс или фабричную функцию.9899Вызывает [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), если кодировка не найдена.100101Пользовательские кодеки становятся доступными при регистрации подходящей функции поиска кодека :102103#### `codecs.register(search_function)`104105Регистрирует функцию поиска кодека. Функция поиска должна принимать один аргумент – имя кодировки строчными буквами, где дефисы и пробелы преобразуются в символы подчёркивания, и возвращать объект [`CodecInfo`](https://python-all.ru/3.10/library/codecs.html#codecs.CodecInfo). Если функция поиска не может найти указанную кодировку, она должна вернуть `None`.106107Изменено в версии 3.9: Дефисы и пробелы преобразуются в символ подчёркивания.108109#### `codecs.unregister(search_function)`110111Отменяет регистрацию функции поиска кодека и очищает кэш реестра. Если функция поиска не зарегистрирована, ничего не делает.112113Новое в версии 3.10.114115Хотя встроенная функция [`open()`](https://python-all.ru/3.10/library/functions.html#open) и связанный с ней модуль [`io`](https://python-all.ru/3.10/library/io.html#module-io) являются рекомендуемым способом работы с закодированными текстовыми файлами, этот модуль предоставляет дополнительные вспомогательные функции и классы, позволяющие использовать более широкий набор кодеков при работе с бинарными файлами:116117#### `codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=- 1)`118119Открывает закодированный файл, используя указанный *режим*, и возвращает экземпляр [`StreamReaderWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReaderWriter), обеспечивая прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, что означает открытие файла в режиме чтения.120121> **Примечание**122>123> Если *encoding* не равен `None`, то базовые закодированные файлы всегда открываются в бинарном режиме. Автоматическое преобразование `'\n'` не выполняется при чтении и записи. Аргумент *mode* может быть любым бинарным режимом, допустимым для встроенной функции [`open()`](https://python-all.ru/3.10/library/functions.html#open); `'b'` добавляется автоматически.124125*encoding* указывает кодировку, которая будет использоваться для файла. Допускается любая кодировка, которая кодирует в байты и декодирует из байтов, а типы данных, поддерживаемые методами файла, зависят от используемого кодека.126127Параметр *errors* можно задать для определения обработки ошибок. По умолчанию он равен `'strict'`, что приводит к возбуждению [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError) при возникновении ошибки кодирования.128129Параметр *buffering* имеет то же значение, что и для встроенной функции [`open()`](https://python-all.ru/3.10/library/functions.html#open). По умолчанию он равен -1, что означает использование размера буфера по умолчанию.130131#### `codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')`132133Возвращает экземпляр [`StreamRecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamRecoder), обёртку для *file*, которая обеспечивает прозрачное перекодирование. Исходный файл закрывается при закрытии обёртки.134135Данные, записываемые в обёрнутый файл, декодируются согласно заданной *data\_encoding*, а затем записываются в исходный файл в виде байтов с использованием *file\_encoding*. Байты, читаемые из исходного файла, декодируются согласно *file\_encoding*, а результат кодируется с использованием *data\_encoding*.136137Если *file\_encoding* не указан, по умолчанию используется *data\_encoding*.138139Параметр *errors* может быть задан для определения обработки ошибок. По умолчанию он равен `'strict'`, что приводит к возникновению [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError) в случае ошибки кодирования.140141#### `codecs.iterencode(iterator, encoding, errors='strict', **kwargs)`142143Использует инкрементальный кодировщик для итеративного кодирования входных данных, предоставляемых *iterator*. Эта функция является [генератором](https://python-all.ru/3.10/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному кодировщику.144145Эта функция требует, чтобы кодек принимал текстовые объекты [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) для кодирования. Поэтому она не поддерживает кодировщики типа «байты-в-байты», такие как `base64_codec`.146147#### `codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)`148149Использует инкрементальный декодировщик для итеративного декодирования входных данных, предоставляемых *iterator*. Эта функция является [генератором](https://python-all.ru/3.10/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному декодировщику.150151Эта функция требует, чтобы кодек принимал объекты [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes) для декодирования. Поэтому она не поддерживает кодировщики типа «текст-в-текст», такие как `rot_13`, хотя `rot_13` может использоваться аналогично с [`iterencode()`](https://python-all.ru/3.10/library/codecs.html#codecs.iterencode).152153Модуль также предоставляет следующие константы, полезные для чтения и записи в платформенно-зависимые файлы:154155#### `codecs.BOM`156157#### `codecs.BOM_BE`158159#### `codecs.BOM_LE`160161#### `codecs.BOM_UTF8`162163#### `codecs.BOM_UTF16`164165#### `codecs.BOM_UTF16_BE`166167#### `codecs.BOM_UTF16_LE`168169#### `codecs.BOM_UTF32`170171#### `codecs.BOM_UTF32_BE`172173#### `codecs.BOM_UTF32_LE`174175Эти константы определяют различные последовательности байтов, являющиеся метками порядка байтов Unicode (BOM) для нескольких кодировок. Они используются в потоках данных UTF-16 и UTF-32 для указания используемого порядка байтов, а в UTF-8 – как сигнатура Unicode. [`BOM_UTF16`](https://python-all.ru/3.10/library/codecs.html#codecs.BOM_UTF16) это либо [`BOM_UTF16_BE`](https://python-all.ru/3.10/library/codecs.html#codecs.BOM_UTF16_BE), либо [`BOM_UTF16_LE`](https://python-all.ru/3.10/library/codecs.html#codecs.BOM_UTF16_LE) в зависимости от нативного порядка байтов платформы; [`BOM`](https://python-all.ru/3.10/library/codecs.html#codecs.BOM) – псевдоним [`BOM_UTF16`](https://python-all.ru/3.10/library/codecs.html#codecs.BOM_UTF16), [`BOM_LE`](https://python-all.ru/3.10/library/codecs.html#codecs.BOM_LE) – [`BOM_UTF16_LE`](https://python-all.ru/3.10/library/codecs.html#codecs.BOM_UTF16_LE), [`BOM_BE`](https://python-all.ru/3.10/library/codecs.html#codecs.BOM_BE) – [`BOM_UTF16_BE`](https://python-all.ru/3.10/library/codecs.html#codecs.BOM_UTF16_BE). Остальные представляют BOM в кодировках UTF-8 и UTF-32.176177## Базовые классы кодеков178179Модуль [`codecs`](https://python-all.ru/3.10/library/codecs.html#module-codecs) определяет набор базовых классов, которые задают интерфейсы для работы с объектами кодеков, а также могут использоваться как основа для реализации пользовательских кодеков.180181Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в Python: статический кодировщик, статический декодер, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно используют статический кодировщик/декодер для реализации файловых протоколов. Разработчикам кодеков также необходимо определить, как кодек будет обрабатывать ошибки кодирования и декодирования.182183### Обработчики ошибок184185Чтобы упростить и стандартизировать обработку ошибок, кодеки могут реализовывать разные схемы обработки ошибок, принимая строковый аргумент *errors*:186187```python188>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')189b'German \\xdf, \\u266c'190>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')191b'German &#223;, &#9836;'192```193194Следующие обработчики ошибок можно использовать со всеми кодеками [стандартных кодировок](https://python-all.ru/3.10/library/codecs.html#standard-encodings) Python:195196| Значение | Значение |197| --- | --- |198| `'strict'` | Выбрасывает [`UnicodeError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeError) (или подкласс). Это поведение по умолчанию. Реализовано в [`strict_errors()`](https://python-all.ru/3.10/library/codecs.html#codecs.strict_errors). |199| `'ignore'` | Игнорировать повреждённые данные и продолжить без дополнительных уведомлений. Реализовано в [`ignore_errors()`](https://python-all.ru/3.10/library/codecs.html#codecs.ignore_errors). |200| `'replace'` | Замена на символ-заменитель. При кодировании используется `?` (ASCII-символ). При декодировании используется `�` (U+FFFD, официальный символ замены). Реализовано в [`replace_errors()`](https://python-all.ru/3.10/library/codecs.html#codecs.replace_errors). |201| `'backslashreplace'` | Замена на escape-последовательности с обратной косой чертой. При кодировании используется шестнадцатеричная форма кодовой точки Unicode в форматах `\xhh` `\uxxxx` `\Uxxxxxxxx`. При декодировании используется шестнадцатеричная форма значения байта в формате `\xhh`. Реализовано в [`backslashreplace_errors()`](https://python-all.ru/3.10/library/codecs.html#codecs.backslashreplace_errors). |202| `'surrogateescape'` | При декодировании заменяет байт на отдельный суррогатный код в диапазоне от `U+DC80` до `U+DCFF`. Этот код затем преобразуется обратно в тот же байт при использовании обработчика ошибок `'surrogateescape'` при кодировании данных. (Подробнее см. [**PEP 383**](https://python-all.ru/3.10/library/codecs.html).) |203204Следующие обработчики ошибок применимы только к кодированию (в рамках [текстовых кодировок](https://python-all.ru/3.10/glossary.html#term-text-encoding)):205206| Значение | Значение |207| --- | --- |208| `'xmlcharrefreplace'` | Замена на числовую символьную ссылку XML/HTML, которая представляет собой десятичную форму кодовой точки Unicode в формате `&#num;`. Реализовано в [`xmlcharrefreplace_errors()`](https://python-all.ru/3.10/library/codecs.html#codecs.xmlcharrefreplace_errors). |209| `'namereplace'` | Замена на escape-последовательности `\N{...}`; то, что находится в фигурных скобках, – это свойство Name из базы данных символов Unicode. Реализовано в [`namereplace_errors()`](https://python-all.ru/3.10/library/codecs.html#codecs.namereplace_errors). |210211Кроме того, следующий обработчик ошибок специфичен для указанных кодеков:212213| Значение | Кодеки | Значение |214| --- | --- | --- |215| `'surrogatepass'` | utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le | Разрешает кодирование и декодирование суррогатных кодовых точек (`U+D800` – `U+DFFF`) как обычных кодовых точек. В противном случае эти кодеки считают наличие суррогатной кодовой точки в [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) ошибкой. |216217Новое в версии 3.1: Обработчики ошибок `'surrogateescape'` и `'surrogatepass'`.218219Изменено в версии 3.4: обработчик ошибок `'surrogatepass'` теперь работает с кодеками utf-16\* и utf-32\*.220221Новое в версии 3.5: Обработчик ошибок `'namereplace'`.222223Изменено в версии 3.5: обработчик ошибок `'backslashreplace'` теперь работает с декодированием и трансляцией.224225Набор допустимых значений можно расширить, зарегистрировав новый именованный обработчик ошибок:226227#### `codecs.register_error(name, error_handler)`228229Регистрирует функцию обработки ошибок *error\_handler* под именем *name*. Аргумент *error\_handler* будет вызываться во время кодирования и декодирования в случае ошибки, когда в качестве параметра errors указано *name*.230231При кодировании *error\_handler* будет вызываться с экземпляром [`UnicodeEncodeError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeEncodeError), который содержит информацию о местоположении ошибки. Обработчик ошибок должен либо повторно выбросить это или другое исключение, либо вернуть кортеж с заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Замена может быть либо [`str`](https://python-all.ru/3.10/library/stdtypes.html#str), либо [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes). Если замена – bytes, кодировщик просто скопирует их в выходной буфер. Если замена – строка, кодировщик закодирует замену. Кодирование продолжается с исходных входных данных начиная с указанной позиции. Отрицательные значения позиции интерпретируются как смещение относительно конца входной строки. Если результирующая позиция выходит за границы, выбрасывается [`IndexError`](https://python-all.ru/3.10/library/exceptions.html#IndexError).232233Декодирование и трансляция работают аналогично, за исключением того, что обработчику передаётся [`UnicodeDecodeError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeTranslateError), а замена от обработчика ошибок помещается в выходные данные напрямую.234235Ранее зарегистрированные обработчики ошибок (включая стандартные) можно найти по имени:236237#### `codecs.lookup_error(name)`238239Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.240241Выбрасывает [`LookupError`](https://python-all.ru/3.10/library/exceptions.html#LookupError), если обработчик не найден.242243Следующие стандартные обработчики ошибок также доступны как функции уровня модуля:244245#### `codecs.strict_errors(exception)`246247Реализует обработку ошибок `'strict'`.248249Каждая ошибка кодирования или декодирования выбрасывает [`UnicodeError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeError).250251#### `codecs.ignore_errors(exception)`252253Реализует обработку ошибок `'ignore'`.254255Некорректные данные игнорируются; кодирование или декодирование продолжается без дополнительных уведомлений.256257#### `codecs.replace_errors(exception)`258259Реализует обработку ошибок `'replace'`.260261Заменяет `?` (символ ASCII) при ошибках кодирования или `�` (U+FFFD, официальный ЗАМЕНЯЮЩИЙ СИМВОЛ) при ошибках декодирования.262263#### `codecs.backslashreplace_errors(exception)`264265Реализует обработку ошибок `'backslashreplace'`.266267Некорректные данные заменяются escape-последовательностью с обратной косой чертой. При кодировании используется шестнадцатеричная форма кодовой точки Unicode в форматах `\xhh` `\uxxxx` `\Uxxxxxxxx`. При декодировании используется шестнадцатеричная форма значения байта в формате `\xhh`.268269Изменено в версии 3.5: Работает с декодированием и трансляцией.270271#### `codecs.xmlcharrefreplace_errors(exception)`272273Реализует обработку ошибок `'xmlcharrefreplace'` (только для кодирования в рамках [текстовой кодировки](https://python-all.ru/3.10/glossary.html#term-text-encoding)).274275Не кодируемый символ заменяется соответствующей XML/HTML числовой ссылкой на символ, которая представляет собой десятичную форму кодовой точки Unicode в формате `&#num;`.276277#### `codecs.namereplace_errors(exception)`278279Реализует обработку ошибок `'namereplace'` (только для кодирования в рамках [текстовой кодировки](https://python-all.ru/3.10/glossary.html#term-text-encoding)).280281Не кодируемый символ заменяется управляющей последовательностью `\N{...}`. Набор символов, которые появляются в фигурных скобках, – это свойство Name из базы данных символов Unicode. Например, немецкая строчная буква `'ß'` будет преобразована в последовательность байтов `\N{LATIN SMALL LETTER SHARP S}`.282283Новое в версии 3.5.284285### Кодирование и декодирование без сохранения состояния286287Базовый класс `Codec` определяет эти методы, которые также задают интерфейсы функций кодировщика и декодировщика без сохранения состояния:288289#### `Codec.encode(input, errors='strict')`290291Кодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Например, [текстовая кодировка](https://python-all.ru/3.10/glossary.html#term-text-encoding) преобразует строковый объект в объект bytes, используя определённую кодировку набора символов (например, `cp1252` или `iso-8859-1`).292293Аргумент *errors* задаёт применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.294295Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) для кодеков, которым необходимо сохранять состояние для эффективного кодирования.296297Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.298299#### `Codec.decode(input, errors='strict')`300301Декодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Например, для [текстовой кодировки](https://python-all.ru/3.10/glossary.html#term-text-encoding) декодирование преобразует объект bytes, закодированный с использованием определённой кодировки набора символов, в строковый объект.302303Для текстовых кодировок и кодеков bytes-to-bytes *input* должен быть объектом bytes или объектом, предоставляющим интерфейс буфера только для чтения – например, буферные объекты и файлы, отображаемые в память.304305Аргумент *errors* задаёт применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.306307Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) для кодеков, которым необходимо сохранять состояние для эффективного декодирования.308309Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.310311### Инкрементальное кодирование и декодирование312313Классы [`IncrementalEncoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder) предоставляют базовый интерфейс для инкрементального кодирования и декодирования. Кодирование/декодирование входных данных выполняется не одним вызовом функции кодировщика/декодировщика без состояния, а несколькими вызовами метода [`encode()`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder.decode) инкрементального кодировщика/декодировщика. Инкрементальный кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.314315Объединённый вывод вызовов метода [`encode()`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder.decode) совпадает с тем, что получилось бы, если бы все отдельные входные данные были объединены в один, и этот вход был закодирован/декодирован кодировщиком/декодировщиком без состояния.316317#### Объекты IncrementalEncoder318319Класс [`IncrementalEncoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный кодировщик для совместимости с реестром кодеков Python.320321#### `class codecs.IncrementalEncoder(errors='strict')`322323Конструктор экземпляра [`IncrementalEncoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder).324325Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.326327Декодер [`IncrementalEncoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Список возможных значений приведён в разделе [Обработчики ошибок](https://python-all.ru/3.10/library/codecs.html#error-handlers).328329Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalEncoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder).330331#### `encode(object, final=False)`332333Кодирует *object* (с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов [`encode()`](https://python-all.ru/3.10/library/codecs.html#codecs.encode), *final* должен быть истинным (по умолчанию – ложь).334335#### `reset()`336337Сбрасывает кодировщик в исходное состояние. Выходные данные отбрасываются: при необходимости вызовите `.encode(object, final=True)`, передав пустую строку байтов или текстовую строку, чтобы сбросить кодировщик и получить выходные данные.338339#### `getstate()`340341Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что `0` является наиболее распространённым состоянием. (Состояния, более сложные, чем целые числа, можно преобразовать в целое число с помощью маршалинга/сериализации состояния и кодирования байтов результирующей строки в целое число.)342343#### `setstate(state)`344345Устанавливает состояние кодировщика в *state*. *state* должно быть состоянием кодировщика, возвращённым [`getstate()`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalEncoder.getstate).346347#### Объекты IncrementalDecoder348349Класс [`IncrementalDecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный декодер для совместимости с реестром кодеков Python.350351#### `class codecs.IncrementalDecoder(errors='strict')`352353Конструктор экземпляра [`IncrementalDecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder).354355Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.356357Декодер [`IncrementalDecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Список возможных значений приведён в разделе [Обработчики ошибок](https://python-all.ru/3.10/library/codecs.html#error-handlers).358359Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта [`IncrementalDecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder).360361#### `decode(object, final=False)`362363Декодирует *object* (с учётом текущего состояния декодера) и возвращает результирующий декодированный объект. Если это последний вызов [`decode()`](https://python-all.ru/3.10/library/codecs.html#codecs.decode), *final* должен быть истинным (по умолчанию – ложь). Если *final* истинно, декодер должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).364365#### `reset()`366367Сбрасывает декодер в исходное состояние.368369#### `getstate()`370371Возвращает текущее состояние декодера. Это должен быть кортеж из двух элементов: первый – буфер, содержащий ещё не декодированные входные данные; второй – целое число, которое может содержать дополнительную информацию о состоянии. (Реализация должна гарантировать, что `0` является наиболее распространённой дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии равна `0`, должна быть возможность установить декодер в состояние без буферизованных входных данных и с `0` в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованных входных данных в декодер возвращала его в предыдущее состояние без вывода каких-либо данных. (Дополнительная информация о состоянии, более сложная, чем целые числа, может быть преобразована в целое число с помощью маршалинга/сериализации этой информации и кодирования байтов результирующей строки в целое число.)372373#### `setstate(state)`374375Устанавливает состояние декодера в *state*. *state* должно быть состоянием декодера, возвращённым [`getstate()`](https://python-all.ru/3.10/library/codecs.html#codecs.IncrementalDecoder.getstate).376377### Потоковое кодирование и декодирование378379Классы [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) предоставляют универсальные рабочие интерфейсы, которые можно использовать для очень простой реализации новых подмодулей кодирования. Пример см. в `encodings.utf_8`.380381#### Объекты StreamWriter382383Класс [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый писатель должен реализовать для совместимости с реестром кодеков Python.384385#### `class codecs.StreamWriter(stream, errors='strict')`386387Конструктор экземпляра [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter).388389Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.390391Аргумент *поток данных* должен быть файлоподобным объектом, открытым для записи текстовых или двоичных данных, в зависимости от конкретного кодека.392393Объект [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. См. [Обработчики ошибок](https://python-all.ru/3.10/library/codecs.html#error-handlers) для получения списка стандартных обработчиков ошибок, которые может поддерживать базовый потоковый кодек.394395Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter).396397#### `write(object)`398399Записывает в поток закодированное содержимое объекта.400401#### `writelines(list)`402403Записывает в поток конкатенированный итерируемый объект из строк (возможно, с использованием метода [`write()`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter.write)). Бесконечные или очень большие итерируемые объекты не поддерживаются. Стандартные кодеки «байты-в-байты» не поддерживают этот метод.404405#### `reset()`406407Сбрасывает буферы кодекa, используемые для хранения внутреннего состояния.408409Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.410411В дополнение к приведённым выше методам, [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.412413#### Объекты StreamReader414415Класс [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) является подклассом `Codec` и определяет следующие методы, которые каждый потоковый читатель должен реализовать для совместимости с реестром кодеков Python.416417#### `class codecs.StreamReader(stream, errors='strict')`418419Конструктор экземпляра [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader).420421Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.422423Аргумент *поток данных* должен быть файлоподобным объектом, открытым для чтения текстовых или двоичных данных, в зависимости от конкретного кодека.424425Объект [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. См. [Обработчики ошибок](https://python-all.ru/3.10/library/codecs.html#error-handlers) для получения списка стандартных обработчиков ошибок, которые может поддерживать базовый потоковый кодек.426427Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader).428429Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.10/library/codecs.html#codecs.register_error).430431#### `read(size=- 1, chars=- 1, firstline=False)`432433Декодирует данные из потока и возвращает результирующий объект.434435Аргумент *chars* указывает количество декодированных кодовых точек или байтов для возврата. Метод [`read()`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader.read) никогда не вернёт больше данных, чем запрошено, но может вернуть меньше, если доступно недостаточно.436437Аргумент *size* указывает приблизительное максимальное количество закодированных байтов или кодовых точек для чтения при декодировании. Декодер может изменять этот параметр по своему усмотрению. Значение по умолчанию -1 означает чтение и декодирование максимально возможного объёма. Этот параметр предназначен для того, чтобы не приходилось декодировать огромные файлы за один шаг.438439Флаг *firstline* указывает, что достаточно вернуть только первую строку, если на последующих строках возникают ошибки декодирования.440441Метод должен использовать жадную стратегию чтения, то есть читать столько данных, сколько допускается определением кодировки и заданным размером; например, если в потоке доступны необязательные окончания кодировки или маркеры состояния, их также следует прочитать.442443#### `readline(size=None, keepends=True)`444445Читает одну строку из входного потока и возвращает декодированные данные.446447*size*, если задан, передаётся как аргумент size в метод [`read()`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader.read) потока данных.448449Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.450451#### `readlines(sizehint=None, keepends=True)`452453Читает все строки из входного потока данных и возвращает их в виде списка строк.454455Символы конца строки обрабатываются с помощью метода [`decode()`](https://python-all.ru/3.10/library/codecs.html#codecs.decode) кодекa и включаются в элементы списка, если *keepends* равен True.456457*sizehint*, если задан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader.read) потока данных.458459#### `reset()`460461Сбрасывает буферы кодекa, используемые для хранения внутреннего состояния.462463Обратите внимание, что перемещение по потоку данных не должно выполняться. Этот метод в первую очередь предназначен для восстановления после ошибок декодирования.464465В дополнение к приведённым выше методам, [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.466467#### Объекты StreamReaderWriter468469[`StreamReaderWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReaderWriter) – это удобный класс, который позволяет оборачивать потоки данных, работающие как в режиме чтения, так и в режиме записи.470471Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.10/library/codecs.html#codecs.lookup).472473#### `class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')`474475Создаёт экземпляр [`StreamReaderWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReaderWriter). *поток данных* должен быть файлоподобным объектом. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими интерфейсы [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) соответственно. Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.476477Экземпляры [`StreamReaderWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReaderWriter) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.478479#### Объекты StreamRecoder480481[`StreamRecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamRecoder) преобразует данные из одной кодировки в другую, что иногда полезно при работе с различными кодировочными средами.482483Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.10/library/codecs.html#codecs.lookup).484485#### `class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')`486487Создаёт экземпляр [`StreamRecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamRecoder), который реализует двустороннее преобразование: *encode* и *decode* работают на внешней стороне – данные, видимые коду, вызывающему `read()` и `write()`, а *Reader* и *Writer* работают на внутренней стороне – данные в *поток данных*.488489Эти объекты можно использовать для прозрачной перекодировки, например, из Latin-1 в UTF-8 и обратно.490491Аргумент *поток данных* должен быть файлоподобным объектом.492493Аргументы *encode* и *decode* должны соответствовать интерфейсу `Codec`. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими объекты интерфейсов [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter) соответственно.494495Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.496497Экземпляры [`StreamRecoder`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamRecoder) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.10/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.498499## Кодировки и Unicode500501Строки внутри хранятся как последовательности кодовых точек в диапазоне `U+0000`–`U+10FFFF`. (Подробнее об реализации см. [**PEP 393**](https://python-all.ru/3.10/library/codecs.html).) Как только строковый объект используется за пределами ЦП и памяти, порядок байтов и способ хранения этих массивов в виде байтов становятся проблемой. Как и для других кодеков, сериализация строки в последовательность байтов называется *кодированием*, а восстановление строки из последовательности байтов – *декодированием*. Существует множество различных текстовых кодеков сериализации, которые в совокупности называются [текстовыми кодировками](https://python-all.ru/3.10/glossary.html#term-text-encoding).502503Простейшая текстовая кодировка (называемая `'latin-1'` или `'iso-8859-1'`) отображает кодовые точки 0–255 на байты `0x0`–`0xff`, что означает, что строковый объект, содержащий кодовые точки больше `U+00FF`, не может быть закодирован этим кодеком. Попытка сделать это вызовет исключение [`UnicodeEncodeError`](https://python-all.ru/3.10/library/exceptions.html#UnicodeEncodeError), которое выглядит следующим образом (хотя детали сообщения об ошибке могут отличаться): `UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256)`.504505Существует ещё одна группа кодировок (так называемые charmap-кодировки), которые выбирают другое подмножество всех кодовых точек Юникода и определяют, как эти кодовые точки отображаются на байты `0x0`–`0xff`. Чтобы увидеть, как это работает, достаточно открыть, например, `encodings/cp1252.py` (кодировку, которая в основном используется в Windows). В ней есть строковая константа из 256 символов, показывающая, какой символ какому значению байта соответствует.506507Все эти кодировки могут закодировать только 256 из 1114112 кодовых точек, определённых в Unicode. Простой и прямолинейный способ хранить каждую кодовую точку Unicode – хранить каждую точку в виде четырёх последовательных байтов. Есть два варианта: хранить байты в порядке от старшего к младшему (big endian) или от младшего к старшему (little endian). Эти две кодировки называются соответственно `UTF-32-BE` и `UTF-32-LE`. Их недостаток в том, что если, например, использовать `UTF-32-BE` на машине с little endian, то при кодировании и декодировании всегда придётся менять порядок байтов. `UTF-32` избегает этой проблемы: байты всегда будут в естественном порядке байтов. Однако при чтении этих байтов процессором с другим порядком байтов их всё равно придётся переставлять. Чтобы иметь возможность определить порядок байтов последовательности `UTF-16` или `UTF-32`, существует так называемый BOM («Byte Order Mark» – метка порядка байтов). Это символ Unicode `U+FEFF`. Этот символ может быть добавлен в начало каждой последовательности байтов `UTF-16` или `UTF-32`. Версия этого символа с переставленными байтами (`0xFFFE`) является недопустимым символом, который не может встречаться в тексте Unicode. Поэтому если первый символ в последовательности байтов `UTF-16` или `UTF-32` оказывается `U+FFFE`, то при декодировании байты необходимо переставить. К сожалению, символ `U+FEFF` имел и второе назначение – `ZERO WIDTH NO-BREAK SPACE`: символ, не имеющий ширины и не допускающий разрыва слова. Его можно использовать, например, для подсказок алгоритму лигатур. В Unicode 4.0 использование `U+FEFF` в качестве `ZERO WIDTH NO-BREAK SPACE` признано устаревшим (эту роль взял на себя `U+2060` (`WORD JOINER`)). Тем не менее, программное обеспечение Unicode всё ещё должно уметь обрабатывать `U+FEFF` в обеих ролях: как BOM он служит для определения способа хранения закодированных байтов и исчезает после декодирования последовательности в строку; как `ZERO WIDTH NO-BREAK SPACE` он является обычным символом, который декодируется как любой другой.508509Существует ещё одна кодировка, способная кодировать весь диапазон символов Unicode: UTF-8. UTF-8 – это 8-битная кодировка, поэтому в UTF-8 нет проблем с порядком байтов. Каждый байт в последовательности UTF-8 состоит из двух частей: маркерных битов (старших битов) и полезных битов. Маркерные биты представляют собой последовательность от нуля до четырёх `1` битов, за которой следует `0` бит. Символы Unicode кодируются следующим образом (где x – полезные биты, которые при объединении дают символ Unicode):510511| Диапазон | Кодировка |512| --- | --- |513| `U-00000000` … `U-0000007F` | 0xxxxxxx |514| `U-00000080` … `U-000007FF` | 110xxxxx 10xxxxxx |515| `U-00000800` … `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |516| `U-00010000` … `U-0010FFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |517518Младший значащий бит символа Unicode – это самый правый бит x.519520Поскольку UTF-8 является 8-битной кодировкой, BOM не требуется, и любой символ `U+FEFF` в декодированной строке (даже если это первый символ) рассматривается как `ZERO WIDTH NO-BREAK SPACE`.521522Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Любая charmap-кодировка может декодировать любую случайную последовательность байтов. Однако с UTF-8 это невозможно, поскольку последовательности байтов UTF-8 имеют структуру, не допускающую произвольных последовательностей байтов. Чтобы повысить надёжность обнаружения кодировки UTF-8, Microsoft изобрела вариант UTF-8 (который Python называет `"utf-8-sig"`) для своей программы «Блокнот»: перед тем, как любой символ Unicode записывается в файл, записывается BOM в кодировке UTF-8 (который выглядит как последовательность байтов: `0xef`, `0xbb`, `0xbf`). Поскольку маловероятно, что какой-либо файл в charmap-кодировке начинается с этих значений байтов (которые, например, отображаются на523524> ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЭРЕЗИСОМ525>526> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА527>528> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК529530в iso-8859-1), это повышает вероятность того, что кодировка `utf-8-sig` будет правильно угадана по последовательности байтов. Таким образом, здесь BOM используется не для определения порядка байтов, использованного при генерации последовательности байтов, а как сигнатура, помогающая угадать кодировку. При кодировании кодек utf-8-sig запишет `0xef`, `0xbb`, `0xbf` в качестве первых трёх байтов в файл. При декодировании `utf-8-sig` пропустит эти три байта, если они окажутся первыми тремя байтами в файле. В UTF-8 использование BOM не рекомендуется и его обычно следует избегать.531532## Стандартные кодировки533534Python поставляется с рядом встроенных кодеков, реализованных либо как функции на C либо с использованием словарей в качестве таблиц сопоставления. В следующей таблице перечислены кодеки по имени, а также некоторые распространённые псевдонимы и языки, для которых вероятно используется данная кодировка. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что альтернативные написания, различающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами; поэтому, например, `'utf-8'` является допустимым псевдонимом для кодека `'utf_8'`.535536**Особенность реализации CPython:** Некоторые распространённые кодировки могут обходить механизм поиска кодеков для повышения производительности. Эти возможности оптимизации распознаются CPython только для ограниченного набора псевдонимов (без учёта регистра): utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (только Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32, а также те же с использованием подчёркивания вместо дефисов. Использование альтернативных псевдонимов для этих кодировок может привести к более медленному выполнению.537538Изменено в версии 3.6: Возможность оптимизации распознаётся для us-ascii.539540Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:541542- набор символов ISO 8859543- кодовая страница Microsoft Windows, которая обычно происходит из набора 8859, но заменяет управляющие символы дополнительными графическими символами544- кодовая страница IBM EBCDIC545- кодовая страница IBM PC, совместимая с ASCII546547| Кодек | Псевдонимы | Языки |548| --- | --- | --- |549| ascii | 646, us-ascii | Английский |550| big5 | big5-tw, csbig5 | Китайский традиционный |551| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |552| cp037 | IBM037, IBM039 | Английский |553| cp273 | 273, IBM273, csIBM273 | Немецкий Новое в версии 3.4. |554| cp424 | EBCDIC-CP-HE, IBM424 | Иврит |555| cp437 | 437, IBM437 | Английский |556| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Западная Европа |557| cp720 |  | Арабский |558| cp737 |  | Греческий |559| cp775 | IBM775 | Балтийские языки |560| cp850 | 850, IBM850 | Западная Европа |561| cp852 | 852, IBM852 | Центральная и Восточная Европа |562| cp855 | 855, IBM855 | болгарский, белорусский, македонский, русский, сербский |563| cp856 |  | Иврит |564| cp857 | 857, IBM857 | Турецкий |565| cp858 | 858, IBM858 | Западная Европа |566| cp860 | 860, IBM860 | португальский |567| cp861 | 861, CP-IS, IBM861 | Исландский |568| cp862 | 862, IBM862 | Иврит |569| cp863 | 863, IBM863 | канадский |570| cp864 | IBM864 | Арабский |571| cp865 | 865, IBM865 | датский, норвежский |572| cp866 | 866, IBM866 | Русский |573| cp869 | 869, CP-GR, IBM869 | Греческий |574| cp874 |  | Тайский |575| cp875 |  | Греческий |576| cp932 | 932, ms932, mskanji, ms-kanji | Японский |577| cp949 | 949, ms949, uhc | Корейский |578| cp950 | 950, ms950 | Китайский традиционный |579| cp1006 |  | Урду |580| cp1026 | ibm1026 | Турецкий |581| cp1125 | 1125, ibm1125, cp866u, ruscii | Украинский Новое в версии 3.4. |582| cp1140 | ibm1140 | Западная Европа |583| cp1250 | windows-1250 | Центральная и Восточная Европа |584| cp1251 | windows-1251 | болгарский, белорусский, македонский, русский, сербский |585| cp1252 | windows-1252 | Западная Европа |586| cp1253 | windows-1253 | Греческий |587| cp1254 | windows-1254 | Турецкий |588| cp1255 | windows-1255 | Иврит |589| cp1256 | windows-1256 | Арабский |590| cp1257 | windows-1257 | Балтийские языки |591| cp1258 | windows-1258 | вьетнамский |592| euc\_jp | eucjp, ujis, u-jis | Японский |593| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |594| euc\_jisx0213 | eucjisx0213 | Японский |595| euc\_kr | euckr, корейский, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |596| gb2312 | китайский, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58 | Упрощённый китайский |597| gbk | 936, cp936, ms936 | Унифицированный китайский |598| gb18030 | gb18030-2000 | Унифицированный китайский |599| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |600| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |601| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |602| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |603| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |604| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |605| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |606| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |607| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |608| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |609| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |610| iso8859\_4 | iso-8859-4, latin4, L4 | Балтийские языки |611| iso8859\_5 | iso-8859-5, кириллица | болгарский, белорусский, македонский, русский, сербский |612| iso8859\_6 | iso-8859-6, арабский | Арабский |613| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |614| iso8859\_8 | iso-8859-8, иврит | Иврит |615| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |616| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |617| iso8859\_11 | iso-8859-11, тайская | Тайские языки |618| iso8859\_13 | iso-8859-13, latin7, L7 | Балтийские языки |619| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |620| iso8859\_15 | iso-8859-15, latin9, L9 | Западная Европа |621| iso8859\_16 | iso-8859-16, latin10, L10 | Юго-Восточная Европа |622| johab | cp1361, ms1361 | Корейский |623| koi8\_r |  | Русский |624| koi8\_t |  | Таджикский Новое в версии 3.5. |625| koi8\_u |  | Украинский |626| kz1048 | kz\_1048, strk1048\_2002, rk1048 | Казахский Новое в версии 3.5. |627| mac\_cyrillic | maccyrillic | болгарский, белорусский, македонский, русский, сербский |628| mac\_greek | macgreek | Греческий |629| mac\_iceland | maciceland | Исландский |630| mac\_latin2 | maclatin2, maccentraleurope, mac\_centeuro | Центральная и Восточная Европа |631| mac\_roman | macroman, macintosh | Западная Европа |632| mac\_turkish | macturkish | Турецкий |633| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |634| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |635| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |636| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |637| utf\_32 | U32, utf32 | все языки |638| utf\_32\_be | UTF-32BE | все языки |639| utf\_32\_le | UTF-32LE | все языки |640| utf\_16 | U16, utf16 | все языки |641| utf\_16\_be | UTF-16BE | все языки |642| utf\_16\_le | UTF-16LE | все языки |643| utf\_7 | U7, unicode-1-1-utf-7 | все языки |644| utf\_8 | U8, UTF, utf8, cp65001 | все языки |645| utf\_8\_sig |  | все языки |646647Изменено в версии 3.4: Кодировщики utf-16\* и utf-32\* больше не позволяют кодировать суррогатные кодовые точки (`U+D800`–`U+DFFF`). Декодировщики utf-32\* больше не декодируют последовательности байтов, соответствующие суррогатным кодовым точкам.648649Изменено в версии 3.8: `cp65001` теперь является псевдонимом `utf_8`.650651## Специфичные для Python кодировки652653Ряд предопределённых кодеков специфичны для Python, поэтому их имена не имеют смысла вне Python. Они перечислены в таблицах ниже на основе ожидаемых типов ввода и вывода (обратите внимание: хотя текстовые кодировки – наиболее распространённый случай использования кодеков, базовая инфраструктура кодеков поддерживает произвольные преобразования данных, а не только текстовые кодировки). Для асимметричных кодеков указанное назначение описывает направление кодирования.654655### Текстовые кодировки656657Следующие кодеки обеспечивают кодирование из [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) в [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes) и декодирование из [байтоподобного объекта](https://python-all.ru/3.10/glossary.html#term-bytes-like-object) в [`str`](https://python-all.ru/3.10/library/stdtypes.html#str), аналогично текстовым кодировкам Unicode.658659| Кодек | Псевдонимы | Значение |660| --- | --- | --- |661| idna |  | Реализует [**RFC 3490**](https://python-all.ru/3.10/library/codecs.html), см. также [`encodings.idna`](https://python-all.ru/3.10/library/codecs.html#module-encodings.idna). Поддерживается только `errors='strict'`. |662| mbcs | ansi, dbcs | Только для Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |663| oem |  | Только для Windows: кодирует операнд в соответствии с кодовой страницей OEM (CP\_OEMCP). Новое в версии 3.6. |664| palmos |  | Кодировка PalmOS 3.5. |665| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/3.10/library/codecs.html). Кодеки с состоянием не поддерживаются. |666| raw\_unicode\_escape |  | Кодировка Latin-1 с `\uXXXX` и `\UXXXXXXXX` для остальных кодовых точек. Существующие обратные слеши никак не экранируются. Используется в протоколе pickle языка Python. |667| undefined |  | Вызывает исключение для всех преобразований, даже для пустых строк. Обработчик ошибок игнорируется. |668| unicode\_escape |  | Кодировка, подходящая для содержимого Unicode-литерала в исходном коде Python в кодировке ASCII, за исключением того, что кавычки не экранируются. Декодирование из исходного кода в Latin-1. Имейте в виду, что исходный код Python на самом деле по умолчанию использует UTF-8. |669670Изменено в версии 3.8: кодек «unicode\_internal» удалён.671672### Двоичные преобразования673674Следующие кодеки обеспечивают двоичные преобразования: [объект, подобный байтовой строке](https://python-all.ru/3.10/glossary.html#term-bytes-like-object) в [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes). Они не поддерживаются [`bytes.decode()`](https://python-all.ru/3.10/library/stdtypes.html#bytes.decode) (который создаёт только вывод [`str`](https://python-all.ru/3.10/library/stdtypes.html#str)).675676| Кодек | Псевдонимы | Значение | Кодировщик / декодировщик |677| --- | --- | --- | --- |678| base64\_codec [1](https://python-all.ru/3.10/library/codecs.html#b64) | base64, base\_64 | Преобразует операнд в многострочный MIME base64 (результат всегда включает завершающий `'\n'`). Изменено в версии 3.4: принимает любой [объект, подобный байтовой строке](https://python-all.ru/3.10/glossary.html#term-bytes-like-object) в качестве входных данных для кодирования и декодирования | [`base64.encodebytes()`](https://python-all.ru/3.10/library/base64.html#base64.encodebytes) / [`base64.decodebytes()`](https://python-all.ru/3.10/library/base64.html#base64.decodebytes) |679| bz2\_codec | bz2 | Сжимает операнд с помощью bz2. | [`bz2.compress()`](https://python-all.ru/3.10/library/bz2.html#bz2.compress) / [`bz2.decompress()`](https://python-all.ru/3.10/library/bz2.html#bz2.decompress) |680| hex\_codec | hex | Преобразует операнд в шестнадцатеричное представление, по два символа на байт. | [`binascii.b2a_hex()`](https://python-all.ru/3.10/library/binascii.html#binascii.b2a_hex) / [`binascii.a2b_hex()`](https://python-all.ru/3.10/library/binascii.html#binascii.a2b_hex) |681| quopri\_codec | quopri, quotedprintable, quoted\_printable | Преобразует операнд в MIME quoted printable. | [`quopri.encode()`](https://python-all.ru/3.10/library/quopri.html#quopri.encode) с `quotetabs=True` / [`quopri.decode()`](https://python-all.ru/3.10/library/quopri.html#quopri.decode) |682| uu\_codec | uu | Преобразует операнд с помощью uuencode. | [`uu.encode()`](https://python-all.ru/3.10/library/uu.html#uu.encode) / [`uu.decode()`](https://python-all.ru/3.10/library/uu.html#uu.decode) |683| zlib\_codec | zip, zlib | Сжимает операнд с помощью gzip. | [`zlib.compress()`](https://python-all.ru/3.10/library/zlib.html#zlib.compress) / [`zlib.decompress()`](https://python-all.ru/3.10/library/zlib.html#zlib.decompress) |684685**[1](https://python-all.ru/3.10/library/codecs.html#id5)**686687В дополнение к [байтоподобным объектам](https://python-all.ru/3.10/glossary.html#term-bytes-like-object), `'base64_codec'` также принимает экземпляры [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) только с ASCII для декодирования688689Новое в версии 3.2: Восстановление бинарных преобразований.690691Изменено в версии 3.4: Восстановление псевдонимов для двоичных преобразований.692693### Текстовые преобразования694695Следующий кодек предоставляет текстовое преобразование: отображение [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) в [`str`](https://python-all.ru/3.10/library/stdtypes.html#str). Он не поддерживается [`str.encode()`](https://python-all.ru/3.10/library/stdtypes.html#str.encode) (который создаёт только вывод [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes)).696697| Кодек | Псевдонимы | Значение |698| --- | --- | --- |699| rot\_13 | rot13 | Возвращает шифр Цезаря для операнда. |700701Новое в версии 3.2: Восстановление `rot_13` текстового преобразования.702703Изменено в версии 3.4: Восстановление псевдонима `rot13`.704705## [`encodings.idna`](https://python-all.ru/3.10/library/codecs.html#module-encodings.idna) – Интернационализированные доменные имена в приложениях706707Этот модуль реализует [**RFC 3490**](https://python-all.ru/3.10/library/codecs.html) (Internationalized Domain Names in Applications) и [**RFC 3492**](https://python-all.ru/3.10/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/3.10/library/stringprep.html#module-stringprep).708709Если нужен стандарт IDNA 2008 из [**RFC 5891**](https://python-all.ru/3.10/library/codecs.html) и [**RFC 5895**](https://python-all.ru/3.10/library/codecs.html), используйте сторонний [модуль idna](https://python-all.ru/3.10/library/codecs.html).710711Эти RFC совместно определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (например, `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, такую как `www.xn--alliancefranaise-npb.nu`). Форма ACE доменного имени затем используется во всех местах, где протокол не допускает произвольных символов, таких как DNS-запросы, поля HTTP *Host* и так далее. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки доменов Unicode в IDNA при передаче по сети и преобразовывать обратно метки ACE в Unicode перед представлением их пользователю.712713Python поддерживает это преобразование несколькими способами: кодек `idna` выполняет преобразование между Unicode и ACE, разделяя входную строку на метки на основе символов-разделителей, определённых в [**раздел 3.1 RFC 3490**](https://python-all.ru/3.10/library/codecs.html), и преобразуя каждую метку в ACE по мере необходимости, и, наоборот, разделяя входную байтовую строку на метки на основе разделителя `.` и преобразуя любые найденные метки ACE в Unicode. Кроме того, модуль [`socket`](https://python-all.ru/3.10/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно беспокоиться о преобразовании имён хостов самостоятельно при передаче их в модуль socket. Вдобавок, модули, которые принимают имена хостов в качестве параметров функций, такие как [`http.client`](https://python-all.ru/3.10/library/http.client.html#module-http.client) и [`ftplib`](https://python-all.ru/3.10/library/ftplib.html#module-ftplib), принимают Unicode-имена хостов ([`http.client`](https://python-all.ru/3.10/library/http.client.html#module-http.client) затем также прозрачно отправляет IDNA-имя хоста в поле *Host*, если вообще отправляет это поле).714715При получении имён хостов из сети (например, при обратном поиске имени) никакого автоматического преобразования в Unicode не выполняется: приложения, желающие представить такие имена хостов пользователю, должны декодировать их в Unicode.716717Модуль [`encodings.idna`](https://python-all.ru/3.10/library/codecs.html#module-encodings.idna) также реализует процедуру nameprep, которая выполняет определённые нормализации имён хостов для достижения нечувствительности к регистру интернационализированных доменных имён и унификации похожих символов. Функции nameprep можно использовать напрямую, если необходимо.718719#### `encodings.idna.nameprep(label)`720721Возвращает версию *label* после обработки nameprep. В текущей реализации предполагаются строки запроса, поэтому `AllowUnassigned` имеет значение истина.722723#### `encodings.idna.ToASCII(label)`724725Преобразует метку в ASCII, как указано в [**RFC 3490**](https://python-all.ru/3.10/library/codecs.html). Предполагается, что `UseSTD3ASCIIRules` имеет значение false.726727#### `encodings.idna.ToUnicode(label)`728729Преобразует метку в Unicode, как указано в [**RFC 3490**](https://python-all.ru/3.10/library/codecs.html).730731## [`encodings.mbcs`](https://python-all.ru/3.10/library/codecs.html#module-encodings.mbcs) – кодовая страница Windows ANSI732733Этот модуль реализует кодовую страницу ANSI (CP\_ACP).734735[Доступность](https://python-all.ru/3.10/library/intro.html#availability): только в Windows.736737Изменено в версии 3.3: Поддержка любого обработчика ошибок.738739Изменено в версии 3.2: До версии 3.2 аргумент *errors* игнорировался; `'replace'` всегда использовался для кодирования, а `'ignore'` для декодирования.740741## [`encodings.utf_8_sig`](https://python-all.ru/3.10/library/codecs.html#module-encodings.utf_8_sig) – UTF-8 кодек с сигнатурой BOM742743Этот модуль реализует разновидность кодека UTF-8. При кодировании перед байтами, закодированными в UTF-8, добавляется BOM в кодировке UTF-8. Для кодера с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный BOM в кодировке UTF-8 в начале данных пропускается.744