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 составляет 78, а значение по умолчанию для 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 передаётся в качестве аргумента ошибки вызову decode, если s — строка байтов.

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

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

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

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

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

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

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

__str__()

Возвращает приблизительное представление Header в виде строки, используя неограниченную длину строки. Все части преобразуются в unicode с использованием указанной кодировки и объединяются соответствующим образом. Любые части с кодировкой '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.