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
作为时区。如果它是一个 awaredatetime
,则使用数字时区偏移量。如果它是一个具有零偏移量的 aware 时区,则可以将 usegmt 设置为True
,在这种情况下,使用字符串GMT
而不是数字时区偏移量。这提供了一种生成符合标准的 HTTP 日期头的方法。在版本 3.3 中添加。
- 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 元组序列。
脚注