email.charset: Представление наборов символов

Исходный код: Lib/email/charset.py

Этот модуль предоставляет класс Charset для представления наборов символов и преобразований наборов символов в сообщениях электронной почты, а также реестр наборов символов и несколько удобных методов для работы с этим реестром. Экземпляры класса Charset используются в нескольких других модулях пакета email.

Импортируйте этот класс из модуля email.charset.

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

Сопоставление наборов символов с их свойствами в электронных письмах.

Этот класс предоставляет информацию о требованиях, предъявляемых к электронным письмам для определенного набора символов. Он также предоставляет удобные функции для преобразования между наборами символов при наличии соответствующих кодеков. Для заданного набора символов он сделает все возможное, чтобы предоставить информацию о том, как использовать этот набор символов в сообщении электронной почты в соответствии с RFC.

Некоторые наборы символов должны кодироваться с использованием quoted-printable или base64 при использовании в заголовках или телах электронных писем. Некоторые наборы символов должны быть преобразованы, и их использование в электронных письмах запрещено.

Необязательный параметр input_charset описан ниже; он всегда преобразуется в нижний регистр. После нормализации псевдонима он также используется в качестве ключа для поиска в реестре наборов символов, чтобы узнать кодировку заголовков, кодировку тела и кодек преобразования вывода для данного набора символов. Например, если input_charset равен iso-8859-1, то заголовки и тела будут кодироваться с помощью quoted-printable, и преобразование кодека вывода не требуется. Если input_charset равен euc-jp, то заголовки будут кодироваться с помощью base64, тела не будут кодироваться, но текст вывода будет преобразован из набора символов euc-jp в набор символов iso-2022-jp.

Экземпляры класса Charset имеют следующие атрибуты данных:

input_charset

Начальный набор символов. Общие псевдонимы преобразуются в свои официальные имена в электронных письмах (например, latin_1 преобразуется в iso-8859-1). По умолчанию используется 7-битный набор символов us-ascii.

header_encoding

Если набор символов должен быть закодирован перед использованием в заголовке электронного письма, этот атрибут будет иметь значение Charset.QP (для кодировки quoted-printable), Charset.BASE64 (для кодировки base64) или Charset.SHORTEST для наименьшего из QP или BASE64 кодирования. В противном случае, он будет иметь значение None.

body_encoding

Аналогично header_encoding, но описывает кодировку для тела сообщения электронной почты, которая может отличаться от кодировки заголовка. Charset.SHORTEST не допускается для body_encoding.

output_charset

Некоторые наборы символов должны быть преобразованы перед использованием в заголовках или телах электронных писем. Если input_charset относится к ним, этот атрибут будет содержать имя набора символов, к которому будет преобразован вывод. В противном случае, он будет None.

input_codec

Имя Python-кодека, используемого для преобразования input_charset в Unicode. Если преобразование кодека не требуется, этот атрибут будет None.

output_codec

Имя Python-кодека, используемого для преобразования Unicode в output_charset. Если преобразование кодека не требуется, этот атрибут будет иметь то же значение, что и input_codec.

Экземпляры Charset также имеют следующие методы:

get_body_encoding()

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

Это либо строка quoted-printable или base64 в зависимости от используемой кодировки, либо это функция, в таком случае вы должны вызвать функцию с одним аргументом, объектом Message, который кодируется. Функция затем должна установить заголовок Content-Transfer-Encoding сам по себе, в соответствии с тем, что подходит.

Возвращает строку quoted-printable если body_encoding равно QP, возвращает строку base64 если body_encoding равно BASE64, и возвращает строку 7bit в противном случае.

get_output_charset()

Возвращает выходной набор символов.

Это атрибут output_charset, если он не равен None, в противном случае это input_charset.

header_encode(string)

Кодирует заголовок строки string.

Тип кодирования (base64 или quoted-printable) будет основан на атрибуте header_encoding.

header_encode_lines(string, maxlengths)

Кодирует заголовок строки string, сначала преобразовав её в байты.

Это аналогично header_encode(), за исключением того, что строка разбивается на строки максимальной длины, заданной аргументом maxlengths, который должен быть итератором: каждый элемент, возвращаемый этим итератором, указывает следующую максимальную длину строки.

body_encode(string)

Кодирует тело строки string.

Тип кодирования (base64 или quoted-printable) будет основан на атрибуте body_encoding.

Класс Charset также предоставляет ряд методов для поддержки стандартных операций и встроенных функций.

__str__()

Возвращает input_charset в виде строки, преобразованной в нижний регистр. __repr__() является псевдонимом для __str__().

__eq__(other)

Этот метод позволяет сравнивать два объекта Charset на равенство.

__ne__(other)

Этот метод позволяет сравнивать два объекта Charset на неравенство.

Модуль email.charset также предоставляет следующие функции для добавления новых записей в глобальные реестры наборов символов, псевдонимов и кодеков:

email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)

Добавление свойств набора символов в глобальный реестр.

charset — входной набор символов, и должен быть каноническим именем набора символов.

Необязательные header_enc и body_enc могут быть равны Charset.QP для кодирования quoted-printable, Charset.BASE64 для кодирования base64, Charset.SHORTEST для наименьшего из кодирования quoted-printable или base64, или None для отсутствия кодирования. SHORTEST допустимо только для header_enc. По умолчанию используется None для отсутствия кодирования.

Необязательный output_charset — набор символов для вывода. Преобразования будут происходить от входного набора символов, к Unicode, к выходному набору символов, когда вызывается метод Charset.convert(). По умолчанию вывод будет в том же наборе символов, что и вход.

И input_charset, и output_charset должны иметь записи кодеков Unicode в сопоставлении набора символов-кодек модуля; используйте add_codec() для добавления кодеков, которые модуль не знает. Смотрите документацию модуля codecs для получения дополнительной информации.

Глобальный реестр наборов символов хранится в глобальном словаре модуля CHARSETS.

email.charset.add_alias(alias, canonical)

Добавление псевдонима набора символов. alias — имя псевдонима, например, latin-1. canonical — каноническое имя набора символов, например, iso-8859-1.

Глобальный реестр псевдонимов наборов символов хранится в глобальном словаре модуля ALIASES.

email.charset.add_codec(charset, codecname)

Добавление кодека, который сопоставляет символы в заданном наборе символов с Unicode и из него.

charset — каноническое имя набора символов. codecname — имя Python-кодека, соответствующее второму аргументу метода str’s encode().