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

Базовые классы кодировщиков

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

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

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

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

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

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 module <https://pypi.org/project/idna/>_.

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

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

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, в начале данных будет пропущен.