email.headerregistry: Пользовательские объекты заголовка

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

---

Добавлено в версии 3.6: [1]

Заголовки представлены настраиваемыми подклассы str. Особый класс используемый, чтобы представлять данный заголовок определен header_factory policy в действительности, когда заголовки созданы. Этот раздел документирует особый header_factory, осуществленный почтовым пакетом для обработки RFC 5322 соответствующие электронные письма, который не только обеспечивает настроенные объекты заголовка для различных типов заголовка, но также и обеспечивает дополнительный механизм для заявлений добавить их собственные типы заголовка.

Используя любой из стратегических объектов, полученных из EmailPolicy, все заголовки созданы HeaderRegistry и имеют BaseHeader как свой последний базовый класс. Каждый класс заголовка имеет дополнительный базовый класс, определяемый типом заголовка. Например, многие заголовки имеют класс UnstructuredHeader в качестве другого базового класса. Специализированный второй класс для заголовка определен под названием заголовок, используя справочную таблицу, сохраненную в HeaderRegistry. Все это управляется прозрачно для типичной прикладной программы, но предусмотрены интерфейсы для изменения поведения по умолчанию для использования более сложными приложениями.

В разделах ниже сначала документируются базовые классы заголовков и их атрибуты, а затем API для изменения поведения HeaderRegistry и, наконец, классы поддержки используемый для представления данных, проанализированных из структурированных заголовков.

class email.headerregistry.BaseHeader(name, value)

name и value передаются BaseHeader из вызова header_factory. строка значение любого объекта заголовка является value, полностью декодированным до юникода.

Этот базовый класс определяет следующие свойства, доступные только для чтения:

name

Имя заголовка (часть поля, предшествующая „:“). Это - точно значение, переданный в призыве header_factory к name; то есть случай сохраняется.

defects

Кортеж HeaderDefect сущности, сообщающих о любых проблемах соответствия RFC, обнаруженных во время парсинг. Пакет электронной почты пытается быть полным для обнаружения проблем соответствия. Для получения информации о типах дефектов, о которых можно сообщить, см. модуль errors.

max_count

Максимальное число заголовков этого типа, которые могут иметь одинаковый name. значение None означает неограниченный. BaseHeader значение для этого атрибут является None; ожидается, что специализированные классы заголовка отвергнут этот значение по мере необходимости.

BaseHeader также предоставляет следующий метод, который вызывается библиотекой электронной почты код и обычно не должен вызываться прикладными программами:

fold(*, policy)

Возвращает строка, содержащий символы linesep, необходимые для правильного сворачивания заголовка в соответствии с policy. cte_type 8bit будет рассматриваться как 7bit, так как заголовки могут не содержать произвольных двоичных данных. Если utf8 является False, данные, не являющиеся данными ASCII, будут RFC 2047 кодированный.

BaseHeader само по себе не может быть используемый для создания объекта заголовка. Он определяет протокол, с которым взаимодействует каждый специализированный заголовок для создания объекта заголовка. В частности, BaseHeader требует, чтобы специализированный класс предоставил classmethod() с именем parse. Этот метод называется следующим образом:

parse(string, kwds)

kwds - словарь, содержащий один предварительно инициализированный ключ defects. defects является пустым списком. Метод синтаксического анализа должен добавлять обнаруженные дефекты в этот список. По возвращению словарь kwds must содержат значения, по крайней мере, для ключей decoded и defects. decoded должен быть строка значение для заголовка (то есть, заголовок значение, полностью расшифрованный к unicode). Метод разбора должен предположить, что string может содержать content- transfer-кодированный части, но должен правильно обращаться со всеми действительными unicode знаками также так, чтобы он мог разобрать un-кодированный заголовок значения.

BaseHeader __new__ тогда создает заголовок сущность и называет его метод init. Специализированный класс только должен предоставить метод init, если он хочет установить дополнительный атрибуты вне обеспеченных самим BaseHeader. Такой метод init должен выглядеть так:

def init(self, /, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)

То есть все лишнее, что специализированный класс помещает в словарь kwds, должно быть удалено и обработано, а оставшееся содержимое kw (и args) передано методу BaseHeader init.

class email.headerregistry.UnstructuredHeader

«Неструктурированный» заголовок является типом заголовка по умолчанию в RFC 5322. Любой заголовок, не имеющий указанного синтаксиса, рассматривается как неструктурированный. Классическим примером неструктурированного заголовка является заголовок Subject.

В RFC 5322 неструктурированный удар головой - пробег произвольного текста в наборе ASCII символ. RFC 2047, однако, имеет совместимый с RFC 5322 механизм для кодировка текста, отличного от ASCII, в качестве символов ASCII в заголовке значение. При передаче конструктору value, содержащего кодированный слова, UnstructuredHeader парсер преобразует такие кодированный слова в юникод, следуя правилам RFC 2047 для неструктурированного текста. В парсер используется эвристика для дешифрования некоторых несовместимых кодированный слов. В таких случаях регистрируются дефекты, а также дефекты в таких вопросах, как недопустимые символы в кодированный словах или тексте non-кодированный.

Этот тип заголовка не предоставляет дополнительных атрибуты.

class email.headerregistry.DateHeader

RFC 5322 задает очень конкретный формат для дат в заголовках электронной почты. В DateHeader парсер признаётся тот формат даты, а также распознаётся ряд вариантов форм, которые иногда встречаются «в дикой природе».

Этот тип заголовка предоставляет следующие дополнительные атрибуты:

datetime

Если заголовок значение можно распознать как действительную дату той или иной формы, эта атрибут будет содержать datetime сущность, представляющую эту дату. Если часовой пояс даты ввода указан как -0000 (указывает, что он находится в формате UTC, но не содержит информации об исходном часовом поясе), то datetime будет наивным datetime. Если найден определенный сдвиг часового пояса (включая «+ 0000»), то datetime будет содержать осведомленный datetime, который использует datetime.timezone для записи смещения часового пояса.

decoded значение заголовка определяется форматированием datetime в соответствии с правилами RFC 5322; то есть установлено значение:

email.utils.format_datetime(self.datetime)

Создавая DateHeader, value может быть datetime сущность. Это означает, например, что следующее код является действительным и делает то, что можно ожидать:

msg['Date'] = datetime(2011, 7, 15, 21)

Поскольку это наивный datetime, он будет интерпретирован как метка времени UTC, и результирующий значение будет иметь часовой пояс -0000. Гораздо более полезным является использование функции localtime() из модуля utils:

msg['Date'] = utils.localtime()

В этом примере заголовок даты устанавливается на текущее время и дату с использованием текущего смещения часового пояса.

class email.headerregistry.AddressHeader

Заголовки адресов являются одним из наиболее сложных структурированных типов заголовков. Класс AddressHeader предоставляет универсальный интерфейс для любого заголовка адреса.

Этот тип заголовка предоставляет следующие дополнительные атрибуты:

groups

Кортеж объектов Group кодировка адреса и группы, найденные в заголовке значение. Адреса, которые не являются частью группы, представлены в этом списке как единственный адрес Groups, display_name которого - None.

addresses

Кортеж объектов Address кодировка все отдельные адреса из заголовка значение. Если заголовок значение содержит какие-либо группы, отдельные адреса из группы включаются в список в точке, где группа находится в значение (то есть список адресов «распрямляется» в одномерный список).

decoded значение заголовка будут иметь все кодированный слова, декодированные в юникоде. idna кодированный доменные имена также декодируются в юникоде. Значение decoded значение задается в join через str значение элементов groups атрибут с ', '.

Список объектов Address и Group в любой комбинации может быть используемый для установки значение заголовка адреса. Group объекты, display_name которых является None, будут интерпретироваться как отдельные адреса, что позволяет копировать список адресов с целыми группами с использованием списка, полученного из groups атрибут исходного заголовка.

class email.headerregistry.SingleAddressHeader

подкласс AddressHeader, который добавляет один дополнительный атрибут:

address

Единственный адрес кодированный по заголовку значение. Если бы заголовок, значение на самом деле содержит больше чем один адрес (который был бы нарушением RFC под дефолтом policy), получая доступ к этому атрибут приведет к ValueError.

Многие из вышеуказанных классов также имеют вариант Unique (например, UniqueUnstructuredHeader). Единственная разница - то, что в варианте Unique, max_count установлен в 1.

class email.headerregistry.MIMEVersionHeader

Для заголовка MIME-Version действительно существует только одно действительное значение, то есть 1.0. Для проверки правописания в будущем этот класс заголовка поддерживает другие допустимые номера версий. Если номер версии имеет допустимое значение значение на RFC 2045, то объект заголовка будет иметь значение не-None значения для следующего атрибуты:

version

Номер версии в виде строка с удаленными пробелами и/или комментариями.

major

Основной номер версии в виде целого числа

minor

Дополнительный номер версии в виде целого числа

class email.headerregistry.ParameterizedMIMEHeader

все заголовки MIME начинаются с префикса Content-. Каждый конкретный заголовок имеет определенный значение, описанный в классе для этого заголовка. Некоторые могут также взять список дополнительных параметров, которые имеют общий формат. Этот класс служит основой для всех заголовков MIME, принимающих параметры.

params

Словарь, сопоставляющий имена параметров параметру значения.

class email.headerregistry.ContentTypeHeader

Класс ParameterizedMIMEHeader, обрабатывающий заголовок Content-Type.

content_type

Тип содержимого строка в форме maintype/subtype.

maintype

subtype

class email.headerregistry.ContentDispositionHeader

Класс ParameterizedMIMEHeader, обрабатывающий заголовок Content-Disposition.

content_disposition

inline и attachment являются единственными допустимыми значения в общем использовании.

class email.headerregistry.ContentTransferEncoding

Обрабатывает заголовок Content-Transfer-Encoding.

cte

Действительные значения - 7bit, 8bit, base64 и quoted-printable. Дополнительные сведения см. в разделе RFC 2045.

class email.headerregistry.HeaderRegistry(base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)

Это - фабрика используемый EmailPolicy по умолчанию. HeaderRegistry создает класс используемый для создания заголовка сущность динамически, используя base_class и специализированный класс, извлеченный из реестра, который он содержит. Когда данное название заголовка не появляется в регистрации, класс, определенный default_class, является используемый как специализированным классом. Когда use_default_map - True (дефолт), стандартное отображение названий заголовка к классам скопировано в к регистрации во время инициализации. base_class всегда является последним классом в списке __bases__ созданного класса.

Сопоставлениями по умолчанию являются:

subject:UniqueUnstructuredHeader date:UniqueDateHeader resent-date:DateHeader orig-date:UniqueDateHeader sender:UniqueSingleAddressHeader resent-sender:SingleAddressHeader to:UniqueAddressHeader resent-to:AddressHeader cc:UniqueAddressHeader resent-cc:AddressHeader bcc:UniqueAddressHeader resent-bcc:AddressHeader from:UniqueAddressHeader resent-from:AddressHeader reply-to:UniqueAddressHeader mime-version:MIMEVersionHeader content-type:ContentTypeHeader content-disposition:  ContentDispositionHeader content-transfer-encoding:  ContentTransferEncodingHeader message-id:MessageIDHeader

HeaderRegistry имеет следующие методы:

map_to_type(self, name, cls)

name - имя отображаемого заголовка. Он будет преобразован в нижний регистр реестра. cls - специализированный класс, чтобы быть используемый, наряду с base_class, создать класс используемый, чтобы иллюстрировать примерами заголовки тот матч name.

__getitem__(name)

Создание и класс возвращает для обработки создания заголовка name.

__call__(name, value)

Восстанавливает специализированный заголовок, связанный с name от регистрации (использующий default_class, если name не появляется в регистрации), и составляет его с base_class, чтобы произвести класс, вызывает конструктора построенного класса, передавая ему тот же список аргументов, и наконец возвращает класс сущность, созданный, таким образом.

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

class email.headerregistry.Address(display_name='', username='', domain='', addr_spec=None)

Класс используемый для представления адреса электронной почты. Общая форма адреса:

[display_name] <username@domain>

или:

username@domain

где каждая деталь должна соответствовать определенным правилам синтаксиса, указанным в разделе RFC 5322.

В качестве удобства вместо addr_spec и username можно указать domain, в этом случае username и domain будут проанализированы из addr_spec. addr_spec должен быть надлежащим RFC-кодом строка; если он не является Address вызовет ошибку. Символы юникода разрешены и будут свойством кодированный при сериализации. Однако за RFCs, unicode - не, позволенный в части имени пользователя адреса.

display_name

Часть отображаемого имени адреса, если она имеется, с удаленными квотированием. Если у адреса не будет названия дисплея, то этот атрибут будет пустым строка.

username

username часть адреса с удаленными цитатами.

domain

domain часть адреса.

addr_spec

username@domain часть адреса, правильно предложенная для использования в качестве пустого адреса (вторая форма показана выше). Этот атрибут не может изменяться.

__str__()

str значение объекта - это адрес, цитируемый в соответствии с правилами RFC 5322, но без кодировки передачи содержимого любых символов, отличных от ASCII.

Чтобы поддержать SMTP (RFC 5321), Address обращается с одним особым случаем: если username и domain - оба пустой строка (или None), то строка значение Address - <>.

class email.headerregistry.Group(display_name=None, addresses=None)

Класс используемый для представления адресной группы. Общая форма группы адресов:

display_name: [address-list];

Как удобство для обработки списков адресов, которые состоят из смеси групп и единственных адресов, Group может также быть используемый, чтобы представлять единственные адреса, которые не являются частью группы, устанавливая display_name в None и предоставляя список единственного адреса как addresses.

display_name

display_name группы. Если это None и в addresses есть ровно один Address, то Group представляет единственный адрес, которого нет в группе.

addresses

Возможно, пустой кортеж объектов Address, представляющих адреса в группе.

__str__()

str значение Group отформатирован согласно RFC 5322, но без довольного кодирование передачи любых знаков не ASCII. Если display_name нет и в списке Address есть один addresses, str значение будет таким же, как и str этого отдельного Address.

Сноски

[1]	Первоначально добавлен в 3.3 как временный модуль