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.

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

email.charset.add_codec(charset, codecname)

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

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