email.header: Интернационализированные заголовки

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

Этот модуль является частью устаревшего (Compat32) API для работы с электронной почтой. В текущем API кодирование и декодирование заголовков обрабатываются прозрачно с помощью подобного словарю API класса EmailMessage. Помимо использования в устаревшем коде, этот модуль может быть полезен в приложениях, которые нуждаются в полном контроле над наборами символов, используемых при кодировании заголовков.

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

RFC 2822 является базовым стандартом, описывающим формат сообщений электронной почты. Он происходит от более старого стандарта RFC 822, который стал широко распространённым в то время, когда большинство сообщений электронной почты состояло только из символов ASCII. RFC 2822 — это спецификация, написанная с предположением, что сообщения электронной почты содержат только символы 7-битного ASCII.

Конечно, по мере глобального распространения электронной почты она стала интернационализированной, так что теперь в сообщениях электронной почты можно использовать наборы символов, специфичные для языка. Базовый стандарт по-прежнему требует, чтобы сообщения электронной почты передавались только с использованием символов 7-битного ASCII, поэтому было написано множество RFC, описывающих, как закодировать электронную почту, содержащую символы, не являющиеся ASCII, в формат, совместимый с RFC 2822. Эти RFC включают RFC 2045, RFC 2046, RFC 2047 и RFC 2231. Пакет email поддерживает эти стандарты в своих модулях email.header и email.charset.

Если вы хотите включить символы, не являющиеся ASCII, в свои заголовки электронных писем, например, в поля Тема или Кому, вы должны использовать класс Header и присвоить поле в объекте Message экземпляру класса Header вместо использования строки для значения заголовка. Импортируйте класс Header из модуля email.header. Например:

>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

Обратите внимание, как мы хотели, чтобы поле Тема содержало символ, не являющийся ASCII? Мы сделали это, создав экземпляр Header и передав набор символов, в котором была закодирована строка байтов. При последующем развёртывании объекта Message поле Тема было должным образом закодировано по RFC 2047. Совместимые с MIME программы чтения почты отображали бы этот заголовок с использованием встроенного набора символов ISO-8859-1.

Вот описание класса Header:

class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

Создайте заголовок MIME, который может содержать строки в разных наборах символов.

Необязательный параметр s — это начальное значение заголовка. Если None (по умолчанию), начальное значение заголовка не задано. Позже вы можете добавить в заголовок с помощью вызовов метода append(). s может быть экземпляром bytes или str, но см. документацию метода append() для семантики.

Необязательный параметр charset выполняет две задачи: он имеет то же значение, что и аргумент charset для метода append(). Он также устанавливает набор символов по умолчанию для всех последующих вызовов метода append(), которые опускают аргумент charset. Если в конструкторе не указан параметр charset (по умолчанию), используется набор символов us-ascii, как начальный набор символов для s, и как набор символов по умолчанию для последующих вызовов метода append().

Максимальная длина строки может быть явно задана через maxlinelen. Для разделения первой строки на более короткую строку (для учета заголовка поля, который не включен в s, например, Subject) передайте имя поля в параметре header_name. Значение maxlinelen по умолчанию равно 76, а значение header_name по умолчанию равно None, что означает, что он не учитывается для первой строки длинного разделяемого заголовка.

Необязательный параметр continuation_ws должен быть соответствовать требованиям RFC 2822 (пробел или табуляция), и обычно является пробелом или символом табуляции. Этот символ будет добавлен в начало продолжения строк. Значение continuation_ws по умолчанию — одиночный пробел.

Необязательный параметр errors передаётся непосредственно методу append().

append(s, charset=None, errors='strict')

Добавить строку s к заголовку MIME.

Необязательный параметр charset, если задан, должен быть экземпляром Charset (см. email.charset) или именем набора символов, который будет преобразован в экземпляр Charset. Значение None (по умолчанию) означает, что используется charset, указанный в конструкторе.

s может быть экземпляром bytes или str. Если это экземпляр bytes, тогда charset — это кодировка этой строки байтов, и будет поднято исключение UnicodeError, если строку нельзя декодировать с помощью этого набора символов.

Если s является экземпляром str, тогда charset — это подсказка, указывающая набор символов символов в строке.

В любом случае при создании заголовка, соответствующего RFC 2822, используя правила RFC 2047, строка будет закодирована с использованием кодировки вывода набора символов. Если строку нельзя закодировать с помощью кодировки вывода, будет поднято исключение UnicodeError.

Необязательный параметр errors передаётся как аргумент errors в вызов decode, если s является строкой байтов.

encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

Кодирует заголовок сообщения в соответствии с RFC, возможно, разбивая длинные строки и заключая не-ASCII части в кодировки base64 или quoted-printable.

Необязательный параметр splitchars — это строка, содержащая символы, которым алгоритм разделения должен уделить больше внимания при нормальном разбиении заголовка. Это приближенная поддержка «синтаксических разрывов на более высоком уровне» RFC 2822: точки разбиения, предваряемые символом разбиения, предпочтительнее при разбиении строк, а символы предпочтительнее в порядке их появления в строке. Пробел и табуляция могут быть включены в строку, чтобы указать, какой из них следует предпочесть в качестве точки разбиения, когда другие символы разбиения не появляются в разделяемой строке. Splitchars не влияет на строки, закодированные в формате RFC 2047.

maxlinelen, если задано, переопределяет значение максимальной длины строки экземпляра.

linesep задаёт символы, используемые для разделения строк в заголовке. По умолчанию используется наиболее полезное значение для кода приложения Python (\n), но \r\n может быть указано, чтобы создать заголовки с разделителями строк, соответствующими RFC.

Изменено в версии 3.2: Добавлен аргумент linesep.

Класс Header также предоставляет ряд методов для поддержки стандартных операторов и встроенных функций.

__str__()

Возвращает приблизительное представление Header как строку, используя неограниченную длину строки. Все части преобразуются в юникод с использованием указанной кодировки и объединяются соответствующим образом. Любые части с набором символов 'unknown-8bit' декодируются как ASCII с обработчиком ошибок 'replace'.

Изменено в версии 3.2: Добавлена обработка набора символов 'unknown-8bit'.

__eq__(other)

Этот метод позволяет сравнивать два экземпляра Header на равенство.

__ne__(other)

Этот метод позволяет сравнивать два экземпляра Header на неравенство.

Модуль email.header также предоставляет следующие удобные функции.

email.header.decode_header(header)

Декодирует значение заголовка сообщения без преобразования набора символов. Значение заголовка содержится в header.

Функция возвращает список пар (decoded_string, charset) содержащих каждую из декодированных частей заголовка. charset равно None для незакодированных частей заголовка, в противном случае — строка в нижнем регистре, содержащая имя набора символов, указанное в закодированной строке.

Вот пример:

>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]

email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

Создаёт экземпляр Header из последовательности пар, как возвращает функция decode_header().

decode_header() принимает строку значения заголовка и возвращает последовательность пар в формате (decoded_string, charset), где charset — имя набора символов.

Эта функция принимает одну из таких последовательностей пар и возвращает экземпляр Header. Необязательные параметры maxlinelen, header_name и continuation_ws аналогичны параметрам конструктора Header.