email.utils: 雜項工具

原始碼： Lib/email/utils.py

email.utils 模組中提供了一些有用的工具。

email.utils.localtime(dt=None)

以一個感知型 datetime 物件的形式返回本地時間。 如果在不帶引數的情況下呼叫，則返回當前時間。 否則 dt 引數應當為一個 datetime 例項，並且它會根據系統時區資料庫被轉換為本地時區。 如果 dt 是簡單型（即 dt.tzinfo 為 None），則會假定它為本地時間。

在 3.3 版本加入。

自 3.12 版本起廢棄，將在 3.14 版本中移除: isdst 形參。

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

返回一個適用於符合 RFC 2822 標準的 Message-ID 標頭的字串。 可選的 idstring 如果給出，則為用於增強訊息 id 唯一性的字串。 可選的 domain 如果給出，則提供了 msgid 中 ‘@’ 之後的部分。 預設值為本地主機名。 通常沒有必要過載此預設值，但在某些情況下可能會很有用，例如構建一個在多臺主機上使用一致域名的分散式系統。

在 3.2 版更改: 增加了 domain 關鍵字。

其餘函式是舊式 (Compat32) 電子郵件 API 的一部分。 在新的 API 中沒有必要直接使用它們，因為它們提供的解析和格式化功能是由新 API 的標頭解析機制自動完成的。

email.utils.quote(str)

返回一個新字串，其中 str 裡的反斜槓被替換為兩個反斜槓，雙引號被替換為反斜槓-雙引號。

email.utils.unquote(str)

返回一個新字串，它是 str 的*反引號*版本。 如果 str 以雙引號開始和結束，它們將被剝離。 同樣地，如果 str 以尖括號開始和結束，它們也將被剝離。

email.utils.parseaddr(address, *, strict=True)

解析地址 --- address 應為某個包含地址的欄位的值，例如 To 或 Cc --- 將其分解為*真實姓名*和*電子郵件地址*部分。 返回包含這些資訊的元組，除非解析失敗，在這種情況下將返回一個 2 元組 ('', '')。

若 strict 為真值，則使用會拒絕格式錯誤輸入的嚴格解析器。

在 3.13 版更改: 新增 strict 可選形參並預設拒絕格式錯誤的輸入。

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

parseaddr() 的逆操作，它接受一個 (realname, email_address) 形式的 2 元組，並返回適用於 To 或 Cc 標頭的字串值。 如果 pair 的第一個元素為假值，則第二個元素將被不加修改地返回。

可選的 charset 是當 realname 包含非 ASCII 字元時將用於 realname 的 RFC 2047 編碼的字元集。 它可以是 str 的例項或 Charset。 預設為 utf-8。

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

email.utils.getaddresses(fieldvalues, *, strict=True)

此方法返回一個由 parseaddr() 所返回形式的 2-元組構成的列表。 fieldvalues 是標頭欄位值的序列，就像 Message.get_all 可能返回的那樣。

若 strict 為真值，則使用會拒絕格式錯誤輸入的嚴格解析器。

這裡有一個獲取訊息所有收件人的簡單例子

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)

在 3.13 版更改: 新增 strict 可選形參並預設拒絕格式錯誤的輸入。

email.utils.parsedate(date)

嘗試根據 RFC 2822 中的規則解析日期。然而，有些郵件程式並未遵循指定的格式，因此 parsedate() 會在這些情況下嘗試進行正確的猜測。date 是一個包含 RFC 2822 日期的字串，例如 "Mon, 20 Nov 1995 19:12:08 -0500"。如果成功解析日期，parsedate() 將返回一個可直接傳遞給 time.mktime() 的 9-元組；否則將返回 None。請注意，結果元組的索引 6、7 和 8 是不可用的。

email.utils.parsedate_tz(date)

執行與 parsedate() 相同的功能，但返回 None 或一個 10 元組；前 9 個元素組成一個可以直接傳遞給 time.mktime() 的元組，第十個元素是日期時區與 UTC（格林尼治標準時間的官方術語）的偏移量 [1]。如果輸入字串沒有時區，則返回元組的最後一個元素是 0，代表 UTC。請注意，結果元組的索引 6、7 和 8 是不可用的。

email.utils.parsedate_to_datetime(date)

format_datetime() 的逆操作。 執行與 parsedate() 相同的功能，但在成功時會返回一個 datetime；否則如果 date 包含無效值，例如大於 23 的小時或不在 -24 到 24 小時之間的時區偏移，則會引發 ValueError。 如果輸入日期的時區為 -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

可選的 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，但輸入是 datetime 例項。 如果它是一個簡單型 datetime，則假定為“UTC，但沒有關於源時區的資訊”，並使用常規的 -0000 作為時區。 如果它是一個感知型 datetime，則使用數字時區偏移。 如果它是一個偏移為零的感知型時區，則 usegmt 可以設定為 True，在這種情況下，將使用字串 GMT 而不是數字時區偏移。 這提供了一種生成符合標準的 HTTP 日期標頭的方法。

在 3.3 版本加入。

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

當標頭引數以 RFC 2231 格式編碼時，Message.get_param 可能會返回一個包含字元集、語言和值的 3 元組。 collapse_rfc2231_value() 將其轉換為一個 Unicode 字串。 可選的 errors 會被傳遞給 str 的 encode() 方法的 errors 引數；它預設為 'replace'。 可選的 fallback_charset 指定當 RFC 2231 標頭中的字元集不為 Python 所知時要使用的字元集；它預設為 'us-ascii'。

為方便起見，如果傳遞給 collapse_rfc2231_value() 的 value 不是元組，則它應該是一個字串，並且會不加引號地返回。

email.utils.decode_params(params)

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

腳註