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

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

RFC 2822 — это базовый стандарт, описывающий формат сообщений электронной почты. Он произошёл от более старого стандарта RFC 822, который широко использовался в то время, когда большинство писем составлялось только из символов ASCII. RFC 2822 — это спецификация, написанная с предположением, что электронная почта содержит только символы ASCII 7-битной кодировки.

Конечно, по мере глобального распространения электронной почты она стала интернационализированной, так что теперь в сообщениях электронной почты можно использовать наборы символов, специфичные для языка. Базовый стандарт по-прежнему требует, чтобы сообщения электронной почты передавались с использованием только 7-битных символов ASCII, поэтому было написано множество 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, строка будет закодирована с помощью кодировки вывода charset. Если строку нельзя закодировать с помощью кодировки вывода, будет вызвано исключение UnicodeError.

Необязательный параметр errors передаётся как аргумент errors в вызов decode, если s — строка байтов.

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

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

Необязательный параметр splitchars — строка, содержащая символы, которым следует уделять повышенное внимание алгоритмом разделения при обычном обрезании заголовка. Это очень грубо поддерживает «синтаксические разрывы более высокого уровня» RFC 2822: точки разбиения, предшествующие символу splitchar, предпочтительнее при разбиении строк, а символы имеют приоритет в порядке их появления в строке. Пробел и табуляция могут быть включены в строку, чтобы указать, следует ли отдавать предпочтение одному из них перед другим в качестве точки разрыва, когда другие символы разрыва не встречаются в строке, которая разбивается. splitchars не влияет на строки, закодированные с помощью 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.