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

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

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

Если вы хотите включить не-ASCII символы в заголовки email, например, в поля Subject или To, следует использовать класс 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?=

Обратите внимание, как мы хотели, чтобы поле Subject содержало не-ASCII символ? Мы сделали это, создав экземпляр Header и передав набор символов, в котором была закодирована байтовая строка. Когда последующий экземпляр Message был преобразован в плоскую строку, поле Subject было должным образом закодировано с помощью 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, например Subject), передаётся имя поля в 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) истинно), то charset – это кодировка этой строки байтов, и будет вызвано исключение UnicodeError, если строка не может быть декодирована с помощью этой кодировки.

If s is a Unicode string, then charset is a hint specifying the character set of the characters in the string. In this case, when producing an RFC 2822-compliant header using RFC 2047 rules, the Unicode string will be encoded using the following charsets in order: us-ascii, the charset hint, utf-8. The first character set to not provoke a UnicodeError is used.

Необязательный параметр 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.