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)

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

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

body_encode(string)

Тело-кодировка строки string.

Тип кодировки (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=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.

email.charset.add_codec(charset, codecname)

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

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