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