email.headerregistry
:自定义头对象¶
源代码: Lib/email/headerregistry.py
3.6 新版功能: 1
头由自定义的子类表示 str
. 用于表示给定头的特定类由 header_factory
的 policy
在创建标题时生效。本节记录了 header_factory
通过电子邮件包实现处理 RFC 5322 兼容的电子邮件消息,它不仅为各种头类型提供定制的头对象,还为应用程序添加自己的定制头类型提供扩展机制。
当使用从中派生的任何策略对象时 EmailPolicy
,所有标题都由 HeaderRegistry
并拥有 BaseHeader
作为他们最后的基础阶级。每个头类都有一个由头类型决定的附加基类。例如,许多头都有类 UnstructuredHeader
作为他们的另一个基础阶级。头的专用第二类由头的名称确定,使用存储在 HeaderRegistry
. 对于典型的应用程序,所有这些都是透明管理的,但是提供了用于修改默认行为的接口,以供更复杂的应用程序使用。
下面的部分首先记录头基类及其属性,然后是用于修改 HeaderRegistry
最后是用于表示从结构化头解析的数据的支持类。
- class email.headerregistry.BaseHeader(name, value)¶
name 和 value 被传递给
BaseHeader
从header_factory
调用。任何header对象的字符串值都是 value 完全解码为Unicode。此基类定义以下只读属性:
- name¶
头的名称(字段中“:”之前的部分)。这正是
header_factory
需要 name 也就是说,箱子是保存着的。
- 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
词典 must 至少包含键的值decoded
和defects
.decoded
应为头的字符串值(即完全解码为Unicode的头值)。parse方法应该假设 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 标题。
在 RFC 5322 ,非结构化头是一个在ASCII字符集中运行的任意文本。 RFC 2047 但是,有一个 RFC 5322 将非ASCII文本编码为头值内的ASCII字符的兼容机制。当A value 将包含编码的单词传递给构造函数,
UnstructuredHeader
解析器将这些编码的单词转换为Unicode,然后 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
.
这个
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 ,则header对象将具有以下属性的非``none``值:- version¶
将版本号作为字符串,删除任何空白和/或注释。
- major¶
主版本号为整数
- minor¶
作为整数的次要版本号
- class email.headerregistry.ParameterizedMIMEHeader¶
所有的mime头都以前缀“content-”开头。每个特定的头都有一个特定的值,在该头的类下进行描述。有些还可以获取具有通用格式的补充参数列表。这个类作为所有接受参数的mime头的基础。
- params¶
将参数名映射到参数值的字典。
- class email.headerregistry.ContentTypeHeader¶
A
ParameterizedMIMEHeader
类处理 Content-Type 标题。- content_type¶
表单中的内容类型字符串
maintype/subtype
.
- maintype¶
- subtype¶
- class email.headerregistry.ContentDispositionHeader¶
A
ParameterizedMIMEHeader
类处理 Content-Disposition 标题。- content_disposition¶
inline
和attachment
是常用的唯一有效值。
- class email.headerregistry.ContentTransferEncoding¶
处理 Content-Transfer-Encoding 标题。
- 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
- 怨恨
AddressHeader
- 复写的副本
UniqueAddressHeader
- 怨恨CC
AddressHeader
- 基底细胞癌
UniqueAddressHeader
- 重新发送密件抄送
AddressHeader
- 从
UniqueAddressHeader
- 怨恨
AddressHeader
- 答复
UniqueAddressHeader
- MIME版本
MIMEVersionHeader
- 内容类型
ContentTypeHeader
- 内容处置
ContentDispositionHeader
- 内容传输编码
ContentTransferEncodingHeader
- 消息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 可以指定而不是 用户名 和 域 ,在这种情况下 用户名 和 域 将从中分析 addr_spec . 安 addr_spec 必须是正确的RFC引用字符串;如果不是
Address
将引发错误。允许使用Unicode字符,并且在序列化时将对其进行属性编码。但是,根据RFC,Unicode是 not 地址的用户名部分允许。- display_name¶
地址的显示名称部分(如果有的话),删除所有引用。如果地址没有显示名称,则此属性将为空字符串。
- username¶
这个
username
地址的一部分,删除所有引用。
- domain¶
这个
domain
地址的一部分。
- addr_spec¶
这个
username@domain
地址的一部分,正确引用作为裸地址(上面显示的第二种格式)。此属性不可变。
支持SMTP (RFC 5321 )
Address
处理一个特殊情况:如果username
和domain
都是空字符串(或None
)的字符串值,Address
是<>
.
- class email.headerregistry.Group(display_name=None, addresses=None)¶
用于表示地址组的类。地址组的一般形式是:
display_name: [address-list];
为了方便处理由组和单个地址混合组成的地址列表,a
Group
也可以通过设置来表示不属于组的单个地址 display_name 到None
并提供单一地址列表 地址 .- display_name¶
这个
display_name
这个组的如果是None
只有一个Address
在里面addresses
然后Group
表示不在组中的单个地址。
脚注
- 1
最初在3.3中作为 provisional module