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，将提供消息 ID 在 '@' 之后的部分。 默认值为本机的主机名。 通常不需要覆盖此默认值，但在特定情况下可能会有用处，比如构造一个分布式系统在多台主机上使用一致的域名。

在 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 之类包含地址的字段值）解析为其构成部分：真实名字 和 电子邮件地址 部分。返回包含这两个信息的一个元组；如若解析失败，则返回一个二元组 ('', '')。

如果 strict 为真值，将使用拒绝错误形式输入的严格解析器。

在 3.13 版本发生变更: 增加了 strict 可选形参并将默认拒绝错误形式输入。

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

parseaddr() 的逆操作，它接受一个 (realname, email_address) 形式的 2 元组并返回适合作为 To 或 Cc 标头的字符串值。 如果 pair 的第一个元素为假值，则原样返回第二个元素。

可选地，如果指定 charset，则被视为一个符合 RFC 2047 的编码字符集，用于编码 realname 中的非 ASCII 字符。可以是一个 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 Section 3.3 中的规则解析日期。然而，某些邮件发送者并未按照指定格式执行，因此 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 (格林威治平均时 GMT 的正式名称) [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，其对应的 tzinfo 属性为 timezone 对象。

在 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 实例。如果该实例为未设时区的时间戳，则假定其为“采用 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() 可返回一个包含字符集、语言和值的三元组。collapse_rfc2231_value() 将其转换为字符串。可选参数 errors 会被传递给 str 的 encode() 方法的 errors 参数；其默认值为 'replace'。可选参数 fallback_charset 用于指定：如果 RFC 2231 头部中的字符集为 Python 所不支持的字符集，则应使用哪个字符集；其默认值为 'us-ascii'。

为方便起见，如果传给 collapse_rfc2231_value() 的 value 不是一个元组，则应为一个字符串并会将其去除引号后返回。

email.utils.decode_params(params)

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

脚注