email.utils:其他 Util

源代码: Lib/email/utils.py


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

  • email.utils. localtime(* dt = None *)
    • 返回本地时间作为已知的日期时间对象。如果不带参数调用,则返回当前时间。否则,* dt 参数应为datetime实例,并根据系统时区数据库将其转换为本地时区。如果 dt 天真(即dt.tzinfoNone),则假定为当地时间。在这种情况下, 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编码中使用的字符集。可以是strCharset的实例。默认为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 传递给strencode()方法的 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