email.contentmanager：管理 MIME 內容

原始碼： Lib/email/contentmanager.py

3.6 版本新增: [1]

class email.contentmanager.ContentManager

內容管理器的基類。提供標準註冊機制，用於註冊 MIME 內容與其他表示形式之間的轉換器，以及 get_content 和 set_content 排程方法。

get_content(msg, *args, **kw)

根據 msg 的 mimetype（請參閱下一段）查詢處理程式函式，呼叫它，傳遞所有引數，並返回呼叫的結果。期望處理程式將從 msg 中提取有效負載，並返回一個物件，該物件編碼有關提取資料的資訊。

要查詢處理程式，請在登錄檔中查詢以下鍵，並在找到第一個鍵時停止：

  • 表示完整 MIME 型別的字串（maintype/subtype）

  • 表示 maintype 的字串

  • 空字串

如果這些鍵都沒有產生處理程式，則針對完整的 MIME 型別引發 KeyError。

set_content(msg, obj, *args, **kw)

如果 maintype 是 multipart，則引發 TypeError；否則，根據 obj 的型別（請參閱下一段）查詢處理程式函式，在 msg 上呼叫 clear_content()，並呼叫處理程式函式，傳遞所有引數。期望處理程式將轉換 obj 並將其儲存到 msg 中，也可能會對 msg 進行其他更改，例如新增各種 MIME 標頭以編碼解釋儲存資料所需的資訊。

要查詢處理程式，請獲取 obj 的型別（typ = type(obj)），並在登錄檔中查詢以下鍵，並在找到第一個鍵時停止：

  • 型別本身 (typ)

  • 型別的完全限定名稱 (typ.__module__ + '.' + typ.__qualname__)。

  • 型別的 qualname (typ.__qualname__)

  • 型別的 name (typ.__name__)。

如果以上任何一項都不匹配，則對 MRO（typ.__mro__）中的每種型別重複上述所有檢查。最後，如果沒有其他鍵產生處理程式，請檢查鍵 None 的處理程式。如果沒有 None 的處理程式，則為該型別的完全限定名稱引發 KeyError。

如果不存在，還新增一個 MIME-Version 標頭（另請參閱 MIMEPart）。

add_get_handler(key, handler)

將函式 handler 記錄為 key 的處理程式。有關 key 的可能值，請參閱 get_content()。

add_set_handler(typekey, handler)

將 handler 記錄為當型別與 typekey 匹配的物件傳遞給 set_content() 時要呼叫的函式。有關 typekey 的可能值，請參閱 set_content()。

內容管理器例項

目前，email 包僅提供一個具體的內容管理器，即 raw_data_manager，儘管將來可能會新增更多。 raw_data_manager 是 content_manager，由 EmailPolicy 及其派生類提供。

email.contentmanager.raw_data_manager

此內容管理器僅提供超出 Message 本身提供的最小介面：它僅處理文字、原始位元組字串和 Message 物件。儘管如此，與基本 API 相比，它提供了顯著的優勢：文字部分的 get_content 將返回一個 unicode 字串，而無需應用程式手動解碼它，set_content 提供了豐富的選項，用於控制新增到部分和控制內容傳輸編碼的標頭，並且它支援使用各種 add_ 方法，從而簡化了多部分訊息的建立。

email.contentmanager.get_content(msg, errors='replace')

返回部件的載荷，型別為字串（對於 text 部件）、EmailMessage 物件（對於 message/rfc822 部件），或 bytes 物件（對於所有其他非 multipart 型別）。如果在 multipart 上呼叫，則引發 KeyError 異常。如果部件是 text 部件並且指定了 errors，則在將載荷解碼為 Unicode 時，將其用作錯誤處理程式。預設的錯誤處理程式是 replace。

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

向 msg 新增標頭和載荷。

新增一個具有 maintype/subtype 值的 Content-Type 標頭。

  • 對於 str，將 MIME maintype 設定為 text，如果指定了子型別，則將其設定為 subtype，否則設定為 plain。

  • 對於 bytes，請使用指定的 maintype 和 subtype，如果沒有指定，則引發 TypeError 異常。

  • 對於 EmailMessage 物件，將 maintype 設定為 message，如果指定了子型別，則將其設定為 subtype，否則設定為 rfc822。如果 subtype 為 partial，則引發錯誤（必須使用 bytes 物件來構造 message/partial 部件）。

如果提供了 charset（僅對 str 有效），則使用指定的字元集將字串編碼為位元組。預設值為 utf-8。如果指定的 charset 是標準 MIME 字元集名稱的已知別名，則使用標準字元集代替。

如果設定了 cte，則使用指定的內容傳輸編碼對載荷進行編碼，並將 Content-Transfer-Encoding 標頭設定為該值。cte 的可能值為 quoted-printable、base64、7bit、8bit 和 binary。如果無法使用指定的編碼對輸入進行編碼（例如，為包含非 ASCII 值的輸入指定 cte 為 7bit），則引發 ValueError 異常。

  • 對於 str 物件，如果未設定 cte，則使用啟發式方法來確定最緊湊的編碼。

  • 對於 EmailMessage，根據 RFC 2046，如果請求將 cte 設定為 quoted-printable 或 base64 且 subtype 為 rfc822，則引發錯誤；對於 subtype 為 external-body，如果 cte 不是 7bit，則引發錯誤。對於 message/rfc822，如果未指定 cte，則使用 8bit。對於 subtype 的所有其他值，請使用 7bit。

注意

cte 為 binary 實際上尚未正確工作。set_content 修改後的 EmailMessage 物件是正確的，但是 BytesGenerator 未能正確地序列化它。

如果設定了 disposition，則將其用作 Content-Disposition 標頭的值。如果未指定，並且指定了 filename，則新增具有值 attachment 的標頭。如果未指定 disposition 並且也未指定 filename，則不新增該標頭。disposition 的唯一有效值是 attachment 和 inline。

如果指定了 filename，則將其用作 Content-Disposition 標頭的 filename 引數的值。

如果指定了 cid，則新增一個 Content-ID 標頭，並將 cid 作為其值。

如果指定了 params，則遍歷其 items 方法，並使用生成的 (key, value) 對在 Content-Type 標頭上設定其他引數。

如果指定了 headers，並且是 headername: headervalue 形式的字串列表或 header 物件列表（透過具有 name 屬性與字串區分開來），則將標頭新增到 msg。

腳註