19.1.14. email.utils：其他实用程序 — Python 文档
19.1.14. 电子邮件工具 : 其他实用程序
源代码： :source:`Lib/email/utils.py`
email.utils 模块中提供了一些有用的实用程序：
- email.utils.localtime(dt=None)
将本地时间作为感知日期时间对象返回。 如果不带参数调用，则返回当前时间。 否则 dt 参数应该是一个 datetime 实例，并根据系统时区数据库转换为本地时区。 如果 dt 是朴素的（即
dt.tzinfo是None），则假定为本地时间。 在这种情况下，isdst 的正值或零值会导致localtime最初假定夏令时（例如，夏令时）对指定的时间有效或无效（分别）时间。 isdst 的负值会导致localtime尝试判断夏令时是否在指定时间内生效。3.3 版中的新功能。
- email.utils.make_msgid(idstring=None, domain=None)
返回适合 RFC 2822 兼容的 Message-ID 标头的字符串。 可选的 idstring 如果给定，则是用于加强消息 id 唯一性的字符串。 可选的 域 如果给出，则提供 '@' 之后的 msgid 部分。 默认为本地主机名。 通常不需要覆盖此默认值，但在某些情况下可能很有用，例如构建跨多个主机使用一致域名的分布式系统。
3.2 版更改： 添加了 域 关键字。
其余功能是遗留 (Compat32) 电子邮件 API 的一部分。 无需直接将这些与新 API 一起使用，因为它们提供的解析和格式化是由新 API 的标头解析机制自动完成的。
- email.utils.quote(str)
- 返回一个新字符串，其中 str 中的反斜杠被两个反斜杠替换，双引号被反斜杠-双引号替换。
- email.utils.unquote(str)
- 返回一个新字符串，它是 str 的 未加引号的 版本。 如果 str 以双引号结束并开始，它们将被剥离。 同样，如果 str 以尖括号结束并开始，它们将被剥离。
- email.utils.parseaddr(address)
- 解析地址——它应该是一些包含地址的字段的值，如 To 或 Cc——解析为其组成部分 realname 和 电子邮件地址 ] 部分。 返回该信息的元组，除非解析失败，在这种情况下返回
(, )的 2 元组。
- email.utils.formataddr(pair, charset='utf-8')
parseaddr() 的反函数，它采用
(realname, email_address)形式的 2 元组，并返回适合 To 或 Cc 的字符串值] 标题。 如果 pair 的第一个元素为假，则第二个元素原封不动地返回。可选的 charset 是将在
realname的 RFC 2047 编码中使用的字符集，如果realname包含非 ASCII 字符。 可以是 str 或 Charset 的实例。 默认为utf-8。3.3 版更改： 添加 字符集 选项。
- 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()返回一个9元组，可以直接传递给time.mktime()； 否则将返回None。 请注意，结果元组的索引 6、7 和 8 不可用。
- email.utils.parsedate_tz(date)
- 执行与 parsedate() 相同的功能，但返回
None或 10 元组； 前 9 个元素组成一个元组，可以直接传递给 time.mktime()，第十个是日期时区与 UTC（格林威治标准时间的官方术语）的偏移量[ X301X]1。 如果输入字符串没有时区，则返回的元组的最后一个元素是None。 请注意，结果元组的索引 6、7 和 8 不可用。
- email.utils.parsedate_to_datetime(date)
format_datetime() 的倒数。 执行与 parsedate() 相同的功能，但成功时返回 datetime。 如果输入日期的时区为
-0000，则datetime将是一个简单的datetime，如果日期符合 RFC，它将代表 UTC 时间，但没有指示日期来自消息的实际源时区。 如果输入日期有任何其他有效的时区偏移量，datetime将是一个可感知的datetime与相应的 timezone tzinfo。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）需要这样做。 这仅在 localtime 为False时适用。 默认值为False。
- email.utils.format_datetime(dt, usegmt=False)
类似于
formatdate，但输入是 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 元组序列。
脚注
