18.1.9. email.utils：其他 Util

email.utils模块中提供了几个有用的 Util：

• email.utils. quote(* str *)

  • 返回一个新字符串，在* str *中用反斜杠替换为两个反斜杠，并将双引号替换为反斜杠-双引号。

• email.utils. unquote(* str *)

  • 返回一个新字符串，该字符串是* str 的未引用版本。如果* str 结束并以双引号开头，则会将其删除。同样，如果 str *结束并以尖括号开头，则会将其删除。

• email.utils. parseaddr(地址)

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

• email.utils. formataddr(* pair *)

  • parseaddr()的倒数，采用(realname, email_address)形式的 2Tuples，并返回适合* To 或 Cc Headers 的字符串值。如果 pair *的第一个元素为 false，则第二个元素将原样返回。

• email.utils. getaddresses(* fieldvalues *)

  • 此方法返回由parseaddr()返回的形式的 2Tuples 列表。 * fieldvalues *是 Headers 字段值的序列，可能由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 *)

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

• email.utils. parsedate_tz(* date *)

  • 执行与parsedate()相同的Function，但返回None或 10Tuples；前 9 个元素组成一个可以直接传递给time.mktime()的 Tuples，第十个元素是该日期的时区相对 UTC 的偏移量(这是 Greenwich 标准时间的正式术语)[1]。如果 Importing 字符串没有时区，则返回的 Tuples 的最后一个元素是None。请注意，结果 Tuples 的索引 6、7 和 8 不可用。

• email.utils. mktime_tz(* tuple *)

  • 将parsedate_tz()返回的 10Tuples 转换为 UTC 时间戳(距离纪元以来的秒数)。如果 Tuples 中的时区项是None，则假定为本地时间。

• email.utils. formatdate(* [timeval [，localtime] [，usegmt]] *)

  • 根据 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。

2.4 版的新Function。

• email.utils. make_msgid([* idstring *])

  • 返回适合 RFC 2822兼容* Message-ID Headers 的字符串。可选的 idstring *(如果提供)是用于增强消息 ID 唯一性的字符串。

• email.utils. decode_rfc2231(* s *)

  • 根据 RFC 2231解码字符串* s *。

• email.utils. encode_rfc2231(* s * [，字符集 [，语言]])

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

• email.utils. collapse_rfc2231_value(* value * [，* errors * [，* fallback_charset *]])

  • 当 Headers 参数以 RFC 2231格式编码时，Message.get_param可能返回包含字符集，语言和值的 3Tuples。 collapse_rfc2231_value()将其转换为 unicode 字符串。可选的* errors 传递给内置unicode()函数的 errors 参数；它默认为replace。可选的 fallback_charset *指定如果 RFC 2231Headers 中的一个字符不被 Python 知道的字符集；它默认为us-ascii。

为了方便起见，如果传递给collapse_rfc2231_value()的* value *不是 Tuples，则它应该是字符串，并且不加引号就返回。

• email.utils. decode_params(* params *)
  • 根据 RFC 2231解码参数列表。 * params *是 2Tuples 的序列，包含(content-type, string-value)形式的元素。

在版本 2.4 中进行了更改：dump_address_pair()函数已被删除；请改用formataddr()。

在版本 2.4 中进行了更改：decode()Function已被删除；请改用Header.decode_header方法。

在版本 2.4 中进行了更改：encode()函数已被删除；请改用Header.encode方法。

Footnotes

• [1]
  • 请注意，时区偏移量的符号与相同时区的time.timezone变量的符号相反。后一个变量遵循 POSIX 标准，而该模块遵循 RFC 2822。