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 заголовка будет иметь все закодированные слова, декодированные в юникод. Домены, закодированные в 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.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.

Для удобства вместо username и domain можно указать addr_spec, в этом случае 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.

Примечания