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

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

Заголовки представляются настроенными подклассами str. Конкретный класс, используемый для представления данного заголовка, определяется header_factory объекта policy, действующего при создании заголовков. В этом разделе документируются конкретные header_factory реализованные пакетом email для обработки 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, обнаруженных во время анализа. Пакет email пытается полностью обнаружить проблемы соответствия. См. модуль errors для обсуждения типов дефектов, которые могут быть сообщены.

max_count

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

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

fold(*, policy)

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

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

parse(string, kwds)

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

BaseHeader’s __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 для неструктурированного текста. Анализатор использует эвристику, чтобы попытаться декодировать некоторые несоответствующие закодированные слова. В таких случаях регистрируются дефекты, а также дефекты для таких проблем, как недопустимые символы внутри закодированных слов или некодированный текст.

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

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 заголовка будет содержать все закодированные слова, декодированные в unicode. Закодированные доменные имена idna также декодируются в unicode. Значение 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 выведет ошибку. Разрешены символы Юникода и они будут правильно закодированы при сериализации. Однако, согласно RFC, символы Юникода не допускаются в части имени пользователя адреса.

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

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

addresses

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

__str__()

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

Примечания

1

Впервые добавлен в 3.3 в качестве провизорного модуля