`codecs.md`

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