email.utils: 其他工具?

源代碼: Lib/email/utils.py

email.utils 模塊提供如下幾個工具

email.utils.localtime(dt=None)?

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

3.3 新版功能.

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

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

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

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

email.utils.quote(str)?

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

email.utils.unquote(str)?

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

email.utils.parseaddr(address)?

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

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

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

email.utils.parsedate_tz(date)?

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

email.utils.parsedate_to_datetime(date)?

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

3.3 新版功能.

email.utils.mktime_tz(tuple)?

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

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

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

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

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

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

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

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

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

3.3 新版功能.

email.utils.decode_rfc2231(s)?

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

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

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

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

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

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

email.utils.decode_params(params)?

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

備注

1

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