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 (или UnicodeEncodeError, в зависимости от подкласса конкретной кодировки). Обратитесь к Базовые классы кодировки за дополнительными сведениями об обработке ошибок кодировкой.

Исчерпывающую информацию для каждого кодировки также можно посмотреть напрямую:

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() сущности кодировки (см. Интерфейс кодировки). Ожидается, что функции или методы будут работать в режиме без сохранения состояния.
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)

Поиск кодировки для данного кодера, с возвращением класса its 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. Остальные представляют BOM в 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{...} эскейп последовательностью (только для кодирования). Реализовано в 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' (для кодирования только текстовыми кодировками): неопознанные данные заменяется управляющими последовательностями.

codecs.namereplace_errors(exception)

Реализует обработку ошибок 'namereplace' (для кодирования только текстовыми кодировками): некодируемый символ заменяется \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, то должно быть True (значение по умолчанию - False).

reset()

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

getstate()

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

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, то должно быть True (значение по умолчанию - False). Если final истина, декодер должен полностью декодировать вход и должн очистить все буферы. Если это невозможно (например, из-за неполной последовательности байтов в конце ввода) он должен инициировать обработку ошибок, как и в случае без сохранения состояния (который может вызвать исключение).

reset()

Сбросить декодер к первоначальному состоянию.

getstate()

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

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 для получения более подробной информации о реализации.) Как только объект строки используется вне процессора и памяти, порядок байт и как эти массивы хранятся в виде байтов становятся проблемой. Как и с другими кодировками, сериализация строки в последовательность байтов, называется encoding, и восстановление строки из последовательности байтов, называется decoding. Существует множество различных текстовых сериализаций кодировок, которые коллективно называют текстовые кодировки.

Самый простой текстовые кодировки (так называемые '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).

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

Все эти кодировки могут кодировать только 256 из 1114112 кодовых точек определено в Юникоде. Простой и понятный способ, который может хранить каждую Юникод кодовую точку, является хранение каждую кодовую точку в виде четырёх последовательных байтов. Есть два варианта: хранить байтов с big endian порядком байтов или в little endian порядке. Эти две кодировки называются UTF-32-BE и UTF-32-LE соответственно. Их недостатком является то, что если, например, вы используете UTF-32-BE на little endian машине, вам всегда придётся менять местами байты при кодировании и декодировании. UTF-32 позволяет избежать этой проблемы: байт всегда будет в естественный порядок следования байтов. Когда эти байты считываются CPU с различным порядком байтов, то байты должны быть заменены. Для обнаружения порядка следования байтов в 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 в обеих ролях: в качестве BOM это устройство для определения расположения хранения закодированных байтов и исчезает после того как последовательность байтов была декодирована в строку; как 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

Наименее значимым битом символа Unicode является самый правый бит X.

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

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

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

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

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

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

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

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

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

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

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

Кодировка Алиасы Значение Кодер / Декодер
base64_codec [1] base64, base_64

Преобразовать операнд в многострочный MIME base64 (результат всегда включает в себя завершающий символ .

Изменено в версии 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' также принимает только ASCII символы сущности str для декодирования.

Добавлено в версии 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, разделяющей входной строку на метки, основанные на разделителях символов, определенных в документе RFC: раздел 3.1 спецификации раздел 3.1 в RFC 3490 и преобразование каждой метки до ACE по мере необходимости, и наоборот, разделяющей входную байтовую строку на метки, основанные на . сепаратор и преобразования любой ACE метки, найденной в Юникод. Кроме того, модуль socket прозрачно преобразует имена узлов Юникод в ACE, так что приложения не нужно заботиться о конвертировании самими имён хостов, когда они передаются в модуль soket. Кроме того, модули содержащие имена хостов, в качестве параметров функции, такие как http.client и ftplib, принимают Юникод имена узлов (http.client затем также незаметно отправляет имя idna в поле Host если оно вообще отправляется).

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

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

encodings.idna.nameprep(label)

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

encodings.idna.ToASCII(label)

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

encodings.idna.ToUnicode(label)

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

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

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

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

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

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

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