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

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

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

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