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

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

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

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

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

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

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

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

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

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

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

codecs.lookup(encoding)

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

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

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

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

name

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

encode

decode

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

incrementalencoder

incrementaldecoder

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

streamwriter

streamreader

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

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

codecs.getencoder(encoding)

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

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

codecs.getdecoder(encoding)

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

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

codecs.getincrementalencoder(encoding)

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

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

codecs.getincrementaldecoder(encoding)

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

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

codecs.getreader(encoding)

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

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

codecs.getwriter(encoding)

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

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

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

codecs.register(search_function)

Регистрирует функцию поиска кодека. Функции поиска принимают один аргумент, имя кодировки в нижнем регистре, и возвращают объект CodecInfo. Если функция поиска не может найти заданную кодировку, она должна вернуть None.

Примечание

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

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

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

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

Примечание

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

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

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

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

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.

1. Классы-базы кодеков

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

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

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

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

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

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

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

codecs.register_error(name, error_handler)

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

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

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

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

codecs.lookup_error(name)

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

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

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

codecs.strict_errors(exception)

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

codecs.replace_errors(exception)

Реализует обработку ошибок 'replace' (только для кодировок текста): заменяет '?' на ошибки кодирования (для кодирования кодеком) и '\ufffd' (замещающий символ Unicode) на ошибки декодирования.

codecs.ignore_errors(exception)

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

codecs.xmlcharrefreplace_errors(exception)

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

codecs.backslashreplace_errors(exception)

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

codecs.namereplace_errors(exception)

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

Введено в версии 3.5.

1.2. Бессостояние кодирование и декодирование

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

Codec.encode(input[, errors])

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

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

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

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

Codec.decode(input[, errors])

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

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

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

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

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

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

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

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

1.3.1. Объекты IncrementalEncoder

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

class codecs.IncrementalEncoder(errors='strict')

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

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

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

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

encode(object[, final])

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

reset()

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

IncrementalEncoder.getstate()

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

IncrementalEncoder.setstate(state)

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

1.3.2. Объекты IncrementalDecoder

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

class codecs.IncrementalDecoder(errors='strict')

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

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

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

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

decode(object[, final])

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

reset()

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

getstate()

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

setstate(state)

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

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

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

1.4.1. Объекты StreamWriter

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

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

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

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

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

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

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

write(object)

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

writelines(list)

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

reset()

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

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

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

1.4.2. Объекты StreamReader

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

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

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

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

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

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

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

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

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

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

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

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

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

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

readline([size[, keepends]])

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

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

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

readlines([sizehint[, keepends]])

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

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

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

reset()

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

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

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

1.4.3. Объекты StreamReaderWriter

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

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

class codecs.StreamReaderWriter(stream, Reader, Writer, errors)

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

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

1.4.4. Объекты StreamRecoder

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

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

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

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

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

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

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

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

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

2. Обзор кодировок и Unicode

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

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

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

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

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

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

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

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

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

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

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

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

4. Специфичные для Python кодировки

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

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

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

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

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

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

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

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

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

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

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

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

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

encodings.idna.nameprep(label)

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

encodings.idna.ToASCII(label)

Преобразовать метку в ASCII, как указано в RFC 3490. UseSTD3ASCIIRules предполагается false.

encodings.idna.ToUnicode(label)

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

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

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

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

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

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