email.utils: 雜項實用工具

原始碼： Lib/email/utils.py

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

email.utils.localtime(dt=None)

返回作為感知型 datetime 物件的本地時間。如果呼叫時不帶引數，則返回當前時間。否則，dt 引數應該是一個 datetime 例項，並且根據系統時區資料庫將其轉換為本地時區。如果 dt 是樸素的（即 dt.tzinfo 是 None），則假定它處於本地時間。 isdst 引數將被忽略。

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)

將地址（應為包含地址的欄位（例如 To 或 Cc）的值）解析為其組成的 realname 和電子郵件地址部分。 返回該資訊的元組，除非解析失敗，否則返回 ('', '') 的 2 元組。

如果 strict 為 true，則使用嚴格的解析器，該解析器會拒絕格式錯誤的輸入。

在 3.13 版本中更改: 新增 strict 可選引數，預設情況下拒絕格式錯誤的輸入。

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

與 parseaddr() 相反，此方法採用 (realname, email_address) 形式的 2 元組，並返回適用於 To 或 Cc 標頭的字串值。 如果 pair 的第一個元素為 false，則返回第二個元素，不做修改。

如果 realname 包含非 ASCII 字元，可選的 charset 是在 RFC 2047 編碼的 realname 中將使用的字元集。 可以是 str 或 Charset 的例項。 預設為 utf-8。

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

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

此方法返回 parseaddr() 返回的 2 元組形式的列表。 fieldvalues 是標頭欄位值序列，如 Message.get_all 返回的那樣。

如果 strict 為 true，則使用嚴格的解析器，該解析器會拒絕格式錯誤的輸入。

這是一個簡單的示例，獲取訊息的所有收件人

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() 將返回一個 9 元組，該元組可以直接傳遞給 time.mktime()；否則將返回 None。請注意，結果元組的索引 6、7 和 8 不可用。

email.utils.parsedate_tz(date)

執行與 parsedate() 相同的功能，但返回 None 或一個 10 元組；前 9 個元素構成一個可以直接傳遞給 time.mktime() 的元組，第 10 個元素是日期時區與 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 將是一個帶有相應 timezone tzinfo 的感知型 datetime。

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 指定如果 Python 不知道 RFC 2231 標頭中的字元集，則使用的字元集；它預設為 'us-ascii'。

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

email.utils.decode_params(params)

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

腳註