email.contentmanager: 管理 MIME 內容?

源代碼: Lib/email/contentmanager.py

3.6 新版功能: 1

class email.contentmanager.ContentManager?

內容管理器的基類。 提供注冊 MIME 內容和其他表示形式間轉換器的標準注冊機制，以及 get_content 和 set_content 發(fā)送方法。

get_content(msg, *args, **kw)?

基于 msg 的 mimetype 查找處理函數(shù)（參見下一段），調用該函數(shù)，傳遞所有參數(shù)，并返回調用的結果。 預期的效果是處理程序將從 msg 中提取有效載荷并返回編碼了有關被提取數(shù)據(jù)信息的對象。

要找到處理程序，將在注冊表中查找以下鍵，找到第一個鍵即停止:

  • 表示完整 MIME 類型的字符串 (maintype/subtype)

  • 表示 maintype 的字符串

  • 空字符串

如果這些鍵都沒有產(chǎn)生處理程序，則為完整 MIME 類型引發(fā)一個 KeyError。

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

如果 maintype 為 multipart，則引發(fā) TypeError；否則基于 obj 的類型（參見下一段）查找處理函數(shù)，在 msg 上調用 clear_content()，并調用處理函數(shù)，傳遞所有參數(shù)。 預期的效果是處理程序將轉換 obj 并存入 msg，并可能對 msg 進行其他更改，例如添加各種 MIME 標頭來編碼需要用來解釋所存儲數(shù)據(jù)的信息。

要找到處理程序，將獲取 obj 的類型 (typ = type(obj))，并在注冊表中查找以下鍵，找到第一個鍵即停止:

  • 類型本身 (typ)

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

  • 類型的 qualname (typ.__qualname__)

  • 類型的 name (typ.__name__)。

如果未匹配到上述的任何一項，則在 MRO (typ.__mro__) 中為每個類型重復上述的所有檢測。 最后，如果沒有其他鍵產(chǎn)生處理程序，則為 None 鍵檢測處理程序。 如果也沒有 None 的處理程序，則為該類型的完整限定名稱引發(fā) KeyError。

并會添加一個 MIME-Version 標頭，如果沒有的話 (另請參見 MIMEPart)。

add_get_handler(key, handler)?

將 handler 函數(shù)記錄為 key 的處理程序。 對于可能的 key 鍵，請參閱 get_content()。

add_set_handler(typekey, handler)?

將 handler 記錄為當一個匹配 typekey 的類型對象被傳遞給 set_content() 時所要調用的函數(shù)。 對于可能的 typekey 值，請參閱 set_content()。

內容管理器實例?

目前 email 包只提供了一個實體內容管理器 raw_data_manager，不過在未來可能會添加更多。 raw_data_manager 是由 EmailPolicy 及其衍生工具所提供的 content_manager。

email.contentmanager.raw_data_manager?

這個內容管理器僅提供了超出 Message 本身提供內容的最小接口：它只處理文本、原始字節(jié)串和 Message 對象。 不過相比基礎 API，它具有顯著的優(yōu)勢：在文本部分上執(zhí)行 get_content 將返回一個 unicode 字符串而無需由應用程序來手動解碼，set_content 為控制添加到一個部分的標頭和控制內容傳輸編碼格式提供了豐富的選項集合，并且它還啟用了多種 add_ 方法，從而簡化了多部分消息的創(chuàng)建過程。

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

將指定部分的有效載荷作為字符串（對于 text 部分）, EmailMessage 對象（對于 message/rfc822 部分）或 bytes 對象（對于所有其他非多部分類型）返回。 如果是在 multipart 上調用則會引發(fā) 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，如果未指定則會引發(fā) TypeError。

  • 對于 EmailMessage 對象，將 maintype 設為 message，并將指定的 subtype 設為 subtype，如果未指定則設為 rfc822。 如果 subtype 為 partial，則引發(fā)一個錯誤（必須使用 bytes 對象來構造 message/partial 部分）。

如果提供了 charset (這只對 str 適用)，則使用指定的字符集將字符串編碼為字節(jié)串。 默認值為 utf-8。 如果指定的 charset 是某個標準 MIME 字符集名稱的已知別名，則會改用該標準字符集。

如果設置了 cte，則使用指定的內容傳輸編碼格式對有效載荷進行編碼，并將 Content-Transfer-Encoding 標頭設為該值。 可能的 cte 值有 quoted-printable, base64, 7bit, 8bit 和 binary。 如果輸入無法以指定的編碼格式被編碼 (例如，對于包含非 ASCII 值的輸入指定 cte 值為 7bit)，則會引發(fā) ValueError。

  • 對于 str 對象，如果 cte 未設置則會使用啟發(fā)方式來確定最緊湊的編碼格式。

  • 對于 EmailMessage，按照 RFC 2046，如果為 subtype rfc822 請求的 cte 為 quoted-printable 或 base64 ，而為 7bit 以外的任何 cte 為 subtype external-body 則會引發(fā)一個錯誤。 對于 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 參數(shù)的值。

如果設置了 cid，則添加一個 Content-ID 標頭并將其值設為 cid。

如果設置了 params，則迭代其 items 方法并使用輸出的 (key, value) 結果對在 Content-Type 標頭上設置附加參數(shù)。

如果設置了 headers 并且為 headername: headervalue 形式的字符串的列表或為 header 對象的列表（通過一個 name 屬性與字符串相區(qū)分），則將標頭添加到 msg。

備注

1

最初在 3.4 中作為 暫定模塊 添加