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 — представлять каждую кодовую точку четырьмя последовательными байтами. Есть два варианта: хранить байты в порядке от старшего к младшему или от младшего к старшему. Эти две кодировки называются соответственно UTF-32-BE и UTF-32-LE. Их недостаток заключается в том, что, например, при использовании UTF-32-BE на машине с порядком байтов от младшего к старшему байты при кодировании и декодировании всегда приходится переставлять. 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 состоит из двух частей: битов-маркеров (старших битов) и битов полезной нагрузки. Биты-маркеры представляют собой последовательность из нуля — четырёх битов 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 в файл записывается BOM в кодировке UTF-8 (в виде последовательности байтов: 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, обработанную процедурой nameprep. Текущая реализация предполагает, что это строки запроса, поэтому 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 в начале данных пропускается.