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, в заголовки электронных писем, например в поля 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
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

Обратите внимание: мы хотели, чтобы поле Subject содержало символ, отличный от ASCII. Для этого мы создали экземпляр Header и передали набор символов, который следует использовать при его кодировании. При последующем преобразовании экземпляра Message в плоское представление поле Subject было корректно закодировано в соответствии с 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 передаётся как аргумент errors при вызове декодирования, если s является последовательностью байтов.

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

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

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

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

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

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

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

__str__()

Возвращает приближённое представление Header в виде строки без ограничения длины строк. Все фрагменты декодируются с использованием указанной кодировки и надлежащим образом объединяются. Фрагменты с набором символов 'unknown-8bit' декодируются как ASCII с использованием обработчика ошибок 'replace'.

Изменено в версии 3.2: Добавлена поддержка набора символов 'unknown-8bit'.

__eq__(other)

Этот метод позволяет сравнивать два экземпляра Header на равенство.

__ne__(other)

Этот метод позволяет сравнивать два экземпляра Header на неравенство.

Модуль email.header также предоставляет следующие удобные функции.

email.header.decode_header(header)

Декодирует значение заголовка сообщения без преобразования набора символов. Значение заголовка передаётся в аргументе header.

По историческим причинам эта функция может возвращать одно из двух значений:

1. Список пар, содержащих каждую декодированную часть заголовка, (decoded_bytes, charset), где decoded_bytes всегда является экземпляром bytes, а charset — это либо:

   • Строка в нижнем регистре с названием указанного набора символов.
   • None для незакодированных частей заголовка.
2. Список длины 1, содержащий пару (string, None), где string всегда является экземпляром str.

При возникновении некоторых ошибок декодирования (например, исключения при декодировании base64) может быть вызвано исключение email.errors.HeaderParseError.

Примеры:

>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]
>>> decode_header('unencoded_string')
[('unencoded_string', None)]
>>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
[(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]

Примечание

Эта функция существует только для обратной совместимости. В новом коде рекомендуется использовать email.headerregistry.HeaderRegistry.

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.

Примечание

Эта функция существует только для обратной совместимости и не рекомендуется для использования в новом коде.