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

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

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

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

Есть ещё одна группа кодировок (так называемый набором символов кодировок), которые выбрают другой подмножество всех Юникод кодовых точек и как эти кодовые точки преобразуются в байты 0x0– 0xff. Чтобы увидеть, как это делается просто открыть, например, 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-00000000 … U-0000007F	0xxxxxxx
U-00000080 … U-000007FF	110xxxxx 10xxxxxx
U-00000800 … U-0000FFFF	1110xxxx 10xxxxxx 10xxxxxx
U-00010000 … U-0010FFFF	11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

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

Поскольку UTF-8 является 8-битной кодировкой, никакая спецификация не требуется и любой символ 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+D800–U+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 (результат всегда включает в себя завершающий символ '\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' также принимает только 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 в начале данных будет пропущена.