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

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

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

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

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
>>> 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, например, Тема) передайте имя поля в 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, строка будет закодирована с использованием кодировки вывода charset. Если строка не может быть закодирована с использованием кодировки вывода, будет поднято исключение UnicodeError.

Необязательный параметр errors передаётся как аргумент 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.