email.utils: 杂项实用工具

源代码： Lib/email/utils.py

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

email.utils.localtime(dt=None)

返回作为感知型 datetime 对象的本地时间。如果调用时不带参数，则返回当前时间。否则，dt 参数应该是一个 datetime 实例，并且根据系统时区数据库将其转换为本地时区。如果 dt 是朴素的（即 dt.tzinfo 是 None），则假定它处于本地时间。 isdst 参数将被忽略。

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)

将地址（应为包含地址的字段（例如 To 或 Cc）的值）解析为其组成的 realname 和电子邮件地址部分。 返回该信息的元组，除非解析失败，否则返回 ('', '') 的 2 元组。

如果 strict 为 true，则使用严格的解析器，该解析器会拒绝格式错误的输入。

在 3.13 版本中更改: 添加 strict 可选参数，默认情况下拒绝格式错误的输入。

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

与 parseaddr() 相反，此方法采用 (realname, email_address) 形式的 2 元组，并返回适用于 To 或 Cc 标头的字符串值。 如果 pair 的第一个元素为 false，则返回第二个元素，不做修改。

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

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

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

此方法返回 parseaddr() 返回的 2 元组形式的列表。 fieldvalues 是标头字段值序列，如 Message.get_all 返回的那样。

如果 strict 为 true，则使用严格的解析器，该解析器会拒绝格式错误的输入。

这是一个简单的示例，获取消息的所有收件人

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() 将返回一个 9 元组，该元组可以直接传递给 time.mktime()；否则将返回 None。请注意，结果元组的索引 6、7 和 8 不可用。

email.utils.parsedate_tz(date)

执行与 parsedate() 相同的功能，但返回 None 或一个 10 元组；前 9 个元素构成一个可以直接传递给 time.mktime() 的元组，第 10 个元素是日期时区与 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 将是一个带有相应 timezone tzinfo 的感知型 datetime。

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 指定如果 Python 不知道 RFC 2231 标头中的字符集，则使用的字符集；它默认为 'us-ascii'。

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

email.utils.decode_params(params)

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

脚注