`codecs.md`

819 строк · 101.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/library/codecs.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `codecs` – Реестр кодеков и базовые классы89**Исходный код:** [Lib/codecs.py](https://python-all.ru/src/3.13/Lib/codecs.py)1011---1213Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодека и обработки ошибок. Большинство стандартных кодеков являются [текстовыми кодировками](https://python-all.ru/3.13/glossary.html#term-text-encoding), которые кодируют текст в байты (и декодируют байты в текст), но существуют также кодеки, которые кодируют текст в текст и байты в байты. Пользовательские кодеки могут кодировать и декодировать между произвольными типами, но некоторые возможности модуля ограничены для использования только с текстовыми кодировками или с кодеками, которые кодируют в [`bytes`](https://python-all.ru/3.13/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.13/library/exceptions.html#ValueError) (or a more codec specific subclass, such as [`UnicodeEncodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeEncodeError)). Refer to [Codec Base Classes](https://python-all.ru/3.13/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.13/library/exceptions.html#ValueError) (or a more codec specific subclass, such as [`UnicodeDecodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeDecodeError)). Refer to [Codec Base Classes](https://python-all.ru/3.13/library/codecs.html#codec-base-classes) for more information on codec error handling.2829#### `codecs.charmap_build(string)`3031Возвращает отображение, пригодное для кодирования с помощью пользовательской однобайтовой кодировки. Если задана [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) *строка* длиной до 256 символов, представляющая таблицу декодирования, возвращается либо компактный внутренний объект отображения `EncodingMap`, либо [`dictionary`](https://python-all.ru/3.13/library/stdtypes.html#dict), отображающий порядковые номера символов в байтовые значения. Вызывает [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError) при некорректном вводе.3233Полные сведения о каждом кодеке также можно получить напрямую:3435#### `codecs.lookup(encoding)`3637Ищет информацию о кодеке в реестре кодеков Python и возвращает объект [`CodecInfo`](https://python-all.ru/3.13/library/codecs.html#codecs.CodecInfo), как определено ниже.3839Сначала кодировки ищутся в кэше реестра. Если не найдены, просматривается список зарегистрированных функций поиска. Если объект [`CodecInfo`](https://python-all.ru/3.13/library/codecs.html#codecs.CodecInfo) не найден, вызывается [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError). В противном случае объект `CodecInfo` сохраняется в кэше и возвращается вызывающему.4041#### `class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)`4243Сведения о кодеке при поиске в реестре кодеков. Аргументы конструктора хранятся в атрибутах с теми же именами:4445#### `name`4647Имя кодировки.4849#### `encode`5051#### `decode`5253Функции кодирования и декодирования без сохранения состояния. Это должны быть функции или методы с тем же интерфейсом, что и методы [`encode()`](https://python-all.ru/3.13/library/codecs.html#codecs.Codec.encode) и [`decode()`](https://python-all.ru/3.13/library/codecs.html#codecs.Codec.decode) экземпляров Codec (см. [Интерфейс Codec](https://python-all.ru/3.13/library/codecs.html#codec-objects)). Предполагается, что функции или методы работают в режиме без сохранения состояния.5455#### `incrementalencoder`5657#### `incrementaldecoder`5859Классы или фабричные функции инкрементального кодера и декодера. Они должны предоставлять интерфейс, определенный базовыми классами [`IncrementalEncoder`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalDecoder), соответственно. Инкрементальные кодеки могут поддерживать состояние.6061#### `streamwriter`6263#### `streamreader`6465Классы или фабричные функции записи и чтения потоков. Они должны предоставлять интерфейс, определенный базовыми классами [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader), соответственно. Потоковые кодеки могут поддерживать состояние.6667Для упрощения доступа к различным компонентам кодеков модуль предоставляет следующие дополнительные функции, которые используют [`lookup()`](https://python-all.ru/3.13/library/codecs.html#codecs.lookup) для поиска кодека:6869#### `codecs.getencoder(encoding)`7071Находит кодек для указанной кодировки и возвращает его функцию-кодировщик.7273Вызывает [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError), если кодировка не найдена.7475#### `codecs.getdecoder(encoding)`7677Находит кодек для указанной кодировки и возвращает его функцию-декодер.7879Вызывает [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError), если кодировка не найдена.8081#### `codecs.getincrementalencoder(encoding)`8283Находит кодек для указанной кодировки и возвращает его класс инкрементального кодировщика или фабричную функцию.8485Вызывает [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный кодировщик.8687#### `codecs.getincrementaldecoder(encoding)`8889Находит кодек для указанной кодировки и возвращает его класс инкрементального декодера или фабричную функцию.9091Вызывает [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError), если кодировка не найдена или кодек не поддерживает инкрементальный декодер.9293#### `codecs.getreader(encoding)`9495Находит кодек для указанной кодировки и возвращает его [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader) класс или фабричную функцию.9697Вызывает [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError), если кодировка не найдена.9899#### `codecs.getwriter(encoding)`100101Находит кодек для указанной кодировки и возвращает его [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter) класс или фабричную функцию.102103Вызывает [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError), если кодировка не найдена.104105Пользовательские кодеки становятся доступными при регистрации подходящей функции поиска кодека :106107#### `codecs.register(search_function)`108109Регистрирует функцию поиска кодека. Функция поиска должна принимать один аргумент – имя кодировки строчными буквами, где дефисы и пробелы преобразуются в символы подчёркивания, и возвращать объект [`CodecInfo`](https://python-all.ru/3.13/library/codecs.html#codecs.CodecInfo). Если функция поиска не может найти указанную кодировку, она должна вернуть `None`.110111Изменено в версии 3.9: Дефисы и пробелы преобразуются в символ подчёркивания.112113#### `codecs.unregister(search_function)`114115Отменяет регистрацию функции поиска кодека и очищает кэш реестра. Если функция поиска не зарегистрирована, ничего не делает.116117Добавлено в версии 3.10.118119Хотя встроенная функция [`open()`](https://python-all.ru/3.13/library/functions.html#open) и связанный с ней модуль [`io`](https://python-all.ru/3.13/library/io.html#module-io) являются рекомендуемым способом работы с закодированными текстовыми файлами, этот модуль предоставляет дополнительные вспомогательные функции и классы, позволяющие использовать более широкий набор кодеков при работе с бинарными файлами:120121#### `codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)`122123Открывает закодированный файл, используя указанный *режим*, и возвращает экземпляр [`StreamReaderWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReaderWriter), обеспечивая прозрачное кодирование/декодирование. Режим файла по умолчанию – `'r'`, что означает открытие файла в режиме чтения.124125> **Примечание**126>127> Если *encoding* не равен `None`, то базовые закодированные файлы всегда открываются в бинарном режиме. Автоматическое преобразование `'\n'` не выполняется при чтении и записи. Аргумент *mode* может быть любым бинарным режимом, допустимым для встроенной функции `open()`; `'b'` добавляется автоматически.128129*encoding* указывает кодировку, которая будет использоваться для файла. Допускается любая кодировка, которая кодирует в байты и декодирует из байтов, а типы данных, поддерживаемые методами файла, зависят от используемого кодека.130131Параметр *errors* можно задать для определения обработки ошибок. По умолчанию он равен `'strict'`, что приводит к возбуждению [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError) при возникновении ошибки кодирования.132133Параметр *buffering* имеет то же значение, что и для встроенной функции `open()`. По умолчанию он равен -1, что означает использование размера буфера по умолчанию.134135Изменено в версии 3.11: Режим `'U'` удалён.136137#### `codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')`138139Возвращает экземпляр [`StreamRecoder`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamRecoder), обёртку для *file*, которая обеспечивает прозрачное перекодирование. Исходный файл закрывается при закрытии обёртки.140141Данные, записываемые в обёрнутый файл, декодируются согласно заданной *data\_encoding*, а затем записываются в исходный файл в виде байтов с использованием *file\_encoding*. Байты, читаемые из исходного файла, декодируются согласно *file\_encoding*, а результат кодируется с использованием *data\_encoding*.142143Если *file\_encoding* не указан, по умолчанию используется *data\_encoding*.144145Параметр *errors* может быть задан для определения обработки ошибок. По умолчанию он равен `'strict'`, что приводит к возникновению [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError) в случае ошибки кодирования.146147#### `codecs.iterencode(iterator, encoding, errors='strict', **kwargs)`148149Использует инкрементальный кодировщик для итеративного кодирования входных данных, предоставленных *iterator*. *iterator* должен возвращать объекты [`str`](https://python-all.ru/3.13/library/stdtypes.html#str). Эта функция является [генератором](https://python-all.ru/3.13/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному кодировщику.150151Эта функция требует, чтобы кодек принимал текстовые объекты [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) для кодирования. Поэтому она не поддерживает кодировщики типа «байты-в-байты», такие как `base64_codec`.152153#### `codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)`154155Использует инкрементальный декодер для итеративного декодирования входных данных, предоставленных *iterator*. *iterator* должен возвращать объекты [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes). Эта функция является [генератором](https://python-all.ru/3.13/glossary.html#term-generator). Аргумент *errors* (как и любые другие именованные аргументы) передаётся инкрементальному декодеру.156157Эта функция требует, чтобы кодек принимал объекты [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) для декодирования. Поэтому она не поддерживает кодировщики типа «текст-в-текст», такие как `rot_13`, хотя `rot_13` может использоваться аналогично с [`iterencode()`](https://python-all.ru/3.13/library/codecs.html#codecs.iterencode).158159#### `codecs.readbuffer_encode(buffer, errors=None, /)`160161Возвращает [`tuple`](https://python-all.ru/3.13/library/stdtypes.html#tuple), содержащий сырые байты *buffer*, [объекта, совместимого с буфером](https://python-all.ru/3.13/c-api/buffer.html#bufferobjects) или [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) (кодируется в UTF-8 перед обработкой), и их длину в байтах.162163Аргумент *errors* игнорируется.164165```pycon166>>> codecs.readbuffer_encode(b"Zito")167(b'Zito', 4)168```169170Модуль также предоставляет следующие константы, полезные для чтения и записи в платформенно-зависимые файлы:171172#### `codecs.BOM`173174#### `codecs.BOM_BE`175176#### `codecs.BOM_LE`177178#### `codecs.BOM_UTF8`179180#### `codecs.BOM_UTF16`181182#### `codecs.BOM_UTF16_BE`183184#### `codecs.BOM_UTF16_LE`185186#### `codecs.BOM_UTF32`187188#### `codecs.BOM_UTF32_BE`189190#### `codecs.BOM_UTF32_LE`191192Эти константы определяют различные последовательности байтов, являющиеся метками порядка байтов Unicode (BOM) для нескольких кодировок. Они используются в потоках данных UTF-16 и UTF-32 для указания используемого порядка байтов, а в UTF-8 – как сигнатура Unicode. [`BOM_UTF16`](https://python-all.ru/3.13/library/codecs.html#codecs.BOM_UTF16) это либо [`BOM_UTF16_BE`](https://python-all.ru/3.13/library/codecs.html#codecs.BOM_UTF16_BE), либо [`BOM_UTF16_LE`](https://python-all.ru/3.13/library/codecs.html#codecs.BOM_UTF16_LE) в зависимости от нативного порядка байтов платформы; [`BOM`](https://python-all.ru/3.13/library/codecs.html#codecs.BOM) – псевдоним `BOM_UTF16`, [`BOM_LE`](https://python-all.ru/3.13/library/codecs.html#codecs.BOM_LE) – `BOM_UTF16_LE`, [`BOM_BE`](https://python-all.ru/3.13/library/codecs.html#codecs.BOM_BE) – `BOM_UTF16_BE`. Остальные представляют BOM в кодировках UTF-8 и UTF-32.193194## Базовые классы кодеков195196Модуль `codecs` определяет набор базовых классов, которые задают интерфейсы для работы с объектами кодеков, а также могут использоваться как основа для реализации пользовательских кодеков.197198Каждый кодек должен определять четыре интерфейса, чтобы быть пригодным для использования в Python: статический кодировщик, статический декодер, потоковый читатель и потоковый писатель. Потоковые читатели и писатели обычно используют статический кодировщик/декодер для реализации файловых протоколов. Разработчикам кодеков также необходимо определить, как кодек будет обрабатывать ошибки кодирования и декодирования.199200### Обработчики ошибок201202Чтобы упростить и стандартизировать обработку ошибок, кодеки могут реализовывать разные схемы обработки ошибок, принимая строковый аргумент *errors*:203204```python205>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')206b'German \\xdf, \\u266c'207>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')208b'German &#223;, &#9836;'209```210211Следующие обработчики ошибок можно использовать со всеми кодеками [стандартных кодировок](https://python-all.ru/3.13/library/codecs.html#standard-encodings) Python:212213| Значение | Значение |214| --- | --- |215| `'strict'` | Выбрасывает [`UnicodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeError) (или подкласс). Это поведение по умолчанию. Реализовано в [`strict_errors()`](https://python-all.ru/3.13/library/codecs.html#codecs.strict_errors). |216| `'ignore'` | Игнорировать повреждённые данные и продолжить без дополнительных уведомлений. Реализовано в [`ignore_errors()`](https://python-all.ru/3.13/library/codecs.html#codecs.ignore_errors). |217| `'replace'` | Замена на символ-заменитель. При кодировании используется `?` (ASCII-символ). При декодировании используется `�` (U+FFFD, официальный символ замены). Реализовано в [`replace_errors()`](https://python-all.ru/3.13/library/codecs.html#codecs.replace_errors). |218| `'backslashreplace'` | Замена на escape-последовательности с обратной косой чертой. При кодировании используется шестнадцатеричная форма кодовой точки Unicode в форматах `\xhh` `\uxxxx` `\Uxxxxxxxx`. При декодировании используется шестнадцатеричная форма значения байта в формате `\xhh`. Реализовано в [`backslashreplace_errors()`](https://python-all.ru/3.13/library/codecs.html#codecs.backslashreplace_errors). |219| `'surrogateescape'` | При декодировании заменяет байт на отдельный суррогатный код в диапазоне от `U+DC80` до `U+DCFF`. Этот код затем преобразуется обратно в тот же байт при использовании обработчика ошибок `'surrogateescape'` при кодировании данных. (Подробнее см. [**PEP 383**](https://python-all.ru/3.13/library/codecs.html).) |220221Следующие обработчики ошибок применимы только к кодированию (в рамках [текстовых кодировок](https://python-all.ru/3.13/glossary.html#term-text-encoding)):222223| Значение | Значение |224| --- | --- |225| `'xmlcharrefreplace'` | Замена на числовую ссылку на символ XML/HTML (десятичная форма кодовой точки Unicode) в формате `&#num;`. Реализовано в [`xmlcharrefreplace_errors()`](https://python-all.ru/3.13/library/codecs.html#codecs.xmlcharrefreplace_errors). |226| `'namereplace'` | Замена на escape-последовательности `\N{...}`; то, что находится в фигурных скобках, – это свойство Name из базы данных символов Unicode. Реализовано в [`namereplace_errors()`](https://python-all.ru/3.13/library/codecs.html#codecs.namereplace_errors). |227228Кроме того, следующий обработчик ошибок специфичен для указанных кодеков:229230| Значение | Кодеки | Значение |231| --- | --- | --- |232| `'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.13/library/stdtypes.html#str) ошибкой. |233234Добавлено в версии 3.1: обработчики ошибок `'surrogateescape'` и `'surrogatepass'`.235236Изменено в версии 3.4: обработчик ошибок `'surrogatepass'` теперь работает с кодеками utf-16\* и utf-32\*.237238Добавлено в версии 3.5: обработчик ошибок `'namereplace'`.239240Изменено в версии 3.5: обработчик ошибок `'backslashreplace'` теперь работает с декодированием и трансляцией.241242Набор допустимых значений можно расширить, зарегистрировав новый именованный обработчик ошибок:243244#### `codecs.register_error(name, error_handler)`245246Регистрирует функцию обработки ошибок *error\_handler* под именем *name*. Аргумент *error\_handler* будет вызываться во время кодирования и декодирования в случае ошибки, когда в качестве параметра errors указано *name*.247248При кодировании *error\_handler* будет вызываться с экземпляром [`UnicodeEncodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeEncodeError), который содержит информацию о местоположении ошибки. Обработчик ошибок должен либо повторно выбросить это или другое исключение, либо вернуть кортеж с заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Замена может быть либо [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), либо [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes). Если замена – bytes, кодировщик просто скопирует их в выходной буфер. Если замена – строка, кодировщик закодирует замену. Кодирование продолжается с исходных входных данных начиная с указанной позиции. Отрицательные значения позиции интерпретируются как смещение относительно конца входной строки. Если результирующая позиция выходит за границы, выбрасывается [`IndexError`](https://python-all.ru/3.13/library/exceptions.html#IndexError).249250Декодирование и трансляция работают аналогично, за исключением того, что обработчику передаётся [`UnicodeDecodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeDecodeError) или [`UnicodeTranslateError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeTranslateError), а замена от обработчика ошибок помещается в выходные данные напрямую.251252Ранее зарегистрированные обработчики ошибок (включая стандартные) можно найти по имени:253254#### `codecs.lookup_error(name)`255256Возвращает обработчик ошибок, ранее зарегистрированный под именем *name*.257258Выбрасывает [`LookupError`](https://python-all.ru/3.13/library/exceptions.html#LookupError), если обработчик не найден.259260Следующие стандартные обработчики ошибок также доступны как функции уровня модуля:261262#### `codecs.strict_errors(exception)`263264Реализует обработку ошибок `'strict'`.265266Каждая ошибка кодирования или декодирования выбрасывает [`UnicodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeError).267268#### `codecs.ignore_errors(exception)`269270Реализует обработку ошибок `'ignore'`.271272Некорректные данные игнорируются; кодирование или декодирование продолжается без дополнительных уведомлений.273274#### `codecs.replace_errors(exception)`275276Реализует обработку ошибок `'replace'`.277278Заменяет `?` (символ ASCII) при ошибках кодирования или `�` (U+FFFD, официальный ЗАМЕНЯЮЩИЙ СИМВОЛ) при ошибках декодирования.279280#### `codecs.backslashreplace_errors(exception)`281282Реализует обработку ошибок `'backslashreplace'`.283284Некорректные данные заменяются управляющей последовательностью с обратной косой чертой. При кодировании используется шестнадцатеричная форма кодовой точки Unicode в форматах `\xhh` `\uxxxx` `\Uxxxxxxxx`. При декодировании используется шестнадцатеричная форма значения байта в формате `\xhh`.285286Изменено в версии 3.5: Работает с декодированием и трансляцией.287288#### `codecs.xmlcharrefreplace_errors(exception)`289290Реализует обработку ошибок `'xmlcharrefreplace'` (только для кодирования в рамках [текстовой кодировки](https://python-all.ru/3.13/glossary.html#term-text-encoding)).291292Не кодируемый символ заменяется соответствующей XML/HTML числовой ссылкой на символ, которая представляет собой десятичную форму кодовой точки Unicode в формате `&#num;`.293294#### `codecs.namereplace_errors(exception)`295296Реализует обработку ошибок `'namereplace'` (только для кодирования в рамках [текстовой кодировки](https://python-all.ru/3.13/glossary.html#term-text-encoding)).297298Не кодируемый символ заменяется управляющей последовательностью `\N{...}`. Набор символов, которые появляются в фигурных скобках, – это свойство Name из базы данных символов Unicode. Например, немецкая строчная буква `'ß'` будет преобразована в последовательность байтов `\N{LATIN SMALL LETTER SHARP S}`.299300Добавлено в версии 3.5.301302### Кодирование и декодирование без сохранения состояния303304Базовый класс [`Codec`](https://python-all.ru/3.13/library/codecs.html#codecs.Codec) определяет эти методы, которые также задают интерфейсы функций кодировщика и декодировщика без сохранения состояния:305306#### `class codecs.Codec`307308#### `encode(input, errors='strict')`309310Кодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Например, [текстовая кодировка](https://python-all.ru/3.13/glossary.html#term-text-encoding) преобразует строковый объект в объект bytes, используя определённую кодировку набора символов (например, `cp1252` или `iso-8859-1`).311312Аргумент *errors* задаёт применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.313314Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter) для кодеков, которым необходимо сохранять состояние для эффективного кодирования.315316Кодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.317318#### `decode(input, errors='strict')`319320Декодирует объект *input* и возвращает кортеж (объект вывода, длина обработанных данных). Например, для [текстовой кодировки](https://python-all.ru/3.13/glossary.html#term-text-encoding) декодирование преобразует объект bytes, закодированный с использованием определённой кодировки набора символов, в строковый объект.321322Для текстовых кодировок и кодеков bytes-to-bytes *input* должен быть объектом bytes или объектом, предоставляющим интерфейс буфера только для чтения – например, буферные объекты и файлы, отображаемые в память.323324Аргумент *errors* задаёт применяемую обработку ошибок. По умолчанию используется обработка `'strict'`.325326Метод не должен сохранять состояние в экземпляре `Codec`. Используйте [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader) для кодеков, которым необходимо сохранять состояние для эффективного декодирования.327328Декодировщик должен уметь обрабатывать входные данные нулевой длины и в этом случае возвращать пустой объект типа объекта вывода.329330### Инкрементальное кодирование и декодирование331332Классы [`IncrementalEncoder`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalEncoder) и [`IncrementalDecoder`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalDecoder) предоставляют базовый интерфейс для инкрементального кодирования и декодирования. Кодирование/декодирование входных данных выполняется не одним вызовом функции кодировщика/декодировщика без состояния, а несколькими вызовами метода [`encode()`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalDecoder.decode) инкрементального кодировщика/декодировщика. Инкрементальный кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.333334Объединённый вывод вызовов метода [`encode()`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalEncoder.encode)/[`decode()`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalDecoder.decode) совпадает с тем, что получилось бы, если бы все отдельные входные данные были объединены в один, и этот вход был закодирован/декодирован кодировщиком/декодировщиком без состояния.335336#### Объекты IncrementalEncoder337338Класс [`IncrementalEncoder`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalEncoder) используется для кодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный кодировщик для совместимости с реестром кодеков Python.339340#### `class codecs.IncrementalEncoder(errors='strict')`341342Конструктор экземпляра `IncrementalEncoder`.343344Все инкрементальные кодировщики должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.345346Декодер `IncrementalEncoder` может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Список возможных значений приведён в разделе [Обработчики ошибок](https://python-all.ru/3.13/library/codecs.html#error-handlers).347348Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта `IncrementalEncoder`.349350#### `encode(object, final=False)`351352Кодирует *object* (с учётом текущего состояния кодировщика) и возвращает результирующий закодированный объект. Если это последний вызов `encode()`, *final* должен быть истинным (по умолчанию – ложь).353354#### `reset()`355356Сбрасывает кодировщик в исходное состояние. Выходные данные отбрасываются: при необходимости вызовите `.encode(object, final=True)`, передав пустую строку байтов или текстовую строку, чтобы сбросить кодировщик и получить выходные данные.357358#### `getstate()`359360Возвращает текущее состояние кодировщика, которое должно быть целым числом. Реализация должна гарантировать, что `0` является наиболее распространённым состоянием. (Состояния, более сложные, чем целые числа, можно преобразовать в целое число с помощью маршалинга/сериализации состояния и кодирования байтов результирующей строки в целое число.)361362#### `setstate(state)`363364Устанавливает состояние кодировщика в *state*. *state* должно быть состоянием кодировщика, возвращённым [`getstate()`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalEncoder.getstate).365366#### Объекты IncrementalDecoder367368Класс [`IncrementalDecoder`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalDecoder) используется для декодирования входных данных за несколько шагов. Он определяет следующие методы, которые должен реализовать любой инкрементальный декодер для совместимости с реестром кодеков Python.369370#### `class codecs.IncrementalDecoder(errors='strict')`371372Конструктор экземпляра `IncrementalDecoder`.373374Все инкрементальные декодеры должны предоставлять этот интерфейс конструктора. Они могут свободно добавлять дополнительные именованные аргументы, однако реестр кодеков Python использует только те, что определены здесь.375376Декодер `IncrementalDecoder` может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. Список возможных значений приведён в разделе [Обработчики ошибок](https://python-all.ru/3.13/library/codecs.html#error-handlers).377378Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между разными стратегиями обработки ошибок в течение времени жизни объекта `IncrementalDecoder`.379380#### `decode(object, final=False)`381382Декодирует *object* (с учётом текущего состояния декодера) и возвращает результирующий декодированный объект. Если это последний вызов `decode()`, *final* должен быть истинным (по умолчанию – ложь). Если *final* истинно, декодер должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце входных данных), он должен инициировать обработку ошибок, как в случае без сохранения состояния (что может вызвать исключение).383384#### `reset()`385386Сбрасывает декодер в исходное состояние.387388#### `getstate()`389390Возвращает текущее состояние декодера. Это должен быть кортеж из двух элементов: первый – буфер, содержащий ещё не декодированные входные данные; второй – целое число, которое может содержать дополнительную информацию о состоянии. (Реализация должна гарантировать, что `0` является наиболее распространённой дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии равна `0`, должна быть возможность установить декодер в состояние без буферизованных входных данных и с `0` в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованных входных данных в декодер возвращала его в предыдущее состояние без вывода каких-либо данных. (Дополнительная информация о состоянии, более сложная, чем целые числа, может быть преобразована в целое число с помощью маршалинга/сериализации этой информации и кодирования байтов результирующей строки в целое число.)391392#### `setstate(state)`393394Устанавливает состояние декодера в *state*. *state* должно быть состоянием декодера, возвращённым [`getstate()`](https://python-all.ru/3.13/library/codecs.html#codecs.IncrementalDecoder.getstate).395396### Потоковое кодирование и декодирование397398Классы [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter) и [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader) предоставляют универсальные рабочие интерфейсы, которые можно использовать для очень простой реализации новых подмодулей кодирования. Пример см. в `encodings.utf_8`.399400#### Объекты StreamWriter401402Класс [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter) является подклассом [`Codec`](https://python-all.ru/3.13/library/codecs.html#codecs.Codec) и определяет следующие методы, которые каждый потоковый писатель должен реализовать для совместимости с реестром кодеков Python.403404#### `class codecs.StreamWriter(stream, errors='strict')`405406Конструктор экземпляра `StreamWriter`.407408Все потоковые писатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.409410Аргумент *поток данных* должен быть файлоподобным объектом, открытым для записи текстовых или двоичных данных, в зависимости от конкретного кодека.411412Объект `StreamWriter` может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. См. [Обработчики ошибок](https://python-all.ru/3.13/library/codecs.html#error-handlers) для получения списка стандартных обработчиков ошибок, которые может поддерживать базовый потоковый кодек.413414Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта `StreamWriter`.415416#### `write(object)`417418Записывает в поток закодированное содержимое объекта.419420#### `writelines(list)`421422Записывает в поток конкатенированный итерируемый объект из строк (возможно, с использованием метода [`write()`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter.write)). Бесконечные или очень большие итерируемые объекты не поддерживаются. Стандартные кодеки «байты-в-байты» не поддерживают этот метод.423424#### `reset()`425426Сбрасывает буферы кодекa, используемые для хранения внутреннего состояния.427428Вызов этого метода должен гарантировать, что выходные данные перейдут в чистое состояние, позволяющее добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.429430В дополнение к приведённым выше методам, [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.431432#### Объекты StreamReader433434Класс [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader) является подклассом [`Codec`](https://python-all.ru/3.13/library/codecs.html#codecs.Codec) и определяет следующие методы, которые каждый потоковый читатель должен реализовать для совместимости с реестром кодеков Python.435436#### `class codecs.StreamReader(stream, errors='strict')`437438Конструктор экземпляра `StreamReader`.439440Все потоковые читатели должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные именованные аргументы, но реестр кодеков Python использует только те, что определены здесь.441442Аргумент *поток данных* должен быть файлоподобным объектом, открытым для чтения текстовых или двоичных данных, в зависимости от конкретного кодека.443444Объект `StreamReader` может реализовывать различные схемы обработки ошибок с помощью именованного аргумента *errors*. См. [Обработчики ошибок](https://python-all.ru/3.13/library/codecs.html#error-handlers) для получения списка стандартных обработчиков ошибок, которые может поддерживать базовый потоковый кодек.445446Аргумент *errors* будет присвоен атрибуту с тем же именем. Присваивание этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение времени жизни объекта `StreamReader`.447448Набор допустимых значений для аргумента *errors* можно расширить с помощью [`register_error()`](https://python-all.ru/3.13/library/codecs.html#codecs.register_error).449450#### `read(size=-1, chars=-1, firstline=False)`451452Декодирует данные из потока и возвращает результирующий объект.453454Аргумент *chars* указывает количество декодированных кодовых точек или байтов для возврата. Метод [`read()`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader.read) никогда не вернёт больше данных, чем запрошено, но может вернуть меньше, если доступно недостаточно.455456Аргумент *size* указывает приблизительное максимальное количество закодированных байтов или кодовых точек для чтения при декодировании. Декодер может изменять этот параметр по своему усмотрению. Значение по умолчанию -1 означает чтение и декодирование максимально возможного объёма. Этот параметр предназначен для того, чтобы не приходилось декодировать огромные файлы за один шаг.457458Флаг *firstline* указывает, что достаточно вернуть только первую строку, если на последующих строках возникают ошибки декодирования.459460Метод должен использовать жадную стратегию чтения, то есть читать столько данных, сколько допускается определением кодировки и заданным размером; например, если в потоке доступны необязательные окончания кодировки или маркеры состояния, их также следует прочитать.461462#### `readline(size=None, keepends=True)`463464Читает одну строку из входного потока и возвращает декодированные данные.465466*size*, если задан, передаётся как аргумент size в метод [`read()`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader.read) потока данных.467468Если *keepends* равен False, из возвращаемых строк будут удалены символы конца строки.469470#### `readlines(sizehint=None, keepends=True)`471472Читает все строки из входного потока данных и возвращает их в виде списка строк.473474Символы конца строки обрабатываются с помощью метода [`decode()`](https://python-all.ru/3.13/library/codecs.html#codecs.decode) кодекa и включаются в элементы списка, если *keepends* равен True.475476*sizehint*, если задан, передаётся как аргумент *size* в метод [`read()`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader.read) потока данных.477478#### `reset()`479480Сбрасывает буферы кодекa, используемые для хранения внутреннего состояния.481482Обратите внимание, что перемещение по потоку данных не должно выполняться. Этот метод в первую очередь предназначен для восстановления после ошибок декодирования.483484В дополнение к приведённым выше методам, [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader) также должен наследовать все остальные методы и атрибуты от нижележащего потока данных.485486#### Объекты StreamReaderWriter487488[`StreamReaderWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReaderWriter) – это удобный класс, который позволяет оборачивать потоки данных, работающие как в режиме чтения, так и в режиме записи.489490Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.13/library/codecs.html#codecs.lookup).491492#### `class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')`493494Создаёт экземпляр `StreamReaderWriter`. *поток данных* должен быть файлоподобным объектом. *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими интерфейсы [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter) соответственно. Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.495496Экземпляры [`StreamReaderWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReaderWriter) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.497498#### Объекты StreamRecoder499500[`StreamRecoder`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamRecoder) преобразует данные из одной кодировки в другую, что иногда полезно при работе с различными кодировочными средами.501502Конструкция такова, что для создания экземпляра можно использовать фабричные функции, возвращаемые функцией [`lookup()`](https://python-all.ru/3.13/library/codecs.html#codecs.lookup).503504#### `class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')`505506Создаёт экземпляр `StreamRecoder`, реализующий двунаправленное преобразование: *encode* и *decode* работают на внешней стороне – данные, видимые коду, вызывающему [`read()`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader.read) и [`write()`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter.write), в то время как *Reader* и *Writer* работают на внутренней стороне – данные в *поток данных*.507508Эти объекты можно использовать для прозрачной перекодировки, например, из Latin-1 в UTF-8 и обратно.509510Аргумент *поток данных* должен быть файлоподобным объектом.511512Аргументы *encode* и *decode* должны соответствовать интерфейсу [`Codec`](https://python-all.ru/3.13/library/codecs.html#codecs.Codec). *Reader* и *Writer* должны быть фабричными функциями или классами, предоставляющими объекты интерфейсов [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter) соответственно.513514Обработка ошибок выполняется так же, как определено для читателей и писателей потоков данных.515516Экземпляры [`StreamRecoder`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamRecoder) определяют объединённые интерфейсы классов [`StreamReader`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamReader) и [`StreamWriter`](https://python-all.ru/3.13/library/codecs.html#codecs.StreamWriter). Они наследуют все остальные методы и атрибуты от нижележащего потока данных.517518## Кодировки и Unicode519520Строки внутри хранятся как последовательности кодовых точек в диапазоне `U+0000`–`U+10FFFF`. (Подробнее об реализации см. [**PEP 393**](https://python-all.ru/3.13/library/codecs.html).) Как только строковый объект используется за пределами ЦП и памяти, порядок байтов и способ хранения этих массивов в виде байтов становятся проблемой. Как и для других кодеков, сериализация строки в последовательность байтов называется *кодированием*, а восстановление строки из последовательности байтов – *декодированием*. Существует множество различных текстовых кодеков сериализации, которые в совокупности называются [текстовыми кодировками](https://python-all.ru/3.13/glossary.html#term-text-encoding).521522Простейшая текстовая кодировка (называемая `'latin-1'` или `'iso-8859-1'`) отображает кодовые точки 0–255 на байты `0x0`–`0xff`, что означает, что строковый объект, содержащий кодовые точки больше `U+00FF`, не может быть закодирован этим кодеком. Попытка сделать это вызовет исключение [`UnicodeEncodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeEncodeError), которое выглядит следующим образом (хотя детали сообщения об ошибке могут отличаться): `UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256)`.523524Существует ещё одна группа кодировок (так называемые charmap-кодировки), которые выбирают другое подмножество всех кодовых точек Юникода и определяют, как эти кодовые точки отображаются на байты `0x0`–`0xff`. Чтобы увидеть, как это работает, достаточно открыть, например, `encodings/cp1252.py` (кодировку, которая в основном используется в Windows). В ней есть строковая константа из 256 символов, показывающая, какой символ какому значению байта соответствует.525526Все эти кодировки могут закодировать только 256 из 1114112 кодовых точек, определённых в Юникоде. Простой и прямой способ хранить каждую кодовую точку Юникода – хранить её в виде четырёх последовательных байтов. Есть две возможности: хранить байты в порядке big endian или little endian. Эти две кодировки называются соответственно `UTF-32-BE` и `UTF-32-LE`. Их недостаток в том, что если, например, использовать `UTF-32-BE` на машине с little endian, придётся постоянно менять порядок байтов при кодировании и декодировании. Кодеки Python `UTF-16` и `UTF-32` избегают этой проблемы, используя собственный порядок байтов платформы, если BOM отсутствует. Python следует общепринятой практике платформы, поэтому данные в собственном порядке байтов проходят туда и обратно без лишней перестановки байтов, даже если стандарт Юникода по умолчанию использует big endian, когда порядок байтов не указан. Когда эти байты читаются процессором с другим порядком байтов, байты приходится переставлять. Чтобы иметь возможность определить порядок байтов последовательности байтов `UTF-16` или `UTF-32`, используется BOM (маркер порядка байтов). Это символ Юникода `U+FEFF`. Этот символ может быть добавлен в начало каждой последовательности байтов `UTF-16` или `UTF-32`. Версия этого символа с переставленными байтами (`0xFFFE`) является недопустимым символом, который не может встречаться в тексте Юникода. Если первым символом последовательности байтов `UTF-16` или `UTF-32` является `U+FFFE`, байты должны быть переставлены при декодировании.527528К сожалению, символ `U+FEFF` имел второе назначение – `ZERO WIDTH NO-BREAK SPACE`: символ, не имеющий ширины и не допускающий переноса слова. Его можно использовать, например, для подсказок алгоритму лигатур. Начиная с Unicode 4.0 использование `U+FEFF` в качестве `ZERO WIDTH NO-BREAK SPACE` было объявлено устаревшим (эту роль принял `U+2060` (`WORD JOINER`)). Тем не менее, программное обеспечение Юникода по-прежнему должно уметь обрабатывать `U+FEFF` в обеих ролях: как BOM это средство определения порядка хранения закодированных байтов, которое исчезает после декодирования последовательности байтов в строку; как `ZERO WIDTH NO-BREAK SPACE` это обычный символ, который декодируется как любой другой.529530Существует ещё одна кодировка, способная кодировать весь диапазон символов Unicode: UTF-8. UTF-8 – это 8-битная кодировка, поэтому в UTF-8 нет проблем с порядком байтов. Каждый байт в последовательности UTF-8 состоит из двух частей: маркерных битов (старших битов) и полезных битов. Маркерные биты представляют собой последовательность от нуля до четырёх `1` битов, за которой следует `0` бит. Символы Unicode кодируются следующим образом (где x – полезные биты, которые при объединении дают символ Unicode):531532| Диапазон | Кодировка |533| --- | --- |534| `U-00000000` … `U-0000007F` | 0xxxxxxx |535| `U-00000080` … `U-000007FF` | 110xxxxx 10xxxxxx |536| `U-00000800` … `U-0000FFFF` | 1110xxxx 10xxxxxx 10xxxxxx |537| `U-00010000` … `U-0010FFFF` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |538539Младший значащий бит символа Unicode – это самый правый бит x.540541Поскольку UTF-8 является 8-битной кодировкой, BOM не требуется, и любой символ `U+FEFF` в декодированной строке (даже если это первый символ) рассматривается как `ZERO WIDTH NO-BREAK SPACE`.542543Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Любая charmap-кодировка может декодировать любую случайную последовательность байтов. Однако с UTF-8 это невозможно, поскольку последовательности байтов UTF-8 имеют структуру, не допускающую произвольных последовательностей байтов. Чтобы повысить надёжность обнаружения кодировки UTF-8, Microsoft изобрела вариант UTF-8 (который Python называет `"utf-8-sig"`) для своей программы «Блокнот»: перед тем, как любой символ Unicode записывается в файл, записывается BOM в кодировке UTF-8 (который выглядит как последовательность байтов: `0xef`, `0xbb`, `0xbf`). Поскольку маловероятно, что какой-либо файл в charmap-кодировке начинается с этих значений байтов (которые, например, отображаются на544545> ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЭРЕЗИСОМ546>547> ПРАВАЯ ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА548>549> ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК550551в iso-8859-1), это повышает вероятность того, что кодировка `utf-8-sig` будет правильно угадана по последовательности байтов. Таким образом, здесь BOM используется не для определения порядка байтов, использованного при генерации последовательности байтов, а как сигнатура, помогающая угадать кодировку. При кодировании кодек utf-8-sig запишет `0xef`, `0xbb`, `0xbf` в качестве первых трёх байтов в файл. При декодировании `utf-8-sig` пропустит эти три байта, если они окажутся первыми тремя байтами в файле. В UTF-8 использование BOM не рекомендуется и его обычно следует избегать.552553## Стандартные кодировки554555Python поставляется с рядом встроенных кодеков, реализованных либо как функции на C, либо с помощью словарей в качестве таблиц отображения. В следующей таблице перечислены кодеки по имени, вместе с несколькими распространёнными псевдонимами, и языками, для которых, вероятно, используется кодировка. Ни список псевдонимов, ни список языков не является исчерпывающим. Обратите внимание, что альтернативные написания, различающиеся только регистром или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами, поскольку они эквивалентны после нормализации с помощью [`normalize_encoding()`](https://python-all.ru/3.13/library/codecs.html#encodings.normalize_encoding). Например, `'utf-8'` является допустимым псевдонимом для кодека `'utf_8'`.556557> **Примечание**558>559> В таблице ниже перечислены наиболее распространённые псевдонимы; полный список можно найти в исходном файле [aliases.py](https://python-all.ru/src/3.13/Lib/encodings/aliases.py).560561**Особенность реализации CPython:** Некоторые распространённые кодировки могут обходить механизм поиска кодеков для повышения производительности. Эти возможности оптимизации распознаются CPython только для ограниченного набора псевдонимов (без учёта регистра): utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (только Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32, а также те же с использованием подчёркивания вместо дефисов. Использование альтернативных псевдонимов для этих кодировок может привести к более медленному выполнению.562563Изменено в версии 3.6: Возможность оптимизации распознаётся для us-ascii.564565Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли знак евро), и распределением символов по кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:566567- набор символов ISO 8859568- кодовая страница Microsoft Windows, которая обычно происходит из набора 8859, но заменяет управляющие символы дополнительными графическими символами569- кодовая страница IBM EBCDIC570- кодовая страница IBM PC, совместимая с ASCII571572| Кодек | Псевдонимы | Языки |573| --- | --- | --- |574| ascii | 646, us-ascii | Английский |575| big5 | big5-tw, csbig5 | Китайский традиционный |576| big5hkscs | big5-hkscs, hkscs | Китайский традиционный |577| cp037 | IBM037, IBM039 | Английский |578| cp273 | 273, IBM273, csIBM273 | Немецкий Добавлено в версии 3.4. |579| cp424 | EBCDIC-CP-HE, IBM424 | Иврит |580| cp437 | 437, IBM437 | Английский |581| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500 | Западная Европа |582| cp720 |  | Арабский |583| cp737 |  | Греческий |584| cp775 | IBM775 | Балтийские языки |585| cp850 | 850, IBM850 | Западная Европа |586| cp852 | 852, IBM852 | Центральная и Восточная Европа |587| cp855 | 855, IBM855 | Белорусский, болгарский, македонский, русский, сербский |588| cp856 |  | Иврит |589| cp857 | 857, IBM857 | Турецкий |590| cp858 | 858, IBM00858 | Западная Европа |591| cp860 | 860, IBM860 | португальский |592| cp861 | 861, CP-IS, IBM861 | Исландский |593| cp862 | 862, IBM862 | Иврит |594| cp863 | 863, IBM863 | канадский |595| cp864 | IBM864 | Арабский |596| cp865 | 865, IBM865 | датский, норвежский |597| cp866 | 866, IBM866 | Русский |598| cp869 | 869, CP-GR, IBM869 | Греческий |599| cp874 |  | Тайский |600| cp875 |  | Греческий |601| cp932 | 932, ms932, mskanji, ms-kanji, windows-31j | Японский |602| cp949 | 949, ms949, uhc | Корейский |603| cp950 | 950, ms950 | Китайский традиционный |604| cp1006 |  | Урду |605| cp1026 | ibm1026 | Турецкий |606| cp1125 | 1125, ibm1125, cp866u, ruscii | Украинский Добавлено в версии 3.4. |607| cp1140 | IBM01140 | Западная Европа |608| cp1250 | windows-1250 | Центральная и Восточная Европа |609| cp1251 | windows-1251 | Белорусский, болгарский, македонский, русский, сербский |610| cp1252 | windows-1252 | Западная Европа |611| cp1253 | windows-1253 | Греческий |612| cp1254 | windows-1254 | Турецкий |613| cp1255 | windows-1255 | Иврит |614| cp1256 | windows-1256 | Арабский |615| cp1257 | windows-1257 | Балтийские языки |616| cp1258 | windows-1258 | вьетнамский |617| euc\_jp | eucjp, ujis, u-jis | Японский |618| euc\_jis\_2004 | jisx0213, eucjis2004 | Японский |619| euc\_jisx0213 | eucjisx0213 | Японский |620| euc\_kr | euckr, korean, ksc5601, ks\_c-5601, ks\_c-5601-1987, ksx1001, ks\_x-1001 | Корейский |621| gb2312 | chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58 | Упрощённый китайский |622| gbk | 936, cp936, ms936 | Унифицированный китайский |623| gb18030 | gb18030-2000 | Унифицированный китайский |624| hz | hzgb, hz-gb, hz-gb-2312 | Упрощённый китайский |625| iso2022\_jp | csiso2022jp, iso2022jp, iso-2022-jp | Японский |626| iso2022\_jp\_1 | iso2022jp-1, iso-2022-jp-1 | Японский |627| iso2022\_jp\_2 | iso2022jp-2, iso-2022-jp-2 | Японский, корейский, упрощённый китайский, западноевропейские языки, греческий |628| iso2022\_jp\_2004 | iso2022jp-2004, iso-2022-jp-2004 | Японский |629| iso2022\_jp\_3 | iso2022jp-3, iso-2022-jp-3 | Японский |630| iso2022\_jp\_ext | iso2022jp-ext, iso-2022-jp-ext | Японский |631| iso2022\_kr | csiso2022kr, iso2022kr, iso-2022-kr | Корейский |632| latin\_1 | iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1 | Западная Европа |633| iso8859\_2 | iso-8859-2, latin2, L2 | Центральная и Восточная Европа |634| iso8859\_3 | iso-8859-3, latin3, L3 | Эсперанто, мальтийский |635| iso8859\_4 | iso-8859-4, latin4, L4 | Северная Европа |636| iso8859\_5 | iso-8859-5, кириллица | Белорусский, болгарский, македонский, русский, сербский |637| iso8859\_6 | iso-8859-6, арабский | Арабский |638| iso8859\_7 | iso-8859-7, греческий, greek8 | Греческий |639| iso8859\_8 | iso-8859-8, иврит | Иврит |640| iso8859\_9 | iso-8859-9, latin5, L5 | Турецкий |641| iso8859\_10 | iso-8859-10, latin6, L6 | Скандинавские языки |642| iso8859\_11 | iso-8859-11, тайская | Тайские языки |643| iso8859\_13 | iso-8859-13, latin7, L7 | Балтийские языки |644| iso8859\_14 | iso-8859-14, latin8, L8 | Кельтские языки |645| iso8859\_15 | iso-8859-15, latin9, L9 | Западная Европа |646| iso8859\_16 | iso-8859-16, latin10, L10 | Юго-Восточная Европа |647| johab | cp1361, ms1361 | Корейский |648| koi8\_r |  | Русский |649| koi8\_t |  | Таджикский Добавлено в версии 3.5. |650| koi8\_u |  | Украинский |651| kz1048 | kz\_1048, strk1048\_2002, rk1048 | Казахский Добавлено в версии 3.5. |652| mac\_cyrillic | maccyrillic | Белорусский, болгарский, македонский, русский, сербский |653| mac\_greek | macgreek | Греческий |654| mac\_iceland | maciceland | Исландский |655| mac\_latin2 | maclatin2, maccentraleurope, mac\_centeuro | Центральная и Восточная Европа |656| mac\_roman | macroman, macintosh | Западная Европа |657| mac\_turkish | macturkish | Турецкий |658| ptcp154 | csptcp154, pt154, cp154, cyrillic-asian | Казахский |659| shift\_jis | csshiftjis, shiftjis, sjis, s\_jis | Японский |660| shift\_jis\_2004 | shiftjis2004, sjis\_2004, sjis2004 | Японский |661| shift\_jisx0213 | shiftjisx0213, sjisx0213, s\_jisx0213 | Японский |662| utf\_32 | U32, utf32 | все языки |663| utf\_32\_be | UTF-32BE | все языки |664| utf\_32\_le | UTF-32LE | все языки |665| utf\_16 | U16, utf16 | все языки |666| utf\_16\_be | UTF-16BE | все языки |667| utf\_16\_le | UTF-16LE | все языки |668| utf\_7 | U7, unicode-1-1-utf-7 | все языки |669| utf\_8 | U8, UTF, utf8, cp65001 | все языки |670| utf\_8\_sig |  | все языки |671672Изменено в версии 3.4: Кодировщики utf-16\* и utf-32\* больше не позволяют кодировать суррогатные кодовые точки (`U+D800`–`U+DFFF`). Декодировщики utf-32\* больше не декодируют последовательности байтов, соответствующие суррогатным кодовым точкам.673674Изменено в версии 3.8: `cp65001` теперь является псевдонимом `utf_8`.675676## Специфичные для Python кодировки677678Ряд предопределённых кодеков специфичны для Python, поэтому их имена не имеют смысла вне Python. Они перечислены в таблицах ниже на основе ожидаемых типов ввода и вывода (обратите внимание: хотя текстовые кодировки – наиболее распространённый случай использования кодеков, базовая инфраструктура кодеков поддерживает произвольные преобразования данных, а не только текстовые кодировки). Для асимметричных кодеков указанное назначение описывает направление кодирования.679680### Текстовые кодировки681682Следующие кодеки обеспечивают кодирование из [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) в [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) и декодирование из [байтоподобного объекта](https://python-all.ru/3.13/glossary.html#term-bytes-like-object) в `str`, аналогично текстовым кодировкам Unicode.683684| Кодек | Псевдонимы | Значение |685| --- | --- | --- |686| idna |  | Реализует [**RFC 3490**](https://python-all.ru/3.13/library/codecs.html), см. также [`encodings.idna`](https://python-all.ru/3.13/library/codecs.html#module-encodings.idna). Поддерживается только `errors='strict'`. |687| mbcs | ansi, dbcs | Только для Windows: кодирует операнд в соответствии с кодовой страницей ANSI (CP\_ACP). |688| oem |  | Только для Windows: кодирует операнд в соответствии с кодовой страницей OEM (CP\_OEMCP). Добавлено в версии 3.6. |689| palmos |  | Кодировка PalmOS 3.5. |690| punycode |  | Реализует [**RFC 3492**](https://python-all.ru/3.13/library/codecs.html). Кодеки с состоянием не поддерживаются. Предупреждение Алгоритмы декодирования и кодирования плохо масштабируются, поэтому длину входных данных из ненадёжных источников следует ограничивать. |691| raw\_unicode\_escape |  | Кодировка Latin-1 с `\uXXXX` и `\UXXXXXXXX` для остальных кодовых точек. Существующие обратные слеши никак не экранируются. Используется в протоколе pickle Python. |692| undefined |  | Этот кодек следует использовать только в целях тестирования. Вызывает исключение для всех преобразований, даже для пустых строк. Обработчик ошибок игнорируется. |693| unicode\_escape |  | Кодировка, подходящая для содержимого Unicode-литерала в исходном коде Python в кодировке ASCII, за исключением того, что кавычки не экранируются. Декодирование из исходного кода в Latin-1. Имейте в виду, что исходный код Python на самом деле по умолчанию использует UTF-8. |694695Изменено в версии 3.8: кодек «unicode\_internal» удалён.696697### Двоичные преобразования698699Следующие кодеки обеспечивают двоичные преобразования: [объект, подобный байтовой строке](https://python-all.ru/3.13/glossary.html#term-bytes-like-object) в [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes). Они не поддерживаются [`bytes.decode()`](https://python-all.ru/3.13/library/stdtypes.html#bytes.decode) (который создаёт только вывод [`str`](https://python-all.ru/3.13/library/stdtypes.html#str)).700701| Кодек | Псевдонимы | Значение | Кодировщик / декодировщик |702| --- | --- | --- | --- |703| base64\_codec [\[1\]](https://python-all.ru/3.13/library/codecs.html#b64) | base64, base\_64 | Преобразует операнд в многострочный MIME base64 (результат всегда включает завершающий `'\n'`). Изменено в версии 3.4: принимает любой [объект, подобный байтовой строке](https://python-all.ru/3.13/glossary.html#term-bytes-like-object) в качестве входных данных для кодирования и декодирования | [`base64.encodebytes()`](https://python-all.ru/3.13/library/base64.html#base64.encodebytes) / [`base64.decodebytes()`](https://python-all.ru/3.13/library/base64.html#base64.decodebytes) |704| bz2\_codec | bz2 | Сжимает операнд с помощью bz2. | [`bz2.compress()`](https://python-all.ru/3.13/library/bz2.html#bz2.compress) / [`bz2.decompress()`](https://python-all.ru/3.13/library/bz2.html#bz2.decompress) |705| hex\_codec | hex | Преобразует операнд в шестнадцатеричное представление, по два символа на байт. | [`binascii.b2a_hex()`](https://python-all.ru/3.13/library/binascii.html#binascii.b2a_hex) / [`binascii.a2b_hex()`](https://python-all.ru/3.13/library/binascii.html#binascii.a2b_hex) |706| quopri\_codec | quopri, quotedprintable, quoted\_printable | Преобразует операнд в MIME quoted printable. | [`quopri.encode()`](https://python-all.ru/3.13/library/quopri.html#quopri.encode) с `quotetabs=True` / [`quopri.decode()`](https://python-all.ru/3.13/library/quopri.html#quopri.decode) |707| uu\_codec | uu | Преобразует операнд с помощью uuencode. |  |708| zlib\_codec | zip, zlib | Сжимает операнд с помощью gzip. | [`zlib.compress()`](https://python-all.ru/3.13/library/zlib.html#zlib.compress) / [`zlib.decompress()`](https://python-all.ru/3.13/library/zlib.html#zlib.decompress) |709710\[[1](https://python-all.ru/3.13/library/codecs.html#id5)\]711712В дополнение к [байтоподобным объектам](https://python-all.ru/3.13/glossary.html#term-bytes-like-object), `'base64_codec'` также принимает экземпляры [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) только с ASCII для декодирования713714Добавлено в версии 3.2: Восстановление двоичных преобразований.715716Изменено в версии 3.4: Восстановление псевдонимов для двоичных преобразований.717718### Автономные функции кодеков719720Следующие функции предоставляют возможности кодирования и декодирования, аналогичные кодекам, но недоступны как именованные кодеки через [`codecs.encode()`](https://python-all.ru/3.13/library/codecs.html#codecs.encode) или [`codecs.decode()`](https://python-all.ru/3.13/library/codecs.html#codecs.decode). Они используются внутри (например, [`pickle`](https://python-all.ru/3.13/library/pickle.html#module-pickle)) и ведут себя аналогично кодеку `string_escape`, который был удалён в Python 3.721722#### `codecs.escape_encode(input, errors=None)`723724Кодирует *input* с использованием escape-последовательностей. Аналогично тому, как [`repr()`](https://python-all.ru/3.13/library/functions.html#repr) для bytes создаёт экранированные значения байтов.725726*input* должен быть объектом [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes).727728Возвращает кортеж `(output, length)`, где *output* – это объект [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes), а *length* – количество потреблённых байтов.729730#### `codecs.escape_decode(input, errors=None)`731732Декодирует *input* из escape-последовательностей обратно в исходные байты.733734*input* должен быть [байтоподобным объектом](https://python-all.ru/3.13/glossary.html#term-bytes-like-object).735736Возвращает кортеж `(output, length)`, где *output* – это объект [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes), а *length* – количество потреблённых байтов.737738### Текстовые преобразования739740Следующий кодек предоставляет текстовое преобразование: отображение [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) в `str`. Он не поддерживается [`str.encode()`](https://python-all.ru/3.13/library/stdtypes.html#str.encode) (который создаёт только вывод [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes)).741742| Кодек | Псевдонимы | Значение |743| --- | --- | --- |744| rot\_13 | rot13 | Возвращает шифр Цезаря для операнда. |745746Добавлено в версии 3.2: Восстановление текстового преобразования `rot_13`.747748Изменено в версии 3.4: Восстановление псевдонима `rot13`.749750## `encodings` – пакет encodings751752Этот модуль реализует следующие функции:753754#### `encodings.normalize_encoding(encoding)`755756Нормализовать имя кодировки *encoding*.757758Нормализация работает следующим образом: все небуквенно-цифровые символы, кроме точки, используемой в именах пакетов Python, схлопываются и заменяются одним символом подчёркивания; начальные и конечные подчёркивания удаляются. Например, `' -;#'` становится `'_'`.759760Обратите внимание, что *encoding* должен содержать только ASCII.761762> **Примечание**763>764> Следующую функцию не следует использовать напрямую, за исключением целей тестирования; вместо неё следует использовать [`codecs.lookup()`](https://python-all.ru/3.13/library/codecs.html#codecs.lookup).765766#### `encodings.search_function(encoding)`767768Ищет модуль кодека, соответствующий заданному имени кодировки *encoding*.769770Эта функция сначала нормализует *encoding* с помощью [`normalize_encoding()`](https://python-all.ru/3.13/library/codecs.html#encodings.normalize_encoding), затем ищет соответствующий псевдоним. Она пытается импортировать модуль кодека из пакета encodings, используя либо псевдоним, либо нормализованное имя. Если модуль найден и определяет допустимую функцию `getregentry()`, которая возвращает объект [`codecs.CodecInfo`](https://python-all.ru/3.13/library/codecs.html#codecs.CodecInfo), кодек кэшируется и возвращается.771772Если модуль кодека определяет функцию `getaliases()`, все возвращаемые псевдонимы регистрируются для дальнейшего использования.773774Этот модуль реализует следующее исключение:775776#### `exception encodings.CodecRegistryError`777778Возбуждается, когда кодек недействителен или несовместим.779780## `encodings.idna` – Интернационализированные доменные имена в приложениях781782Этот модуль реализует [**RFC 3490**](https://python-all.ru/3.13/library/codecs.html) (Internationalized Domain Names in Applications) и [**RFC 3492**](https://python-all.ru/3.13/library/codecs.html) (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке `punycode` и [`stringprep`](https://python-all.ru/3.13/library/stringprep.html#module-stringprep).783784Если вам нужен стандарт IDNA 2008 из [**RFC 5891**](https://python-all.ru/3.13/library/codecs.html) и [**RFC 5895**](https://python-all.ru/3.13/library/codecs.html), используйте сторонний модуль [idna](https://python-all.ru/3.13/library/codecs.html).785786Эти RFC совместно определяют протокол для поддержки не-ASCII символов в доменных именах. Доменное имя, содержащее не-ASCII символы (например, `www.Alliancefrançaise.nu`), преобразуется в ASCII-совместимую кодировку (ACE, такую как `www.xn--alliancefranaise-npb.nu`). Форма ACE доменного имени затем используется во всех местах, где протокол не допускает произвольных символов, таких как DNS-запросы, поля HTTP *Host* и так далее. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: приложение должно прозрачно преобразовывать метки доменов Unicode в IDNA при передаче по сети и преобразовывать обратно метки ACE в Unicode перед представлением их пользователю.787788Python поддерживает это преобразование несколькими способами: кодек `idna` выполняет преобразование между Unicode и ACE, разделяя входную строку на метки на основе символов-разделителей, определённых в [**раздел 3.1 RFC 3490**](https://python-all.ru/3.13/library/codecs.html), и преобразуя каждую метку в ACE по мере необходимости, и, наоборот, разделяя входную байтовую строку на метки на основе разделителя `.` и преобразуя любые найденные метки ACE в Unicode. Кроме того, модуль [`socket`](https://python-all.ru/3.13/library/socket.html#module-socket) прозрачно преобразует Unicode-имена хостов в ACE, так что приложениям не нужно беспокоиться о преобразовании имён хостов самостоятельно при передаче их в модуль socket. Вдобавок, модули, которые принимают имена хостов в качестве параметров функций, такие как [`http.client`](https://python-all.ru/3.13/library/http.client.html#module-http.client) и [`ftplib`](https://python-all.ru/3.13/library/ftplib.html#module-ftplib), принимают Unicode-имена хостов (`http.client` затем также прозрачно отправляет IDNA-имя хоста в поле *Host*, если вообще отправляет это поле).789790При получении имён хостов из сети (например, при обратном поиске имени) никакого автоматического преобразования в Unicode не выполняется: приложения, желающие представить такие имена хостов пользователю, должны декодировать их в Unicode.791792Модуль `encodings.idna` также реализует процедуру nameprep, которая выполняет определённые нормализации имён хостов для достижения нечувствительности к регистру интернационализированных доменных имён и унификации похожих символов. Функции nameprep можно использовать напрямую, если необходимо.793794#### `encodings.idna.nameprep(label)`795796Возвращает версию *label* после обработки nameprep. В текущей реализации предполагаются строки запроса, поэтому `AllowUnassigned` имеет значение истина.797798#### `encodings.idna.ToASCII(label)`799800Преобразует метку в ASCII, как указано в [**RFC 3490**](https://python-all.ru/3.13/library/codecs.html). Предполагается, что `UseSTD3ASCIIRules` имеет значение false.801802#### `encodings.idna.ToUnicode(label)`803804Преобразует метку в Unicode, как указано в [**RFC 3490**](https://python-all.ru/3.13/library/codecs.html).805806## `encodings.mbcs` – кодовая страница Windows ANSI807808Этот модуль реализует кодовую страницу ANSI (CP\_ACP).809810[Доступность](https://python-all.ru/3.13/library/intro.html#availability): Windows.811812Изменено в версии 3.2: До версии 3.2 аргумент *errors* игнорировался; `'replace'` всегда использовался для кодирования, а `'ignore'` для декодирования.813814Изменено в версии 3.3: Поддержка любого обработчика ошибок.815816## `encodings.utf_8_sig` – UTF-8 кодек с сигнатурой BOM817818Этот модуль реализует разновидность кодека UTF-8. При кодировании перед байтами, закодированными в UTF-8, добавляется BOM в кодировке UTF-8. Для кодера с состоянием это делается только один раз (при первой записи в байтовый поток). При декодировании необязательный BOM в кодировке UTF-8 в начале данных пропускается.819