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

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

Этот модуль является частью устаревшего (Compat32) API электронной почты. В новом API используется только таблица псевдонимов.

Остальной текст в этом разделе представляет собой оригинальную документацию модуля.

Этот модуль предоставляет класс 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)¶

Заголовки кодируют строку, преобразуя ее сначала в байты.

Это аналогично 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 - это набор символов, в котором должен быть вывод. При вызове метода Charset.convert() преобразования будут выполняться от входного набора символов к Юникоду и выходному набору символов. По умолчанию вывод осуществляется в том же наборе символов, что и ввод.

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

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

email.charset.add_alias(alias, canonical)¶

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

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

email.charset.add_codec(charset, codecname)¶

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

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