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

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

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

Каждый кодек должен определить четыре интерфейса, чтобы его можно было использовать как кодек в Python: stateless encoder, stateless decoder, stream reader и stream writer. Читатель и писатель потоков обычно повторно используют кодер/декодер без статики для реализации файловых протоколов. Авторам кодеков также необходимо определить, как кодек будет обрабатывать ошибки кодирования и декодирования.

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

Кодировки и Юникод¶

Строки хранятся внутри как последовательности кодовых точек в диапазоне U+0000–U+10FFFF. (Более подробно о реализации см. в PEP 393.) Как только строковый объект используется за пределами процессора и памяти, становится актуальным вопрос о конечности и о том, как эти массивы хранятся в виде байтов. Как и в других кодеках, сериализация строки в последовательность байтов называется кодированием, а воссоздание строки из последовательности байтов - декодированием. Существует множество различных кодеков сериализации текста, которые собирательно называются text encodings.

Простейшая кодировка текста (называемая '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. Простой и понятный способ хранения каждой кодовой точки Юникода - это хранение каждой кодовой точки в виде четырех последовательных байтов. Есть две возможности: хранить байты в порядке 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»). Это символ Юникода 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. Символы Юникода кодируются следующим образом (с x - биты полезной нагрузки, которые при объединении дают символ Юникода):

Наименьший значащий бит символа Unicode - это самый правый х-бит.

Поскольку 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") для своей программы Notepad: Перед записью в файл любого из символов Unicode записывается BOM в кодировке UTF-8 (которая в виде последовательности байтов выглядит так: 0xef, 0xbb, 0xbf). Поскольку довольно маловероятно, что любой файл, закодированный в charmap, начинается с этих значений байтов (которые, например, отображаются на

ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I С ДИЕРЕЗИСОМ

НАПРАВЛЕННАЯ ВПРАВО ДВОЙНАЯ УГЛОВАЯ КАВЫЧКА

ПЕРЕВЁРНУТЫЙ ВОПРОСИТЕЛЬНЫЙ ЗНАК

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

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

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

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

• набор кодов 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 module.

Эти 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, разделяя входную строку на метки на основе символов-разделителей, определенных в section 3.1 of RFC 3490, и преобразуя каждую метку в ACE по мере необходимости, и наоборот, разделяя входную байтовую строку на метки на основе разделителя . и преобразуя все найденные метки ACE в юникод. Более того, модуль socket прозрачно преобразует имена хостов Unicode в ACE, так что приложениям не нужно заботиться о преобразовании имен хостов, когда они передают их модулю сокета. Кроме того, модули, имеющие имена хостов в качестве параметров функций, такие как http.client и ftplib, принимают имена хостов в Unicode (http.client затем также прозрачно передает имя хоста IDNA в поле Host, если вообще передает это поле).

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

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

encodings.idna.nameprep(label)¶

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

encodings.idna.ToASCII(label)¶

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

encodings.idna.ToUnicode(label)¶

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

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

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

Availability: Только Windows.

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

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