email: Интернационализированные заголовки¶email: Internationalized headers
RFC 2822 – это базовый стандарт, описывающий формат email-сообщений. Он происходит от более старого стандарта RFC 822, который получил широкое распространение в то время, когда большинство писем состояло только из символов ASCII. RFC 2822 – это спецификация, написанная в предположении, что email содержит только 7-битные символы ASCII.
Of course, as email has been deployed worldwide, it has become internationalized, such that language specific character sets can now be used in email messages. The base standard still requires email messages to be transferred using only 7-bit ASCII characters, so a slew of RFCs have been written describing how to encode email containing non-ASCII characters into RFC 2822-compliant format. These RFCs include RFC 2045, RFC 2046, RFC 2047, and RFC 2231. The email package supports these standards in its email.header and email.charset modules.
Чтобы включить не-ASCII символы в заголовки электронных писем, например в поля 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 может быть экземпляром bytes или str, но за разъяснением семантики обратитесь к документации append().
Optional charset serves two purposes: it has the same meaning as the charset argument to the append() method. It also sets the default character set for all subsequent append() calls that omit the charset argument. If charset is not provided in the constructor (the default), the us-ascii character set is used both as s‘s initial charset and as the default for subsequent append() calls.
Максимальную длину строки можно явно указать через maxlinelen. Чтобы разбить первую строку на более короткое значение (с учётом заголовка поля, который не включён в s, например, Subject), передайте имя поля в header_name. Значение maxlinelen по умолчанию равно 76, а значение header_name по умолчанию – None, то есть оно не учитывается для первой строки длинного разделённого заголовка.
Необязательный параметр continuation_ws должен быть RFC 2822-совместимым пробельным символом для переноса и обычно представляет собой либо пробел, либо символ табуляции. Этот символ будет добавляться в начало строк продолжения.
Необязательный параметр errors передаётся напрямую методу append().
- append(s[, charset[, errors]])¶
Добавляет строку s к MIME-заголовку.
Необязательный параметр charset, если указан, должен быть экземпляром Charset (см. email.charset) или именем кодировки, которая будет преобразована в экземпляр Charset. Значение None (по умолчанию) означает, что используется charset, указанный в конструкторе.
s может быть экземпляром bytes или str. Если это экземпляр bytes, то charset – это кодировка этой байтовой строки, и будет вызвано исключение UnicodeError, если строку невозможно декодировать с помощью этой кодировки.
Если s является экземпляром str, то charset – это подсказка, указывающая кодировку символов в строке. В этом случае при создании заголовка, совместимого с RFC 2822, с использованием правил RFC 2047, строка Unicode будет закодирована с помощью следующих кодировок по порядку: us-ascii, подсказка charset, utf-8. Используется первая кодировка, которая не вызывает UnicodeError.
Необязательный параметр errors передаётся в любой вызов encode() или ustr.encode() и по умолчанию равен "strict".
- encode([splitchars])¶
- Кодирует заголовок сообщения в формат, совместимый с RFC, возможно, с переносом длинных строк и заключением не-ASCII частей в кодировки base64 или quoted-printable. Необязательный параметр splitchars – это строка, содержащая символы, по которым можно разбивать длинные ASCII-строки, в грубом соответствии с RFC 2822‘s синтаксическими разрывами наивысшего уровня. Это не влияет на строки, закодированные согласно RFC 2047.
Класс Header также предоставляет ряд методов для поддержки стандартных операторов и встроенных функций.
- __str__()¶
- Синоним для Header.encode(). Полезно для str(aHeader).
Модуль 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.