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)¶
Кодируйте строку, преобразуя ее сначала в байты.
Это аналогично
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 - это набор символов, в котором должен быть выполнен вывод. При вызове метода
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
.