19.1.12. email.utils：其他实用程序

源代码： Lib / email / utils.py

在email.utils模块中提供了几个有用的实用程序：

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头的字符串值。如果对的第一个元素为假，那么第二个元素将不被修改。

Optional charset is the character set that will be used in the RFC 2047 encoding of the realname if the realname contains non-ASCII characters. 可以是str或Charset的实例。默认为utf-8。

在版本3.3中已更改：添加了字符集选项。

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()返回一个可以直接传递到time.mktime()的9元组；否则将返回None。请注意，结果元组的索引6，7和8不可用。

email.utils.parsedate_tz(date)

执行与parsedate()相同的功能，但返回None或10元组；前9个元素组成一个元组，可以直接传递到time.mktime()，第十个元素是日期的时区与UTC（这是格林威治标准时间的官方术语）的偏移量， [1]。如果输入字符串没有时区，返回的元组的最后一个元素为None。请注意，结果元组的索引6，7和8不可用。

email.utils.parsedate_to_datetime(date)

format_datetime()的逆。执行与parsedate()相同的功能，但在成功时返回datetime。如果输入日期的时区为-0000，则datetime将是天真的datetime，如果日期符合RFC将表示UTC中的时间，但没有指示日期来自的消息的实际源时区。If the input date has any other valid timezone offset, the datetime will be an aware datetime with the corresponding a 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

如果给定的是time.gmtime()和time.localtime()接受的浮点时间值，则可选timeval用来。

可选localtime是True时解释timeval的标志，并返回相对于本地时区而不是UTC的日期，正确采用夏令时时间考虑。默认值为False，表示使用UTC。

可选usegmt是在True时输出带有时区的日期字符串作为ascii字符串GMT而不是数字-0000。这是一些协议（如HTTP）所需要的。这仅适用于localtime为False时。默认值为False。

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

像formatdate，但输入是datetime实例。如果它是一个朴素的datetime，它被假定为“UTC没有有关源时区的信息”，常规的-0000用于时区。如果它是感知datetime，则使用数字时区偏移。如果是具有偏移零的感知时区，则usegmt可以设置为True，在这种情况下使用字符串GMT数字时区偏移。这提供了一种生成标准一致的HTTP日期标头的方法。

版本3.3中的新功能。

email.utils.localtime(dt=None)

将本地时间作为感知datetime对象返回。如果无参数调用，返回当前时间。否则，dt参数应为datetime实例，并根据系统时区数据库将其转换为本地时区。如果dt是朴素的（即，dt.tzinfo是None），则假定它在本地时间。在这种情况下，isdst的正值或零值导致localtime最初假定夏令时（例如，夏令时）是（分别）有效的在指定的时间。isdst的负值会导致localtime尝试判断夏令时是否在指定时间内有效。

版本3.3中的新功能。

email.utils.make_msgid(idstring=None, domain=None)

Returns a string suitable for an RFC 2822-compliant Message-ID header. 可选idstring如果给定，是用于加强消息id的唯一性的字符串。可选的域（如果给出）在“@”之后提供msgid的部分。默认值为本地主机名。通常不需要覆盖此默认值，但在某些情况下可能有用，例如构建在多个主机之间使用一致域名的分布式系统。

在版本3.2中已更改：添加了域关键字。

email.utils.decode_rfc2231(s)

根据 RFC 2231解码字符串s。

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

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

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

When a header parameter is encoded in RFC 2231 format, Message.get_param may return a 3-tuple containing the character set, language, and value. collapse_rfc2231_value()将其转换为Unicode字符串。将可选的错误传递给str的encode()方法的错误它默认为'replace'。可选fallback_charset指定如果Python中未知 RFC 2231头中的字符集，则使用的字符集；它默认为'us-ascii'。

为了方便起见，如果值传递给collapse_rfc2231_value()不是元组，它应该是一个字符串，并且返回不引用。

email.utils.decode_params(params)

根据 RFC 2231解码参数列表。 params是包含形式（content-type， string-value）的元素的2元组序列。 。

脚注

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