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)

Кодирует заголовок строки 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().