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 в качестве провизорного модуля