email.headerregistry：自定义标题对象

源代码： Lib / email / headerregistry.py

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

当使用EmailPolicy派生的任何策略对象时，所有标题都由HeaderRegistry生成并且有BaseHeader作为他们的最后一个基类。每个头类都有一个额外的基类，它由头的类型决定。例如，许多标题都有类UnstructuredHeader作为他们的另一个基类。标题的专用第二类由标题的名称决定，使用存储在HeaderRegistry。所有这些都是针对典型应用程序的透明管理，但提供的接口用于修改默认行为以供更复杂的应用程序使用.

下面的部分首先记录了头基类及其属性，然后是用于修改HeaderRegistry，最后用于表示从structuredheaders解析的数据的支持类

class email.headerregistry.BaseHeader (name, value）

name和value传递给BaseHeader来自header_factory呼叫。任何头对象的字符串值是value完全解码为unicode

这个基类定义了以下只读属性：

name

标题的名称（“：”之前的字段部分）。这正是中传递的值header_factory呼唤name;案件，案件保存.

defects

一个HeaderDefect报告解析过程中发现的任何RFC合规性问题的实例。电子邮件包会尝试完成有关检测合规性问题的信息。有关可能报告的缺陷类型的讨论，请参见errors模块.

max_count

此类型的最大标题数可以与name相同。值None表示无限制。这个属性的BaseHeader值是None;期望专门的头文件将根据需要覆盖此值.

BaseHeader还提供以下方法，该方法由电子邮件库代码调用，通常不应由applicationprograms调用：

fold（*, policy）

根据需要返回一个包含linesep字符的字符串，以便根据policy正确折叠标题。一个cte_type 8bit将被视为7bit，因为标题可能不包含任意二进制数据。如果utf8是False，非ASCII数据将是 RFC 2047 编码

BaseHeader本身不能用于创建头对象。它定义了每个专用头与之协作的协议，以便产生头对象。具体来说，BaseHeader要求专门的类提供classmethod()命名parse。这个方法的调用如下：

parse(string, kwds)

kwds是一个包含一个预先初始化的密钥的字典，defects.defects是一个空列表。解析方法应将任何检测到的缺陷附加到此列表中。返回时，kwds字典must包含至少键decoded和defects. decoded的值应该是标题的字符串值（即标题）value完全解码为unicode）。解析方法应该假设string可以包含内容传输编码的部分，但是也应该正确处理所有有效的unicode字符，以便它可以解析未编码的头部值.

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 header.

In RFC 5322 ，非结构化标题是ASCII字符集中的任意文本。 RFC 2047 然而， RFC 5322 compatiblemechanism用于将非ASCII文本编码为headervalue中的ASCII字符。当value包含编码的单词传递给构造函数时，UnstructuredHeader解析器将这样编码的单词转换成unicode，跟 RFC 2047 非结构化文本的规则。Theparser使用启发式方法尝试解码某些不兼容的编码字。在这种情况下会出现缺陷，以及编码单词或非编码文本中的无效字符等问题.

此标题类型不提供其他属性.

class email.headerregistry.DateHeader

RFC 5322 为电子邮件标题中的日期指定一种非常具体的格式.DateHeader解析器识别日期格式，以及识别有时在“thewild”中找到的多种变体形式.

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

datetime

如果标头值可以被识别为另一个表单的有效日期，则此属性将包含表示该日期的datetime实例。如果输入日期的时区指定为-0000（表示它是UTC，但不包含关于源时区的信息），则datetime将是一个主动的datetime。如果发现特定的时区偏移（包括 + 0000 ），那么datetime将包含一个知道的datetime使用datetime.timezone来记录timezoneoffset .

decoded根据datetime RFC 5322 规则格式化确定标题的值;也就是说，设置为：

email.utils.format_datetime(self.datetime)

创建DateHeader, value时可能是datetime实例。这意味着，例如，以下代码是有效的并且可以达到预期的效果：

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

因为这是一个天真的datetime它将被解释为UTCtimestamp，结果值的时区为-0000。更有用的是使用localtime()模块中的utils函数：

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

此示例使用当前时区偏移量将日期标题设置为当前时间和日期.

class email.headerregistry.AddressHeader

地址标题是最复杂的结构化标题类型之一.AddressHeaderclass为任何addressheader提供通用接口.

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

groups

一个Group编码在标头值中找到的地址和组的对象。不属于组的地址在此列表中表示为单地址Groups谁的 display_name是None.

addresses

一个Address从头标记编码所有单个地址的对象。如果标题值包含任何组，则该组中的各个地址将包含在列表中该组出现的位置（即，地址列表被“展平”为一维列表）.

decoded标题的值将使所有编码的单词解码为tounicode。idna编码的域名也被解码为tounicode。decoded值由joinstr元素的价值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 header.

content_type

内容类型字符串，格式为maintype/subtype.

maintype

subtype

class email.headerregistry.ContentDispositionHeader

一个ParameterizedMIMEHeader上课的Content-Dispositionheader.

content-disposition

inline和attachment是常用的唯一有效值.

class email.headerregistry.ContentTransferEncoding

处理Content-Transfer-Encoding header.

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和一个从它持有的isgistry中检索出来的专门类。当一个给定的标题名称没有出现在wheregistry中时，default_class指定的类被用作专门类。什么时候 use_default_map是True（默认值），标题名称到类的标准映射在初始化期间被复制到注册表中。base_class总是生成类__bases__列表中的最后一个类

默认映射为：

subject：	UniqueUnstructuredHeader
date：	UniqueDateHeader
resent-date：	DateHeader
原稿日：	UniqueDateHeader
发件人：	UniqueSingleAddressHeader
怨恨发件人：	SingleAddressHeader
到：	UniqueAddressHeader
重新发送至：	AddressHeader
CC：	UniqueAddressHeader
重新发送-CC：	AddressHeader
来自：	UniqueAddressHeader
怨恨-来源：	AddressHeader
回复到：	UniqueAddressHeader

HeaderRegistry有以下方法：

map_to_type（self, name, cls）

name是要映射的标头的名称。它将在注册表中转换为tolower案例。cls是专门用的类，还有base_class，创建用于实例化匹配的类name.

__getitem__（name）

构造并返回一个类来处理创建name header.

__call__（name, value）

从theregistry中检索与name相关联的专用标题（使用default_class如果name没有出现在wheregistry中）并用base_class生成一个类，调用构造的类的构造函数，将它传递给同一个参数列表，最后返回由此创建的类实例.

以下类是用于表示从结构化头文件解析的数据的类，通常可以由应用程序使用toconstruct结构化值来分配给特定的头文件.

class email.headerregistry.Address（display_name=””, username=””, domain=””, addr_spec=None）

用于表示电子邮件地址的类。anaddress的一般形式是：

[display_name] <username@domain>

或：

username@domain

其中每个部分必须符合 RFC 5322 .

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

display_name

地址的显示名称部分（如果有），所有quotingremoved。如果地址没有显示名称，则此属性将为空字符串.

username

username地址的一部分，删除所有引用.

domain

domain部分地址

addr_spec

username@domain地址的一部分，正确引用用作裸地址（上面显示的第二种形式）。这个属性是不可变的

__str__ (）

str对象的值是根据 RFC 5322 //引用的地址规则，但没有任何nonASCII字符的内容传输编码.

支持SMTP（ RFC 5321 ），Address处理一个特例：如果username和domain都是空字符串（或None），则Address的字符串值是<>.

class email.headerregistry.Group（display_name=None, addresses=None）

用于表示地址组的类。anaddress组的一般形式是：

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.

脚注