email.contentmanager: 管理 MIME 內(nèi)容?

源代碼: Lib/email/contentmanager.py

3.6 新版功能: 1

class email.contentmanager.ContentManager?

內(nèi)容管理器的基類。 提供注冊(cè) MIME 內(nèi)容和其他表示形式間轉(zhuǎn)換器的標(biāo)準(zhǔn)注冊(cè)機(jī)制，以及 get_content 和 set_content 發(fā)送方法。

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

基于 msg 的 mimetype 查找處理函數(shù)（參見下一段），調(diào)用該函數(shù)，傳遞所有參數(shù)，并返回調(diào)用的結(jié)果。 預(yù)期的效果是處理程序?qū)?msg 中提取有效載荷并返回編碼了有關(guān)被提取數(shù)據(jù)信息的對(duì)象。

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

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

  • 表示 maintype 的字符串

  • 空字符串

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

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

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

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

  • 類型本身 (typ)

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

  • 類型的 qualname (typ.__qualname__)

  • 類型的 name (typ.__name__)。

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

并會(huì)添加一個(gè) MIME-Version 標(biāo)頭，如果沒有的話 (另請(qǐng)參見 MIMEPart)。

add_get_handler(key, handler)?

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

add_set_handler(typekey, handler)?

將 handler 記錄為當(dāng)一個(gè)匹配 typekey 的類型對(duì)象被傳遞給 set_content() 時(shí)所要調(diào)用的函數(shù)。 對(duì)于可能的 typekey 值，請(qǐng)參閱 set_content()。

內(nèi)容管理器實(shí)例?

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

email.contentmanager.raw_data_manager?

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

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

將指定部分的有效載荷作為字符串（對(duì)于 text 部分）, EmailMessage 對(duì)象（對(duì)于 message/rfc822 部分）或 bytes 對(duì)象（對(duì)于所有其他非多部分類型）返回。 如果是在 multipart 上調(diào)用則會(huì)引發(fā) KeyError。 如果指定部分是一個(gè) text 部分并且指明了 errors，則會(huì)在將載荷解碼為 unicode 時(shí)將其用作錯(cuò)誤處理程序。 默認(rèn)的錯(cuò)誤處理程序是 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 添加標(biāo)頭和有效載荷:

添加一個(gè)帶有 maintype/subtype 值的 Content-Type 標(biāo)頭。

  • 對(duì)于 str，將 MIME maintype 設(shè)為 text，如果指定了子類型 subtype 則設(shè)為指定值，否則設(shè)為 plain。

  • 對(duì)于 bytes，將使用指定的 maintype 和 subtype，如果未指定則會(huì)引發(fā) TypeError。

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

如果提供了 charset (這只對(duì) str 適用)，則使用指定的字符集將字符串編碼為字節(jié)串。 默認(rèn)值為 utf-8。 如果指定的 charset 是某個(gè)標(biāo)準(zhǔn) MIME 字符集名稱的已知?jiǎng)e名，則會(huì)改用該標(biāo)準(zhǔn)字符集。

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

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

  • 對(duì)于 EmailMessage，按照 RFC 2046，如果為 subtype rfc822 請(qǐng)求的 cte 為 quoted-printable 或 base64 ，而為 7bit 以外的任何 cte 為 subtype external-body 則會(huì)引發(fā)一個(gè)錯(cuò)誤。 對(duì)于 message/rfc822，如果 cte 未指定則會(huì)使用 8bit。 對(duì)于所有其他 subtype 值，都會(huì)使用 7bit。

備注

cte 值為 binary 實(shí)際上還不能正確工作。 由 set_content 所修改的 EmailMessage 對(duì)象是正確的，但 BytesGenerator 不會(huì)正確地將其序列化。

如果設(shè)置了 disposition，它會(huì)被用作 Content-Disposition 標(biāo)頭的值。 如果未設(shè)置，并且指定了 filename，則添加值為 attachment 的標(biāo)頭。 如果未設(shè)置 disposition 并且也未指定 filename，則不添加標(biāo)頭。 disposition 的有效值僅有 attachment 和 inline。

如果設(shè)置了 filename，則將其用作 Content-Disposition 標(biāo)頭的 filename 參數(shù)的值。

如果設(shè)置了 cid，則添加一個(gè) Content-ID 標(biāo)頭并將其值設(shè)為 cid。

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

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

備注

1

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