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 и из Unicode.

charset — каноническое имя набора символов. codecname — имя Python кодека, соответствующее второму аргументу метода str’s encode().