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

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

Этот модуль является частью устаревшего (Compat32) почтового API. В новом API используется только таблица псевдонимов.

Оставшийся текст в этом разделе представляет собой оригинальную документацию по модулю.

Этот модуль предоставляет класс Charset для представления наборов символов и преобразований наборов символов в сообщениях электронной почты, а также реестр наборов символов и несколько удобных методов управления этим реестром. Экземпляры Charset используются в нескольких других модулях пакета email.

Импортируйте этот класс из модуля email.charset.

class email.charset.Charset(input_charset=DEFAULT_CHARSET)¶

Сопоставьте наборы символов с их свойствами электронной почты.

Этот класс предоставляет информацию о требованиях, предъявляемых к электронной почте для определенного набора символов. Он также предоставляет удобные процедуры для преобразования между наборами символов, учитывая доступность соответствующих кодеков. Учитывая набор символов, мы сделаем все возможное, чтобы предоставить информацию о том, как использовать этот набор символов в сообщении электронной почты в соответствии с RFC.

Некоторые наборы символов должны быть закодированы с помощью кавычек-printable или base64, если они используются в заголовках или текстах сообщений электронной почты. Некоторые наборы символов должны быть преобразованы напрямую и не допускаются в электронной почте.

Необязательный параметр input_charset, как описано ниже; он всегда вводится в нижний регистр. После нормализации псевдонима он также используется для поиска в реестре наборов символов, чтобы узнать кодировку заголовка, основную кодировку и кодек преобразования выходных данных, которые будут использоваться для набора символов. Например, если значение input_charset равно iso-8859-1, то заголовки и текстовые части будут закодированы с использованием функции печати в кавычках, и кодек преобразования выходных данных не потребуется. Если значение 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 (для печати в кавычках), 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 в зависимости от используемой кодировки, либо это функция, и в этом случае вы должны вызвать функцию с одним аргументом, в котором кодируется объект сообщения. Затем функция должна установить для самого заголовка 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 или с возможностью печати в кавычках) будет зависеть от атрибута header_encoding.

header_encode_lines(string, maxlengths)¶

Заголовок - кодирует строку, сначала преобразуя ее в байты.

Это аналогично header_encode(), за исключением того, что строка соответствует максимальной длине строки, заданной аргументом maxlengths, который должен быть итератором: каждый элемент, возвращаемый этим итератором, будет указывать следующую максимальную длину строки.

body_encode(string)¶

Тело - закодируйте строку string.

Тип кодировки (base64 или с возможностью печати в кавычках) будет зависеть от атрибута 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 для печати в кавычках, Charset.BASE64 для кодировки base64, Charset.SHORTEST для самой короткой из кодировок для печати в кавычках или base64, либо None для никакой кодировки. SHORTEST допустимо только для header_enc. По умолчанию используется None без кодировки.

Необязательный output_charset - это набор символов, в котором должны быть представлены выходные данные. При вызове метода Charset.convert() будут выполнены преобразования из входной кодировки в Unicode в выходную кодировку. По умолчанию выводится тот же набор символов, что и при вводе.

Как input_charset, так и output_charset должны содержать записи кодека Unicode в модуле character-set-to-codecmapping; используйте add_codec() для добавления кодеков, о которых модуль не знает. Смотрите документацию к модулю codecs для получения дополнительной информации.

Глобальный реестр кодировок хранится в модуле global dictionary CHARSETS.

email.charset.add_alias(alias, canonical)¶

Добавьте псевдоним набора символов. alias - это имя псевдонима, например latin-1. canonical - это каноническое имя набора символов, например iso-8859-1.

Глобальный реестр псевдонимов кодировок хранится в модуле global dictionary ALIASES.

email.charset.add_codec(charset, codecname)¶

Добавьте кодек, который преобразует символы из заданного набора символов в Юникод и обратно.

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