email.charset: Представление наборов символов

Исходный код: Lib/email/charset.py

Этот модуль относится к устаревшему API электронной почты (Compat32). В новом 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 задаёт набор символов, в котором должны быть представлены выходные данные. При вызове метода Charset.convert() преобразование выполняется из входного набора символов в Unicode, а затем в выходной набор. По умолчанию выходные данные представлены в том же наборе символов, что и входные.

Для 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 encode().