email.headerregistry自定义标题对象

源代码: Lib / email / headerregistry.py


版本3.6中新增: [1]

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

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

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

class email.headerregistry.BaseHeader (name, value

namevalue传递给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,因为标题可能不包含任意二进制数据。如果utf8False,非ASCII数据将是 RFC 2047 编码

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

parse(string, kwds)

kwds是一个包含一个预先初始化的密钥的字典,defects.defects是一个空列表。解析方法应将任何检测到的缺陷附加到此列表中。返回时,kwds字典must包含至少键decodeddefects. 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_nameNone.

addresses

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

decoded标题的值将使所有编码的单词解码为tounicode。idna编码的域名也被解码为tounicode。decoded值由joinstr元素的价值groups属性",".

的列表 AddressGroup任何组合中的对象都可以用来设置地址头的值。Group的对象display_nameNone将被解释为单个地址,通过使用从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

inlineattachment是常用的唯一有效值.

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_mapTrue(默认值),标题名称到类的标准映射在初始化期间被复制到注册表中。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_typeself, 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.Addressdisplay_name=””, username=””, domain=””, addr_spec=None

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

[display_name] <username@domain>

或:

username@domain

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

为方便起见addr_spec可以指定而不是usernamedomain, 在这种情况下 usernamedomain将从解析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处理一个特例:如果usernamedomain都是空字符串(或None),则Address的字符串值是<>.

class email.headerregistry.Groupdisplay_name=None, addresses=None

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

display_name: [address-list];

为方便处理由组和单个地址混合组成的地址列表,Group也可用于表示不属于的单个地址通过设置display_nameNone并提供单个地址列表为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作为临时模块

评论被关闭。