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 устанавливается путём объединения значений 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, но без кодирования символов с кодами больше 127.

Для поддержки 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, но без кодирования символов с кодами больше 127. Если display_name равно None и в списке addresses содержится один Address, значение str будет таким же, как значение str этого единственного Address.

Примечания