email.headerregistry.md

1> **Источник:** https://python-all.ru/3.8/library/email.headerregistry.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`email.headerregistry`](https://python-all.ru/3.8/library/email.headerregistry.html#module-email.headerregistry): настраиваемые объекты заголовков89**Исходный код:** [Lib/email/headerregistry.py](https://python-all.ru/src/3.8/Lib/email/headerregistry.py)1011---1213Новое в версии 3.6: [1](https://python-all.ru/3.8/library/email.headerregistry.html#id2)1415Заголовки представлены настраиваемыми подклассами [`str`](https://python-all.ru/3.8/library/stdtypes.html#str). Конкретный класс, используемый для представления данного заголовка, определяется [`header_factory`](https://python-all.ru/3.8/library/email.policy.html#email.policy.EmailPolicy.header_factory) [`policy`](https://python-all.ru/3.8/library/email.policy.html#module-email.policy), действующей на момент создания заголовков. В этом разделе описаны конкретные `header_factory`, реализованные в пакете email для обработки [**RFC 5322**](https://python-all.ru/3.8/library/email.headerregistry.html)-совместимых сообщений электронной почты. Они не только предоставляют настраиваемые объекты заголовков для различных типов заголовков, но и содержат механизм расширения, позволяющий приложениям добавлять собственные типы заголовков.1617При использовании любого объекта политики, производного от [`EmailPolicy`](https://python-all.ru/3.8/library/email.policy.html#email.policy.EmailPolicy), все заголовки создаются [`HeaderRegistry`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.HeaderRegistry) и имеют [`BaseHeader`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.BaseHeader) в качестве своего последнего базового класса. Каждый класс заголовков имеет дополнительный базовый класс, определяемый типом заголовка. Например, у многих заголовков другим базовым классом является [`UnstructuredHeader`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.UnstructuredHeader). Специализированный второй класс для заголовка определяется по имени заголовка с помощью таблицы поиска, хранящейся в [`HeaderRegistry`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.HeaderRegistry). Всё это прозрачно управляется для типичных прикладных программ, но для более сложных приложений предусмотрены интерфейсы для изменения поведения по умолчанию.1819В следующих разделах сначала описаны базовые классы заголовков и их атрибуты, затем API для изменения поведения [`HeaderRegistry`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.HeaderRegistry), и, наконец, вспомогательные классы, используемые для представления данных, полученных при разборе структурированных заголовков.2021#### `class email.headerregistry.BaseHeader(name, value)`2223*name* и *value* передаются в `BaseHeader` из вызова [`header_factory`](https://python-all.ru/3.8/library/email.policy.html#email.policy.EmailPolicy.header_factory). Строковое значение любого объекта заголовка – это *value*, полностью декодированное в Unicode.2425Этот базовый класс определяет следующие свойства, доступные только для чтения:2627#### `name`2829Имя заголовка (часть поля до двоеточия). Это в точности то значение, которое было передано в вызове [`header_factory`](https://python-all.ru/3.8/library/email.policy.html#email.policy.EmailPolicy.header_factory) для *name*; то есть регистр сохраняется.3031#### `defects`3233Кортеж экземпляров `HeaderDefect`, сообщающих о любых проблемах с соответствием RFC, обнаруженных во время разбора. Пакет email старается быть полным в выявлении проблем соответствия. См. модуль [`errors`](https://python-all.ru/3.8/library/email.errors.html#module-email.errors) для обсуждения типов дефектов, которые могут быть зарегистрированы.3435#### `max_count`3637Максимальное количество заголовков данного типа, которые могут иметь одинаковое `name`. Значение `None` означает неограниченное количество. Значение `BaseHeader` для этого атрибута равно `None`; предполагается, что специализированные классы заголовков будут переопределять это значение по мере необходимости.3839`BaseHeader` также предоставляет следующий метод, который вызывается библиотечным кодом email и, как правило, не должен вызываться прикладными программами:4041#### `fold(*, policy)`4243Возвращает строку, содержащую символы [`linesep`](https://python-all.ru/3.8/library/email.policy.html#email.policy.Policy.linesep), необходимые для правильной укладки заголовка в соответствии с *policy*. Значение [`cte_type`](https://python-all.ru/3.8/library/email.policy.html#email.policy.Policy.cte_type), равное `8bit`, будет обрабатываться так, как если бы оно было `7bit`, поскольку заголовки не могут содержать произвольные двоичные данные. Если [`utf8`](https://python-all.ru/3.8/library/email.policy.html#email.policy.EmailPolicy.utf8) равно `False`, не-ASCII данные будут закодированы по [**RFC 2047**](https://python-all.ru/3.8/library/email.headerregistry.html).4445Сам по себе `BaseHeader` не может использоваться для создания объекта заголовка. Он определяет протокол, с которым взаимодействует каждый специализированный заголовок для создания объекта заголовка. В частности, `BaseHeader` требует, чтобы специализированный класс предоставлял [`classmethod()`](https://python-all.ru/3.8/library/functions.html#classmethod) с именем `parse`. Этот метод вызывается следующим образом:4647```python48parse(string, kwds)49```5051`kwds` – это словарь, содержащий один предварительно инициализированный ключ: `defects`. `defects` – пустой список. Метод разбора должен добавлять в этот список все обнаруженные дефекты. После возврата словарь `kwds` *должен* содержать значения как минимум для ключей `decoded` и `defects`. `decoded` должно быть строковым значением заголовка (то есть значение заголовка, полностью декодированное в Юникод). Метод разбора должен предполагать, что *строка* может содержать части, закодированные с помощью кодирования передачи содержимого, но также должен корректно обрабатывать все допустимые символы Юникода, чтобы иметь возможность разбирать незакодированные значения заголовков.5253Затем `__new__` из `BaseHeader` создаёт экземпляр заголовка и вызывает его метод `init`. Специализированному классу нужно предоставить метод `init` только в том случае, если он хочет установить дополнительные атрибуты, выходящие за рамки тех, что предоставляет сам `BaseHeader`. Такой метод `init` должен выглядеть следующим образом:5455```python56def init(self, /, *args, **kw):57    self._myattr = kw.pop('myattr')58    super().init(*args, **kw)59```6061То есть всё лишнее, что специализированный класс поместил в словарь `kwds`, должно быть удалено и обработано, а оставшееся содержимое `kw` (и `args`) передано методу `init` из `BaseHeader`.6263#### `class email.headerregistry.UnstructuredHeader`6465«Неструктурированный» заголовок – это тип заголовка по умолчанию в [**RFC 5322**](https://python-all.ru/3.8/library/email.headerregistry.html). Любой заголовок, не имеющий заданного синтаксиса, считается неструктурированным. Классический пример неструктурированного заголовка – *Subject*.6667In [**RFC 5322**](https://python-all.ru/3.8/library/email.headerregistry.html), an unstructured header is a run of arbitrary text in the ASCII character set. [**RFC 2047**](https://python-all.ru/3.8/library/email.headerregistry.html), however, has an [**RFC 5322**](https://python-all.ru/3.8/library/email.headerregistry.html) compatible mechanism for encoding non-ASCII text as ASCII characters within a header value. When a *value* containing encoded words is passed to the constructor, the `UnstructuredHeader` parser converts such encoded words into unicode, following the [**RFC 2047**](https://python-all.ru/3.8/library/email.headerregistry.html) rules for unstructured text. The parser uses heuristics to attempt to decode certain non-compliant encoded words. Defects are registered in such cases, as well as defects for issues such as invalid characters within the encoded words or the non-encoded text.6869Этот тип заголовка не предоставляет дополнительных атрибутов.7071#### `class email.headerregistry.DateHeader`7273[**RFC 5322**](https://python-all.ru/3.8/library/email.headerregistry.html) задаёт очень конкретный формат для дат в заголовках электронной почты. Анализатор `DateHeader` распознаёт этот формат даты, а также множество вариантов, которые иногда встречаются «в дикой природе».7475Этот тип заголовка предоставляет следующие дополнительные атрибуты:7677#### `datetime`7879Если значение заголовка можно распознать как допустимую дату в том или ином формате, этот атрибут будет содержать экземпляр [`datetime`](https://python-all.ru/3.8/library/datetime.html#datetime.datetime), представляющий эту дату. Если часовой пояс входной даты указан как `-0000` (что означает, что дата в UTC, но не содержит информации об исходном часовом поясе), тогда [`datetime`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.DateHeader.datetime) будет наивным [`datetime`](https://python-all.ru/3.8/library/datetime.html#datetime.datetime). Если же найден конкретный сдвиг часового пояса (включая *+0000*), тогда [`datetime`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.DateHeader.datetime) будет содержать осведомлённый `datetime`, который использует [`datetime.timezone`](https://python-all.ru/3.8/library/datetime.html#datetime.timezone) для записи сдвига часового пояса.8081Значение `decoded` заголовка определяется форматированием `datetime` в соответствии с правилами [**RFC 5322**](https://python-all.ru/3.8/library/email.headerregistry.html); то есть оно устанавливается в:8283```python84email.utils.format_datetime(self.datetime)85```8687При создании `DateHeader`, *value* может быть экземпляром [`datetime`](https://python-all.ru/3.8/library/datetime.html#datetime.datetime). Это означает, например, что следующий код корректен и делает то, что можно ожидать:8889```python90msg['Date'] = datetime(2011, 7, 15, 21)91```9293Поскольку это наивный `datetime`, он будет интерпретироваться как временная метка UTC, и результирующее значение будет иметь часовой пояс `-0000`. Гораздо полезнее использовать функцию [`localtime()`](https://python-all.ru/3.8/library/email.utils.html#email.utils.localtime) из модуля [`utils`](https://python-all.ru/3.8/library/email.utils.html#module-email.utils):9495```python96msg['Date'] = utils.localtime()97```9899В этом примере заголовок даты устанавливается в текущее время и дату с использованием текущего сдвига часового пояса.100101#### `class email.headerregistry.AddressHeader`102103Заголовки адресов – одни из самых сложных структурированных типов заголовков. Класс `AddressHeader` предоставляет универсальный интерфейс для любого заголовка адреса.104105Этот тип заголовка предоставляет следующие дополнительные атрибуты:106107#### `groups`108109Кортеж объектов [`Group`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.Group), кодирующих адреса и группы, найденные в значении заголовка. Адреса, не входящие в группу, представляются в этом списке как одноадресные `Groups`, чьё [`display_name`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.Group.display_name) равно `None`.110111#### `addresses`112113Кортеж объектов [`Address`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.Address), кодирующих все отдельные адреса из значения заголовка. Если значение заголовка содержит группы, отдельные адреса из группы включаются в список в том месте, где группа встречается в значении (то есть список адресов «уплощается» до одномерного списка).114115Значение `decoded` заголовка будет содержать все закодированные слова, декодированные в Юникод. [`idna`](https://python-all.ru/3.8/library/codecs.html#module-encodings.idna) закодированные доменные имена также декодируются в Юникод. Значение `decoded` устанавливается [`join`](https://python-all.ru/3.8/library/stdtypes.html#str.join)анием значения [`str`](https://python-all.ru/3.8/library/stdtypes.html#str) элементов атрибута `groups` с помощью `', '`.116117Список объектов [`Address`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.Address) и [`Group`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.Group) в любой комбинации может использоваться для установки значения заголовка адреса. Объекты `Group`, у которых `display_name` равно `None`, будут интерпретироваться как отдельные адреса, что позволяет копировать список адресов с сохранением групп, используя список, полученный из атрибута `groups` исходного заголовка.118119#### `class email.headerregistry.SingleAddressHeader`120121Подкласс [`AddressHeader`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.AddressHeader), добавляющий один дополнительный атрибут:122123#### `address`124125Единственный адрес, закодированный значением заголовка. Если значение заголовка фактически содержит более одного адреса (что будет нарушением RFC при стандартном [`policy`](https://python-all.ru/3.8/library/email.policy.html#module-email.policy)), обращение к этому атрибуту приведёт к [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError).126127Многие из перечисленных выше классов также имеют вариант `Unique` (например, `UniqueUnstructuredHeader`). Единственное отличие состоит в том, что в варианте `Unique` [`max_count`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.BaseHeader.max_count) установлено в 1.128129#### `class email.headerregistry.MIMEVersionHeader`130131На самом деле существует только одно допустимое значение для заголовка *MIME-Version*, и это `1.0`. Для обеспечения будущей совместимости этот класс заголовка поддерживает другие корректные номера версий. Если номер версии имеет допустимое значение в соответствии с [**RFC 2045**](https://python-all.ru/3.8/library/email.headerregistry.html), то объект заголовка будет иметь не-`None` значения для следующих атрибутов:132133#### `version`134135Номер версии в виде строки, из которой удалены все пробелы и/или комментарии.136137#### `major`138139Номер основной версии в виде целого числа.140141#### `minor`142143Номер дополнительной версии в виде целого числа.144145#### `class email.headerregistry.ParameterizedMIMEHeader`146147Все MIME-заголовки начинаются с префикса «Content-». Каждый конкретный заголовок имеет определённое значение, описанное в классе этого заголовка. Некоторые также могут принимать список дополнительных параметров, имеющих общий формат. Этот класс служит базовым для всех MIME-заголовков, принимающих параметры.148149#### `params`150151Словарь, сопоставляющий имена параметров со значениями параметров.152153#### `class email.headerregistry.ContentTypeHeader`154155Класс [`ParameterizedMIMEHeader`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.ParameterizedMIMEHeader), обрабатывающий заголовок *Content-Type*.156157#### `content_type`158159Строка типа содержимого в формате `maintype/subtype`.160161#### `maintype`162163#### `subtype`164165#### `class email.headerregistry.ContentDispositionHeader`166167Класс [`ParameterizedMIMEHeader`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.ParameterizedMIMEHeader), обрабатывающий заголовок *Content-Disposition*.168169#### `content_disposition`170171`inline` и `attachment` – единственные общеупотребительные допустимые значения.172173#### `class email.headerregistry.ContentTransferEncoding`174175Обрабатывает заголовок *Content-Transfer-Encoding*.176177#### `cte`178179Допустимые значения: `7bit`, `8bit`, `base64` и `quoted-printable`. Подробнее см. [**RFC 2045**](https://python-all.ru/3.8/library/email.headerregistry.html).180181#### `class email.headerregistry.HeaderRegistry(base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)`182183Это фабрика, используемая [`EmailPolicy`](https://python-all.ru/3.8/library/email.policy.html#email.policy.EmailPolicy) по умолчанию. `HeaderRegistry` динамически создаёт класс для построения экземпляра заголовка, используя *base\_class* и специализированный класс из своего внутреннего реестра. Если заданное имя заголовка отсутствует в реестре, в качестве специализированного используется класс, указанный в *default\_class*. Когда *use\_default\_map* равно `True` (по умолчанию), стандартное сопоставление имён заголовков с классами копируется в реестр при инициализации. *base\_class* всегда является последним классом в списке `__bases__` создаваемого класса.184185Стандартные сопоставления:186187> **subject**188>189> UniqueUnstructuredHeader190>191> **date**192>193> UniqueDateHeader194>195> **resent-date**196>197> DateHeader198>199> **orig-date**200>201> UniqueDateHeader202>203> **sender**204>205> UniqueSingleAddressHeader206>207> **resent-sender**208>209> SingleAddressHeader210>211> **на**212>213> UniqueAddressHeader214>215> **resent-to**216>217> AddressHeader218>219> **cc**220>221> UniqueAddressHeader222>223> **resent-cc**224>225> AddressHeader226>227> **bcc**228>229> UniqueAddressHeader230>231> **resent-bcc**232>233> AddressHeader234>235> **from**236>237> UniqueAddressHeader238>239> **resent-from**240>241> AddressHeader242>243> **reply-to**244>245> UniqueAddressHeader246>247> **mime-version**248>249> MIMEVersionHeader250>251> **content-type**252>253> ContentTypeHeader254>255> **content-disposition**256>257> ContentDispositionHeader258>259> **content-transfer-encoding**260>261> ContentTransferEncodingHeader262>263> **message-id**264>265> MessageIDHeader266267`HeaderRegistry` имеет следующие методы:268269#### `map_to_type(self, name, cls)`270271*name* – это имя сопоставляемого заголовка. Оно будет преобразовано в нижний регистр в реестре. *cls* – это специализированный класс, используемый, вместе с *base\_class*, для создания класса, с помощью которого создаются экземпляры заголовков, соответствующих *name*.272273#### `__getitem__(name)`274275Создаёт и возвращает класс для создания заголовка *name*.276277#### `__call__(name, value)`278279Извлекает из реестра специализированный заголовок, связанный с *name* (используя *default\_class*, если *name* отсутствует в реестре), и объединяет его с *base\_class* для получения нового класса, вызывает конструктор созданного класса, передавая ему тот же список аргументов, и, наконец, возвращает полученный экземпляр класса.280281Следующие классы используются для представления данных, извлечённых при разборе структурированных заголовков. В общем случае прикладная программа может применять их для формирования структурированных значений, присваиваемых конкретным заголовкам.282283#### `class email.headerregistry.Address(display_name='', username='', domain='', addr_spec=None)`284285Класс, используемый для представления адреса электронной почты. Общий вид адреса:286287```python288[display_name] <username@domain>289```290291или:292293```python294username@domain295```296297где каждая часть должна соответствовать определённым правилам синтаксиса, изложенным в [**RFC 5322**](https://python-all.ru/3.8/library/email.headerregistry.html).298299Для удобства можно указать *addr\_spec* вместо *username* и *domain*; в этом случае *username* и *domain* будут извлечены из *addr\_spec*. Значение *addr\_spec* должно быть строкой, правильно экранированной в соответствии с RFC; если это не так, `Address` вызовет ошибку. Допускаются символы Unicode, которые будут корректно закодированы при сериализации. Однако согласно RFC, Unicode *не* разрешён в части имени пользователя адреса.300301#### `display_name`302303Часть адреса, содержащая отображаемое имя, если оно есть, с удалёнными кавычками. Если у адреса нет отображаемого имени, этот атрибут будет пустой строкой.304305#### `username`306307Часть адреса `username`, с удалёнными кавычками.308309#### `domain`310311Часть адреса `domain`.312313#### `addr_spec`314315Часть адреса `username@domain`, правильно экранированная для использования в качестве «голого» адреса (вторая форма, показанная выше). Этот атрибут не изменяем.316317#### `__str__()`318319Значение `str` объекта – это адрес, экранированный в соответствии с правилами [**RFC 5322**](https://python-all.ru/3.8/library/email.headerregistry.html), но без кодирования передачи содержимого для любых не-ASCII символов.320321Для поддержки SMTP ([**RFC 5321**](https://python-all.ru/3.8/library/email.headerregistry.html)) `Address` обрабатывает один особый случай: если `username` и `domain` оба являются пустыми строками (или `None`), то строковое значение `Address` равно `<>`.322323#### `class email.headerregistry.Group(display_name=None, addresses=None)`324325Класс, используемый для представления группы адресов. Общий вид группы адресов:326327```python328display_name: [address-list];329```330331Для удобства обработки списков адресов, состоящих из смеси групп и отдельных адресов, `Group` также может использоваться для представления отдельных адресов, не входящих в группу, путём установки *display\_name* в `None` и передачи списка из одного адреса в качестве *addresses*.332333#### `display_name`334335`display_name` группы. Если оно равно `None` и в `addresses` есть ровно один `Address`, то `Group` представляет отдельный адрес, не входящий в группу.336337#### `addresses`338339Возможно пустой кортеж объектов [`Address`](https://python-all.ru/3.8/library/email.headerregistry.html#email.headerregistry.Address), представляющих адреса в группе.340341#### `__str__()`342343Значение `str` объекта `Group` форматируется в соответствии с [**RFC 5322**](https://python-all.ru/3.8/library/email.headerregistry.html), но без кодирования передачи содержимого для любых не-ASCII символов. Если `display_name` равно None и в списке `addresses` есть один `Address`, то значение `str` будет совпадать со значением `str` этого единственного `Address`.344345Сноски346347**[1](https://python-all.ru/3.8/library/email.headerregistry.html#id1)**348349Изначально добавлен в версии 3.3 как [временный модуль](https://python-all.ru/3.8/glossary.html#term-provisional-package)350