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