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 равно 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: точки разрыва, предшествующие символу splitchar, предпочтительнее при разделении строк, причём символы предпочтительны в том порядке, в котором они появляются в строке. Пробел и табуляция могут быть включены в строку, чтобы указать, какой из них следует предпочесть как точку разрыва, когда другие символы splitchar не появляются в строке, разделяемой на строки. Символы splitchar не влияют на закодированные строки 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.