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