Docs4dev
Docs
python / 3.7.2rc1 / all / library-email.utils.html

email.utils：其他 Util

源代码： Lib/email/utils.py

email.utils模块中提供了几个有用的 Util：

  • email.utils. localtime(* dt = None *)
    • 返回本地时间作为已知的日期时间对象。如果不带参数调用，则返回当前时间。否则，* dt 参数应为datetime实例，并根据系统时区数据库将其转换为本地时区。如果 dt 天真(即dt.tzinfo为None)，则假定为当地时间。在这种情况下， isdst *的正值或零值会导致localtime最初假定夏令时(例如，夏时制)在指定时间内(分别)有效。 * isdst *为负值会使localtimetry判断指定时间的夏令时是否有效。

版本 3.3 中的新Function。

  • email.utils. make_msgid(* idstring = None ， domain = None *)
    • 返回适合 RFC 2822兼容* Message-ID Headers 的字符串。可选的 idstring (如果提供)是用于增强消息 ID 唯一性的字符串。可选的 domain *(如果提供)提供了 msgid 在“ @”之后的部分。默认值为 localhost 名。通常不必覆盖此默认值，但在某些情况下可能很有用，例如在多个主机之间使用一致域名的构造分布式系统。

在 3.2 版中进行了更改：添加了* domain *关键字。

其余Function是旧版(Compat32)电子邮件 API 的一部分。不需要直接将它们与新 API 一起使用，因为它们提供的解析和格式化是由新 API 的 Headers 解析机制自动完成的。

  • email.utils. quote(* str *)

    • 返回一个新字符串，在* str *中用反斜杠替换为两个反斜杠，并将双引号替换为反斜杠-双引号。

  • email.utils. unquote(* str *)

    • 返回一个新字符串，该字符串是* str 的未引用版本。如果* str 结束并以双引号开头，则会将其删除。同样，如果 str *结束并以尖括号开头，则会将其删除。

  • email.utils. parseaddr(地址)

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

  • email.utils. formataddr(* pair ， charset ='utf-8'*)

    • parseaddr()的倒数，采用(realname, email_address)形式的 2Tuples，并返回适合* To 或 Cc Headers 的字符串值。如果 pair *的第一个元素为 false，则第二个元素将原样返回。

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

在版本 3.3 中进行了更改：添加了* charset *选项。

  • email.utils. getaddresses(* fieldvalues *)
    • 此方法返回由parseaddr()返回的形式的 2Tuples 列表。 * fieldvalues *是 Headers 字段值的序列，可能由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 *)

    • try根据 RFC 2822中的规则解析日期。但是，某些邮件程序未遵循指定的格式，因此parsedate()在这种情况下会try正确猜测。 * date *是包含 RFC 2822日期的字符串，例如"Mon, 20 Nov 1995 19:12:08 -0500"。如果成功解析日期，则parsedate()返回一个 9Tuples，可以直接传递给time.mktime()；否则将返回None。请注意，结果 Tuples 的索引 6、7 和 8 不可用。

  • email.utils. parsedate_tz(* date *)

    • 执行与parsedate()相同的Function，但返回None或 10Tuples；前 9 个元素组成一个可以直接传递给time.mktime()的 Tuples，第十个元素是该日期的时区相对于 UTC(Greenwich 标准时间的正式术语)[1]的偏移量。如果 Importing 字符串没有时区，则返回的 Tuples 的最后一个元素是0，它表示 UTC。请注意，结果 Tuples 的索引 6、7 和 8 不可用。

  • email.utils. parsedate_to_datetime(* date *)

    • format_datetime()的倒数。执行与parsedate()相同的Function，但成功返回datetime。如果 Importing 日期的时区为-0000，则datetime将为天真datetime，并且如果该日期符合 RFC，则它将以 UTC 表示一个时间，但不表示该消息来自的实际消息时区。如果 Importing 日期具有任何其他有效时区偏移，则datetime将是有意识的datetime，其对应的是timezone tzinfo。

版本 3.3 中的新Function。

  • email.utils. mktime_tz(* tuple *)

    • 将parsedate_tz()返回的 10Tuples 转换为 UTC 时间戳(距离纪元以来的秒数)。如果 Tuples 中的时区项是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，但是 Importing 是datetime实例。如果是原始日期时间，则将其假定为“没有有关源时区的信息的 UTC”，并且将常规-0000用作时区。如果它是datetime，则使用数字时区偏移量。如果它是偏移量为零的感知时区，则可以将* usegmt *设置为True，在这种情况下，将使用字符串GMT代替数字时区偏移量。这提供了一种生成符合标准 HTTP 日期 Headers 的方法。

版本 3.3 中的新Function。

  • 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'*)

    • 当 Headers 参数以 RFC 2231格式编码时，Message.get_param可能返回包含字符集，语言和值的 3Tuples。 collapse_rfc2231_value()将其转换为 unicode 字符串。可选的* errors 传递给str的encode()方法的 errors 参数；它默认为'replace'。可选的 fallback_charset *指定如果 RFC 2231Headers 中的一个不被 Python 知道的字符集；它默认为'us-ascii'。

为了方便起见，如果传递给collapse_rfc2231_value()的* value *不是 Tuples，则它应该是字符串，并且不加引号就返回。

  • email.utils. decode_params(* params *)
    • 根据 RFC 2231解码参数列表。 * params *是 2Tuples 的序列，包含(content-type, string-value)形式的元素。

Footnotes

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