codecs — Реестр кодеков и базовые классы

Исходный код: Lib/codecs.py

Этот модуль определяет базовые классы для стандартных Python кодеков (кодировщиков и декодировщиков) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодеков и обработки ошибок. Большинство стандартных кодеков являются кодировками текста, которые кодируют текст в байты, но также есть кодеки, кодирующие текст в текст и байты в байты. Пользовательские кодеки могут кодировать и декодировать между произвольными типами, но некоторые функции модуля ограничены использованием именно с кодировками текста, или с кодеками, которые кодируют в bytes.

Модуль определяет следующие функции для кодирования и декодирования с любым кодеком:

codecs.encode(obj, encoding='utf-8', errors='strict')

Кодирует obj с помощью кодека, зарегистрированного для encoding.

Errors можно указать, чтобы установить желаемый механизм обработки ошибок. По умолчанию используется обработчик ошибок 'strict' , что означает, что ошибки кодирования вызывают ValueError (или подкласс, специфичный для кодека, например, UnicodeEncodeError). Дополнительную информацию об обработке ошибок кодеков см. в разделе Базовые классы кодеков.

codecs.decode(obj, encoding='utf-8', errors='strict')

Декодирует obj с помощью кодека, зарегистрированного для encoding.

Errors можно указать, чтобы установить желаемый механизм обработки ошибок. По умолчанию используется обработчик ошибок 'strict' , что означает, что ошибки декодирования вызывают ValueError (или подкласс, специфичный для кодека, например, UnicodeDecodeError). Дополнительную информацию об обработке ошибок кодеков см. в разделе Базовые классы кодеков.

Полные сведения о каждом кодеке также можно получить напрямую:

codecs.lookup(encoding)

Ищет информацию о кодеке в реестре кодеков Python и возвращает объект CodecInfo, как определено ниже.

Кодировки сначала ищутся в кэше реестра. Если не найдены, сканируется список зарегистрированных функций поиска. Если объект CodecInfo не найден, генерируется LookupError. В противном случае объект CodecInfo сохраняется в кэше и возвращается вызывающей стороне.

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

Детали кодека при поиске в реестре кодеков. Аргументы конструктора хранятся в атрибутах с тем же именем:

name: Имя кодировки.

encode
decode: Функции без состояния для кодирования и декодирования. Они должны быть функциями или методами с таким же интерфейсом, как методы encode() и decode() экземпляров Codec (см. Интерфейс кодека). Ожидается, что функции или методы будут работать в бессостоятельном режиме.

incrementalencoder
incrementaldecoder: Классы или фабричные функции для инкрементального кодировщика и декодировщика. Они должны предоставить интерфейс, определенный базовыми классами IncrementalEncoder и IncrementalDecoder соответственно. Инкрементальные кодеки могут сохранять состояние.

streamwriter
streamreader: Классы или фабричные функции для потокового записи и чтения. Они должны предоставить интерфейс, определенный базовыми классами StreamWriter и StreamReader соответственно. Потоковые кодеки могут сохранять состояние.

Для упрощения доступа к различным компонентам кодеков модуль предоставляет эти дополнительные функции, использующие lookup() для поиска кодека:

codecs.getencoder(encoding)

Ищет кодек для заданной кодировки и возвращает его функцию кодирования.

В случае, если кодировка не найдена, генерируется LookupError.

codecs.getdecoder(encoding)

Ищет кодек для заданной кодировки и возвращает его функцию декодирования.

В случае, если кодировка не найдена, генерируется LookupError.

codecs.getincrementalencoder(encoding)

Ищет кодек для заданной кодировки и возвращает его класс или фабричную функцию инкрементального кодировщика.

В случае, если кодировка не найдена или кодек не поддерживает инкрементального кодировщика, генерируется LookupError.

codecs.getincrementaldecoder(encoding)

Ищет кодек для заданной кодировки и возвращает его класс или фабричную функцию инкрементального декодировщика.

В случае, если кодировка не найдена или кодек не поддерживает инкрементального декодировщика, генерируется LookupError.

codecs.getreader(encoding)

Ищет кодек для заданной кодировки и возвращает его класс StreamReader или фабричную функцию.

В случае, если кодировка не найдена, генерируется LookupError.

codecs.getwriter(encoding)

Ищет кодек для заданной кодировки и возвращает его класс StreamWriter или фабричную функцию.

В случае, если кодировка не найдена, генерируется LookupError.

Пользовательские кодеки предоставляются путем регистрации подходящей функции поиска кодеков:

codecs.register(search_function): Регистрирует функцию поиска кодеков. Ожидается, что функции поиска примут один аргумент — имя кодировки в нижнем регистре, и вернут объект CodecInfo. В случае, если функция поиска не может найти заданную кодировку, она должна вернуть None.

Примечание

Регистрация функций поиска в настоящее время необратима, что может вызвать проблемы в некоторых случаях, таких как тестирование или перезагрузка модулей.

В то время как встроенная функция open() и связанный с ней модуль io рекомендуются для работы с закодированными текстовыми файлами, этот модуль предоставляет дополнительные служебные функции и классы, которые позволяют использовать более широкий спектр кодеков при работе с двоичными файлами:

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=1)

Открывает закодированный файл с заданным режимом и возвращает экземпляр StreamReaderWriter, обеспечивая прозрачное кодирование/декодирование. Режим файла по умолчанию — 'r', что означает открытие файла в режиме чтения.

Примечание

Внутренние закодированные файлы всегда открываются в двоичном режиме. Автоматического преобразования '\n' при чтении и записи не выполняется. Аргумент mode может быть любым двоичным режимом, допустимым для встроенной функции open(); 'b' добавляется автоматически.

encoding указывает кодировку, которая должна использоваться для файла. Допускается любая кодировка, кодирующая и декодирующая байты, и типы данных, поддерживаемые методами файла, зависят от используемого кодека.

errors может быть указано для определения обработки ошибок. По умолчанию используется 'strict' , что приводит к ValueError в случае возникновения ошибки кодирования.

buffering имеет такое же значение, как и для встроенной функции open(). По умолчанию буферизация по строкам.

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')

Возвращает экземпляр StreamRecoder, обернутую версию file, которая обеспечивает прозрачное преобразование кодировок. Исходный файл закрывается при закрытии обернутой версии.

Данные, записанные в обернутый файл, декодируются в соответствии с заданной data_encoding и затем записываются в исходный файл в виде байтов с использованием file_encoding. Байты, считанные из исходного файла, декодируются в соответствии с file_encoding, а результат кодируется с использованием data_encoding.

Если file_encoding не указан, он по умолчанию равен data_encoding.

errors может быть указан для определения обработки ошибок. По умолчанию это 'strict', что вызывает ValueError в случае возникновения ошибки кодирования.

codecs.iterencode(iterator, encoding, errors='strict', **kwargs)

Использует инкрементный кодировщик для итерационного кодирования ввода, предоставляемого iterator. Эта функция является генератором. Аргумент errors (а также любые другие ключевые аргументы) передаются инкрементному кодировщику.

Эта функция требует, чтобы кодек принимал объекты текста str для кодирования. Поэтому она не поддерживает кодировщики байт-в-байты, такие как base64_codec.

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)

Использует инкрементный декодер для итерационного декодирования ввода, предоставляемого iterator. Эта функция является генератором. Аргумент errors (а также любые другие ключевые аргументы) передаются инкременному декодеру.

Эта функция требует, чтобы кодек принимал объекты bytes для декодирования. Поэтому она не поддерживает кодировщики текст-в-текст, такие как rot_13, хотя rot_13 может быть использован аналогично с iterencode().

Модуль также предоставляет следующие константы, которые полезны для чтения и записи в платформенно-зависимые файлы:

codecs.BOM
codecs.BOM_BE
codecs.BOM_LE
codecs.BOM_UTF8
codecs.BOM_UTF16
codecs.BOM_UTF16_BE
codecs.BOM_UTF16_LE
codecs.BOM_UTF32
codecs.BOM_UTF32_BE
codecs.BOM_UTF32_LE: Эти константы определяют различные последовательности байтов, являющиеся метками порядка байтов Юникода (BOM) для нескольких кодировок. Они используются в потоках данных UTF-16 и UTF-32 для указания порядка байтов, используемого, и в UTF-8 в качестве подписи Юникода. BOM_UTF16 это либо BOM_UTF16_BE, либо BOM_UTF16_LE в зависимости от родного порядка байтов платформы, BOM является псевдонимом для BOM_UTF16, BOM_LE для BOM_UTF16_LE и BOM_BE для BOM_UTF16_BE. Остальные представляют BOM в кодировках UTF-8 и UTF-32.

7.2.1. Базовые классы кодеков

Модуль codecs определяет набор базовых классов, которые определяют интерфейсы для работы с объектами кодеков, а также могут быть использованы в качестве основы для реализации пользовательских кодеков.

Каждый кодек должен определить четыре интерфейса, чтобы сделать его пригодным в качестве кодека в Python: бессостояние кодировщик, бессостояние декодер, поток-читатель и поток-писатель. Поток-читатель и писатели обычно повторно используют бессостояние кодировщик/декодер для реализации файловых протоколов. Авторы кодеков также должны определить, как кодек будет обрабатывать ошибки кодирования и декодирования.

7.2.1.1. Обработчики ошибок

Для упрощения и стандартизации обработки ошибок кодеки могут реализовать различные схемы обработки ошибок, принимая строковый аргумент errors. Следующие строковые значения определены и реализованы всеми стандартными кодеками Python:

Значение	Значение
`'strict'`	Выбросить `UnicodeError` (или подкласс); это значение по умолчанию. Реализовано в `strict_errors()`.
`'ignore'`	Проигнорировать повреждённые данные и продолжить без дальнейших уведомлений. Реализовано в `ignore_errors()`.

Следующие обработчики ошибок применимы только к кодировкам текста:

Значение	Значение
`'replace'`	Заменить подходящим маркером замены; Python будет использовать официальный `U+FFFD` СИМВОЛ ЗАМЕНЫ для встроенных кодеков при декодировании и ‘?’ при кодировании. Реализовано в `replace_errors()`.
`'xmlcharrefreplace'`	Заменить соответствующей ссылкой на символ XML (только для кодирования). Реализовано в `xmlcharrefreplace_errors()`.
`'backslashreplace'`	Заменить последовательностями экранирования с обратной косой чертой. Реализовано в `backslashreplace_errors()`.
`'namereplace'`	Заменить последовательностями экранирования `\N{...}` (только для кодирования). Реализовано в `namereplace_errors()`.
`'surrogateescape'`	При декодировании заменить байт отдельным суррогатным кодом, изменяющимся от `U+DC80` до `U+DCFF`. Этот код затем будет преобразован обратно в тот же байт, когда обработчик `'surrogateescape'` ошибок используется при кодировании данных. (См. PEP 383 для более подробной информации.)

Кроме того, следующий обработчик ошибок специфичен для данного кодеков:

Значение	Кодеки	Значение
`'surrogatepass'`	utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le	Разрешить кодирование и декодирование суррогатных кодов. Эти кодеки обычно рассматривают присутствие суррогатов как ошибку.

Новое в версии 3.1: Обработчики ошибок 'surrogateescape' и 'surrogatepass'.

Изменено в версии 3.4: Обработчики ошибок 'surrogatepass' теперь работают с кодеками utf-16* и utf-32*.

Новое в версии 3.5: Обработчик ошибок 'namereplace'.

Изменено в версии 3.5: Обработчики ошибок 'backslashreplace' теперь работают с декодированием и переводом.

Набор допустимых значений может быть расширен путём регистрации нового обработчика ошибок с именем:

codecs.register_error(name, error_handler)

Зарегистрировать функцию обработки ошибок error_handler под именем name. Функция error_handler будет вызываться во время кодирования и декодирования в случае ошибки, когда name указан в качестве параметра errors.

При кодировании функция error_handler будет вызвана с экземпляром UnicodeEncodeError, содержащим информацию о местоположении ошибки. Обработчик ошибок должен либо выбросить это или другое исключение, либо вернуть кортеж с заменой для некодируемой части входных данных и позиции, с которой должно продолжиться кодирование. Замена может быть либо str, либо bytes. Если замена представляет собой байты, кодировщик просто скопирует их в буфер вывода. Если замена — строка, кодировщик закодирует замену. Кодирование продолжается на исходных входных данных с указанной позиции. Отрицательные значения позиции будут обрабатываться как относительные к концу входной строки. Если результирующая позиция выходит за пределы границ, будет выброшено исключение IndexError.

Декодирование и преобразование работают аналогично, за исключением того, что обработчику будет передан UnicodeDecodeError или UnicodeTranslateError, и что замена из обработчика ошибок будет помещена непосредственно в выходные данные.

Ранее зарегистрированные обработчики ошибок (включая стандартные) могут быть найдены по имени:

codecs.lookup_error(name)

Возвращает обработчик ошибок, ранее зарегистрированный под именем name.

Вызывает исключение LookupError в случае, если обработчик не найден.

Следующие стандартные обработчики ошибок также доступны в виде функций уровня модуля:

codecs.strict_errors(exception): Реализует обработку ошибок 'strict': каждая ошибка кодирования или декодирования вызывает исключение UnicodeError.

codecs.replace_errors(exception): Реализует обработку ошибок 'replace' (только для кодировок текста): заменяет '?' на ошибки кодирования (для кодирования кодеком) и '\ufffd' (символ замены Юникода) на ошибки декодирования.

codecs.ignore_errors(exception): Реализует обработку ошибок 'ignore': некорректные данные игнорируются, и кодирование или декодирование продолжается без дальнейших уведомлений.

codecs.xmlcharrefreplace_errors(exception): Реализует обработку ошибок 'xmlcharrefreplace' (только для кодирования с помощью кодировок текста): некодируемый символ заменяется соответствующей ссылкой на символ XML.

codecs.backslashreplace_errors(exception): Реализует обработку ошибок 'backslashreplace' (только для кодировок текста): некорректные данные заменяются экранированной последовательностью обратной косой черты.

codecs.namereplace_errors(exception): Реализует обработку ошибок 'namereplace' (только для кодирования с помощью кодировок текста): некодируемый символ заменяется экранированной последовательностью \N{...}.

Добавлена в версии 3.5.

7.2.1.2. Бессостоятельные кодирование и декодирование

Базовый класс Codec определяет эти методы, которые также определяют функциональные интерфейсы бессостоятельного кодировщика и декодировщика:

Codec.encode(input[, errors])

Кодирует объект input и возвращает кортеж (объект вывода, количество потреблённых символов). Например, кодирование текста преобразует строковый объект в байтовый объект, используя кодировку набора символов (например, cp1252 или iso-8859-1).

Аргумент errors определяет применяемую обработку ошибок. По умолчанию используется обработка 'strict'.

Метод не должен хранить состояние в экземпляре Codec. Используйте StreamWriter для кодеков, которым необходимо сохранять состояние, чтобы сделать кодирование эффективным.

Кодировщик должен уметь обрабатывать входные данные нулевой длины и возвращать пустой объект типа объекта вывода в этой ситуации.

Codec.decode(input[, errors])

Декодирует объект input и возвращает кортеж (объект вывода, количество потреблённых символов). Например, для кодировки текста декодирование преобразует байтовый объект, закодированный с помощью определённой кодировки набора символов, в строковый объект.

Для кодировок текста и кодеков байты-в-байты input должен быть байтовым объектом или объектом, предоставляющим интерфейс чтения буфера только для чтения — например, объекты буфера и файлы с отображением памяти.

Аргумент errors определяет применяемую обработку ошибок. По умолчанию используется обработка 'strict'.

Метод не должен хранить состояние в экземпляре Codec. Используйте StreamReader для кодеков, которым необходимо сохранять состояние, чтобы сделать декодирование эффективным.

Декодер должен уметь обрабатывать входные данные нулевой длины и возвращать пустой объект типа объекта вывода в этой ситуации.

7.2.1.3. Инкрементальное кодирование и декодирование

Классы IncrementalEncoder и IncrementalDecoder предоставляют базовый интерфейс для инкрементального кодирования и декодирования. Кодирование/декодирование входных данных не выполняется с помощью одного вызова функции бессостоятельного кодировщика/декодировщика, а с помощью нескольких вызовов метода encode()/decode() инкрементального кодировщика/декодировщика. Инкрементальный кодировщик/декодировщик отслеживает процесс кодирования/декодирования во время вызовов методов.

Объединённый вывод вызовов метода encode()/decode() такой же, как если бы все отдельные входные данные были объединены в один, и этот вход был закодирован/декодирован бессостоятельным кодировщиком/декодировщиком.

7.2.1.3.1. Объекты IncrementalEncoder

Класс IncrementalEncoder используется для кодирования входных данных в несколько этапов. Он определяет следующие методы, которые каждый инкрементальный кодировщик должен определить, чтобы быть совместимым с реестром кодеков Python.

class codecs.IncrementalEncoder(errors='strict')

Конструктор для экземпляра IncrementalEncoder.

Все инкрементные кодеры должны предоставить этот интерфейс конструктора. Они могут свободно добавлять дополнительные ключевые аргументы, но только те, которые определены здесь, используются реестром кодеков Python.

Объект IncrementalEncoder может реализовывать различные схемы обработки ошибок, предоставляя ключевой аргумент errors. Возможные значения см. в разделе Обработчики ошибок.

Аргумент errors будет присвоен атрибуту с таким же именем. Присвоение этому атрибуту позволяет переключаться между различными стратегиями обработки ошибок в течение жизненного цикла объекта IncrementalEncoder.

encode(object[, final]): Кодирует object (учитывая текущее состояние кодера) и возвращает результирующий закодированный объект. Если это последний вызов encode(), final должно быть истинным (по умолчанию ложно).

reset(): Сбросить кодер до начального состояния. Вывод отбрасывается: вызовите .encode(object, final=True), передав пустую байтовую или текстовую строку, если необходимо, чтобы сбросить кодер и получить вывод.

getstate(): Возвращает текущее состояние кодера, которое должно быть целым числом. Реализация должна гарантировать, что 0 является наиболее распространённым состоянием. (Состояния, которые сложнее целых чисел, можно преобразовать в целые числа, используя сериализацию/запись состояния и кодирование байтов получившейся строки в целое число).

setstate(state): Установить состояние кодера на state. state должен быть состоянием кодера, возвращённым методом getstate().

7.2.1.3.2. Объекты IncrementalDecoder

Класс IncrementalDecoder используется для декодирования входных данных по частям. Он определяет следующие методы, которые каждый инкрементный декодер должен определить, чтобы быть совместимым с реестром кодеков Python.

class codecs.IncrementalDecoder(errors='strict')

Конструктор для экземпляра IncrementalDecoder.

Все инкрементные декодеры должны предоставить этот интерфейс конструктора. Они могут свободно добавлять дополнительные ключевые аргументы, но только те, которые определены здесь, используются реестром кодеков Python.

Объект IncrementalDecoder может реализовывать различные схемы обработки ошибок, предоставляя ключевой аргумент errors. Возможные значения см. в разделе Обработчики ошибок.

decode(object[, final]): Декодирует object (учитывая текущее состояние декодера) и возвращает результирующий декодированный объект. Если это последний вызов decode(), final должно быть истинным (по умолчанию ложно). Если final истинно, декодер должен полностью декодировать входные данные и сбросить все буферы. Если это невозможно (например, из-за неполных байтовых последовательностей в конце входных данных), он должен инициировать обработку ошибок так же, как и в бессостоятельном случае (что может вызвать исключение).

reset(): Сбросить декодер до начального состояния.

getstate(): Возвращает текущее состояние декодера. Это должен быть кортеж из двух элементов: первый — буфер, содержащий ещё не декодированные входные данные, второй — целое число и может содержать дополнительную информацию о состоянии. (Реализация должна гарантировать, что 0 является наиболее распространенной дополнительной информацией о состоянии.) Если эта дополнительная информация о состоянии 0 , то должно быть возможно установить декодер в состояние, в котором нет буферизованных входных данных, и 0 в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованных входных данных декодеру вернула его в предыдущее состояние без вывода каких-либо результатов. (Дополнительная информация о состоянии, которая сложнее целых чисел, может быть преобразована в целое число путём сериализации/записи информации и кодирования байтов получившейся строки в целое число).

setstate(state): Установить состояние декодера на state. state должен быть состоянием декодера, возвращённым методом getstate().

7.2.1.4. Потоковая кодировка и декодировка

Классы StreamWriter и StreamReader обеспечивают универсальные рабочие интерфейсы, которые можно использовать для лёгкой реализации новых модулей кодирования. См. encodings.utf_8 для примера, как это сделать.

7.2.1.4.1. Объекты StreamWriter

Класс StreamWriter является подклассом Codec и определяет следующие методы, которые каждый потоковый писатель должен определить для совместимости с реестром кодеков Python.

class codecs.StreamWriter(stream, errors='strict')

Конструктор для экземпляра StreamWriter.

Все потоковые писатели должны предоставить этот интерфейс конструктора. Они могут свободно добавлять дополнительные ключевые аргументы, но только те, которые определены здесь, используются реестром кодеков Python.

Аргумент stream должен быть объектом, подобным файлу, открытым для записи текстовых или двоичных данных, соответствующих конкретному кодеку.

Объект StreamWriter может реализовывать различные схемы обработки ошибок, предоставляя ключевой аргумент errors. См. раздел Обработчики ошибок для стандартных обработчиков ошибок, которые может поддерживать кодек базового потока.

write(object): Записывает содержимое объекта, закодированное в поток.

writelines(list): Записывает конкатенированный список строк в поток (возможно, повторно используя метод write()). Стандартные кодеки байты-в-байты не поддерживают этот метод.

reset()

Сбрасывает и обнуляет буферы кодеков, используемые для сохранения состояния.

Вызов этого метода должен гарантировать, что данные на выходе находятся в чистом состоянии, что позволяет добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.

Помимо вышеперечисленных методов, StreamWriter также должен наследовать все другие методы и атрибуты от базового потока.

7.2.1.4.2. Объекты StreamReader

Класс StreamReader является подклассом Codec и определяет следующие методы, которые каждый потоковый читатель должен определить для совместимости с реестром кодеков Python.

class codecs.StreamReader(stream, errors='strict')

Конструктор для экземпляра StreamReader.

Все читатели потоков должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные ключевые аргументы, но только определённые здесь используются реестром кодеков Python.

Аргумент stream должен быть объектом, подобным файлу, открытым для чтения текстовых или двоичных данных, в зависимости от конкретного кодека.

Класс StreamReader может реализовать различные схемы обработки ошибок, предоставив ключевой аргумент errors. См. Обработчики ошибок для стандартных обработчиков ошибок, которые может поддерживать кодек базового потока.

Аргумент errors будет назначен атрибуту с тем же именем. Назначение этого атрибута позволяет переключаться между различными стратегиями обработки ошибок в течение срока действия объекта StreamReader.

Множество разрешённых значений для аргумента errors можно расширить с помощью register_error().

read([size[, chars[, firstline]]])

Декодирует данные из потока и возвращает результирующий объект.

Аргумент chars указывает количество декодированных кодовых точек или байтов для возврата. Метод read() никогда не вернёт больше данных, чем запрошено, но может вернуть меньше, если недостаточно доступных данных.

Аргумент size указывает приблизительное максимальное количество закодированных байтов или кодовых точек для чтения при декодировании. Декодер может изменить это значение по мере необходимости. Значение по умолчанию -1 означает чтение и декодирование максимального количества доступных данных. Этот параметр предназначен для предотвращения декодирования огромных файлов за один шаг.

Флаг firstline указывает, что достаточно вернуть только первую строку, если есть ошибки декодирования в последующих строках.

Метод должен использовать стратегию жадного чтения, то есть читать столько данных, сколько разрешено в соответствии с определением кодировки и заданным размером, например, если на потоке доступны необязательные окончания кодировки или маркеры состояния, они также должны быть прочитаны.

readline([size[, keepends]])

Читает одну строку из входного потока и возвращает декодированные данные.

size, если задан, передаётся как аргумент size методу read() потока.

Если keepends имеет значение false, окончания строк будут удалены из возвращённых строк.

readlines([sizehint[, keepends]])

Читает все доступные строки из входного потока и возвращает их в виде списка строк.

Окончания строк реализуются с помощью метода декодера кодека и включаются в записи списка, если keepends имеет значение true.

sizehint, если задан, передаётся как аргумент size методу read() потока.

reset()

Сбрасывает буферы кодека, используемые для сохранения состояния.

Обратите внимание, что никакого перемещения потока не должно происходить. Этот метод предназначен в первую очередь для возможности восстановления после ошибок декодирования.

Помимо вышеперечисленных методов, класс StreamReader также должен наследовать все остальные методы и атрибуты от базового потока.

7.2.1.4.3. Объекты StreamReaderWriter

Класс StreamReaderWriter — это удобный класс, который позволяет оборачивать потоки, работающие в режимах чтения и записи.

Конструкции такого рода позволяют использовать функции-фабрики, возвращаемые функцией lookup(), для создания экземпляра.

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict'): Создаёт экземпляр StreamReaderWriter. stream должен быть объектом, подобным файлу. Reader и Writer должны быть функциями-фабриками или классами, предоставляющими интерфейсы StreamReader и StreamWriter соответственно. Обработка ошибок выполняется так же, как определено для читателей и писателей потоков.

Экземпляры StreamReaderWriter определяют объединённые интерфейсы классов StreamReader и StreamWriter. Они наследуют все остальные методы и атрибуты от базового потока.

7.2.1.4.4. Объекты StreamRecoder

Класс StreamRecoder преобразует данные из одной кодировки в другую, что иногда полезно при работе с различными кодировочными средами.

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')

Создаёт экземпляр StreamRecoder, который реализует двустороннее преобразование: encode и decode работают с внешними данными — данными, видимыми кодом, вызывающим read() и write(), а Reader и Writer работают с внутренними данными — данными в stream.

Эти объекты можно использовать для прозрачных преобразований кодировок, например, из Latin-1 в UTF-8 и обратно.

Аргумент stream должен быть объектом, подобным файлу.

Аргументы encode и decode должны соответствовать интерфейсу Codec. Reader и Writer должны быть функциями-фабриками или классами, предоставляющими объекты интерфейса StreamReader и StreamWriter соответственно.

Обработка ошибок выполняется так же, как определено для читателей и писателей потоков.

Экземпляры StreamRecoder определяют объединённые интерфейсы классов StreamReader и StreamWriter. Они наследуют все остальные методы и атрибуты от базового потока.

7.2.2. Кодировки и Unicode

Строки хранятся в виде последовательностей кодовых точек в диапазоне 0x0–0x10FFFF. (См. PEP 393 для получения дополнительной информации об реализации.) После использования объекта строки вне процессора и памяти возникает проблема с порядком байтов и способом хранения этих массивов в виде байтов. Как и в случае с другими кодеками, сериализация строки в последовательность байтов называется кодированием, а восстановление строки из последовательности байтов — декодированием. Существует множество различных кодеков сериализации текста, которые коллективно называются кодировками текста.

Самая простая кодировка текста (называемая 'latin-1' или 'iso-8859-1' ) сопоставляет кодовые точки 0–255 с байтами 0x0–0xff, что означает, что объект строки, содержащий кодовые точки выше U+00FF, не может быть закодирован этим кодеком. В таком случае будет поднято исключение UnicodeEncodeError, которое будет выглядеть следующим образом (хотя детали сообщения об ошибке могут отличаться): UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256).

Существует ещё одна группа кодировок (так называемые кодировки charmap), которые выбирают другое подмножество всех кодовых точек Unicode и то, как эти кодовые точки отображаются на байты 0x0–0xff. Чтобы увидеть, как это делается, просто откройте, например, encodings/cp1252.py (кодировка, которая используется в основном в Windows). Существует строковая константа из 256 символов, которая показывает, какой символ отображается в каком байтовом значении.

Все эти кодировки могут кодировать только 256 из 1114112 кодовых точек, определённых в Unicode. Простой и прямой способ хранения каждой кодовой точки — хранить каждую кодовую точку как четыре последовательных байта. Существуют два варианта: хранить байты в порядке big endian или little endian. Эти две кодировки называются UTF-32-BE и UTF-32-LE соответственно. Их недостатком является то, что, например, если вы используете UTF-32-BE на машине с little endian, вам всегда придётся переставлять байты при кодировании и декодировании. UTF-32 избегает этой проблемы: байты всегда будут в естественном порядке эндианности. Однако, если эти байты будут считываться процессором с другой эндианностью, то байты придётся переставить. Для возможности определения эндианности последовательности байтов UTF-16 или UTF-32 существует так называемый BOM («Byte Order Mark»). Это символ Unicode U+FEFF. Этот символ может быть добавлен перед каждой последовательностью байтов UTF-16 или UTF-32. Переставленная версия этого символа (0xFFFE) является недопустимым символом, который не может появляться в тексте Unicode. Поэтому, когда первый символ в последовательности байтов UTF-16 или UTF-32 оказывается U+FFFE, байты должны быть переставлены при декодировании. К сожалению, символ U+FEFF имел второе назначение как ZERO WIDTH NO-BREAK SPACE: символ, у которого нет ширины и который не позволяет разделить слово. Он может, например, использоваться для предоставления подсказок алгоритму лигатур. В Unicode 4.0 использование U+FEFF в качестве ZERO WIDTH NO-BREAK SPACE было устаревшим (с U+2060 (WORD JOINER) взявшим на себя эту роль). Тем не менее, программное обеспечение Unicode должно по-прежнему уметь обрабатывать U+FEFF в обеих ролях: в качестве BOM это устройство для определения расположения данных байтов, и исчезает после того, как последовательность байтов была декодирована в строку; как ZERO WIDTH NO-BREAK SPACE это обычный символ, который будет декодирован как любой другой.

Существует ещё одна кодировка, способная кодировать весь диапазон символов Unicode: UTF-8. UTF-8 — это 8-битная кодировка, что означает, что проблем с порядком байтов в UTF-8 нет. Каждый байт в последовательности байтов UTF-8 состоит из двух частей: маркеров битов (самые значимые биты) и полезных битов. Маркеры битов — это последовательность от нуля до четырёх 1 битов, за которыми следует 0 бит. Символы Unicode кодируются так (x — это полезные биты, которые при объединении дают символ Unicode):

Диапазон	Кодировка
`U-00000000` … `U-0000007F`	0xxxxxxx
`U-00000080` … `U-000007FF`	110xxxxx 10xxxxxx
`U-00000800` … `U-0000FFFF`	1110xxxx 10xxxxxx 10xxxxxx
`U-00010000` … `U-0010FFFF`	11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

Самый младший бит символа Unicode — это правый крайний бит x.

Так как UTF-8 — 8-битная кодировка, BOM не требуется, и любой U+FEFF символ в декодированной строке (даже если это первый символ) обрабатывается как ZERO WIDTH NO-BREAK SPACE.

Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Каждая кодировка charmap может декодировать любую случайную последовательность байтов. Однако это невозможно с UTF-8, так как последовательности байтов UTF-8 имеют структуру, которая не допускает произвольных последовательностей байтов. Для повышения надёжности обнаружения кодировки UTF-8 Microsoft изобрели вариант UTF-8 (который Python 2.5 называет "utf-8-sig") для своей программы «Блокнот»: перед записью любого символа Unicode в файл записывается закодированный в UTF-8 BOM (который выглядит так как последовательность байтов: 0xef, 0xbb, 0xbf). Поскольку маловероятно, что любой файл, закодированный с помощью charmap, начинается с этих значений байтов (которые, например, отображаются в iso-8859-1), это увеличивает вероятность того, что кодировку utf-8-sig можно правильно угадать по последовательности байтов. Таким образом, здесь BOM используется не для определения порядка байтов, используемого для генерации последовательности байтов, а как подпись, которая помогает в угадывании кодировки. При кодировании кодек utf-8-sig запишет 0xef, 0xbb, 0xbf в качестве первых трёх байтов в файл. При декодировании utf-8-sig пропустит эти три байта, если они появляются как первые три байта в файле. В UTF-8 использование BOM не рекомендуется и следует избегать в целом.

7.2.3. Стандартные кодировки

Python поставляется с несколькими встроенными кодеками, реализованными либо как функции C, либо с таблицами соответствий в виде словарей. В следующей таблице перечислены кодеки по имени, вместе с несколькими общими псевдонимами и языками, для которых кодировка, вероятно, используется. Ни список псевдонимов, ни список языков не претендует на полноту. Обратите внимание, что альтернативные варианты написания, которые различаются только регистром или используют дефис вместо нижнего подчёркивания, также являются допустимыми псевдонимами; поэтому, например, 'utf-8' является допустимым псевдонимом для кодека 'utf_8'.

Примечание реализации CPython: Некоторые распространённые кодировки могут обойти механизм поиска кодеков для повышения производительности. Эти возможности оптимизации распознаются CPython только для ограниченного набора (регистронезависимых) псевдонимов: utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (только Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32, и то же самое с использованием нижних подчёркиваний вместо дефисов. Использование альтернативных псевдонимов для этих кодировок может привести к более медленной работе.

Изменено в версии 3.6: Возможность оптимизации распознаётся для us-ascii.

Многие наборы символов поддерживают одни и те же языки. Они различаются по отдельным символам (например, по тому, поддерживается ли символ EURO SIGN или нет) и по присвоению символов кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:

набор символов ISO 8859
страница кодировки Microsoft Windows, которая обычно выводится из набора символов 8859, но заменяет управляющие символы дополнительными графическими символами
страница кодировки IBM EBCDIC
страница кодировки IBM PC, которая совместима с ASCII

Кодек	Псевдонимы	Языки
ascii	646, us-ascii	Английский
big5	big5-tw, csbig5	Традиционный китайский
big5hkscs	big5-hkscs, hkscs	Традиционный китайский
cp037	IBM037, IBM039	Английский
cp273	273, IBM273, csIBM273	Немецкий Добавлен в версии 3.4.
cp424	EBCDIC-CP-HE, IBM424	Иврит
cp437	437, IBM437	Английский
cp500	EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500	Западная Европа
cp720		Арабский
cp737		Греческий
cp775	IBM775	Балтийские языки
cp850	850, IBM850	Западная Европа
cp852	852, IBM852	Центральная и Восточная Европа
cp855	855, IBM855	Болгарский, Белорусский, Македонский, Русский, Сербский
cp856		Иврит
cp857	857, IBM857	Турецкий
cp858	858, IBM858	Западная Европа
cp860	860, IBM860	Португальский
cp861	861, CP-IS, IBM861	Исландский
cp862	862, IBM862	Иврит
cp863	863, IBM863	Канадский
cp864	IBM864	Арабский
cp865	865, IBM865	Датский, Норвежский
cp866	866, IBM866	Русский
cp869	869, CP-GR, IBM869	Греческий
cp874		Тайский
cp875		Греческий
cp932	932, ms932, mskanji, ms-kanji	Японский
cp949	949, ms949, uhc	Корейский
cp950	950, ms950	Традиционный китайский
cp1006		Урду
cp1026	ibm1026	Турецкий
cp1125	1125, ibm1125, cp866u, ruscii	Украинский Добавлен в версии 3.4.
cp1140	ibm1140	Западная Европа
cp1250	windows-1250	Центральная и Восточная Европа
cp1251	windows-1251	Болгарский, Белорусский, Македонский, Русский, Сербский
cp1252	windows-1252	Западная Европа
cp1253	windows-1253	Греческий
cp1254	windows-1254	Турецкий
cp1255	windows-1255	Иврит
cp1256	windows-1256	Арабский
cp1257	windows-1257	Балтийские языки
cp1258	windows-1258	Вьетнамский
cp65001		Только Windows: Windows UTF-8 (`CP_UTF8`) Добавлен в версии 3.3.
euc_jp	eucjp, ujis, u-jis	Японский
euc_jis_2004	jisx0213, eucjis2004	Японский
euc_jisx0213	eucjisx0213	Японский
euc_kr	euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001	Корейский
gb2312	chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58	Упрощённый китайский
gbk	936, cp936, ms936	Объединённый китайский
gb18030	gb18030-2000	Объединённый китайский
hz	hzgb, hz-gb, hz-gb-2312	Упрощённый китайский
iso2022_jp	csiso2022jp, iso2022jp, iso-2022-jp	Японский
iso2022_jp_1	iso2022jp-1, iso-2022-jp-1	Японский
iso2022_jp_2	iso2022jp-2, iso-2022-jp-2	Японский, Корейский, Упрощённый китайский, Западная Европа, Греческий
iso2022_jp_2004	iso2022jp-2004, iso-2022-jp-2004	Японский
iso2022_jp_3	iso2022jp-3, iso-2022-jp-3	Японский
iso2022_jp_ext	iso2022jp-ext, iso-2022-jp-ext	Японский
iso2022_kr	csiso2022kr, iso2022kr, iso-2022-kr	Корейский
latin_1	iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1	Западная Европа
iso8859_2	iso-8859-2, latin2, L2	Центральная и Восточная Европа
iso8859_3	iso-8859-3, latin3, L3	Эсперанто, Мальтийский
iso8859_4	iso-8859-4, latin4, L4	Балтийские языки
iso8859_5	iso-8859-5, cyrillic	Болгарский, Белорусский, Македонский, Русский, Сербский
iso8859_6	iso-8859-6, arabic	Арабский
iso8859_7	iso-8859-7, greek, greek8	Греческий
iso8859_8	iso-8859-8, hebrew	Иврит
iso8859_9	iso-8859-9, latin5, L5	Турецкий
iso8859_10	iso-8859-10, latin6, L6	Скандинавские языки
iso8859_11	iso-8859-11, thai	Тайские языки
iso8859_13	iso-8859-13, latin7, L7	Балтийские языки
iso8859_14	iso-8859-14, latin8, L8	Келтские языки
iso8859_15	iso-8859-15, latin9, L9	Западная Европа
iso8859_16	iso-8859-16, latin10, L10	Юго-Восточная Европа
johab	cp1361, ms1361	Корейский
koi8_r		Русский
koi8_t		Таджикский Добавлен в версии 3.5.
koi8_u		Украинский
kz1048	kz_1048, strk1048_2002, rk1048	Казахский Добавлен в версии 3.5.
mac_cyrillic	maccyrillic	Болгарский, Белорусский, Македонский, Русский, Сербский
mac_greek	macgreek	Греческий
mac_iceland	maciceland	Исландский
mac_latin2	maclatin2, maccentraleurope	Центральная и Восточная Европа
mac_roman	macroman, macintosh	Западная Европа
mac_turkish	macturkish	Турецкий
ptcp154	csptcp154, pt154, cp154, cyrillic-asian	Казахский
shift_jis	csshiftjis, shiftjis, sjis, s_jis	Японский
shift_jis_2004	shiftjis2004, sjis_2004, sjis2004	Японский
shift_jisx0213	shiftjisx0213, sjisx0213, s_jisx0213	Японский
utf_32	U32, utf32	все языки
utf_32_be	UTF-32BE	все языки
utf_32_le	UTF-32LE	все языки
utf_16	U16, utf16	все языки
utf_16_be	UTF-16BE	все языки
utf_16_le	UTF-16LE	все языки
utf_7	U7, unicode-1-1-utf-7	все языки
utf_8	U8, UTF, utf8	все языки
utf_8_sig		все языки

Изменено в версии 3.4: Кодировщики utf-16* и utf-32* больше не допускают кодовые точки суррогатных символов (U+D800) – (U+DFFF). Декодеры utf-32* больше не декодируют последовательности байтов, которые соответствуют кодовым точкам суррогатных символов.

7.2.4. Кодировки, специфичные для Python

Ряд предопределённых кодировщиков специфичны для Python, поэтому их имена кодировщиков не имеют смысла вне Python. Эти кодировщики перечислены в таблицах ниже в зависимости от ожидаемых типов входных и выходных данных (обратите внимание, что, хотя кодировки текста являются наиболее распространённым случаем использования кодировщиков, базовая инфраструктура кодировщиков поддерживает произвольные преобразования данных, а не только кодировки текста).

7.2.4.1. Кодировки текста

Следующие кодировщики предоставляют кодирование от str к bytes и декодирование от байтовых-подобных объектов к str, подобно кодировкам Unicode текста.

END_OF_DOCUMENT_MARKER

Кодек	Псевдонимы	Назначение
idna		Реализует RFC 3490, см. также `encodings.idna`. Поддерживается только `errors='strict'`.
mbcs	ansi, dbcs	Только для Windows: Кодирует операнд в соответствии с кодовой страницей ANSI (CP_ACP)
oem		Только для Windows: Кодирует операнд в соответствии с кодовой страницей OEM (CP_OEMCP) Добавлена в версии 3.6.
palmos		Кодировка PalmOS 3.5
punycode		Реализует RFC 3492. Состоятельные кодеки не поддерживаются.
raw_unicode_escape		Кодировка Latin-1 с `\uXXXX` и `\UXXXXXXXX` для других кодовых точек. Существующие обратные слэши не экранируются. Используется в протоколе Python pickle.
undefined		Вызывает исключение для всех преобразований, даже для пустых строк. Обработчик ошибок игнорируется.
unicode_escape		Кодировка, подходящая в качестве содержимого Unicode-литерала в коде Python, закодированном в ASCII, за исключением того, что кавычки не экранируются. Декодируется из исходного кода Latin-1. Обратите внимание, что код Python по умолчанию использует UTF-8.
unicode_internal		Возвращает внутреннее представление операнда. Состоятельные кодеки не поддерживаются. Устарело начиная с версии 3.3: Это представление устарело из-за PEP 393.

7.2.4.2. Бинарные преобразования

Следующие кодеки обеспечивают бинарные преобразования: отображение байтового объекта на bytes. Они не поддерживаются bytes.decode() (который производит только выход str).

Кодек	Псевдонимы	Назначение	Кодировщик / декодер
base64_codec 1	base64, base_64	Преобразует операнд в многострочный MIME base64 (результат всегда включает заключительный `'\n'`) Изменено в версии 3.4: принимает любой байтовый объект в качестве входных данных для кодирования и декодирования	`base64.encodebytes()` / `base64.decodebytes()`
bz2_codec	bz2	Сжимает операнд с помощью bz2	`bz2.compress()` / `bz2.decompress()`
hex_codec	hex	Преобразует операнд в шестнадцатеричное представление с двумя цифрами на байт	`binascii.b2a_hex()` / `binascii.a2b_hex()`
quopri_codec	quopri, quotedprintable, quoted_printable	Преобразует операнд в MIME quoted printable	`quopri.encode()` с `quotetabs=True` / `quopri.decode()`
uu_codec	uu	Преобразует операнд с помощью uuencode	`uu.encode()` / `uu.decode()`
zlib_codec	zip, zlib	Сжимает операнд с помощью gzip	`zlib.compress()` / `zlib.decompress()`

1: В дополнение к байтовым объектам, 'base64_codec' также принимает ASCII-строки str для декодирования

Добавлена в версии 3.2: Восстановление бинарных преобразований.

Изменено в версии 3.4: Восстановление псевдонимов для бинарных преобразований.

7.2.4.3. Текстовые преобразования

Следующий кодек обеспечивает текстовое преобразование: отображение str на str. Он не поддерживается str.encode() (который производит только выход bytes).

Кодек	Псевдонимы	Назначение
rot_13	rot13	Возвращает шифрование Цезаря для операнда

Добавлена в версии 3.2: Восстановление текстового преобразования rot_13.

Изменено в версии 3.4: Восстановление псевдонима rot13.

7.2.5. encodings.idna — Международные доменные имена в приложениях

Этот модуль реализует RFC 3490 (Международные доменные имена в приложениях) и RFC 3492 (Nameprep: Профиль Stringprep для международных доменных имён (IDN)). Он строится на основе кодирования punycode и stringprep.

Эти RFC вместе определяют протокол для поддержки символов, отличных от ASCII, в доменных именах. Доменное имя, содержащее символы, отличные от ASCII (например, www.Alliancefrançaise.nu ), преобразуется в совместимую с ASCII кодировку (ACE, например, www.xn--alliancefranaise-npb.nu). Форма ACE доменного имени затем используется во всех местах, где произвольные символы не допускаются протоколом, таких как запросы DNS, поля HTTP Host и так далее. Это преобразование выполняется в приложении; по возможности незаметно для пользователя: Приложение должно прозрачно преобразовывать метки Unicode доменных имён в IDNA в сети и преобразовывать метки ACE обратно в Unicode перед представлением их пользователю.

Python поддерживает это преобразование несколькими способами: кодек idna выполняет преобразование между Unicode и ACE, разделяя входную строку на метки на основе разделителей, определённых в разделе 3.1 RFC 3490 и преобразуя каждую метку в ACE по мере необходимости, и наоборот, разделяя входную строку байтов на метки на основе . разделителя и преобразуя любые найденные метки ACE в Unicode. Кроме того, модуль socket прозрачно преобразует имена хостов Unicode в ACE, поэтому приложениям не нужно беспокоиться о преобразовании имён хостов самих по себе, когда они передают их модулю socket. Кроме того, модули, имеющие имена хостов в качестве параметров функций, такие как http.client и ftplib, принимают имена хостов Unicode (http.client затем также прозрачно отправляет имя хоста IDNA в поле Host, если оно отправляет это поле вообще).

При получении имён хостов из сети (например, при обратном поиске имён) автоматическое преобразование в Unicode не выполняется: приложения, желающие отобразить такие имена хостов пользователю, должны декодировать их в Unicode.

Модуль encodings.idna также реализует процедуру nameprep, которая выполняет определённые нормализации для имён хостов, чтобы достичь регистронезависимости международных доменных имён и объединить похожие символы. Функции nameprep можно использовать напрямую, если это необходимо.

encodings.idna.nameprep(label): Возвращает результат обработки метки label в соответствии с алгоритмом nameprep. Реализация в настоящее время предполагает, что это строка запроса, поэтому AllowUnassigned имеет значение true.

encodings.idna.ToASCII(label): Преобразует метку в ASCII-представление, как указано в RFC 3490. Предполагается, что UseSTD3ASCIIRules равно false.

encodings.idna.ToUnicode(label): Преобразует метку в Unicode-представление, как указано в RFC 3490.

7.2.6. encodings.mbcs — Кодировка Windows ANSI

Кодирует операнд в соответствии с кодовой страницей ANSI (CP_ACP).

Доступно только в Windows.

Изменено в версии 3.3: Поддержка любого обработчика ошибок.

Изменено в версии 3.2: До версии 3.2 аргумент errors игнорировался; для кодирования всегда использовался 'replace', а для декодирования — 'ignore'.

7.2.7. encodings.utf_8_sig — Кодировка UTF-8 с сигнатурой BOM

Этот модуль реализует вариант кодировки UTF-8: при кодировании перед байтами UTF-8 будет добавлена сигнатура BOM. Для состоятельного кодера это выполняется только один раз (при первом записи в поток байтов). При декодировании необязательная сигнатура BOM в начале данных будет пропущена.