email.headerregistry：自定义标题对象

源代码： Lib/email/headerregistry.py

3.6 版的新Function：[1]

Headers 由str的自定义子类表示。用于创建给定 Headers 的特定类由创建 Headers 时有效的policy的header_factory确定。本节记录了由电子邮件软件包实现的用于处理 RFC 5322兼容电子邮件的特定header_factory，它不仅为各种 Headers 类型提供了自定义的 Headers 对象，还为应用程序提供了扩展机制以添加自己的自定义 Headers 类型。

使用从EmailPolicy派生的任何策略对象时，所有 Headers 均由HeaderRegistry生成，并以BaseHeader作为其最后一个 Base Class。每个 Headers 类都有一个附加的 Base Class，该 Base Class 由 Headers 的类型确定。例如，许多 Headers 将UnstructuredHeader类作为其其他 Base Class。头的专用第二类由头的名称决定，使用存储在HeaderRegistry中的查找表。对于典型的应用程序，所有这些都是透明 Management 的，但是提供了用于修改默认行为以供更复杂的应用程序使用的接口。

以下各节首先介绍 HeadersBase Class 及其属性，然后介绍用于修改HeaderRegistry行为的 API，最后介绍用于表示从结构化 Headers 解析的数据的支持类。

该 Base Class 定义以下只读属性：

BaseHeader还提供以下方法，该方法由电子邮件库代码调用，一般不应由应用程序调用：

BaseHeader本身不能用于创建头对象。它定义了每个专用 Headers 与之配合以生成 Headers 对象的协议。具体来说，BaseHeader要求专门的类提供名为parse的classmethod()。此方法称为：

parse(string, kwds)

kwds是包含一个预初始化键defects的字典。 defects是一个空列表。解析方法应将任何检测到的缺陷添加到此列表中。返回时，kwds字典必须至少包含键decoded和defects的值。 decoded应该是 Headers 的字符串值(即 Headers 值已完全解码为 unicode)。 parse 方法应假定* string *可能包含内容传输编码的部分，但也应正确处理所有有效的 unicode 字符，以便它可以解析未编码的 Headers 值。

BaseHeader的__new__然后创建标题实例，并调用其init方法。如果专用类希望设置BaseHeader本身提供的属性以外的其他属性，则仅需要提供init方法。这样的init方法应如下所示：

def init(self, /, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)

也就是说，应删除并处理专用类在kwds字典中添加的所有内容，并将kw(和args)的其余内容传递给BaseHeader init方法。

在 RFC 5322中，非结构化标题是 ASCII 字符集中的任意文本。 RFC 2047但是具有 RFC 5322兼容机制，用于将非 ASCII 文本编码为 Headers 值内的 ASCII 字符。当将包含编码单词的“值”传递给构造函数时，UnstructuredHeader解析器将按照非结构化文本的 RFC 2047规则将此类编码单词转换为 unicode。解析器使用试探法try对某些不符合要求的编码字进行解码。在这种情况下，会记录缺陷以及诸如编码字或非编码文本中无效字符之类的问题的缺陷。

此 Headers 类型不提供其他属性。

此 Headers 类型提供以下附加属性：

Headers 的decoded值是pass根据 RFC 5322规则格式化datetime来确定的；也就是说，它设置为：

email.utils.format_datetime(self.datetime)

创建DateHeader时，* value *可能是datetime实例。例如，这意味着以下代码有效，并且可以完成预期的工作：

msg['Date'] = datetime(2011, 7, 15, 21)

因为这是天真的datetime，它将被解释为 UTC 时间戳，并且所得值的时区为-0000。更有用的是使用utils模块中的localtime()Function：

msg['Date'] = utils.localtime()

本示例使用当前时区偏移量将日期 Headers 设置为当前时间和日期。

此 Headers 类型提供以下附加属性：

Headers 的decoded值会将所有编码的字解码为 unicode。 idna编码的域名也被解码为 unicode。 decoded的值是pass__ groups属性的元素str值和', '来设置的。

任意组合的Address和Group对象的列表可用于设置地址 Headers 的值。 display_name为None的Group对象将被解释为单个地址，这允许使用从源码的groups属性获得的列表完整地复制地址列表。

上述许多类还具有Unique变体(例如UniqueUnstructuredHeader)。唯一的区别是在Unique变体中，max_count设置为 1.

默认 Map 为：

Note

  • 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具有以下方法：

以下类是用于表示从结构化 Headers 解析的数据的类，通常，应用程序可以使用这些类来构造结构化值以分配给特定的 Headers。

[display_name] <username@domain>

or:

username@domain

其中每个部分必须符合 RFC 5322中阐明的特定语法规则。

为了方便起见，可以指定* addr_spec 而不是 username 和 domain ，在这种情况下，将从 addr_spec 解析 username 和 domain *。 * addr_spec 必须是正确的 RFC 引号字符串；如果不是Address，则会引发错误。允许使用 Unicode 字符，并在序列化时对其进行属性编码。但是，根据 RFC，在地址的用户名部分中不允许 Unicode。

为了支持 SMTP( RFC 5321)，Address处理一种特殊情况：如果username和domain都是空字符串(或None)，则Address的字符串值为<>。

display_name: [address-list];

为了方便处理由组和单个地址组成的地址列表，Group也可以pass将* display_name 设置为None并提供单个列表来表示不属于组的单个地址。地址为 addresses *。

Footnotes

首页