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 не возникает. Каждый байт последовательности 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, либо с помощью словарей в качестве таблиц сопоставления. В следующей таблице перечислены кодеки по имени, а также несколько распространённых псевдонимов и языки, для которых, вероятно, используется кодировка. Ни список псевдонимов, ни список языков не являются исчерпывающими. Обратите внимание: варианты написания, отличающиеся только регистром букв или использующие дефис вместо подчёркивания, также являются допустимыми псевдонимами, поскольку после нормализации с помощью normalize_encoding() они эквивалентны. Например, 'utf-8' — допустимый псевдоним кодека 'utf_8'.

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

• набор кодов ISO 8859
• кодовая страница Microsoft Windows, обычно производная от набора кодов 8859, но с управляющими символами, заменёнными дополнительными графическими символами
• кодовая страница IBM EBCDIC
• кодовая страница IBM PC, совместимая с ASCII

Специальные кодировки Python

Некоторые предопределённые кодеки предназначены специально для Python, поэтому их имена не имеют значения за пределами Python. Они перечислены в таблицах ниже в соответствии с ожидаемыми типами входных и выходных данных (обратите внимание: хотя кодеки чаще всего используются для кодирования текста, базовая инфраструктура кодеков поддерживает произвольные преобразования данных, а не только кодирование текста). Для асимметричных кодеков указанное описание относится к направлению кодирования.

encodings — пакет кодировок

Этот модуль реализует следующие функции:

encodings.normalize_encoding(encoding)

Нормализует имя кодировки encoding.

При нормализации все неалфавитно-цифровые символы, кроме точки, используемой в именах пакетов Python, объединяются и заменяются одним символом подчёркивания; начальные и конечные подчёркивания удаляются. Например, '  -;#' становится '_'.

Обратите внимание: encoding должен состоять только из символов ASCII.

encodings.search_function(encoding)

Выполняет поиск модуля кодека, соответствующего указанному имени кодировки encoding.

Сначала эта функция нормализует encoding с помощью normalize_encoding(), а затем ищет соответствующий псевдоним. Она пытается импортировать модуль кодека из пакета encodings, используя псевдоним или нормализованное имя. Если модуль найден и определяет допустимую функцию getregentry(), возвращающую объект codecs.CodecInfo, кодек кэшируется и возвращается.

Если модуль кодека определяет функцию getaliases(), все возвращённые псевдонимы регистрируются для дальнейшего использования.

Этот модуль реализует следующее исключение:

exception encodings.CodecRegistryError

Возникает, если кодек недействителен или несовместим.

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-запросах, полях Host HTTP и т. д. Это преобразование выполняется на уровне приложения; по возможности оно должно быть незаметно для пользователя: приложение должно прозрачно преобразовывать метки домена 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)

Возвращает результат применения nameprep к 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 и расположенный в начале данных, пропускается.