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, так как строки не могут содержать двоичные данные.

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

parse(string, kwds)

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

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

version

Номер версии в виде строки, с удаленными пробелами и/или комментариями.

major

Главный номер версии в виде целого числа.

minor

Вспомогательный номер версии в виде целого числа.

class email.headerregistry.ParameterizedMIMEHeader

Все заголовки MOME начинаются с префикса ‘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.