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)

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

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

parseaddr() 的逆运算，它接受一个形式为 (realname, email_address) 的 2 元组，并返回适合 To 或 Cc 头部的字符串值。如果 pair 的第一个元素为假，则返回第二个元素而不修改。

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

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

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（格林威治标准时间）的偏移量 [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，具有相应的 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 实例。如果它是一个 naive datetime，则假定它为“UTC，没有有关源时区的信息”，并且使用传统的 -0000 作为时区。如果它是一个 aware datetime，则使用数字时区偏移量。如果它是一个具有零偏移量的 aware 时区，则可以将 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 指定在 RFC 2231 头部中的字符集不被 Python 识别时要使用的字符集；它默认为 'us-ascii'。

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

email.utils.decode_params(params)

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

脚注