Skip to main content

19.1.14. email.utils:杂项实用程序

源代码: Lib/email/utils.py


email.utils 模块中提供了一些有用的实用程序:

email.utils.localtime(dt=None)

将本地时间作为感知datetime对象返回。如果无参数调用,返回当前时间。否则,dt 参数应为 datetime 实例,并根据系统时区数据库转换为本地时区。如果 dt 是幼稚的(即,dt.tzinfoNone),则假定是在本地时间。在这种情况下,isdst 的正值或零值使得 localtime 最初假定夏令时(例如夏令时)在指定时间内(或分别)有效。 isdst 的负值导致 localtime 尝试去判断夏令时是否在指定时间内有效。

3.3 新版功能.

email.utils.make_msgid(idstring=None, domain=None)

返回适用于符合 RFC 2822Message-ID 标题的字符串。可选的 idstring (如果给定)是用于加强消息id的唯一性的字符串。可选 domain (如果给定)在“@”之后提供msgid的部分。默认值为本地主机名。通常不需要覆盖此默认值,但在某些情况下可能有用,例如构建在多个主机之间使用一致域名的分布式系统。

在 3.2 版更改: 添加了 domain 关键字。

其余的功能是遗留(Compat32)电子邮件API的一部分。没有必要直接使用这些与新的API,因为它们提供的解析和格式化是由新的API的头解析机制自动完成。

email.utils.quote(str)

返回一个新的字符串,反斜杠在 str 中被两个反斜杠替换,双引号替换为反斜杠双引号。

email.utils.unquote(str)

返回一个新的字符串,它是 strunquoted 版本。如果 str 结束并以双引号开头,它们将被删除。同样,如果 str 结束并以尖括号开始,则它们被剥离。

email.utils.parseaddr(address)

解析地址 - 它应该是一些包含地址的字段的值,例如 ToCc - 到其组成的 realname电子邮件地址 部分。返回该信息的元组,除非解析失败,在这种情况下返回一个2元组的 ('', '')

email.utils.formataddr(pair, charset='utf-8')

parseaddr() 的逆,这需要一个形式为 (realname, email_address) 的2元组,并返回适用于 ToCc 头的字符串值。如果 pair 的第一个元素是false,那么第二个元素是未修改的。

可选 charset 是将在 RFC 2047 编码中用于 realname 的字符集,如果 realname 包含非ASCII字符。可以是 strCharset 的实例。默认为 utf-8

在 3.3 版更改: 添加了 charset 选项。

email.utils.getaddresses(fieldvalues)

此方法返回由 parseaddr() 返回的表单的2元组列表。 fieldvalues 是可能由 Message.get_all 返回的报头字段值的序列。这是一个简单的示例,获取邮件的所有收件人:

from email.utils import getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
email.utils.parsedate(date)

尝试根据 RFC 2822 中的规则解析日期。然而,一些邮件程序不遵循指定的格式,因此 parsedate() 尝试在这种情况下正确猜测。 date 是包含 RFC 2822 日期的字符串,例如 "Mon, 20 Nov 1995 19:12:08 -0500"。如果它成功解析日期,parsedate() 返回一个可以直接传递给 time.mktime() 的9元组;否则将返回 None。请注意,结果元组的索引6,7和8不可用。

email.utils.parsedate_tz(date)

执行与 parsedate() 相同的功能,但返回 None 或10元组;前9个元素组成一个可以直接传递给 time.mktime() 的元组,第十个元素是日期的时区与UTC(这是格林威治标准时间的官方术语) [1] 的偏移量。如果输入字符串没有时区,返回的元组的最后一个元素是 None。请注意,结果元组的索引6,7和8不可用。

email.utils.parsedate_to_datetime(date)

format_datetime() 的逆。执行与 parsedate() 相同的功能,但在成功时返回 datetime。如果输入日期具有 -0000 的时区,则 datetime 将是原始 datetime,并且如果日期符合RFC,则它将表示UTC中的时间,但是没有指示日期来自消息的实际源时区。如果输入日期具有任何其他有效的时区偏移,则 datetime 将是具有相应的 timezone tzinfo 的感知 datetime

3.3 新版功能.

email.utils.mktime_tz(tuple)

parsedate_tz() 返回的10元组转换为UTC时间戳(自纪元以来的秒数)。如果元组中的时区项为 None,则假定本地时间。

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

返回根据 RFC 2822 的日期字符串,例如。:

Fri, 09 Nov 2001 01:08:47 -0000

如果给定的可选 timeval 是由 time.gmtime()time.localtime() 接受的浮点时间值,否则使用当前时间。

可选 localtime 是一个标志,当 True 解释 timeval 时,并返回相对于本地时区而不是UTC的日期,正确考虑夏令时。默认值为 False,表示使用UTC。

可选 usegmt 是一个标志,当 True 输出具有时区的日期字符串作为ascii字符串 GMT,而不是数字 -0000。这是一些协议(如HTTP)所需要的。这仅适用于 localtimeFalse 时。默认值为 False

email.utils.format_datetime(dt, usegmt=False)

formatdate,但输入是一个 datetime 实例。如果它是一个朴素的datetime,它被假定为“UTC没有有关源时区的信息”,常规的 -0000 用于时区。如果它是一个感知 datetime,则使用数字时区偏移。如果它是具有偏移零的感知时区,则 usegmt 可以被设置为 True,在这种情况下,使用字符串 GMT 而不是数字时区偏移。这提供了一种生成符合标准的HTTP日期标头的方法。

3.3 新版功能.

email.utils.decode_rfc2231(s)

根据 RFC 2231 解码字符串 s

email.utils.encode_rfc2231(s, charset=None, language=None)

根据 RFC 2231 编码字符串 s。可选的 charsetlanguage,如果给出的是要使用的字符集名称和语言名称。如果没有给出,则 s 按原样返回。如果给定 charset 但不是 language,则使用 language 的空字符串对该字符串进行编码。

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

当头参数以 RFC 2231 格式编码时,Message.get_param 可以返回包含字符集,语言和值的3元组。 collapse_rfc2231_value() 将其转换为Unicode字符串。可选 errors 被传递给 strencode() 方法的 errors 参数;它默认为 'replace'。可选的 fallback_charset 指定要使用的字符集,如果Python不知道 RFC 2231 头中的字符集;它默认为 'us-ascii'

为了方便起见,如果传递给 collapse_rfc2231_value()value 不是元组,它应该是一个字符串,并且返回不引用。

email.utils.decode_params(params)

根据 RFC 2231 解码参数列表。 params 是包含形式为 (content-type, string-value) 的元素的2元组序列。

脚注

[1]

注意,时区偏移的符号与相同时区的 time.timezone 变量的符号相反;后一个变量遵循POSIX标准,而此模块遵循 RFC 2822