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 (кратчайшая из QP или 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().