18.1.6. email.charset: Представление наборов символов¶email.charset: Representing character sets
Этот модуль предоставляет класс Charset для представления кодировок и преобразования кодировок в email-сообщениях, а также реестр кодировок и несколько удобных методов для работы с этим реестром. Экземпляры 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¶
Указанная исходная кодировка. Распространённые псевдонимы преобразуются в их официальные email-имена (например, latin_1 преобразуется в iso-8859-1). По умолчанию – 7-битная us-ascii.
- header_encoding¶
Если кодировку необходимо закодировать перед использованием в заголовке email, этот атрибут будет установлен в Charset.QP (для quoted-printable), Charset.BASE64 (для кодирования base64) или Charset.SHORTEST для наикратчайшего из QP или BASE64. В противном случае он будет равен None.
- body_encoding¶
Аналогично header_encoding, но описывает кодировку для тела почтового сообщения, которая может отличаться от кодировки заголовка. Charset.SHORTEST не допускается для body_encoding.
- output_charset¶
Некоторые кодировки необходимо преобразовать перед использованием в заголовках или телах email. Если 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__().
Модуль 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.