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, полностью декодированное в Unicode.

Этот базовый класс определяет следующие только для чтения свойства:

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 должно быть строковым значением для заголовка (то есть значение заголовка, полностью декодированное в Unicode). Метод parse должен предполагать, что string может содержать закодированные части, но должен правильно обрабатывать все допустимые символы Unicode, чтобы он мог анализировать незакодированные значения заголовков.

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 преобразует такие закодированные слова в Unicode, следуя правилам 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 устанавливается с помощью 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 как провизорный модуль