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 — пустой список. Метод разбора должен добавлять в этот список все обнаруженные дефекты. При возврате словарь kwds должен содержать значения как минимум для ключей decoded, defects и parse_tree. decoded должно быть строковым значением заголовка (то есть значением заголовка, полностью декодированным в строку). В parse_tree помещается дерево разбора, полученное при разборе заголовка. Метод разбора должен исходить из того, что string может содержать части, закодированные методом кодирования передачи содержимого, но при этом должен корректно обрабатывать и все допустимые символы Unicode, чтобы разбирать незакодированные значения заголовков.

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

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

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 формируется путем объединения значений 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.ContentTransferEncodingHeader

Обрабатывает заголовок 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.

Для удобства вместо username и domain можно указать addr_spec; в этом случае username и domain будут извлечены из addr_spec. Значение addr_spec должно быть правильно заключенной в кавычки строкой согласно RFC; в противном случае Address вызовет ошибку. Символы Unicode разрешены и будут корректно закодированы при сериализации. Однако согласно RFC символы 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 не задано и в списке addresses содержится один Address, то значение str будет совпадать со значением str этого единственного Address.

Сноски