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.
-
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
представляет единственный адрес, которого нет в группе.
-
Сноски
[1] | Первоначально добавлен в 3.3 как временный модуль |