email.utils: 杂项工具

源代码: Lib/email/utils.py

在 email.utils 模块中提供了多个有用的工具：

email.utils.localtime(dt=None)

将本地时间作为一个感知型 datetime 对象返回。 如果不带参数地调用，则返回当前时间。 在其他情况下 dt 参数应为 datetime 的实例，并将根据系统时区数据库将其转换为本地时区。 如果 dt 为简单型 (即 dt.tzinfo 为 None)，它将被视为本地时间。

Added in version 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)

Attempts to parse a date according to the rules in RFC 2822 Section 3.3. However, some mailers don't follow that format as specified, so parsedate() tries to guess correctly in such cases. date is a string containing an RFC 2822 date, such as "Mon, 20 Nov 1995 19:12:08 -0500". If it succeeds in parsing the date, parsedate() returns a 9-tuple that can be passed directly to time.mktime(); otherwise None will be returned. Note that indexes 6, 7, and 8 of the result tuple are not usable.

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)

The inverse of format_datetime(). Performs the same function as parsedate(), but on success returns a datetime; otherwise ValueError is raised if date contains an invalid value such as an hour greater than 23 or a timezone offset not between -24 and 24 hours. If the input date has a timezone of -0000, the datetime will be a naive datetime, and if the date conforms to the RFCs it will represent a time in UTC but with no indication of the actual source timezone of the message the date comes from. If the input date has any other valid timezone offset, the datetime will be an aware datetime whose corresponding tzinfo attribute is a timezone object.

Added in version 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

Optional timeval, if given, is a floating-point time value as accepted by time.gmtime() and time.localtime(), otherwise the current time is used.

Optional localtime is a flag that when True, interprets timeval, and returns a date relative to the local timezone instead of UTC, properly taking daylight saving time into account. The default is False meaning UTC is used.

Optional usegmt is a flag that when True, outputs a date string with the timezone as an ASCII string GMT, rather than a numeric -0000. This is needed for some protocols (such as HTTP). This only applies when localtime is False. The default is False.

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

Like formatdate(), but the input is a datetime instance. If it is a naive datetime, it is assumed to be "UTC with no information about the source timezone", and the conventional -0000 is used for the timezone. If it is an aware datetime, then the numeric timezone offset is used. If it is an aware timezone with offset zero, then usegmt may be set to True, in which case the string GMT is used instead of the numeric timezone offset. This provides a way to generate standards-conformant HTTP date headers.

Added in version 3.3.

email.utils.decode_rfc2231(s)

根据 RFC 2231 解码字符串 s。

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

Encode the string s according to RFC 2231. Optional charset and language, if given, are the character set name and language name to use. If neither is given, s is returned as-is. If charset is given but language is not, the string is encoded using the empty string for language.

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() turns this into a string. Optional errors is passed to the errors argument of str's encode() method; it defaults to 'replace'. Optional fallback_charset specifies the character set to use if the one in the RFC 2231 header is not known by Python; it defaults to 'us-ascii'.

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

email.utils.decode_params(params)

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

脚注