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

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.

Для удобства вместо username и domain можно указать addr_spec, в этом случае username и domain будут извлечены из addr_spec. addr_spec должен быть правильно процитированной строкой в соответствии с RFC; в противном случае Address выведет ошибку. Разрешены символы Юникода, которые будут корректно закодированы при сериализации. Однако, согласно RFC, символы Юникода не допускаются в части username адреса.

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 и существует ровно один Address в addresses, то Group представляет одиночный адрес, который не входит в группу.

addresses

Возможный пустой кортеж из объектов Address, представляющих адреса в группе.

__str__()

Значение str объекта Group форматируется согласно RFC 5322, но без кодирования передачи содержимого для любых символов, отличных от ASCII. Если display_name равно None и в списке addresses содержится один Address, то значение str будет таким же, как значение str этого единственного Address.

Примечания

1

Изначально добавлен в 3.3 как временный модуль