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)

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

Примечание

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

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

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

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

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. Остальные представляют спецификацию в кодировках UTF-8 и UTF-32.

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

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

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

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

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

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

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

Значение Описание
'replace' Заменить подходящим маркером замены; Python будет использовать официальный U+FFFD ЗАМЕНЯЮЩИЙ СИМВОЛ для встроенных кодеков при декодировании и „?“ при кодировании. Реализовано в replace_errors().
'xmlcharrefreplace' Заменить соответствующий XML символ ссылкой (только для кодирования). Реализовано в xmlcharrefreplace_errors().
'backslashreplace' Заменить на escape-последовательности с обратной косой чертой. Реализовано в backslashreplace_errors().
'namereplace' Заменить \N{...} escape-последовательностью (только для кодирования). Реализовано в 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.

Для кодирования будет вызываться 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' (только для текстовых кодировок): искаженные данные заменяются escape-последовательностью с обратной косой чертой.

codecs.namereplace_errors(exception)

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

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

Кодирование и декодирование без сохранения состояния

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

Codec.encode(input[, errors])

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

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

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

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

Codec.decode(input[, errors])

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

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

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

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

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

Инкрементное кодирование и декодирование

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

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

Объекты 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().

Объекты IncrementalDecoder

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

class codecs.IncrementalDecoder(errors='strict')

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

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

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

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

decode(object[, final])

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

reset()

Сбросить декодер в исходное состояние.

getstate()

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

setstate(state)

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

Кодирование и декодирование потока

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

Объекты StreamWriter

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

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

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

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

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

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

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

write(object)

Записывает закодированное содержимое объекта в поток.

writelines(list)

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

reset()

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

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

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

Объекты 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, если он задан, передаётся как аргумент размера методу read() потока.

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

readlines([sizehint[, keepends]])

Прочитать все строки, доступные во входном потоке, и вернуть их в виде списка строк.

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

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

reset()

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

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

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

Объекты StreamReaderWriter

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

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

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')

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

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

Объекты StreamRecoder

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

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

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. Они наследуют все другие методы и атрибуты от базового потока.

Кодировки и Юникод

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

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

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

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

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

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

Наименьший значащий бит символа Юникода — это крайний правый бит x.

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

Без внешней информации невозможно достоверно определить, какая кодировка использовалась для кодирования строки. Каждая кодировка charmap может декодировать любую случайную последовательность байтов. Однако это невозможно с UTF-8, поскольку у байтовых последовательностей UTF-8 структура, которая не допускает произвольных байтовых последовательностей. Чтобы повысить надежность, с которой может быть обнаружена кодировка UTF-8, Microsoft изобрела вариант UTF-8 (который Python 2.5 называет "utf-8-sig") для своей программы Notepad: перед тем, как любой из символов Юникод будет записан в файл, UTF- записывается 8 закодированная BOM (которая выглядит как последовательность байтов: 0xef, 0xbb, 0xbf). Поскольку маловероятно, что какой-либо файл с кодировкой charmap начинается с этих байтовых значений (которые, например, сопоставляются с

LATIN SMALL LETTER I WITH DIAERESIS
RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
INVERTED QUESTION MARK

в iso-8859-1), это увеличивает вероятность того, что кодировка utf-8-sig может быть правильно угадана из последовательности байтов. Таким образом, здесь спецификация используется не для определения порядка байтов, используемого для генерации последовательности байтов, а в качестве сигнатуры, которая помогает угадать кодировку. При кодировании кодек utf-8-sig запишет 0xef, 0xbb, 0xbf в качестве первых трех байтов в файл. При декодировании utf-8-sig пропустит эти три байта, если они появятся как первые три байта в файле. В UTF-8 использование спецификации не рекомендуется, и её обычно следует избегать.

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

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.

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

  • множество кодов 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 Вьетнамский
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, cp65001 все языки
utf_8_sig   все языки

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

Изменено в версии 3.8: cp65001 теперь является псевдонимом utf_8.

Специальные кодировки Python

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

Текстовые кодировки

Следующие кодеки обеспечивают кодирование str в bytes и декодирование байтоподобного объекта в str, аналогично текстовым Юникод кодировкам.

Кодек Алиасы Значение
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   Кодировка подходит в качестве содержимого Юникод литерала в кодированном ASCII исходном коде Python, за исключением того, что кавычки не экранируются. Декодирование исходного кода с Latin-1. Будьте осторожны, т. к. исходный код Python фактически использует UTF-8 по умолчанию.

Изменено в версии 3.8: Кодек unicode_internal удалён.

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

Следующие кодировки обеспечивают двоичное преобразование: сопоставления байтоподобный объект в 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 для печати. 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' также принимает экземпляры str только в формате ASCII для расшифровки.

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

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

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

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

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

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

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

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 и т. д. Это преобразование выполняется в приложении; если возможно, невидимый для пользователя: приложение должно прозрачно преобразовывать метки домена Юникод в IDNA на проводе и конвертировать обратно метки ACE в Юникод перед их представлением пользователю.

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

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

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

encodings.idna.nameprep(label)

Возвращает nameprepped версию label. Реализация в настоящее время предполагает строки запроса, поэтому AllowUnassigned истинен.

encodings.idna.ToASCII(label)

Преобразовать метку в ASCII, как указано в RFC 3490. UseSTD3ASCIIRules считается ложным.

encodings.idna.ToUnicode(label)

Преобразовать метку в Юникод, как указано в RFC 3490.

encodings.mbcs — Кодовая страница Windows ANSI

Этот модуль реализует кодовую страницу ANSI (CP_ACP).

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

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

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

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

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