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

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

Этот модуль является частью устаревшего (Compat32) API email. В новом 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().