7.2. codecs – Реестр кодеков и базовые классы¶codecs – Codec registry and base classes

7.2.1.1. Объекты Codec¶Codec Objects

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

Codec.encode(input[, errors])¶

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

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

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

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

Codec.decode(input[, errors])¶

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

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

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

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

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

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

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

7.2.1.2. Объекты IncrementalEncoder¶IncrementalEncoder Objects

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

class codecs.IncrementalEncoder([errors])¶

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

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

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

• 'strict' Вызывает ValueError (или подкласс); это значение по умолчанию.
• 'ignore' Игнорирует символ и переходит к следующему.
• 'replace' Заменяет подходящим замещающим символом.
• 'xmlcharrefreplace' Заменяет соответствующей символьной ссылкой XML.
• 'backslashreplace' Заменяет управляющими последовательностями с обратной косой чертой.

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

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

encode(object[, final])¶

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

reset()¶

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

IncrementalEncoder.getstate()¶

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

IncrementalEncoder.setstate(state)¶

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

7.2.1.3. Объекты IncrementalDecoder¶IncrementalDecoder Objects

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

class codecs.IncrementalDecoder([errors])¶

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

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

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

• 'strict' Вызывает ValueError (или подкласс); это значение по умолчанию.
• 'ignore' Игнорирует символ и переходит к следующему.
• 'replace' Заменяет подходящим замещающим символом.

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

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

decode(object[, final])¶

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

reset()¶

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

getstate()¶

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

setstate(state)¶

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

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

7.2.1.4. Объекты StreamWriter¶StreamWriter Objects

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

class codecs.StreamWriter(stream[, errors])¶

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

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

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

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

• 'strict' Возбуждает ValueError (или подкласс); это значение по умолчанию.
• 'ignore' Игнорирует символ и продолжает со следующего.
• 'replace' Заменяет подходящим заменяющим символом
• 'xmlcharrefreplace' Заменяет соответствующей символьной ссылкой XML
• 'backslashreplace' Заменяет управляющими последовательностями с обратной косой чертой.

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

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

write(object)¶

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

writelines(list)¶

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

reset()¶

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

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

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

7.2.1.5. Объекты StreamReader¶StreamReader Objects

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

class codecs.StreamReader(stream[, errors])¶

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

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

поток данных должен быть файлоподобным объектом, открытым для чтения (двоичных) данных.

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

• 'strict' Возбуждает ValueError (или подкласс); это значение по умолчанию.
• 'ignore' Игнорирует символ и продолжает со следующего.
• 'replace' Заменяет подходящим заменяющим символом.

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

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

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

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

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

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

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

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

readline([size[, keepends]])¶

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

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

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

readlines([sizehint[, keepends]])¶

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

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

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

reset()¶

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

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

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

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

7.2.1.6. Объекты StreamReaderWriter¶StreamReaderWriter Objects

StreamReaderWriter позволяет оборачивать потоки, работающие как в режиме чтения, так и записи.

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

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

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

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

7.2.1.7. Объекты StreamRecoder¶StreamRecoder Objects

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

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

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

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

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

Поток данных должен быть файлоподобным объектом.

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

encode и decode нужны для преобразования на фронтенде, а Reader и Writer – на бэкенде.

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

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