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().