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)¶

Имя и Значение передаются в BaseHeader из вызова header_factory. Строковое значение любого объекта заголовка - это значение, полностью декодированное в юникод.

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

name¶

Имя заголовка (часть поля перед „:“). Это в точности то же значение, которое было передано в вызове header_factory для name; то есть регистр сохраняется.

defects¶

Кортеж экземпляров HeaderDefect, сообщающий о любых проблемах с соответствием RFC, обнаруженных при разборе. Пакет email старается быть полным в обнаружении проблем соответствия. См. модуль errors для обсуждения типов дефектов, о которых может быть сообщено.

max_count¶

Максимальное количество заголовков данного типа, которые могут иметь одинаковое значение name. Значение None означает неограниченное количество. Значение BaseHeader для этого атрибута равно None; ожидается, что специализированные классы заголовков будут переопределять это значение по мере необходимости.

BaseHeader также предоставляет следующий метод, который вызывается кодом библиотеки электронной почты и в общем случае не должен вызываться прикладными программами:

fold(*, policy)¶

Возвращает строку, содержащую linesep символов, необходимых для корректного сворачивания заголовка в соответствии с policy. Если cte_type из 8bit будет рассматриваться как 7bit, поскольку заголовки не могут содержать произвольные двоичные данные. Если utf8 является False, данные, не относящиеся к кодировке ASCII, будут закодированы RFC 2047.

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

parse(string, kwds)

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

Затем BaseHeader в __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 символов в значении заголовка. Когда конструктору передается значение, содержащее кодированные слова, синтаксический анализатор 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 заголовка все закодированные слова будут декодированы в юникод. Закодированные доменные имена idna также декодируются в юникод. Значение decoded устанавливается путем joining 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__ генерируемых классов.

По умолчанию используются следующие сопоставления:

тема

UniqueUnstructuredHeader

дата

UniqueDateHeader

дата отправки

DateHeader

дата происхождения

UniqueDateHeader

отправитель

UniqueSingleAddressHeader

отправитель

SingleAddressHeader

на

UniqueAddressHeader

resent-to

AddressHeader

cc

UniqueAddressHeader

resent-cc

AddressHeader

bcc

UniqueAddressHeader

resent-bcc

AddressHeader

с сайта

UniqueAddressHeader

resent-from

AddressHeader

ответ на

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, но без кодировки Content Transfer Encoding любых не-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 и есть ровно один Address в addresses, то Group представляет один адрес, который не входит в группу.

addresses¶

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

__str__()¶

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

Сноски

1

Первоначально был добавлен в 3.3 как provisional module.