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 — хранить каждую кодовую точку как четыре последовательных байта. Есть два варианта: хранить байты в порядке 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, это устройство для определения схемы хранения закодированных байтов, и исчезает после декодирования последовательности байтов в строку; как 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'.

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

• набор символов 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 и т. д. Это преобразование выполняется в приложении; если возможно, незаметно для пользователя: приложение должно прозрачно преобразовывать метки 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. Реализация в настоящее время предполагает запросы, поэтому AllowUnassigned имеет значение true.

encodings.idna.ToASCII(label)

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

encodings.idna.ToUnicode(label)

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

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

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

encodings.utf_8_sig — Кодировка UTF-8 с сигнатурой BOM

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