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

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

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

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

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

class email.headerregistry.BaseHeader(name, value)

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

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

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 должно быть строковым значением для заголовка (то есть значение заголовка, полностью декодированное в unicode). Метод parse должен предполагать, что string может содержать части, закодированные с помощью передачи содержимого, но также должен правильно обрабатывать все допустимые символы unicode, чтобы он мог анализировать значения заголовков без кодирования.

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

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

from

UniqueAddressHeader

resent-from

AddressHeader

reply-to

UniqueAddressHeader

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

Имя 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 как временный модуль