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'.

Многие наборы символов поддерживают одни и те же языки. Они различаются отдельными символами (например, поддерживается ли символ 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 и так далее. Это преобразование выполняется в приложении; по возможности, незаметно для пользователя: Приложение должно прозрачно преобразовывать метки доменных имён 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 — Кодировка Windows ANSI

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

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

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