email.utils
: 其他工具¶
源代码: Lib/email/utils.py
email.utils
模块提供如下几个工具
-
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)¶ 返回一个适合作为兼容 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)¶ 将地址(应为诸如 To 或者 Cc 之类包含地址的字段值)解析为构成之的 真实名字 和 电子邮件地址 部分。返回包含这两个信息的一个元组;如若解析失败,则返回一个二元组
('', '')
。
-
email.utils.
formataddr
(pair, charset='utf-8')¶ 是
parseaddr()
的逆操作,接受一个(真实名字, 电子邮件地址)
的二元组,并返回适合于 To or Cc 标头的字符串。如果第一个元素为假性值,则第二个元素将被原样返回。可选地,如果指定 charset,则被视为一符合 RFC 2047 的编码字符集,用于编码
真实名字
中的非 ASCII 字符。可以是一个str
类的实例,或者一个Charset
类。默认为utf-8
。3.3 版更變: 添加了 charset 选项。
-
email.utils.
getaddresses
(fieldvalues)¶ 该方法返回一个形似
parseaddr()
返回的二元组的列表。 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 是一个字符串包含了一个形如"Mon, 20 Nov 1995 19:12:08 -0500"
的 RFC 2822 格式日期。如果日期解析成功,parsedate()
将返回一个九元组,可直接传递给time.mktime()
;否则返回None
。注意返回的元组中下标为 6、7、8 的部分是无用的。
-
email.utils.
parsedate_tz
(date)¶ Performs the same function as
parsedate()
, but returns eitherNone
or a 10-tuple; the first 9 elements make up a tuple that can be passed directly totime.mktime()
, and the tenth is the offset of the date's timezone from UTC (which is the official term for Greenwich Mean Time) 1. If the input string has no timezone, the last element of the tuple returned is0
, which represents UTC. Note that indexes 6, 7, and 8 of the result tuple are not usable.
-
email.utils.
parsedate_to_datetime
(date)¶ format_datetime()
的逆操作。 执行与parsedate()
相同的功能,但会在成功时返回一个datetime
。 如果输入日期的时区值为-0000
,则datetime
将为一个简单型datetime
,而如果日期符合 RFC 标准则它将代表一个 UTC 时间,但是并不指明日期所在消息的实际源时区。 如果输入日期具有任何其他有效的时区差值,则datetime
将为一个感知型datetime
并与timezone
tzinfo
相对应。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()
andtime.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 savings time into account. The default isFalse
meaning UTC is used.Optional usegmt is a flag that when
True
, outputs a date string with the timezone as an ascii stringGMT
, rather than a numeric-0000
. This is needed for some protocols (such as HTTP). This only applies when localtime isFalse
. The default isFalse
.
-
email.utils.
format_datetime
(dt, usegmt=False)¶ Like
formatdate
, but the input is adatetime
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 awaredatetime
, then the numeric timezone offset is used. If it is an aware timezone with offset zero, then usegmt may be set toTrue
, in which case the stringGMT
is used instead of the numeric timezone offset. This provides a way to generate standards conformant HTTP date headers.3.3 版新加入.
-
email.utils.
encode_rfc2231
(s, charset=None, language=None)¶ Encode the string s according to RFC 2231. Optional charset and language, if given is 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 unicode string. Optional errors is passed to the errors argument ofstr
'sencode()
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'
.For convenience, if the value passed to
collapse_rfc2231_value()
is not a tuple, it should be a string and it is returned unquoted.
-
email.utils.
decode_params
(params)¶ Decode parameters list according to RFC 2231. params is a sequence of 2-tuples containing elements of the form
(content-type, string-value)
.
备注