email.utils: 其他工具?

源代碼: Lib/email/utils.py

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

email.utils.localtime(dt=None)?

以感知型 datetime 對象返回當地時(shí)間。 如果調用時(shí)參數為空，則返回當前時(shí)間。 否則 dt 參數應該是一個(gè) datetime 實(shí)例，并根據系統時(shí)區數據庫轉換為當地時(shí)區。 如果 dt 是簡(jiǎn)單型的 （即 dt.tzinfo 是 None )，則假定為當地時(shí)間。 在這種情況下，為正值或零的 isdst 會(huì )使 localtime 假定夏季時(shí)間（例如，夏令時(shí)）對指定時(shí)間（分別）生效或不生效。 負值 isdst 會(huì )使 localtime 預測夏季時(shí)間對指定時(shí)間是否生效。

3.3 新版功能.

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

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

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

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

email.utils.quote(str)?

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

email.utils.unquote(str)?

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

email.utils.parseaddr(address)?

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

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

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

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

在 3.3 版更改: 添加了 charset 選項。

email.utils.getaddresses(fieldvalues)?

該方法返回一個(gè)形似 parseaddr() 返回的二元組的列表。 fieldvalues 是一個(gè)序列，包含了形似 Message.get_all 返回值的標頭字段值。獲取了一消息的所有收件人的簡(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)?

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

email.utils.parsedate_tz(date)?

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

email.utils.parsedate_to_datetime(date)?

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

3.3 新版功能.

email.utils.mktime_tz(tuple)?

將 parsedate_tz() 所返回的 10 元組轉換為一個(gè) UTC 時(shí)間戳（相距 Epoch 紀元初始的秒數）。 如果元組中的時(shí)區項為 None，則視為當地時(shí)間。

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

返回 RFC 2822 標準的日期字符串，例如:

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

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

可選的 localtime 是一個(gè)旗標，當為 True 時(shí)，將會(huì )解析 timeval，并返回一個(gè)相對于當地時(shí)區而非 UTC 的日期值，并會(huì )適當地考慮夏令時(shí)。 默認值 False 表示使用 UTC。

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

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

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

3.3 新版功能.

email.utils.decode_rfc2231(s)?

根據 RFC 2231 解碼字符串 s。

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

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

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

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

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

email.utils.decode_params(params)?

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

備注

1

請注意時(shí)區時(shí)差的符號與同一時(shí)區的 time.timezone 變量的符號相反；后者遵循 POSIX 標準而此模塊遵循 RFC 2822。