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

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

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

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

Класс Charset импортируется из модуля 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.SWORTEST для самой короткой кодировки QP или BASE64. В противном случае будет None.

body_encoding

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

output_charset

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

input_codec

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

output_codec

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

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

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

email.charset.add_alias(alias, canonical)

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

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

email.charset.add_codec(charset, codecname)

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

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