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

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

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

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

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

Конечно, поскольку электронная почта была развернута по всему миру, она стала интернационализированной, так что языковые наборы символов теперь можно использовать в сообщениях электронной почты. Основной стандарт все еще требует, чтобы электронные письма были переданы, используя только 7-битные символы ASCII, таким образом, убивание RFCs было написано, описав, как закодировать электронную почту, содержащую не ASCII символы в RFC 2822-соответствующего формата. Эти RFCs включают RFC 2045, RFC 2046, RFC 2047 и RFC 2231. Пакет email поддерживает эти стандарты в своих модулях email.header и email.charset.

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

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

Дополнительный errors передан как ошибочный аргумент расшифровывать требованию, если s - байт строка.

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

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

Необязательный splitchars - это строка, содержащий символы, которым алгоритм разделения должен придавать дополнительный вес во время обычной обертки заголовка. Это в очень грубой поддержке RFC 2822 «более высокого уровня синтаксические разрывы»: точки разделения, предшествующие разделению, предпочтительны во время разделения строки, при этом символы предпочтительны в том порядке, в котором они появляются в строка. Пробел и вкладка могут быть включены в строка, чтобы указать, следует ли отдавать предпочтение одной точке над другой в качестве точки разделения, когда другие знаки разделения не отображаются в разделяемой линии. Разделительные символы не влияют на линии RFC 2047 кодированный.

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

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

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

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

__str__()

Возвращает аппроксимацию Header как строка, используя неограниченную длину линии. Все части преобразуются в юникод с использованием указанного кодировка и соединяются вместе соответствующим образом. Любые части с набором символов '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 для non-кодированный частей заголовка, в противном случае нижний регистр строка, содержащий имя набора символ, указанного в кодированный строка.

Вот пример:

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