codecs – Реестр кодеков и базовые классы¶codecs – Codec registry and base classes

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

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

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

Кодировки и Unicode¶Encodings and 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-кодировки), которые выбирают другое подмножество всех кодовых точек Юникода и определяют, как эти кодовые точки отображаются на байты 0x0–0xff. Чтобы увидеть, как это работает, достаточно открыть, например, encodings/cp1252.py (кодировку, которая в основном используется в Windows). В ней есть строковая константа из 256 символов, показывающая, какой символ какому значению байта соответствует.

Все эти кодировки могут кодировать только 256 из 1 114 112 кодовых точек, определённых в Unicode. Простой и прямой способ хранить каждую кодовую точку Unicode – хранить каждую кодовую точку в виде четырёх последовательных байтов. Есть две возможности: хранить байты в порядке big endian или little endian. Эти две кодировки называются UTF-32-BE и UTF-32-LE соответственно. Их недостаток в том, что если, например, использовать UTF-32-BE на машине с little endian, то при кодировании и декодировании придётся всегда менять порядок байтов. UTF-32 избегает этой проблемы: байты всегда будут в естественном порядке байтов. Однако когда эти байты читаются процессором с другим порядком байтов, байты всё равно приходится переставлять. Чтобы можно было определить порядок байтов последовательности UTF-16 или UTF-32, существует так называемая BOM («метка порядка байтов»). Это символ 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") для своей программы 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 не рекомендуется и его обычно следует избегать.

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

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

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

• набор символов ISO 8859

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

• кодовая страница IBM EBCDIC

• кодовая страница IBM PC, совместимая с ASCII

Специфичные для Python кодировки¶Python Specific Encodings

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

encodings.idna – Интернационализированные доменные имена в приложениях¶encodings.idna – Internationalized Domain Names in Applications

Этот модуль реализует RFC 3490 (Internationalized Domain Names in Applications) и RFC 3492 (Nameprep: профиль Stringprep для интернационализированных доменных имен (IDN)). Он основан на кодировке punycode и stringprep.

Если требуется стандарт IDNA 2008 из RFC 5891 и RFC 5895, используйте сторонний модуль idna <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, так что приложениям не нужно беспокоиться о преобразовании имён хостов самостоятельно при передаче их в модуль socket. Вдобавок, модули, которые принимают имена хостов в качестве параметров функций, такие как http.client и ftplib, принимают Unicode-имена хостов (http.client затем также прозрачно отправляет IDNA-имя хоста в поле Host, если вообще отправляет это поле).

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

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

encodings.idna.nameprep(label)¶

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

encodings.idna.ToASCII(label)¶

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

encodings.idna.ToUnicode(label)¶

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

encodings.mbcs – кодовая страница Windows ANSI¶encodings.mbcs – Windows ANSI codepage

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

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

encodings.utf_8_sig – UTF-8 кодек с сигнатурой BOM¶encodings.utf_8_sig – UTF-8 codec with BOM signature

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