email --- 電子郵件與 MIME 處理包?
email 包是一個(gè)用于管理電子郵件消息的庫。 它 并非 被設(shè)計(jì)為執(zhí)行向 SMTP (RFC 2821), NNTP 或其他服務(wù)器發(fā)送電子郵件消息的操作；這些是 smtplib 和 nntplib 等模塊的功能。 email 包試圖盡可能地遵循 RFC，支持 RFC 5322 和 RFC 6532，以及與 MIME 相關(guān)的各個(gè) RFC 例如 RFC 2045, RFC 2046, RFC 2047, RFC 2183 和 RFC 2231。
email 包的總體結(jié)構(gòu)可以分為三個(gè)主要組件，另外還有第四個(gè)組件用于控制其他組件的行為。
這個(gè)包的中心組件是代表電子郵件消息的“對(duì)象模型”。 應(yīng)用程序主要通過在 message 子模塊中定義的對(duì)象模型接口與這個(gè)包進(jìn)行交互。 應(yīng)用程序可以使用此 API 來詢問有關(guān)現(xiàn)有電子郵件的問題、構(gòu)造新的電子郵件，或者添加或移除自身也使用相同對(duì)象模型接口的電子郵件子組件。 也就是說，遵循電子郵件消息及其 MIME 子組件的性質(zhì)，電子郵件對(duì)象模型是所有提供 EmailMessage API 的對(duì)象所構(gòu)成的樹狀結(jié)構(gòu)。
這個(gè)包的另外兩個(gè)主要組件是 parser 和 generator。 parser 接受電子郵件消息的序列化版本（字節(jié)流）并將其轉(zhuǎn)換為 EmailMessage 對(duì)象樹。 generator 接受 EmailMessage 并將其轉(zhuǎn)回序列化的字節(jié)流。 (parser 和 generator 還能處理文本字符流，但不建議這種用法，因?yàn)檫@很容易導(dǎo)致某種形式的無效消息。
控制組件是 policy 模塊。 每一個(gè) EmailMessage、每一個(gè) generator 和每一個(gè) parser 都有一個(gè)相關(guān)聯(lián)的 policy 對(duì)象來控制其行為。 通常應(yīng)用程序只有在 EmailMessage 被創(chuàng)建時(shí)才需要指明控制策略，或者通過直接實(shí)例代 EmailMessage 來新建電子郵件，或者通過使用 parser 來解析輸入流。 但是策略也可以在使用 generator 序列化消息時(shí)被更改。 例如，這允許從磁盤解析通用電子郵件消息，而在將消息發(fā)送到電子郵件服務(wù)器時(shí)使用標(biāo)準(zhǔn) SMTP 設(shè)置對(duì)其進(jìn)行序列化。
email 包會(huì)盡量地對(duì)應(yīng)用程序隱藏各種控制類 RFC 的細(xì)節(jié)。 從概念上講應(yīng)用程序應(yīng)當(dāng)能夠?qū)㈦娮余]件消息視為 Unicode 文本和二進(jìn)制附件的結(jié)構(gòu)化樹，而不必?fù)?dān)心在序列化時(shí)要如何表示它們。 但在實(shí)際中，經(jīng)常有必要至少了解一部分控制類 MIME 消息及其結(jié)構(gòu)的規(guī)劃，特別是 MIME "內(nèi)容類型" 的名稱和性質(zhì)以及它們是如何標(biāo)識(shí)多部分文檔的。 在大多數(shù)情況下這些知識(shí)應(yīng)當(dāng)僅對(duì)于更復(fù)雜的應(yīng)用程序來說才是必需的，并且即便在那時(shí)它也應(yīng)當(dāng)僅是特定的高層級(jí)結(jié)構(gòu)，而不是如何表示這些結(jié)構(gòu)的細(xì)節(jié)信息。 由于 MIME 內(nèi)容類型被廣泛應(yīng)用于現(xiàn)代因特網(wǎng)軟件（而非只是電子郵件），因此這對(duì)許多程序員來說將是很熟悉的概念。
以下小節(jié)描述了 email 包的具體功能。 我們會(huì)從 message 對(duì)象模型開始，它是應(yīng)用程序?qū)⒁褂玫闹饕涌冢笫?parser 和 generator 組件。 然后我們會(huì)介紹 policy 控制組件，它將完成對(duì)這個(gè)庫的主要組件的處理。
接下來的三個(gè)小節(jié)會(huì)介紹這個(gè)包可能引發(fā)的異常以及 parser 可能檢測(cè)到的缺陷（即與 RFC 不相符）。 然后我們會(huì)介紹 headerregistry 和 contentmanager 子組件，它們分別提供了用于更精細(xì)地操縱標(biāo)題和載荷的工具。 這兩個(gè)組件除了包含使用與生成非簡(jiǎn)單消息的相關(guān)特性，還記錄了它們的可擴(kuò)展性 API，這將是高級(jí)應(yīng)用程序所感興趣的內(nèi)容。
在此之后是一組使用之前小節(jié)所介紹的 API 的基本部分的示例。
前面的內(nèi)容是 email 包的現(xiàn)代（對(duì) Unicode 支持良好）API。 從 Message 類開始的其余小節(jié)則介紹了舊式 compat32 API，它會(huì)更直接地處理如何表示電子郵件消息的細(xì)節(jié)。 compat32 API 不會(huì) 向應(yīng)用程序隱藏 RFC 的相關(guān)細(xì)節(jié)，但對(duì)于需要進(jìn)行此種層級(jí)操作的應(yīng)用程序來說將是很有用的工具。 此文檔對(duì)于因向下兼容理由而仍然使用 compat32 API 的應(yīng)用程序也是很適合的。
在 3.6 版更改: 文檔經(jīng)過重新組織和撰寫以鼓勵(lì)使用新的 EmailMessage/EmailPolicy API。
email 包文檔的內(nèi)容:
舊式 API: