18.1.6. email.charset: Представление наборов символов¶email.charset: Representing character sets

Этот модуль предоставляет класс 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 для «обратного разделения».

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

Символы, которые не удалось преобразовать из 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 – это кодировка, в которой должен быть вывод. Преобразования будут выполняться от входной кодировки к 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 и обратно.

charset – это каноническое имя набора символов. codecname – это имя кодека Python, соответствующее второму аргументу встроенной функции unicode() или методу encode() строки Unicode.