email.header: Международные заголовки

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

Конечно, по мере глобального распространения электронной почты она стала интернациональной, так что теперь в сообщениях электронной почты можно использовать наборы символов, специфичные для языка. Базовый стандарт по-прежнему требует, чтобы сообщения электронной почты передавались только с помощью символов ASCII 7-битной кодировки, поэтому было написано множество 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
>>> print msg.as_string()
Subject: =?iso-8859-1?q?p=F6stal?=

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

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

class email.header.Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])

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

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

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

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

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

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

append(s[, charset[, errors]])

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

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

s может быть байтовой строкой или строкой Unicode. Если это байтовая строка (т. е. isinstance(s, str) равно true), то charset — это кодировка этой байтовой строки, и будет поднято исключение UnicodeError, если строка не может быть декодирована с этим набором символов.

Если s — строка Unicode, то charset — подсказка, указывающая набор символов символов в строке. В этом случае при создании совместимого с RFC 2822 заголовка с использованием правил RFC 2047, строка Unicode будет закодирована в следующих наборах символов в порядке: us-ascii, подсказка charset, utf-8. Первый набор символов, который не вызовет UnicodeError, используется.

Необязательное errors передаётся в любой вызов unicode() или unicode.encode(), и по умолчанию равно “strict”.

encode([splitchars])

Закодировать заголовок сообщения в формате, совместимом с RFC, возможно, разделяя длинные строки и инкапсулируя не-ASCII части в кодировки base64 или quoted-printable. Необязательное splitchars — это строка, содержащая символы для разделения длинных ASCII строк, в грубом соответствии с RFC 2822 правилами «разделителей наивысшего уровня». Это не влияет на строки, закодированные по RFC 2047.

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

__str__()

Синоним для Header.encode(). Полезно для str(aHeader).

__unicode__()

Помощник для встроенной функции unicode(). Возвращает заголовок как строку Unicode.

__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?=')
[('p\xf6stal', 'iso-8859-1')]

email.header.make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])

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

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

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