email.utils: 其他工具?

源代碼: Lib/email/utils.py

email.utils 模塊提供如下幾個(gè)工具

email.utils.localtime(dt=None)?

以感知型 datetime 對(duì)象返回當(dāng)?shù)貢r(shí)間。 如果調(diào)用時(shí)參數(shù)為空，則返回當(dāng)前時(shí)間。 否則 dt 參數(shù)應(yīng)該是一個(gè) datetime 實(shí)例，并根據(jù)系統(tǒng)時(shí)區(qū)數(shù)據(jù)庫(kù)轉(zhuǎn)換為當(dāng)?shù)貢r(shí)區(qū)。 如果 dt 是簡(jiǎn)單型的 （即 dt.tzinfo 是 None )，則假定為當(dāng)?shù)貢r(shí)間。 在這種情況下，為正值或零的 isdst 會(huì)使 localtime 假定夏季時(shí)間（例如，夏令時(shí)）對(duì)指定時(shí)間（分別）生效或不生效。 負(fù)值 isdst 會(huì)使 localtime 預(yù)測(cè)夏季時(shí)間對(duì)指定時(shí)間是否生效。

3.3 新版功能.

email.utils.make_msgid(idstring=None, domain=None)?

返回一個(gè)適合作為兼容 RFC 2822 的 Message-ID 標(biāo)頭的字符串。可選參數(shù) idstring 可傳入一字符串以增強(qiáng)該消息 ID 的唯一性。可選參數(shù) domain 可用于提供消息 ID 中字符 '@' 之后的部分，其默認(rèn)值是本機(jī)的主機(jī)名。正常情況下無(wú)需覆蓋此默認(rèn)值，但在特定情況下覆蓋默認(rèn)值可能會(huì)有用，比如構(gòu)建一個(gè)分布式系統(tǒng)，在多臺(tái)主機(jī)上采用一致的域名。

在 3.2 版更改: 增加了關(guān)鍵字 domain

下列函數(shù)是舊（Compat32）電子郵件 API 的一部分。新 API 提供的解析和格式化在標(biāo)頭解析機(jī)制中已經(jīng)被自動(dòng)完成，故在使用新 API 時(shí)沒(méi)有必要直接使用它們函數(shù)。

email.utils.quote(str)?

返回一個(gè)新的字符串， str 中的反斜杠被替換為兩個(gè)反斜杠，并且雙引號(hào)被替換為反斜杠加雙引號(hào)。

email.utils.unquote(str)?

返回 str 被去除引用版本的字符串。如果 str 開(kāi)頭和結(jié)尾均是雙引號(hào)，則這對(duì)雙引號(hào)被去除。類(lèi)似地，如果 str 開(kāi)頭和結(jié)尾都是尖角括號(hào)，這對(duì)尖角括號(hào)會(huì)被去除。

email.utils.parseaddr(address)?

將地址（應(yīng)為諸如 To 或者 Cc 之類(lèi)包含地址的字段值）解析為構(gòu)成之的 真實(shí)名字 和 電子郵件地址 部分。返回包含這兩個(gè)信息的一個(gè)元組；如若解析失敗，則返回一個(gè)二元組 ('', '') 。

email.utils.formataddr(pair, charset='utf-8')?

是 parseaddr() 的逆操作，接受一個(gè) (真實(shí)名字, 電子郵件地址) 的二元組，并返回適合于 To or Cc 標(biāo)頭的字符串。如果第一個(gè)元素為假性值，則第二個(gè)元素將被原樣返回。

可選地，如果指定 charset，則被視為一符合 RFC 2047 的編碼字符集，用于編碼 真實(shí)名字 中的非 ASCII 字符?？梢允且粋€(gè) str 類(lèi)的實(shí)例，或者一個(gè) Charset 類(lèi)。默認(rèn)為 utf-8 。

在 3.3 版更改: 添加了 charset 選項(xiàng)。

email.utils.getaddresses(fieldvalues)?

該方法返回一個(gè)形似 parseaddr() 返回的二元組的列表。 fieldvalues 是一個(gè)序列，包含了形似 Message.get_all 返回值的標(biāo)頭字段值。獲取了一消息的所有收件人的簡(jiǎn)單示例如下：

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)?

嘗試根據(jù) RFC 2822 的規(guī)則解析一個(gè)日期。然而，有些寄信人不嚴(yán)格遵守這一格式，所以這種情況下 parsedate() 會(huì)嘗試猜測(cè)其形式。date 是一個(gè)字符串包含了一個(gè)形如 "Mon, 20 Nov 1995 19:12:08 -0500" 的 RFC 2822 格式日期。如果日期解析成功， parsedate() 將返回一個(gè)九元組，可直接傳遞給 time.mktime()；否則返回 None。注意返回的元組中下標(biāo)為 6、7、8 的部分是無(wú)用的。

email.utils.parsedate_tz(date)?

執(zhí)行與 parsedate() 相同的功能，但會(huì)返回 None 或是一個(gè) 10 元組；前 9 個(gè)元素構(gòu)成一個(gè)可以直接傳給 time.mktime() 的元組，而第十個(gè)元素則是該日期的時(shí)區(qū)與 UTC (格林威治平均時(shí) GMT 的正式名稱(chēng)) 1 的時(shí)差。 如果輸入字符串不帶時(shí)區(qū)，則所返回元組的最后一個(gè)元素將為 0，這表示 UTC。 請(qǐng)注意結(jié)果元組的索引號(hào) 6, 7 和 8 是不可用的。

email.utils.parsedate_to_datetime(date)?

format_datetime() 的逆操作。 執(zhí)行與 parsedate() 相同的功能，但會(huì)在成功時(shí)返回一個(gè) datetime；否則如果 date 包含無(wú)效的值例如小時(shí)值大于 23 或時(shí)區(qū)偏移量不在 -24 和 24 時(shí)范圍之內(nèi)則會(huì)引發(fā) ValueError。 如果輸入日期的時(shí)區(qū)值為 -0000，則 datetime 將為一個(gè)簡(jiǎn)單形 datetime，而如果日期符合 RFC 標(biāo)準(zhǔn)則它將代表一個(gè) UTC 時(shí)間，但是并不指明日期所在消息的實(shí)際源時(shí)區(qū)。 如果輸入日期具有任何其他有效的時(shí)區(qū)偏移量，則 datetime 將是一個(gè)感知型 datetime 并與 timezone tzinfo 相對(duì)應(yīng)。

3.3 新版功能.

email.utils.mktime_tz(tuple)?

將 parsedate_tz() 所返回的 10 元組轉(zhuǎn)換為一個(gè) UTC 時(shí)間戳（相距 Epoch 紀(jì)元初始的秒數(shù)）。 如果元組中的時(shí)區(qū)項(xiàng)為 None，則視為當(dāng)?shù)貢r(shí)間。

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)?

返回 RFC 2822 標(biāo)準(zhǔn)的日期字符串，例如:

Fri, 09 Nov 2001 01:08:47 -0000

可選的 timeval 如果給出，則是一個(gè)可被 time.gmtime() 和 time.localtime() 接受的浮點(diǎn)數(shù)時(shí)間值，否則會(huì)使用當(dāng)前時(shí)間。

可選的 localtime 是一個(gè)旗標(biāo)，當(dāng)為 True 時(shí)，將會(huì)解析 timeval，并返回一個(gè)相對(duì)于當(dāng)?shù)貢r(shí)區(qū)而非 UTC 的日期值，并會(huì)適當(dāng)?shù)乜紤]夏令時(shí)。 默認(rèn)值 False 表示使用 UTC。

可選的 usegmt 是一個(gè)旗標(biāo)，當(dāng)為 True 時(shí)，將會(huì)輸出一個(gè)日期字符串，其中時(shí)區(qū)表示為 ascii 字符串 GMT 而非數(shù)字形式的 -0000。 這對(duì)某些協(xié)議（例如 HTTP）來(lái)說(shuō)是必要的。 這僅在 localtime 為 False 時(shí)應(yīng)用。 默認(rèn)值為 False。

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

類(lèi)似于 formatdate，但輸入的是一個(gè) datetime 實(shí)例。 如果實(shí)例是一個(gè)簡(jiǎn)單型 datetime，它會(huì)被視為 "不帶源時(shí)區(qū)信息的 UTC"，并且使用傳統(tǒng)的 -0000 作為時(shí)區(qū)。 如果實(shí)例是一個(gè)感知型 datetime，則會(huì)使用數(shù)字形式的時(shí)區(qū)時(shí)差。 如果實(shí)例是感知型且時(shí)區(qū)時(shí)差為零，則 usegmt 可能會(huì)被設(shè)為 True，在這種情況下將使用字符串 GMT 而非數(shù)字形式的時(shí)區(qū)時(shí)差。 這提供了一種生成符合標(biāo)準(zhǔn) HTTP 日期標(biāo)頭的方式。

3.3 新版功能.

email.utils.decode_rfc2231(s)?

根據(jù) RFC 2231 解碼字符串 s。

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

根據(jù) RFC 2231 對(duì)字符串 s 進(jìn)行編碼。 可選的 charset 和 language 如果給出，則為指明要使用的字符集名稱(chēng)和語(yǔ)言名稱(chēng)。 如果兩者均未給出，則會(huì)原樣返回 s。 如果給出 charset 但未給出 language，則會(huì)使用空字符串作為 language 值來(lái)對(duì)字符串進(jìn)行編碼。

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')?

當(dāng)以 RFC 2231 格式來(lái)編碼標(biāo)頭形參時(shí)，Message.get_param 可能返回一個(gè)包含字符集、語(yǔ)言和值的 3 元組。 collapse_rfc2231_value() 會(huì)將此返回為一個(gè) unicode 字符串。 可選的 errors 會(huì)被傳遞給 str 的 encode() 方法的 errors 參數(shù)；它的默認(rèn)值為 'replace'。 可選的 fallback_charset 指定當(dāng) RFC 2231 標(biāo)頭中的字符集無(wú)法被 Python 識(shí)別時(shí)要使用的字符集；它的默認(rèn)值為 'us-ascii'。

為方便起見(jiàn)，如果傳給 collapse_rfc2231_value() 的 value 不是一個(gè)元組，則應(yīng)為一個(gè)字符串并會(huì)將其原樣返回。

email.utils.decode_params(params)?

根據(jù) RFC 2231 解碼參數(shù)列表。 params 是一個(gè)包含 (content-type, string-value) 形式的元素的 2 元組的序列。

備注

1

請(qǐng)注意時(shí)區(qū)時(shí)差的符號(hào)與同一時(shí)區(qū)的 time.timezone 變量的符號(hào)相反；后者遵循 POSIX 標(biāo)準(zhǔn)而此模塊遵循 RFC 2822。