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 на машине с порядком байтов от младшего к старшему при кодировании и декодировании всегда потребуется менять байты местами. Кодеки Python UTF-16 и UTF-32 избегают этой проблемы, используя собственный порядок байтов платформы, если BOM отсутствует. Python следует сложившейся практике платформ, поэтому данные в собственном порядке байтов преобразуются туда и обратно без избыточной перестановки байтов, хотя по умолчанию стандарт Unicode предписывает порядок от старшего к младшему, если порядок байтов не указан. При чтении этих байтов процессором с другим порядком байтов их необходимо поменять местами. Для определения порядка байтов последовательности байтов 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'.

В Windows доступны кодеки cpXXX для всех кодовых страниц. Однако на других платформах гарантированно существуют только кодеки, перечисленные в следующей таблице.

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

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

Специфичные для Python кодировки

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

encodings — пакет Encodings

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

encodings.normalize_encoding(encoding)

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

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

Обратите внимание, что encoding должен содержать только символы ASCII.

encodings.search_function(encoding)

Ищет модуль кодека, соответствующий заданному имени кодировки encoding.

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

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

encodings.win32_code_page_search_function(encoding)

Ищет кодировку кодовой страницы Windows encoding в формате cpXXXX.

Если кодовая страница допустима и поддерживается, возвращает для неё объект codecs.CodecInfo.

Доступность: Windows.

Добавлено в версии 3.14.

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

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)

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