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

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

Без внешней информации невозможно надёжно определить, какая кодировка была использована для кодирования строки. Каждая кодировка символьных наборов может декодировать любую случайную последовательность байтов. Однако это невозможно с UTF-8, так как последовательности байтов UTF-8 имеют структуру, не позволяющую произвольных последовательностей байтов. Для повышения надёжности определения кодировки UTF-8 Microsoft разработала вариант UTF-8 (который Python называет "utf-8-sig") для своей программы Блокнот: перед записью любого символа Unicode в файл записывается закодированный в UTF-8 BOM (который выглядит так в виде последовательности байтов: 0xef, 0xbb, 0xbf). Так как маловероятно, что любой файл, закодированный в символьных наборах, начинается с этих значений байтов (которые, например, отображаются в

в 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 — Кодировка ANSI Windows

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

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

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