email.utils: 杂项工具

源代码： Lib/email/utils.py

email.utils 模块中提供了一些有用的工具。

email.utils.localtime(dt=None)

以一个感知型 datetime 对象的形式返回本地时间。 如果在不带参数的情况下调用，则返回当前时间。 否则 dt 参数应当为一个 datetime 实例，并且它会根据系统时区数据库被转换为本地时区。 如果 dt 是简单型（即 dt.tzinfo 为 None），则会假定它为本地时间。

在 3.3 版本加入。

自 3.12 版本起废弃，将在 3.14 版本中移除: isdst 形参。

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

返回一个适用于符合 RFC 2822 标准的 Message-ID 标头的字符串。 可选的 idstring 如果给出，则为用于增强消息 id 唯一性的字符串。 可选的 domain 如果给出，则提供了 msgid 中 ‘@’ 之后的部分。 默认值为本地主机名。 通常没有必要重载此默认值，但在某些情况下可能会很有用，例如构建一个在多台主机上使用一致域名的分布式系统。

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

其余函数是旧式 (Compat32) 电子邮件 API 的一部分。 在新的 API 中没有必要直接使用它们，因为它们提供的解析和格式化功能是由新 API 的标头解析机制自动完成的。

email.utils.quote(str)

返回一个新字符串，其中 str 里的反斜杠被替换为两个反斜杠，双引号被替换为反斜杠-双引号。

email.utils.unquote(str)

返回一个新字符串，它是 str 的*反引号*版本。 如果 str 以双引号开始和结束，它们将被剥离。 同样地，如果 str 以尖括号开始和结束，它们也将被剥离。

email.utils.parseaddr(address, *, strict=True)

解析地址 --- address 应为某个包含地址的字段的值，例如 To 或 Cc --- 将其分解为*真实姓名*和*电子邮件地址*部分。 返回包含这些信息的元组，除非解析失败，在这种情况下将返回一个 2 元组 ('', '')。

若 strict 为真值，则使用会拒绝格式错误输入的严格解析器。

在 3.13 版更改: 添加 strict 可选形参并默认拒绝格式错误的输入。

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

parseaddr() 的逆操作，它接受一个 (realname, email_address) 形式的 2 元组，并返回适用于 To 或 Cc 标头的字符串值。 如果 pair 的第一个元素为假值，则第二个元素将被不加修改地返回。

可选的 charset 是当 realname 包含非 ASCII 字符时将用于 realname 的 RFC 2047 编码的字符集。 它可以是 str 的实例或 Charset。 默认为 utf-8。

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

email.utils.getaddresses(fieldvalues, *, strict=True)

此方法返回一个由 parseaddr() 所返回形式的 2-元组构成的列表。 fieldvalues 是标头字段值的序列，就像 Message.get_all 可能返回的那样。

若 strict 为真值，则使用会拒绝格式错误输入的严格解析器。

这里有一个获取消息所有收件人的简单例子

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)

在 3.13 版更改: 添加 strict 可选形参并默认拒绝格式错误的输入。

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]。如果输入字符串没有时区，则返回元组的最后一个元素是 0，代表 UTC。请注意，结果元组的索引 6、7 和 8 是不可用的。

email.utils.parsedate_to_datetime(date)

format_datetime() 的逆操作。 执行与 parsedate() 相同的功能，但在成功时会返回一个 datetime；否则如果 date 包含无效值，例如大于 23 的小时或不在 -24 到 24 小时之间的时区偏移，则会引发 ValueError。 如果输入日期的时区为 -0000，则 datetime 将是一个简单型 datetime，并且如果日期符合 RFC 规定，它将表示 UTC 时间，但没有指明日期所在消息的实际源时区。 如果输入日期具有任何其他有效的时区偏移，则 datetime 将是一个感知型 datetime，并带有相应的 timezone tzinfo。

在 3.3 版本加入。

email.utils.mktime_tz(tuple)

将 parsedate_tz() 返回的 10 元组转换为 UTC 时间戳（自 Epoch 以来的秒数）。 如果元组中的时区项为 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）是必需的。 这仅在 localtime 为 False 时适用。 默认为 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 进行编码。 如果给出可选的 charset 和 language，则它们是要使用的字符集名称和语言名称。 如果两者都未给出，则 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 会被传递给 str 的 encode() 方法的 errors 参数；它默认为 'replace'。 可选的 fallback_charset 指定当 RFC 2231 标头中的字符集不为 Python 所知时要使用的字符集；它默认为 'us-ascii'。

为方便起见，如果传递给 collapse_rfc2231_value() 的 value 不是元组，则它应该是一个字符串，并且会不加引号地返回。

email.utils.decode_params(params)

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

脚注