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.

Изменено в версии 3.9: Дефисы и пробелы заменяются символами подчёркивания.

codecs.unregister(search_function): Отменяет регистрацию функции поиска кодека и очищает кэш реестра. Если функция поиска не зарегистрирована, ничего не происходит.

Добавлено в версии 3.10.

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

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

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

Примечание

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

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

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

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

Изменено в версии 3.11: Режим 'U' удалён.

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

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

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

Если file_encoding не задана, по умолчанию используется data_encoding.

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: Эти константы определяют различные последовательности байтов — метки порядка байтов Unicode (BOM) для нескольких кодировок. Они используются в потоках данных UTF-16 и UTF-32 для указания порядка байтов, а в UTF-8 — в качестве сигнатуры Unicode. 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:

>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German &#223;, &#9836;'

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

Значение	Значение
`'strict'`	Вызывает `UnicodeError` (или его подкласс); это значение используется по умолчанию. Реализован в `strict_errors()`.
`'ignore'`	Игнорирует некорректные данные и продолжает работу без дополнительных уведомлений. Реализован в `ignore_errors()`.
`'replace'`	Заменяет данные маркером замены. При кодировании использует `?` (символ ASCII). При декодировании использует `�` (U+FFFD, официальный СИМВОЛ ЗАМЕНЫ). Реализован в `replace_errors()`.
`'backslashreplace'`	Заменяет данные экранированными последовательностями с обратной косой чертой. При кодировании используется шестнадцатеричная форма кодовой точки Unicode в форматах `\xhh` `\uxxxx` `\Uxxxxxxxx`. При декодировании используется шестнадцатеричная форма значения байта в формате `\xhh`. Реализован в `backslashreplace_errors()`.
`'surrogateescape'`	При декодировании заменяет байт отдельной суррогатной кодовой точкой из диапазона от `U+DC80` до `U+DCFF`. При кодировании данных этот код преобразуется обратно в тот же байт, если используется обработчик ошибок `'surrogateescape'`. (Подробнее см. PEP 383.)

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

Значение	Значение
`'xmlcharrefreplace'`	Заменяет данные числовой ссылкой на символ XML/HTML, представляющей собой десятичную форму кодовой точки Unicode в формате `&#num;`. Реализован в `xmlcharrefreplace_errors()`.
`'namereplace'`	Заменяет данные экранированными последовательностями `\N{...}`; внутри фигурных скобок указывается свойство Name из базы данных символов Unicode. Реализован в `namereplace_errors()`.

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

Значение	Кодеки	Значение
`'surrogatepass'`	utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le	Разрешает кодировать и декодировать суррогатные кодовые точки (`U+D800` - `U+DFFF`) как обычные кодовые точки. В противном случае эти кодеки считают наличие суррогатной кодовой точки в `str` ошибкой.

Добавлено в версии 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 будет вызываться при кодировании и декодировании в случае ошибки, если в качестве параметра errors указано значение name.

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

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

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

codecs.lookup_error(name)

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

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

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

codecs.strict_errors(exception)

Реализует обработку ошибок 'strict'.

При каждой ошибке кодирования или декодирования вызывается исключение UnicodeError.

codecs.ignore_errors(exception)

Реализует обработку ошибок 'ignore'.

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

codecs.replace_errors(exception)

Реализует обработку ошибок 'replace'.

При ошибках кодирования вместо символа подставляется ? (символ ASCII), а при ошибках декодирования — � (U+FFFD, официальный СИМВОЛ ЗАМЕНЫ).

codecs.backslashreplace_errors(exception)

Реализует обработку ошибок 'backslashreplace'.

Некорректные данные заменяются экранированной последовательностью с обратной косой чертой. При кодировании используется шестнадцатеричная форма кодовой точки Unicode в форматах \xhh \uxxxx \Uxxxxxxxx. При декодировании используется шестнадцатеричная форма значения байта в формате \xhh.

Изменено в версии 3.5: Работает при декодировании и преобразовании.

codecs.xmlcharrefreplace_errors(exception)

Реализует обработку ошибок 'xmlcharrefreplace' (только при кодировании в рамках текстовой кодировки).

Некодируемый символ заменяется соответствующей числовой ссылкой на символ XML/HTML, представляющей собой десятичную форму кодовой точки Unicode в формате &#num; .

codecs.namereplace_errors(exception)

Реализует обработку ошибок 'namereplace' (только при кодировании в рамках текстовой кодировки).

Некодируемый символ заменяется экранированной последовательностью \N{...}. Набор символов внутри фигурных скобок соответствует свойству Name из базы данных символов Unicode. Например, строчная немецкая буква 'ß' будет преобразована в последовательность байтов \N{LATIN SMALL LETTER SHARP S} .

Добавлено в версии 3.5.

Кодирование и декодирование без сохранения состояния

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

class codecs.Codec

encode(input, errors='strict')

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

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

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

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

decode(input, errors='strict')

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

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

Аргумент 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=False): Кодирует object с учётом текущего состояния кодировщика и возвращает полученный закодированный объект. Если это последний вызов encode(), значение final должно быть истинным (по умолчанию оно ложно).

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

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

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

Объекты IncrementalDecoder

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

class codecs.IncrementalDecoder(errors='strict')

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

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

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

decode(object, final=False): Декодирует object с учётом текущего состояния декодировщика и возвращает полученный декодированный объект. Если это последний вызов decode(), значение final должно быть истинным (по умолчанию оно ложно). Если 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 можно расширить с помощью register_error().

read(size=-1, chars=-1, firstline=False)

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

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

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

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

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

readline(size=None, keepends=True)

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

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

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

readlines(sizehint=None, keepends=True)

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

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

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

Строки хранятся внутри как последовательности кодовых точек в диапазоне U+0000–U+10FFFF. (Подробнее о реализации см. в 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 — хранить каждую из них в виде четырёх последовательных байтов. Есть два варианта: хранить байты в порядке от старшего к младшему или от младшего к старшему. Эти две кодировки называются соответственно UTF-32-BE и UTF-32-LE. Их недостаток в том, что, например, при использовании UTF-32-BE на машине с порядком байтов от младшего к старшему байты всегда придётся переставлять при кодировании и декодировании. UTF-32 позволяет избежать этой проблемы: байты всегда хранятся в естественном порядке. Однако при чтении этих байтов ЦП с другим порядком байтов их всё же придётся переставлять. Чтобы определить порядок байтов последовательности UTF-16 или UTF-32, существует так называемый BOM («маркер порядка байтов»). Это символ 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 состоит из двух частей: маркерных битов (старших битов) и битов данных. Маркерные биты представляют собой последовательность из нуля — четырёх битов 1, за которой следует бит 0. Символы Unicode кодируются следующим образом (x — это биты данных, которые в объединённом виде образуют символ Unicode):

Диапазон	Кодирование
`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-битная кодировка, BOM не требуется, а любой символ U+FEFF в декодированной строке (даже если он стоит первым) считается символом ZERO WIDTH NO-BREAK SPACE.

Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Любая кодировка charmap может декодировать произвольную последовательность байтов. Однако с UTF-8 это невозможно, поскольку структура последовательностей байтов UTF-8 не допускает произвольных последовательностей байтов. Чтобы повысить надёжность определения кодировки UTF-8, Microsoft изобрела вариант UTF-8 (который Python называет "utf-8-sig") для программы «Блокнот»: перед записью в файл любых символов Unicode записывается BOM в кодировке UTF-8 (в виде последовательности байтов: 0xef, 0xbb, 0xbf). Поскольку маловероятно, что файл в какой-либо кодировке charmap начинается с этих значений байтов (которые, например, в 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'.

Особенность реализации CPython: Для повышения производительности некоторые распространённые кодировки могут обходить механизм поиска кодеков. CPython распознаёт возможности такой оптимизации только для ограниченного набора псевдонимов (без учёта регистра): utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (только Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32, а также для тех же вариантов с подчёркиваниями вместо дефисов. Использование других псевдонимов этих кодировок может привести к снижению производительности.

Изменено в версии 3.6: Возможность оптимизации распознаётся для us-ascii.

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

кодировка 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_centeuro	Центральная и Восточная Европа
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 и декодирование из объекта, подобного bytes в str, аналогично текстовым кодировкам Unicode.

Кодек	Псевдонимы	Назначение
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` для остальных кодовых точек. Существующие обратные косые черты никак не экранируются. Используется в протоколе pickle Python.
undefined		Вызывает исключение при любых преобразованиях, даже для пустых строк. Обработчик ошибок игнорируется.
unicode_escape		Кодировка, подходящая для содержимого литерала Unicode в исходном коде Python с кодировкой ASCII, за исключением того, что кавычки не экранируются. Декодирует исходный код в кодировке Latin-1. Обратите внимание, что по умолчанию исходный код Python фактически использует UTF-8.

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

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

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

Кодек	Псевдонимы	Назначение	Кодировщик / декодер
base64_codec [1]	base64, base_64	Преобразует операнд в многострочный формат MIME base64 (результат всегда содержит завершающий `'\n'`). Изменено в версии 3.4: принимает любой объект, подобный bytes, в качестве входных данных для кодирования и декодирования	`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 quoted-printable.	`quopri.encode()` с `quotetabs=True` / `quopri.decode()`
uu_codec	uu	Преобразует операнд с помощью uuencode.	`uu.encode()` / `uu.decode()` (Примечание: `uu` устарел.)
zlib_codec	zip, zlib	Сжимает операнд с помощью gzip.	`zlib.compress()` / `zlib.decompress()`

Добавлено в версии 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.

Если вам нужен стандарт IDNA 2008 из RFC 5891 и RFC 5895, используйте сторонний модуль idna.

Эти 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, обработанную процедурой nameprep. В текущей реализации предполагается, что используются строки запросов, поэтому AllowUnassigned имеет значение true.

encodings.idna.ToASCII(label): Преобразует метку в ASCII согласно RFC 3490. Предполагается, что UseSTD3ASCIIRules имеет значение false.

encodings.idna.ToUnicode(label): Преобразует метку в Unicode согласно RFC 3490.

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

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

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

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

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

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

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