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 и обратно.

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