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

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

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

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

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

Обзор кодировок и 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 («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 это устройство для определения структуры хранения закодированных байтов и исчезает после декодирования последовательности байтов в строку; как 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 символ в декодированной строке (даже если это первый символ) обрабатывается как ZERO WIDTH NO-BREAK SPACE.

Без внешней информации невозможно надёжно определить, какая кодировка использовалась для кодирования строки. Каждая кодировка charmap может декодировать любую случайную последовательность байтов. Однако это невозможно с UTF-8, так как последовательности байтов UTF-8 имеют структуру, не допускающую произвольных последовательностей байтов. Для повышения надёжности распознавания кодировки UTF-8 Microsoft придумала вариант UTF-8 (который Python называет "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 не рекомендуется и, как правило, следует избегать.

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

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

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

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

Утилиты кодирования, специфичные для Python

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

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 и так далее. Это преобразование выполняется в приложении; по возможности, незаметно для пользователя: приложение должно прозрачно преобразовывать метки доменных имён Юникода в IDNA в сети и преобразовывать метки ACE обратно в Юникод перед представлением их пользователю.

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

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

Модуль 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)

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

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

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

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

encodings.utf_8_sig — UTF-8 кодировка с подписью BOM

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