"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 元组的序列。

-[ 脚注 ]-

[1] Note that the sign of the timezone offset is the opposite of the
    sign of the "time.timezone" variable for the same timezone; the
    latter variable follows the POSIX standard while this module
    follows **RFC 2822**.
