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

Этот модуль определяет базовые классы для стандартных кодеков Python (кодировщики и декодировщики) и предоставляет доступ к внутреннему реестру кодеков Python, который управляет процессом поиска кодеков и обработки ошибок.

Он определяет следующие функции:

codecs.encode(obj[, encoding[, errors]])

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

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

Новое в версии 2.4.

codecs.decode(obj[, encoding[, errors]])

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

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

Новое в версии 2.4.

codecs.register(search_function)

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

• name Имя кодировки;
• encode Бессостоятельная функция кодирования;
• decode Бессостоятельная функция декодирования;
• incrementalencoder Класс или функция-фабрика для инкрементального кодировщика;
• incrementaldecoder Класс или функция-фабрика для инкрементального декодировщика;
• streamwriter Класс или функция-фабрика для потокового записи;
• streamreader Класс или функция-фабрика для потокового чтения.

Различные функции или классы принимают следующие аргументы:

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

incrementalencoder и incrementaldecoder: Это функции-фабрики, предоставляющие следующий интерфейс:

factory(errors='strict')

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

streamreader и streamwriter: Эти функции-фабрики должны предоставлять следующий интерфейс:

factory(stream, errors='strict')

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

Возможные значения для ошибок:

• 'strict': вызывать исключение в случае ошибки кодирования
• 'replace': заменять некорректные данные подходящим маркером замены, например '?' или '\ufffd'
• 'ignore': игнорировать некорректные данные и продолжать без дальнейших уведомлений
• 'xmlcharrefreplace': заменить соответствующей ссылкой на символ XML (только для кодирования)
• 'backslashreplace': заменить обратными косыми слешами (только для кодирования)

а также любые другие имена обработки ошибок, определенные через register_error().

В случае, если функция поиска не может найти заданную кодировку, она должна вернуть None.

codecs.lookup(encoding)

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

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

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

codecs.getencoder(encoding)

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

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

codecs.getdecoder(encoding)

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

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

codecs.getincrementalencoder(encoding)

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

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

Новое в версии 2.5.

codecs.getincrementaldecoder(encoding)

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

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

Новое в версии 2.5.

codecs.getreader(encoding)

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

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

codecs.getwriter(encoding)

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

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

codecs.register_error(name, error_handler)

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

Для кодирования error_handler будет вызван с экземпляром UnicodeEncodeError, который содержит информацию о местоположении ошибки. Обработчик ошибок должен либо вызвать это, либо другое исключение, либо вернуть кортеж со заменой для некодируемой части входных данных и позицией, с которой следует продолжить кодирование. Кодировщик закодирует замену и продолжит кодирование исходных данных с указанной позиции. Отрицательные значения позиции будут обрабатываться как относительные к концу входной строки. Если полученная позиция выходит за пределы границ, будет вызвано 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.open(filename, mode[, encoding[, errors[, buffering]]])

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

Примечание

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

Примечание

Файлы всегда открываются в двоичном режиме, даже если не был указан двоичный режим. Это делается для предотвращения потери данных из-за кодировок, использующих 8-битные значения. Это означает, что автоматическое преобразование '\n' при чтении и записи не выполняется.

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

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

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

codecs.EncodedFile(file, input[, output[, errors]])

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

Строки, написанные в обернутый файл, интерпретируются в соответствии с заданной кодировкой input, а затем записываются в исходный файл в виде строк, используя кодировку output. Промежуточной кодировкой обычно будет Юникод, но зависит от указанных кодеков.

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

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

codecs.iterencode(iterable, encoding[, errors])

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

Новое в версии 2.5.

codecs.iterdecode(iterable, encoding[, errors])

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

Новое в версии 2.5.

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

codecs.BOM

codecs.BOM_BE

codecs.BOM_LE

codecs.BOM_UTF8

codecs.BOM_UTF16

codecs.BOM_UTF16_BE

codecs.BOM_UTF16_LE

codecs.BOM_UTF32

codecs.BOM_UTF32_BE

codecs.BOM_UTF32_LE

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

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

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

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

Класс Codec определяет интерфейс для бессостоятельных кодировщиков/декодеров.

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

Множество разрешённых значений может быть расширено через register_error().

1.1. Объекты кодеков

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

Codec.encode(input[, errors])

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

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

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

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

Codec.decode(input[, errors])

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

input должен быть объектом, предоставляющим слот буфера bf_getreadbuf. Примеры объектов, предоставляющих этот слот: строки Python, объекты буферов и файлы с отображением памяти.

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

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

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

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

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

1.2. Объекты IncrementalEncoder

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

class codecs.IncrementalEncoder([errors])

Конструктор объекта IncrementalEncoder.

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

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

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

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

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

encode(object[, final])

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

reset()

Сбросить кодировщик в исходное состояние.

1.3. Объекты IncrementalDecoder

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

class codecs.IncrementalDecoder([errors])

Конструктор объекта IncrementalDecoder.

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

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

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

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

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

decode(object[, final])

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

reset()

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

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

1.4. Объекты StreamWriter

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

class codecs.StreamWriter(stream[, errors])

Конструктор объекта StreamWriter.

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

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

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

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

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

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

write(object)

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

writelines(list)

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

reset()

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

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

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

1.5. Объекты StreamReader

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

class codecs.StreamReader(stream[, errors])

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

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

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

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

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

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

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

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

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

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

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

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

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

Изменено в версии 2.4: Добавлен аргумент chars.

Изменено в версии 2.4.2: Добавлен аргумент firstline.

readline([size[, keepends]])

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

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

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

Изменено в версии 2.4: Добавлен аргумент keepends.

readlines([sizehint[, keepends]])

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

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

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

reset()

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

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

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

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

1.6. Объекты StreamReaderWriter

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

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

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

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

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

1.7. Объекты StreamRecoder

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

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

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

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

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

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

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

encode и decode необходимы для преобразования на фронтенде, Reader и Writer — для преобразования на бэкенде. Промежуточный формат определяется двумя наборами кодировок, например, кодировки Unicode используют Unicode в качестве промежуточной кодировки.

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

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

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

Строки Unicode хранятся во внутреннем представлении как последовательности кодовых точек (точнее, как массивы Py_UNICODE). В зависимости от способа компиляции Python (через --enable-unicode=ucs2 или --enable-unicode=ucs4, причём первый — по умолчанию) Py_UNICODE является либо 16-битным, либо 32-битным типом данных. После использования объекта Unicode вне ЦП и памяти возникает проблема с порядком байтов ЦП и способом хранения этих массивов в виде байтов. Преобразование объекта Unicode в последовательность байтов называется кодированием, а восстановление объекта Unicode из последовательности байтов — декодированием. Существует множество различных методов такого преобразования (эти методы также называются кодировками). Самый простой метод заключается в сопоставлении кодовых точек 0–255 с байтами 0x0–0xff. Это означает, что объект Unicode, содержащий кодовые точки выше U+00FF, не может быть закодирован этим методом (который называется 'latin-1' или 'iso-8859-1'). unicode.encode() сгенерирует исключение UnicodeEncodeError, которое выглядит так: UnicodeEncodeError: 'latin-1' codec can't encode character u'\u1234' in position 3: ordinal not in range(256).

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

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

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

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

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

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

в iso-8859-1), это повышает вероятность того, что кодировка utf-8-sig может быть правильно определена по последовательности байтов. Таким образом, здесь BOM используется не для определения порядка следования байтов при формировании последовательности байтов, а как подпись, которая помогает определить кодировку. При кодировании кодек utf-8-sig запишет 0xef, 0xbb, 0xbf в качестве первых трёх байтов в файл. При декодировании utf-8-sig пропустит эти три байта, если они появятся в качестве первых трёх байтов в файле. В UTF-8 использование BOM не рекомендуется и его следует избегать в целом.

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

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

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

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

4. Python Специфичные Кодеки

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

Следующие кодеки обеспечивают кодирование unicode-to-str 1 и декодирование str-to-unicode 2, аналогично кодировкам Unicode текста.

Следующие кодеки предоставляют кодирование и декодирование str-в-str 2.

1

Объекты str также принимаются в качестве входных данных вместо объектов unicode. Они неявно преобразуются в unicode путём декодирования с использованием кодировки по умолчанию. Если это преобразование завершается неудачей, это может привести к тому, что операции кодирования будут вызывать UnicodeDecodeError.

2(1,2)

Объекты unicode также принимаются в качестве входных данных вместо объектов str. Они неявно преобразуются в str путём кодирования с использованием кодировки по умолчанию. Если это преобразование завершается неудачей, это может привести к тому, что операции декодирования будут вызывать UnicodeEncodeError.

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

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

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

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

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

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

encodings.idna.nameprep(label)

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

encodings.idna.ToASCII(label)

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

encodings.idna.ToUnicode(label)

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

6. encodings.utf_8_sig — UTF-8 кодек с подписью BOM

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