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

incrementalencoder

incrementaldecoder

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

streamwriter

streamreader

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

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

codecs.getencoder(encoding)

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

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

codecs.getdecoder(encoding)

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

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

codecs.getincrementalencoder(encoding)

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

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

codecs.getincrementaldecoder(encoding)

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

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

codecs.getreader(encoding)

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

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

codecs.getwriter(encoding)

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

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

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

codecs.register(search_function)

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

Примечание

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

codecs.BOM

codecs.BOM_BE

codecs.BOM_LE

codecs.BOM_UTF8

codecs.BOM_UTF16

codecs.BOM_UTF16_BE

codecs.BOM_UTF16_LE

codecs.BOM_UTF32

codecs.BOM_UTF32_BE

codecs.BOM_UTF32_LE

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

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

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

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

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

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

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

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

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

codecs.register_error(name, error_handler)

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

При кодировании error_handler будет вызываться с экземпляром UnicodeEncodeError, который содержит информацию о местоположении ошибки. Обработчик ошибок должен либо вызвать эту, либо другую ошибку, либо вернуть кортеж с заменой для некодируемой части входных данных и позиции, где должно продолжить кодирование. Замена может быть либо str, либо bytes. Если замена является объектом типа 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 является наиболее распространенным состоянием. (Состояния, которые сложнее целых чисел, могут быть преобразованы в целое число путем сериализации/записи состояния и кодирования байтов результирующей строки в целое число.)

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

reset()

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

getstate()

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

setstate(state)

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

Потоковая кодировка и декодирование

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

Объекты StreamWriter

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

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

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

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

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

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

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

write(object)

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

writelines(list)

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

reset()

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

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

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

Объекты StreamReader

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

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

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

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

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

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

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

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

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

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

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

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

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

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

readline([size[, keepends]])

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

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

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

readlines([sizehint[, keepends]])

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

Символы конца строки реализуются с помощью метода кодировки decode() и включаются в элементы списка, если keepends равно true.

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

Обзор кодировок и 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 кодовых точек, определённых в Юникоде. Простой и прямой способ хранения каждой кодовой точки — хранение каждой кодовой точки в виде четырёх последовательных байтов. Есть два варианта: хранить байты в порядке следования старших к младшим (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»). Это символ Юникода 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 — это полезные биты, которые, когда они соединены, дают символ Юникода):

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

Поскольку UTF-8 — это 8-битовая кодировка, BOM не требуется, и любой символ 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). Поскольку маловероятно, что любой файл, закодированный с помощью кодировки символов, начинается с этих значений байтов (которые, например, будут отображаться в 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

Python-специфические кодировки

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

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

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

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

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

1

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

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

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

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

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

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

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

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

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

encodings.idna.nameprep(label)

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

encodings.idna.ToASCII(label)

Преобразует метку в ASCII в соответствии со спецификацией RFC 3490. UseSTD3ASCIIRules предполагается равным false.

encodings.idna.ToUnicode(label)

Преобразует метку в Unicode в соответствии со спецификацией RFC 3490.

encodings.mbcs — Кодировка символов Windows ANSI

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

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

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

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