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

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

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

class email.charset.Charset([input_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 в противном случае.

convert(s)

Преобразует строку s из input_codec в output_codec.

to_splittable(s)

Преобразует, возможно, многобайтовую строку в формат, безопасный для разделения. s — это строка для разделения.

Использует input_codec для попытки преобразования строки в Unicode, чтобы она могла быть безопасно разделена на границах символов (даже для многобайтовых символов).

Возвращает строку как есть, если неизвестно, как преобразовать s в Unicode с помощью input_charset.

Символы, которые не удалось преобразовать в Unicode, будут заменены символом замены Unicode 'U+FFFD'.

from_splittable(ustr[, to_output])

Преобразует строку, разбиваемую по разделителям, обратно в закодированную строку. ustr — это строка Юникод для «раздвоения».

Этот метод использует соответствующий кодек для попытки преобразования строки из Юникода обратно в закодированный формат. Возвращает строку как есть, если она не является строкой Юникод или если её не удалось преобразовать из Юникода.

Символы, которые не удалось преобразовать из Unicode, будут заменены соответствующим символом (обычно '?').

Если to_output равен True (по умолчанию), используется output_codec для преобразования в закодированный формат. Если to_output равен False, используется input_codec.

get_output_charset()

Возвращает набор символов вывода.

Это атрибут output_charset, если он не равен None, в противном случае это input_charset.

encoded_header_len()

Возвращает длину закодированной строки заголовка, правильно учитывая кодировку quoted-printable или base64.

header_encode(s[, convert])

Кодирует заголовок строки s.

Если convert равен True, строка будет автоматически преобразована из набора символов ввода в набор символов вывода. Это не полезно для многобайтовых наборов символов, которые имеют проблемы с длиной строки (многобайтовые символы должны быть разделены на символ, а не на байт); используйте класс Header более высокого уровня для решения этих проблем (см. email.header). convert по умолчанию равен False.

Тип кодировки (base64 или quoted-printable) будет основан на атрибуте header_encoding.

body_encode(s[, convert])

Кодирует тело строки s.

Если convert равен True (по умолчанию), строка будет автоматически преобразована из набора символов ввода в набор символов вывода. В отличие от header_encode(), проблемы с границами байтов и многобайтовыми наборами символов в телах электронных писем обычно отсутствуют, поэтому это обычно достаточно безопасно.

Тип кодировки (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[, body_enc[, output_charset]]])

Добавить свойства символов в глобальную базу данных.

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 должны иметь записи кодека Юникода в отображении набора символов модуля; используйте add_codec() для добавления кодеков, которые модуль не знает. См. документацию модуля codecs для получения дополнительной информации.

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

email.charset.add_alias(alias, canonical)

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

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

email.charset.add_codec(charset, codecname)

Добавить кодек, отображающий символы данного набора символов в Юникод и обратно.

charset — это каноническое имя набора символов. codecname — имя Python-кодека, как это подходит для второго аргумента встроенной функции unicode() или для метода encode() строки Юникода.