codecs — Реестр кодировок и базовых классов¶
Этот модуль определяет базовые классы для стандартных кодировок 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 ) ¶
Сведения о кодировке при поиске в реестре кодировок. Аргументы конструктора хранятся в одноименных атрибутах:
Классы инкрементального кодера и декодера или функции фабрики. Они должны предоставлять интерфейс, определенный базовыми классами IncrementalEncoder и IncrementalDecoder соответственно. Дополнительные кодировки могут сохранять состояние.
Классы записи и чтения потоков или функции фабрики. Они должны обеспечивать интерфейс, определенный базовыми классами StreamWriter и StreamReader соответственно. Кодировки потока могут поддерживать состояние.
Чтобы упростить доступ к различным компонентам кодировок, модуль предоставляет следующие дополнительные функции, которые используют lookup() для поиска кодировок:
Найти кодек для данной кодировки и вернуть её функцию кодировки.
Вызывает LookupError в случае, если кодировка не может быть найдена.
codecs. getdecoder ( encoding ) ¶
Найти кодек для данной кодировки и вернуть её функцию декодирования.
Вызывает LookupError в случае, если кодировка не может быть найдена.
codecs. getincrementalencoder ( encoding ) ¶
Найти кодек для данной кодировки и вернуть её класс инкрементального кодера или функцию фабрику.
Вызывает LookupError в случае, если кодировка не может быть найдена или кодек не поддерживает инкрементный кодер.
codecs. getincrementaldecoder ( encoding ) ¶
Найти кодек для данной кодировки и вернуть его класс инкрементного декодера или функцию фабрику.
Вызывает LookupError в случае, если кодировка не может быть найдена или кодек не поддерживает инкрементный декодер.
codecs. getreader ( encoding ) ¶
Найти кодек для данной кодировки и вернуть его класс StreamReader или функцию фабрику.
Вызывает LookupError в случае, если кодировка не может быть найдена.
codecs. getwriter ( encoding ) ¶
Найти кодек для данной кодировки и вернуть его класс StreamWriter или функцию фабрику.
Вызывает LookupError в случае, если кодировка не может быть найдена.
Пользовательские кодеки становятся доступными после регистрации подходящей функции поиска кодека:
codecs. register ( search_function ) ¶
Зарегистрировать функцию поиска кодека. Ожидается, что функции поиска будут принимать один аргумент, представляющий собой имя, состоящее из строчных букв, и возвращать объект CodecInfo . Если функция поиска не может найти заданную кодировку, она должна вернуть None .
Поиск функции регистрации в настоящее время необратима, что в некоторых случаях может вызвать проблемы, например, при модульном тестировании или перезагрузке модуля.
Хотя встроенная open() и связанный с ней модуль io являются рекомендуемым подходом для работы с закодированными текстовыми файлами, этот модуль предоставляет дополнительные служебные функции и классы, которые позволяют использовать более широкий диапазон кодеков при работе с двоичными файлами:
codecs. open ( filename, mode=’r’, encoding=None, errors=’strict’, buffering=-1 ) ¶
Открыть закодированный файл с использованием заданного mode и вернуть экземпляр StreamReaderWriter , обеспечивая прозрачное кодирование/декодирование. Режим файла по умолчанию — ‘r’ , что означает открытие файла в режиме чтения.
Базовые закодированные файлы всегда открываются в двоичном режиме. При чтении и записи автоматическое преобразование ‘\n’ не выполняется. Аргумент mode может быть любым двоичным режимом, приемлемым для встроенной функции open() ; автоматически добавляется ‘b’ .
encoding указывает кодировку, которая будет использоваться для файла. Разрешена любая кодировка, которая кодирует и декодирует из байтов, а типы данных, поддерживаемые файловыми методами, зависят от используемого кодека.
errors может быть задан для определения обработки ошибок. По умолчанию используется ‘strict’ , что вызывает появление ValueError в случае возникновения ошибки кодирования.
У buffering то же значение, что и у встроенной функции open() . По умолчанию -1, что означает, что будет использоваться размер буфера по умолчанию.
codecs. EncodedFile ( file, data_encoding, file_encoding=None, errors=’strict’ ) ¶
Возвращает экземпляр StreamRecoder , обёрнутую версию file, которая обеспечивает прозрачное перекодирование. Исходный файл закрывается при закрытии обёрнутой версии.
Данные, записанные в обёрнутый файл, декодируются в соответствии с заданным data_encoding, а затем записываются в исходный файл в виде байтов с использованием file_encoding. Байты, считанные из исходного файла, декодируются согласно file_encoding, а результат кодируется с использованием data_encoding.
Если file_encoding не указан, по умолчанию используется data_encoding.
errors может быть задан для определения обработки ошибок. По умолчанию используется ‘strict’ , что вызывает повышение ValueError в случае возникновения ошибки кодирования.
codecs. iterencode ( iterator, encoding, errors=’strict’, **kwargs ) ¶
Использует инкрементный кодер для итеративного кодирования входных данных, предоставленных iterator. Это функция является генератором . Аргумент errors (как и любой другой ключевой аргумент) передаётся в инкрементальный кодер.
Функция требует, чтобы кодек принимал текстовые объекты str для кодирования. Поэтому он не поддерживает байтовые кодеки, такие, как base64_codec .
codecs. iterdecode ( iterator, encoding, errors=’strict’, **kwargs ) ¶
Использует инкрементный декодер для итеративного декодирования ввода, предоставленного iterator. Это функция является генератором . Аргумент errors (как и любой другой ключевой аргумент) передаётся инкрементному декодеру.
Функция требует, чтобы кодек принимал для декодирования объекты bytes . Поэтому она не поддерживает кодеки текста в текст, такие как rot_13 , хотя rot_13 может использоваться эквивалентно с iterencode() .
Модуль также предоставляет следующие константы, которые полезны для чтения и записи в файлы, зависящие от платформы:
codecs. BOM ¶ codecs. BOM_BE ¶ codecs. BOM_LE ¶ codecs. BOM_UTF8 ¶ codecs. BOM_UTF16 ¶ codecs. BOM_UTF16_BE ¶ codecs. BOM_UTF16_LE ¶ codecs. BOM_UTF32 ¶ codecs. BOM_UTF32_BE ¶ codecs. BOM_UTF32_LE ¶
Константы определяют различные последовательности байтов, являющиеся метками порядка байтов (BOM) Юникода для нескольких кодировок. Они используются в потоках данных UTF-16 и UTF-32 для обозначения используемого порядка байтов, а в UTF-8 в качестве Юникод сигнатуры. BOM_UTF16 — это BOM_UTF16_BE или BOM_UTF16_LE в зависимости от собственного порядка байтов платформы, BOM — это псевдоним для BOM_UTF16 , BOM_LE для BOM_UTF16_LE и BOM_BE для BOM_UTF16_BE . Остальные представляют спецификацию в кодировках UTF-8 и UTF-32.
Базовые классы кодеков¶
Модуль codecs определяет множество базовых классов, которые определяют интерфейсы для работы с объектами кодеков, а также могут использоваться в качестве основы для пользовательских реализаций кодеков.
Каждый кодек должен определить четыре интерфейса, чтобы его можно было использовать в качестве кодека в Python: кодер без сохранения состояния, декодер без состояния, средство чтения потока и средство записи потока. Средство чтения и записи потока обычно повторно используют кодер/декодер без сохранения состояния для реализации файловых протоколов. Авторам кодировок также необходимо определить, как кодек будет обрабатывать ошибки кодирования и декодирования.
Обработчики ошибок¶
Чтобы упростить и стандартизировать обработку ошибок, кодеки могут реализовывать различные схемы обработки ошибок, принимая строковый аргумент errors. Следующие строковые значения определены и реализованы всеми стандартными кодеками Python:
| Значение | Значение |
|---|---|
| ‘strict’ | Вызвать UnicodeError (или подкласс); этот по умолчанию. Реализовано в strict_errors() . |
| ‘ignore’ | Игнорировать искаженные данных и продолжать без дальнейшего уведомления. Реализовано в ignore_errors() . |
Следующие ниже обработчики ошибок применимы только к текстовым кодировкам :
| Значение | Описание |
|---|---|
| ‘replace’ | Заменить подходящим маркером замены; Python будет использовать официальный U+FFFD ЗАМЕНЯЮЩИЙ СИМВОЛ для встроенных кодеков при декодировании и „?“ при кодировании. Реализовано в replace_errors() . |
| ‘xmlcharrefreplace’ | Заменить соответствующий XML символ ссылкой (только для кодирования). Реализовано в xmlcharrefreplace_errors() . |
| ‘backslashreplace’ | Заменить на escape-последовательности с обратной косой чертой. Реализовано в backslashreplace_errors() . |
| ‘namereplace’ | Заменить \N <. >escape-последовательностью (только для кодирования). Реализовано в namereplace_errors() . |
| ‘surrogateescape’ | При декодировании, заменить байт с индивидуальным суррогатным кодом в диапазоне от U+DC80 до U+DCFF . Затем этот код будет возвращён в тот же байт, когда при кодировании данных будет использоваться обработчик ошибок ‘surrogateescape’ . (См. PEP 383 для получения дополнительной информации.) |
Кроме того, следующий обработчик ошибок специфичен для данных кодеков:
| Значение | Кодеки | Значение |
|---|---|---|
| ‘surrogatepass’ | utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le | Разрешить кодирование и декодирование суррогатных кодов. Эти кодеки обычно рассматривают присутствие суррогатов как ошибку. |
Добавлено в версии 3.1: Обработчики ошибок ‘surrogateescape’ и ‘surrogatepass’ .
Изменено в версии 3.4: Обработчики ошибок ‘surrogatepass’ теперь работают с кодеками utf-16* и utf-32*.
Добавлено в версии 3.5: Обработчик ошибок ‘namereplace’ .
Изменено в версии 3.5: Обработчики ошибок ‘backslashreplace’ теперь работают с декодированием и переводом.
Набор допустимых значений можно расширить, зарегистрировав новый именованный обработчик ошибок:
codecs. register_error ( name, error_handler ) ¶
Зарегистрировать функцию обработки ошибок error_handler под именем name. Аргумент error_handler будет вызываться во время кодирования и декодирования в случае ошибки, если в качестве параметра ошибок указано name.
Для кодирования будет вызываться error_handler с экземпляром UnicodeEncodeError , который содержит информацию о местоположении ошибки. Обработчик ошибок должен либо вызвать его или другое исключение, либо вернуть кортеж с заменой некодируемой части ввода и позицию, в которой должно продолжаться кодирование. Замена может быть str или bytes . Если замена байтами, кодер просто скопирует их в выходной буфер. Если замена является строковой, кодер закодирует замену. Кодирование продолжается на исходном вводе в указанной позиции. Отрицательные значения позиции будут рассматриваться как относящиеся к концу входной строки. Если результирующая позиция выходит за рамки, будет вызвано IndexError .
Декодирование и перевод работают аналогично, за исключением того, что UnicodeDecodeError или UnicodeTranslateError будут переданы обработчику, а замена из обработчика ошибок будет помещена в вывод напрямую.
Ранее зарегистрированные обработчики ошибок (включая стандартные обработчики ошибок) можно найти по имени:
codecs. lookup_error ( name ) ¶
Возвращает обработчик ошибок, ранее зарегистрированный под именем name.
Вызывает LookupError в случае, если обработчик не может быть найден.
Следующие стандартные обработчики ошибок также доступны как функции уровня модуля:
codecs. strict_errors ( exception ) ¶
Реализует обработку ошибок ‘strict’ : каждая ошибка кодирования или декодирования вызывает UnicodeError .
codecs. replace_errors ( exception ) ¶
Реализует обработку ошибок ‘replace’ (только для текстовых кодировок ): заменяет ‘?’ для ошибок кодирования (кодируется кодеком) и ‘\ufffd’ (символ замены Юникод) для ошибок декодирования.
codecs. ignore_errors ( exception ) ¶
Реализует обработку ошибок ‘ignore’ : искаженные данные игнорируются, а кодирование или декодирование продолжается без дальнейшего уведомления.
codecs. xmlcharrefreplace_errors ( exception ) ¶
Реализует обработку ошибок ‘xmlcharrefreplace’ (только для кодирования с текстовыми кодировками ): некодируемый символ заменяется соответствующей ссылкой на XML символ.
codecs. backslashreplace_errors ( exception ) ¶
Реализует обработку ошибок ‘backslashreplace’ (только для текстовых кодировок ): искаженные данные заменяются escape-последовательностью с обратной косой чертой.
codecs. namereplace_errors ( exception ) ¶
Реализует обработку ошибок ‘namereplace’ (только для кодирования с текстовыми кодировками ): некодируемый символ заменяется escape-последовательностью \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 .
Кодирует object (с учётом текущего состояния кодера) и возвращает результирующий закодированный объект. Если это последний вызов encode() , final должен быть истинным (по умолчанию — ложь).
Сбрасывает кодер в исходное состояние. Вывод отбрасывается: вызвать .encode(object, final=True) , передав пустой байт или текстовую строку, если необходимо, чтобы сбросить кодер и получить вывод.
Возвращает текущее состояние кодера, которое должно быть целым числом. Реализация должна убедиться, что 0 является наиболее распространенным состоянием. (Состояния, которые являются более сложными, чем целые числа, могут быть преобразованы в целое число путём маршалинга/пиклинга состояния и кодирования байтов результирующей строки в целое число.)
Установить состояние кодера на state. state должно быть состоянием кодера, возвращаемым getstate() .
Объекты IncrementalDecoder¶
Класс IncrementalDecoder используется для декодирования ввода в несколько этапов. Он определяет следующие методы, которые должны определять каждый инкрементный декодер, чтобы быть совместимым с реестром кодеков Python.
class codecs. IncrementalDecoder ( errors=’strict’ ) ¶
Все инкрементные декодеры должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные ключевые аргументы, но только те, которые определены здесь, используются реестром кодеков Python.
IncrementalDecoder может реализовывать различные схемы обработки ошибок, предоставляя ключевой аргумент errors. Возможные значения см. в Обработчики ошибок .
Аргумент errors будет присвоен атрибуту с таким же именем. Назначение этого атрибута позволяет переключаться между различными стратегиями обработки ошибок в течение жизненного цикла объекта IncrementalDecoder .
Декодирует object (с учётом текущего состояния декодера) и возвращает получившийся декодированный объект. Если это последний вызов decode() , final должен быть истинным (по умолчанию — ложь). Если final истинно, декодер должен полностью декодировать ввод и очистить все буферы. Если это невозможно (например, из-за неполных последовательностей байтов в конце ввода), он должен инициировать обработку ошибок, как и в случае без сохранения состояния (что может вызвать исключение).
Сбросить декодер в исходное состояние.
Возвращает текущее состояние декодера. Это должен быть кортеж с двумя элементами, первым из которых должен быть буфером, содержащий ещё не закодированный ввод. Второй должен быть целым числом и может быть дополнительной информацией о состоянии. (Реализация должна гарантировать, что 0 является наиболее распространенной дополнительной информацией о состоянии.) Если дополнительная информация о состоянии 0 , то должна быть возможность установить декодер в состояние без буферизации ввода и 0 в качестве дополнительной информации о состоянии, чтобы подача ранее буферизованного ввода в декодер возвращает его в предыдущее состояние без выдачи какого-либо вывода. (Дополнительная информация о состоянии, более сложная, чем целые числа, может быть преобразована в целое число путём маршалинга/пиклинга информации и кодирования байтов результирующей строки в целое число.)
Установить состояние декодера на 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() ). Стандартные байтовые кодеки не поддерживают этот метод.
Очищает и сбрасывает буферы кодеков, используемые для сохранения состояния.
Вызов этого метода должен гарантировать, что данные на выходе переведены в чистое состояние, которое позволяет добавлять новые свежие данные без необходимости повторного сканирования всего потока для восстановления состояния.
Помимо вышеуказанных методов, StreamWriter также должен наследовать все другие методы и атрибуты из базового потока.
Объекты StreamReader¶
Класс StreamReader является подклассом Codec и определяет следующие методы, которые должны определять каждый считыватель потоков для обеспечения совместимости с реестром кодеков Python.
class codecs. StreamReader ( stream, errors=’strict’ ) ¶
Конструктор для экземпляра StreamReader .
Все считыватели потока должны предоставлять этот интерфейс конструктора. Они могут добавлять дополнительные ключевые аргументы, но только те, которые определены здесь, используются реестром кодеков Python.
Аргумент stream должен быть файловым объектом, открытым для чтения текста или двоичных данных, в зависимости от кодека.
StreamReader может реализовывать различные схемы обработки ошибок, предоставляя ключевой аргумент errors. См. Обработчики ошибок для стандартных обработчиков ошибок, которые может поддерживать базовый потоковый кодек.
Аргумент errors будет присвоен атрибуту с тем же именем. Назначение этого атрибута позволяет переключаться между различными стратегиями обработки ошибок в течение времени существования объекта StreamReader .
Набор допустимых значений для аргумента errors может быть расширен с помощью register_error() .
Декодирует данные из потока и возвращает получившийся объект.
Аргумент chars указывает количество возвращаемых декодированных кодовых точек или байтов. Метод read() никогда не вернёт больше данных, чем запрошено, но может вернуть меньше, если их недостаточно.
Аргумент size указывает приблизительное максимальное количество закодированных байтов или кодовых точек для чтения для декодирования. Декодер может соответствующим образом изменить эту настройку. Значение по умолчанию -1 указывает на чтение и декодирование в максимально возможной степени. Этот параметр предназначен для предотвращения необходимости декодировать огромные файлы за один шаг.
Флаг firstline указывает, что было бы достаточно вернуть только первую строку, если есть ошибки декодирования на более поздних строках.
Метод должен использовать жадную стратегию чтения, означающую, что он должен читать столько данных, сколько разрешено в рамках определения кодировки и заданного размера, например если в потоке доступны необязательные окончания кодирования или маркеры состояния, их также следует прочитать.
Читает одну строку из входного потока и возвращает декодированные данные.
size, если он задан, передаётся как аргумент размера методу read() потока.
Если keepends ложно, окончание строки будет удалено из возвращаемых строк.
readlines ( [ sizehint [ , keepends ] ] ) ¶
Читает все строки, доступные во входном потоке, и вернуть их в виде списка строк.
Окончания строк реализуются с использованием метода кодировки decode() и включаются в записи списка, если keepends истинно.
Если задан sizehint, передаётся как аргумент size методу read() потока.
Сбрасывает буферы кодека, используемые для сохранения состояния.
Обратите внимание, что изменение положения потока выполняться не должно. Этот метод в первую очередь предназначен для восстановления после ошибок декодирования.
Помимо вышеуказанных методов, StreamReader также должен наследовать все другие методы и атрибуты из базового потока.
Объекты StreamReaderWriter¶
StreamReaderWriter — это удобный обёртывающий потоки класс, которые работают как в режиме чтения, так и в режиме записи.
Дизайн таков, что можно использовать фабричные функции, возвращаемые функцией lookup() , для создания экземпляра.
class codecs. StreamReaderWriter ( stream, Reader, Writer, errors=’strict’ ) ¶
Создаёт экземпляр StreamReaderWriter . stream должен быть файловым объектом. Reader и Writer должны быть функциями фабриками или классами, обеспечивающими интерфейс StreamReader и StreamWriter соответственно. Обработка ошибок выполняется так же, как определено для средств чтения и записи потока.
Экземпляры StreamReaderWriter определяют комбинированные интерфейсы классов StreamReader и StreamWriter . Они наследуют все другие методы и атрибуты от базового потока.
Объекты StreamRecoder¶
StreamRecoder переводит данные из одной кодировки в другую, что иногда полезно при работе с разными средами кодирования.
Дизайн таков, что можно использовать фабричные функции, возвращаемые функцией lookup() , для создания экземпляра.
class codecs. StreamRecoder ( stream, encode, decode, Reader, Writer, errors=’strict’ ) ¶
Создаёт экземпляр StreamRecoder , который реализует двустороннее преобразование: encode и decode работают на интерфейсе — данные видны для кода, вызывающего read() и write() , а Reader и Writer работают на сервере — данные в stream.
Вы можете использовать эти объекты для прозрачного перекодирования, например, из Latin-1 в UTF-8 и обратно.
Аргумент stream должен быть файловым объектом.
Аргументы encode и decode должны соответствовать интерфейсу Codec . Reader и Writer должны быть функциями фабриками или классами, предоставляющими объекты интерфейса StreamReader и StreamWriter соответственно.
Обработка ошибок выполняется так же, как определено для средств чтения и записи потока.
Экземпляры StreamRecoder определяют комбинированные интерфейсы классов StreamReader и StreamWriter . Они наследуют все другие методы и атрибуты от базового потока.
Кодировки и Юникод¶
Строки хранятся внутри как последовательности кодовых точек в диапазоне 0x0 – 0x10FFFF . (См. PEP 393 для получения дополнительной информации о реализации.) Когда строковый объект используется вне ЦПУ и памяти, порядок байтов и порядок хранения этих массивов в байтах становятся проблемой. Как и в случае с другими кодировками, сериализация строки в последовательность байтов известна как кодирование, а воссоздание строки из последовательности байтов известно как декодирование. Существует множество различных кодеков сериализации текста, которые в совокупности называются текстовыми кодировками .
Простейшая кодировка текста (называемая ‘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), которые выбирают другое подмножество всех кодовых точек Юникод и то, как эти кодовые точки отображаются в байты 0x0 — 0xff . Чтобы увидеть, как это делается, просто откройте, например, encodings/cp1252.py (кодировка, которая используется в основном в Windows). Существует строковая константа из 256 символов, которая показывает, какой символ сопоставлен с каким значением байта.
Все эти кодировки могут кодировать только 256 из 1114112 кодовых точек, определенных в Юникоде. Простой и понятный способ сохранить каждую кодовую Юникод точку — это сохранить каждую кодовую точку как четыре последовательных байта. Есть две возможности: хранить байты в прямом или обратном порядке. Эти две кодировки называются UTF-32-BE и UTF-32-LE соответственно. Их недостаток в том, что если, например, вы используете UTF-32-BE на машине с прямым порядком байтов, вам всегда придется менять байты местами при кодировании и декодировании. UTF-32 позволяет избежать этой проблемы: у байтов всегда будет естественный порядок следования байтов. Когда эти байты читаются ЦПУ с другим порядком байтов, тогда байты необходимо поменять местами. Чтобы была возможность определять порядок байтов последовательности байтов UTF-16 или UTF-32 , существует так называемая BOM («Метка порядка байтов»). Это символ Юникода U+FEFF . Этот символ может быть добавлен к каждой последовательности байтов UTF-16 или UTF-32 . Версия этого символа с перестановкой байтов ( 0xFFFE ) является недопустимым символом, который может отсутствовать в тексте Юникод. Поэтому, когда первый символ в байтовой последовательности UTF-16 или UTF-32 оказывается U+FFFE , байты должны быть поменяны местами при декодировании. К сожалению, у символа U+FEFF была вторая цель как ZERO WIDTH NO-BREAK SPACE : символ, у которого нет ширины и не позволяет разделить слово. Это может, например, использоваться для подсказки алгоритма лигатуры. В Юникод 4.0 использование U+FEFF в качестве ZERO WIDTH NO-BREAK SPACE устарело (с U+2060 ( WORD JOINER ), принимающим на себя эту роль). Тем не менее, Юникод программное обеспечение всё ещё должно уметь обрабатывать U+FEFF в обеих ролях: как спецификация это устройство для определения структуры хранения закодированных байтов и исчезает после того, как последовательность байтов была декодирована в строку; как ZERO WIDTH NO-BREAK SPACE это обычный символ, который будет декодирован, как и любой другой.
Есть ещё одна кодировка, которая может кодировать весь диапазон символов Юникод: UTF-8. UTF-8 — это 8-битная кодировка, что означает, что в UTF-8 нет проблем с порядком байтов. Каждый байт в байтовой последовательности UTF-8 состоит из двух частей: битов маркера (старшие биты) и битов полезной нагрузки. Биты маркера представляют собой последовательность от нуля до четырех битов 1 , за которыми следует бит 0 . Символы Юникод кодируются следующим образом (где x — это биты полезной нагрузки, которые при объединении дают символ Юникод):
| Диапазон | Кодировка |
|---|---|
| U-00000000 … U-0000007F | 0xxxxxxx |
| U-00000080 … U-000007FF | 110xxxxx 10xxxxxx |
| U-00000800 … U-0000FFFF | 1110xxxx 10xxxxxx 10xxxxxx |
| U-00010000 … U-0010FFFF | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |
Наименьший значащий бит символа Юникода — это крайний правый бит x.
Поскольку UTF-8 представляет собой 8-битную кодировку, спецификация не требуется, и любой символ U+FEFF в декодированной строке (даже если это первый символ) обрабатывается как ZERO WIDTH NO-BREAK SPACE .
Без внешней информации невозможно достоверно определить, какая кодировка использовалась для кодирования строки. Каждая кодировка charmap может декодировать любую случайную последовательность байтов. Однако это невозможно с UTF-8, поскольку у байтовых последовательностей UTF-8 структура, которая не допускает произвольных байтовых последовательностей. Чтобы повысить надежность обнаружения кодировки UTF-8, Microsoft изобрела вариант UTF-8 (в Python 2.5 называет «utf-8-sig» ) для своей программы Notepad: перед тем, как любой из символов Юникода будет записан в файл, UTF- записывается 8 закодированный BOM (выглядит как последовательность байтов: 0xef , 0xbb , 0xbf ). Поскольку маловероятно, что какой-либо файл с кодировкой charmap начинается с этих байтовых значений (которые, например, сопоставляются с
в iso-8859-1), это увеличивает вероятность того, что кодировка utf-8-sig может быть правильно угадана из последовательности байтов. Таким образом, здесь спецификация используется не для определения порядка байтов, используемого для генерации последовательности байтов, а в качестве сигнатуры, которая помогает угадать кодировку. При кодировании кодек utf-8-sig запишет 0xef , 0xbb , 0xbf в качестве первых трех байтов в файл. При декодировании utf-8-sig пропустит эти три байта, если они появятся как первые три байта в файле. В UTF-8 использование спецификации не рекомендуется, и её обычно следует избегать.
Стандартные кодировки¶
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.
Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли ЗНАК ЕВРО или нет) и назначением символов кодовым позициям. В частности, для европейских языков обычно существуют следующие варианты:
Как узнать кодировку файла в Python?
Кто-нибудь знает, как получить кодировку файла в Python. Я знаю, что вы можете использовать модуль кодеков, чтобы открыть файл с определенной кодировкой, но вы должны знать это заранее.
Есть ли способ автоматически определить, какая кодировка используется для файла?
Редактировать: Спасибо всем за очень интересные ответы. Вас также может заинтересовать http://whatismyencoding.com/ основанный на chardet (более того, сайт работает на основе бутылочного питона)
5 ответов
К сожалению, нет «правильного» способа определить кодировку файла, посмотрев на сам файл. Это универсальная проблема, не ограниченная питоном или какой-либо конкретной файловой системой.
Если вы читаете файл XML, первая строка файла может дать вам подсказку о том, что такое кодировка.
В противном случае вам придется использовать некоторый эвристический подход, такой как chardet (одно из решений, приведенных в других ответах), который пытается угадать кодировку, исследуя данные в файле в необработанном байтовом формате. Если вы работаете в Windows, я считаю, что Windows API также предоставляет методы, позволяющие угадать кодировку на основе данных в файле.
Как работать с Unicode в Python
Unicode (Юникод) — это стандарт кодирования символов для большинства компьютеров. Он гарантирует, что текст — включая буквы, символы, эмодзи и даже управляющие символы — будет выглядеть одинаково на разных устройствах, платформах и в цифровых документах, независимо от операционной системы или программного обеспечения. Это важная составляющая интернета и компьютерной индустрии в целом. Без него всё было бы сложно и хаотично.
Unicode сам по себе не является кодировкой, а больше похож на базу данных почти всех возможных символов. В нём есть кодовая точка (идентификатор для каждого символа в базе данных), которая может иметь значение от 0 до 1,1 миллиона – как видите, скорее всего в ближайшее время эти уникальные кодовые точки не закончатся. Каждая кодовая точка в Unicode обозначается U+n, где U+ — кодовая точка Unicode, а n — это набор для символа из четырех-шести шестнадцатеричных цифр. Unicode намного надежнее ASCII, в котором только 128 символов. Обмен цифровым текстом с помощью ASCII сложнее, так как он основан на американском английском и не поддерживает символы с диакритическими знаками. А в Unicode почти 150 000 символов и он охватывает символы всех языков мира.
Поэтому от языков программирования и требуется правильно обрабатывать текст и обеспечивать интернационализацию программного обеспечения. Python используют для разных целей — от электронной почты до серверов и интернета — у него отличный способ обработки Unicode, он принимает стандарт Unicode для своих строк.
Иногда в работе с Unicode в Python могут возникать трудности и ошибки. В этом мануале представлены основы работы Unicode в Python, которые помогут вам избежать этих проблем. С помощью Python мы интерпретируем Unicode, применим к Unicode функцию нормализации и обработаем ошибки.
Требования
- Python, установленный локально или на удаленном сервере. Если у вас еще не установлен Python, ознакомьтесь с этим мануалом.
- Знание основ программирования и строковых методов Python. Читайте Основы работы со строками в Python 3.
- Знание принципов работы с интерактивной консолью Python. Читайте мануал Использование интерактивной консоли Python.
1: Конвертирование кодовых точек Unicode в Python
Кодирование — это процесс представления данных в читаемой компьютером форме. Существуют разные способы кодирования данных — ASCII, Latin-1 и т. д. У каждой кодировки свои сильные и слабые стороны, но пожалуй, самой распространенной является UTF-8 — тип кодирования, который отображает символы со всего мира в одном наборе. То есть, UTF-8 это незаменимый инструмент для всех, кто работает с интернационализированными данными. В целом, UTF-8 справляется с многими задачами. Он относительно эффективен и может работать в разных программах. UTF-8 конвертирует кодовую точку Unicode в понятные компьютеру шестнадцатеричные байты. Другими словами, Unicode – это маппинг, а UTF-8 позволяет компьютеру понять этот маппинг.
В Python 3 кодировка строк по умолчанию – UTF-8, значит, любая кодовая точка Unicode в строке Python автоматически конвертируется в соответствующий символ.
Сейчас мы создадим символ авторского права (©) с помощью его кодовой точки Unicode в Python. Сначала запустите интерактивную консоль Python в терминале, а затем введите:
В этом коде мы создали строку s с кодовой точкой Unicode \u00A9. Как упоминалось ранее, поскольку строка Python по умолчанию использует кодировку UTF-8, вывод значения s автоматически заменяет его на соответствующий символ Unicode. Обратите внимание, что \u в начале кода обязателен. Без него Python не сможет конвертировать кодовую точку. В выводе получим соответствующий символ Unicode:
В Python есть встроенные функции для кодирования и декодирования строк. Функция encode() конвертирует строку в байтовую строку.
Для этого откройте интерактивную консоль Python и введите код:
В результате получим байтовую строку символа:
Обратите внимание, что перед каждым байтом стоит \x, значит, это шестнадцатеричное число.
Примечание: Ввод спецсимволов Unicode в Windows и Mac отличается. В Windows предыдущий и все последующие примеры этого мануала, где используются символы, вы можете вставить с помощью утилиты Character Map. В Mac нет этой функции, поэтому лучше скопировать символ из примера кода.
Далее с помощью функции decode() конвертируем байтовую строку в обычную. Функция decode() принимает в качестве аргумента тип кодировки. Отметим, что функция decode() может декодировать только байтовую строку, которая задается с помощью буквы b в начале строки. Удаление b приведет к ошибке AttributeError.
В консоли введите:
Получим следующий вывод:
Теперь у вас есть базовое понимание интерпретации Unicode в Python. Далее мы разберем встроенный в Python модуль unicodedata, чтобы применить расширенные методы Unicode для строк.
2: Нормализация Unicode в Python
С помощью нормализации можно определить, одинаковы ли два символа, написанные разными шрифтами. Это удобно, когда два символа с разными кодовыми точками дают одинаковый результат. Например, мы воспринимаем символы Unicode R и ℜ как одинаковые, поскольку они оба представляют собой букву R, но для компьютера они разные.
Следующий пример кода это демонстрирует. Откройте консоль Python и введите следующее:
В результате получим:
Вывод будет False, потому что Python не считает эти два символа одинаковыми. Именно поэтому нормализация важна при работе с Unicode.
В Unicode некоторые символы создаются путем объединения нескольких символов в один. Нормализация также важна в этом случае, потому что она обеспечивает согласованность строк. Рассмотрим это на примере. Откройте консоль Python и введите код:
В этом коде мы создали строку s1, содержащую символ ô, а строка s2 содержит кодовую точку символа циркумфлекса ( ̂ ). Получим такой вывод:
Это значит, что две строки состоят из одинаковых символов, но имеют разную длину. Значит, они не подходят под условие равенства. Чтобы это проверить, введите в той же консоли:
Хотя строковые переменные s1 и s2 производят один и тот же символ Unicode, они различаются по длине и, следовательно, не равны.
Решить эту проблему можно с помощью функции normalize().
3: Нормализация Unicode с помощью NFD, NFC, NFKD и NFKC
Сейчас мы нормализуем строки Unicode с помощью функции normalize() из библиотеки unicodedata Python в модуле unicodedata (он обеспечивает поиск и нормализацию символов). Функция normalize() может принимать форму нормализации в качестве первого аргумента и нормализуемую строку в качестве второго аргумента. В Unicode существует четыре типа форм нормализации: NFD, NFC, NFKD и NFKC.
NFD разбивает символ на несколько комбинируемых символов. Это делает текст нечувствительным к диакритическим символам, что удобно при поиске и сортировке. Для этого нужно закодировать строку в байты.
Откройте консоль и введите следующее:
Получим следующий вывод:
При нормализации строки s1 ее длина увеличилась на один символ. Это происходит по причине того, что символ ô разбивается на два символа — o и ˆ. Следующий код это подтвердит:
В результате, после кодирования нормализованной строки символ o отделился от символа ˆ в строке s1_nfd:
Форма нормализации NFC раскладывает символ, а затем перекомпонует его с любым доступным объединяющим символом. W3C рекомендует использовать NFC в интернете, поскольку NFC компонует строку для получения максимально короткого результата. Ввод с клавиатуры по умолчанию возвращает составленные строки, поэтому в этом случае рекомендуется применять NFC.
Для примера введите в интерактивную консоль:
Вывод будет следующим:
При нормализации строки s2 её длина уменьшилась на единицу. Введите код в интерактивной консоли:
Вывод будет таким:
Символы o и ˆ соединены в один символ ô.
Формы нормализации NFKD и NFKC применяют для «строгой» нормализации и поиска, сопоставления образцов в строках Unicode. “K” в NFKD и NFKC означает совместимость.
NFD и NFC разделяют символы, но NFKD и NFKC выполняют разделение на совместимость для непохожих эквивалентых символов, при этом удаляются любые различия форматирования. Например, строка ②① не похожа на 21, но обе имеют одно значение. Формы нормализации NFKC и NFKD удаляют форматирование (в данном случае круг вокруг цифр) из символов, чтобы представить их упрощенную форму.
На примере разберем разницу между NFD и NFKD. Откройте интерактивную консоль Python и введите:
Получаем следующий вывод:
Форма NFD не смогла разделить символ экспоненты в строке s1, но NFKD вырезала форматирование экспоненты и заменила символ совместимости (в данном случае экспоненту 5) на его эквивалент (5 в виде цифры). Так как NFD и NFKD разделяют символы, следовательно, ô увеличит длину на единицу. Это подтвердит следующее:
Принцип работы NFKC аналогичный, но он скорее не разделяет символы, а компонует их. В консоли Python введите:
Вывод будет следующим:
Строка для символа ô уменьшится на единицу, поскольку в NFKC композиционный подход (в случае разделения значение увеличивается на единицу). Проверим это с помощью кода:
Мы разобрали типы нормализации и различия между ними. Далее мы устраним ошибки Unicode в Python.
4: Устранение ошибок Unicode в Python
При работе с Unicode в Python могут возникать два типа ошибок: UnicodeEncodeError и UnicodeDecodeError. Теперь разберем пути их устранения.
Устранение ошибки UnicodeEncodeError
Кодирование в Unicode — это процесс конвертирования строки Unicode в байты с помощью определенной кодировки. Ошибка UnicodeEncodeError возникает при попытке закодировать строку, символы которой не могут быть представлены в заданной кодировке.
Чтобы создать эту ошибку, давайте попробуем закодировать строку с символами, которые не входят в набор ASCII.
Откройте консоль и введите:
Получим следующий результат:
Наконец, введите следующее:
При запуске этого кода возникнет ошибка:
UnicodeEncodeError: ‘ascii’ codec can’t encode character ‘\ufb06’ in position 0: ordinal not in range(128)
В ASCII ограниченное количество символов, поэтому Python выдает ошибки при нахождении символа, которого нет в кодировке ASCII. Поскольку кодовая система ASCII не распознает кодовую точку \ufb06, Python выдаст сообщение об ошибке. В нем идет речь о том, что ASCII имеет диапазон только 128 символов, а соответствующий десятичный эквивалент этой кодовой точки не входит в этот диапазон.
UnicodeEncodeError можно обработать с помощью аргумента errors в функции encode(). У аргумента errors может быть одно из трех значений: ignore, replace и xmlcharrefreplace.
Откройте консоль и введите:
Получим следующий вывод:
Вывод будет таким:
В результате получим:
Во всех случаях Python не выдает ошибку. Значение
ignore пропускает символ, который не может быть закодирован; replace заменяет символ знаком ?; а xmlcharrefreplace заменяет некодируемые символы сущностью XML.
Устранение ошибки UnicodeDecodeError
Ошибка UnicodeEncodeError возникает при попытке декодировать строку, символы которой не могут быть представлены в заданной кодировке.
Чтобы создать эту ошибку, мы попробуем декодировать строку байтов в кодировку, которую невозможно декодировать.
Откройте консоль и введите:
Получим следующую ошибку:
Если вы столкнулись с этой ошибкой, можете применить аргумент errors в функции decode(), c помощью которого можно декодировать строку. Аргумент errors принимает два значения: ignore и replace.
Откройте консоль Python и введите код:
Вывод будет следующим:
Получим такой вывод:
Значение replace в функции decode() добавляет символ �, а ignore ничего не возвращает, поскольку декодер (в данном случае utf-8) не смог декодировать байты.
При декодировании строки следует помнить, что предполагать ее кодировку нельзя, нужно точно знать, как именно она была закодирована.
Подводим итоги
В этом мануале мы рассмотрели основы работы Unicode в Python. Мы кодировали и декодировали строки, нормализовали данные с помощью NFD, NFC, NFKD и NFKC, а также устранили ошибки Unicode. Также мы применили формы нормализации в сценариях сортировки и поиска. Эти методы помогут устранить ошибки Unicode с помощью Python. Рекомендуем ознакомиться с материалами модуля unicodedata .
How to Convert a String to UTF-8 in Python?
In this article, we will learn to convert a string to UTF-8 in Python. We will use some built-in functions and some custom code as well. Let’s first have a quick look over what is a string in Python.
Python String
The String is a type in python language just like integer, float, boolean, etc. Data surrounded by single quotes or double quotes are said to be a string. A string is also known as a sequence of characters.
What is UTF-8 in Python?
UTF is “Unicode Transformation Format” , and ‘8’ means 8-bit values are used in the encoding. It is one of the most efficient and convenient encoding formats among various encodings. In Python, Strings are by default in utf-8 format which means each alphabet corresponds to a unique code point. utf-8 encodes a Unicode string to bytes. The user receives string data on the server instead of bytes because some frameworks or library on the system has implicitly converted some random bytes to string and it happens due to encoding.
A user might encounter a situation where his server receives utf-8 characters but when he tries to retrieve it from the query string, he gets ASCII coding. Therefore, in order to convert the plain string to utf-8, we will use the encode() method to convert a string to utf-8 in python 3.
Use encode() to convert a String to UTF-8
The encode() method returns the encoded version of the string. In case of failure, a UnicodeDecodeError exception may occur.
Syntax
Parameters
encoding — the encoding type like ‘UTF-8’, ASCII, etc.
errors — response when encoding fails.
There are six types of error responses:
- strict — default response which raises a UnicodeDecodeError exception on failure
- ignore — ignores the unencodable Unicode from the result
- replace — replaces the unencodable Unicode to a question mark?
- xmlcharrefreplace — inserts XML character reference instead of unencodable Unicode
- backslashreplace — inserts a \uNNNN escape sequence instead of unencodable Unicode
- namereplace — inserts a \N <. >escape sequence instead of unencodable Unicode
By default, the encode() method does not take any parameters.
Example
The encoded version is: b’pyth\xc3\xb6n!’
Conclusion
In this article, we learned to convert a plain string to utf-8 format using encode() method. You can also try using different encoding formats and error parameters.