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 в зависимости от используемой кодировки, или это функция, в этом случае вы должны вызвать функцию с одним аргументом, объектом сообщения, которое кодируется. Функция должна установить заголовок 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 и из Unicode.

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