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

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

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

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

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
>>> 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 при вызове decode, если s является байтовой строкой.

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

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

Необязательный параметр splitchars – это строка, содержащая символы, которые должны получать дополнительный вес при разбиении алгоритмом во время обычного переноса заголовка. Это очень грубая поддержка ‘синтаксических разрывов более высокого уровня’ из RFC 2822: точки разрыва, перед которыми стоит символ из splitchars, предпочтительны при разбиении строк, причём символы предпочитаются в порядке их появления в строке. Пробел и табуляция могут быть включены в строку, чтобы указать предпочтение одного перед другим в качестве точки разрыва, когда другие символы разрыва не встречаются в разбиваемой строке. Splitchars не влияет на строки, закодированные по RFC 2047.

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

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

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

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

__str__()¶

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

Изменено в версии 3.2: Добавлена обработка для charset '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.

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

Вот примеры:

>>> 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.

Примечание

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