Python Email.utils

首先，我们应该了解 Python 的 email 包是什么。

email 包是一个用于管理电子邮件消息的库。它明确不打算向 SMTP (RFC 2821)、NNTP 或其他服务器发送任何电子邮件消息；这些任务由 smtplib 和 nntplib 等模块执行。

大多数办公室工作有什么共同点？在大多数工作中，您都需要频繁发送电子邮件。

无论您是工程师、程序员还是数据科学家，您可能每天都需要阅读和回复电子邮件。尽管这项活动不会促进我们的职业发展，但它会扰乱我们的工作效率并消耗宝贵的时间。

在 email.utils 模块中，有一些有用的工具。让我们逐一了解它们。

1.nutils.localtime(dt=None)

作为感知的 datetime 对象，返回本地时间。如果调用时不带任何参数，则返回当前时间。如果没有，则 dt 参数应该是 datetime 实例，它将使用系统的时区数据库转换为本地时区。如果 dt 是朴素的（即，如果 dt.tzinfo 是 None），则假定 dt 是本地时间。在这种情况下，如果 isdst 为正值或负值，localtime 将首先假定在给定时间夏令时（例如，夏令时）生效或不生效。当 isdst 设置为负值时，localtime 会尝试确定在给定时间夏令时是否生效。

这是 3.3 版本的新增功能。

2.mutils.make_msgid(idstring=None, domain=None)

返回一个字符串，适合用作符合 RFC 2822 的 Message-ID 标头。如果提供了可选的 idstring，则它是用于增加消息的唯一性级别的字符串。如果提供了可选的 domain，则它显示 @ 符号后面的 msgid 文本。默认情况下使用本地主机名。尽管覆盖此默认值通常是不必要的，但在某些情况下可能需要，例如构建在多个主机上使用一致域名作为 msgid 的分布式系统。

domain 关键字是在 3.2 版本中添加的。

其余功能包含在旧的 (Compat32) email API 中。新 API 会自动进行解析和格式化，因此无需直接使用这些旧功能。

3. utils.unquote(str)

返回一个新字符串，它是 str 的未加引号的等价物。如果 str 的开头和结尾都有双引号，则会移除它们。同样，如果 str 的开头和结尾都有尖括号，则会移除它们。

4. utils.quote(str)

返回一个格式字符串，其中双引号被替换为反斜杠双引号，反斜杠被替换为两个反斜杠。

5. utils.parseaddr(address)

将地址解析为实际姓名和电子邮件地址组件。address 应该是包含地址的字段（如 To 或 Cc）的值。除非解析失败，否则返回一个包含该信息的元组；解析失败时，返回 (", ") 的 2 元组。

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

该函数接受一个 (真实姓名, 电子邮件地址) 类型的 2 元组，并返回一个适合 To 或 Cc 标头的字符串值。此函数是 parseaddr() 的反向操作。如果 pair 的第一个元素为 false，则 pair 的第二个成员将原样返回。

如果真实姓名包含非 ASCII 字符，则可选的 charset 字符集将用于 RFC 2047 编码的真实姓名。charset 可以是 Charset 或 str 的实现。UTF-8 是默认值。

版本 3.3 引入了编码选择。

7. utils.getaddresses(fieldvalues)

此方法返回一个 2 元组列表，格式与 parseaddr() 返回的相同。fieldvalues 是 Message.get_all() 可能返回的标头字段值列表。以下是一个简单明了的示例，它将触及所有消息收件人，让我们通过示例来理解这一点。

示例

输出

[('', 'java'), ('', 'tpoint'), ('', 'JAVA'), ('', 'TPOINT')]

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

它根据 RFC 2822 返回日期字符串。

如果提供了浮点时间值（如 time.gmtime() 和 time.localtime() 接受的值），则使用可选的 timeval；否则，使用当前时间。

可选的 localtime 是一个标志，当设置为 True 时，它解释 timeval，并返回一个正确考虑了夏令时并与本地时区相关的日期，而不是返回 UTC 日期。如果默认值为 False，则使用 UTC。

可选的 usegmt 标志设置为 True 时，将生成一个带有 GMT 的日期字符串，而不是数字 -0000 作为时区。某些协议（如 HTTP）需要这样做。仅当 localtime 为 False 时，此选项才适用。False 是预设值。

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

与 formatdate 类似，但输入为 datetime 实例。如果 datetime 是朴素的，则假定它为“没有关于原始时区信息的 UTC”，并且使用标准的 -0000 作为时区。如果 datetime 是感知的，则使用数值时区偏移量。

如果 usegmt 设置为 True 并且时区是偏移量为零的感知时区，则使用 GMT 文本代替数值时区偏移量。这提供了一种创建符合标准的 HTTP 日期标头的方法。

10. utils.decode_rfc2231(s)

根据 RFC 2231 解码字符串 s。

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

字符串 s 应使用 RFC 2231 进行编码。如果提供了可选的 charset 和 language，则指定要使用的字符集和语言。如果两者均未提供，则 s 按原样返回。如果指定了 charset 但未指定 language，则使用空字符串作为 language 对字符串进行编码。

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

通过调用 Message.get_param 来处理已使用 RFC 2231 格式编码的标头参数，可以返回一个由字符集、语言和值组成的 3 元组。collapse_rfc2231_value() 将其转换为 unicode 字符串。str 的 encode() 方法的 errors 参数是可选的，默认为“replace”。可选的 fallback_charset，默认为“us-ascii”，指定了在 Python 无法识别 RFC 2231 标头中的字符集时要使用的字符集。

为了方便使用，传递给 collapse_rfc2231_value() 的值应为字符串，如果不是元组，则会作为未加引号的值返回。

13. utils.decode_params(params)

根据 RFC 2231 解码参数列表。“params”是由 (content-type, string-value) 形式的组件组成的 2 元组序列。

14. utils.mktime_tz(tuple)

根据 parsedate_tz() 提供的 10 元组（自 Epoch 以来的秒数）创建 UTC 时间戳。如果元组中的时区项为 None，则假定为本地时间。

15. 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 无法使用。

16. utils.parsedate_tz(date)

执行与 parsedate() 相同的任务，并返回 None 或一个 10 元组，该元组的最后一个元素是日期时区相对于 UTC（格林威治标准时间）的偏移量，而前九个元素组成一个可以立即传递给 time.mktime() 的元组。如果输入字符串没有时区信息，则返回的元组的最后一个元素为 0，表示 UTC。应注意，结果元组的索引 6、7 和 8 无法使用。

17. utils.parsedate_to_datetime(date)

format_datetime() 的替代方法。它的作用与 parsedate() 相同，但如果成功，则提供一个 datetime 对象。如果日期包含无效值（例如，小时大于 23，或时区偏移量不在 -24 到 24 小时之间），则会引发 ValueError。如果输入日期时区为 -0000，则 datetime 对象将是朴素的，并且如果日期符合 RFC 标准，它将表示 UTC 时间，而不会提及消息的真实来源时区。如果输入日期具有任何其他有效时区偏移量，则 datetime 对象将是具有相应时区 tzinfo 的感知 datetime 对象。

结论

在本文中，我们讨论了 email.utils 模块以及上面文章中讨论的一些有用工具。