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 是 EmailPolicy 及其派生類提供的 content_manager。

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，則將其設為 subtype，否則設為 plain。

  • 對於 bytes，使用指定的 maintype 和 subtype，如果未指定，則引發 TypeError。

  • 對於 EmailMessage 物件，將 maintype 設為 message，如果指定了 subtype 則設為 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，則使用啟發式方法確定最緊湊的編碼。在編碼之前，會使用 str.splitlines() 來規範化所有行邊界，確保有效載荷的每一行都以當前策略的 linesep 屬性結尾（即使原始字串不是以換行符結尾）。

  • 對於 bytes 物件，如果未設定，cte 將預設為 base64，並且不執行上述的換行符轉換。

  • 對於 EmailMessage，根據 RFC 2046，如果為 subtype rfc822 請求了 quoted-printable 或 base64 的 cte，或者為 subtype external-body 請求了除 7bit 之外的任何 cte，則會引發錯誤。對於 message/rfc822，如果未指定 cte，則使用 8bit。對於所有其他 subtype 值，使用 7bit。

備註

binary 的 cte 尚未能正確工作。經 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。

腳註