"email" --- 电子邮件与 MIME 处理包
**********************************

**源代码:** Lib/email/__init__.py

======================================================================

"email" 包是一个用于管理电子邮件消息的库。 它 *并非* 被设计为执行向
SMTP (**RFC 2821**), NNTP 或其他服务器发送电子邮件消息的操作；这些是
"smtplib" 和 "nntplib" 等模块的功能。 "email" 包试图尽可能遵循 RFC，支
持 **RFC 5233** 和 **RFC 6532**，以及与 MIME 相关的各个 RFC 例如 **RFC
2045**, **RFC 2046**, **RFC 2047**, **RFC 2183** 和 **RFC 2231**。

email 包的总体结构可以分为三个主要组件，另外还有第四个组件用于控制其他
组件的行为。

这个包的中心组件是代表电子邮件消息的“对象模型”。 应用程序主要通过在
"message" 子模块中定义的对象模型接口与这个包进行交互。 应用程序可以使
用此 API 来询问有关现有电子邮件的问题、构造新的电子邮件，或者添加或移
除自身也使用相同对象模型接口的电子邮件子组件。 也就是说，遵循电子邮件
消息及其 MIME 子组件的性质，电子邮件对象模型是所有提供 "EmailMessage"
API 的对象所构成的树状结构。

这个包的另外两个主要组件是 "parser" 和 "generator"。 parser 接受电子邮
件消息的序列化版本（字节流）并将其转换为 "EmailMessage" 对象树。
generator 接受  "EmailMessage" 并将其转回序列化的字节流。 (parser 和
generator 还能处理文本字符流，但不建议这种用法，因为这很容易导致某种形
式的无效消息。

控制组件是 "policy" 模块。 每一个 "EmailMessage"、每一个 "generator"
和每一个 "parser" 都有一个相关联的 "policy" 对象来控制其行为。 通常应
用程序只有在 "EmailMessage" 被创建时才需要指明控制策略，或者通过直接实
例代 "EmailMessage"  来新建电子邮件，或者通过使用 "parser" 来解析输入
流。 但是策略也可以在使用 "generator" 序列化消息时被更改。 例如，这允
许从磁盘解析通用电子邮件消息，而在将消息发送到电子邮件服务器时使用标准
SMTP 设置对其进行序列化。

email 包会尽量地对应用程序隐藏各种控制类 RFC 的细节。 从概念上讲应用程
序应当能够将电子邮件消息视为 Unicode 文本和二进制附件的结构化树，而不
必担心在序列化时要如何表示它们。 但在实际中，经常有必要至少了解一部分
控制类 MIME 消息及其结构的规划，特别是 MIME "内容类型" 的名称和性质以
及它们是如何标识多部分文档的。 在大多数情况下这些知识应当仅对于更复杂
的应用程序来说才是必需的，并且即便在那时它也应当仅是特定的高层级结构，
而不是如何表示这些结构的细节信息。 由于 MIME 内容类型被广泛应用于现代
因特网软件（而非只是电子邮件），因此这对许多程序员来说将是很熟悉的概念
。

以下小节描述了 "email" 包的具体功能。 我们会从 "message" 对象模型开始
，它是应用程序将要使用的主要接口，之后是 "parser" 和 "generator" 组件
。 然后我们会介绍 "policy" 控制组件，它将完成对这个库的主要组件的处理
。

接下来的三个小节会介绍这个包可能引发的异常以及 "parser" 可能检测到的缺
陷（即与 RFC 不相符）。 然后我们会介绍 "headerregistry" 和
"contentmanager" 子组件，它们分别提供了用于更精细地操纵标题和载荷的工
具。 这两个组件除了包含使用与生成非简单消息的相关特性，还记录了它们的
可扩展性 API，这将是高级应用程序所感兴趣的内容。

在此之后是一组使用之前小节所介绍的 API 的基本部分的示例。

前面的内容是 email 包的现代（对 Unicode 支持良好）API。 从 "Message"
类开始的其余小节则介绍了旧式  "compat32" API，它会更直接地处理如何表示
电子邮件消息的细节。 "compat32" API *不会* 向应用程序隐藏 RFC 的相关细
节，但对于需要进行此种层级操作的应用程序来说将是很有用的工具。 此文档
对于因向下兼容理由而仍然使用 "compat32" API 的应用程序也是很适合的。

在 3.6 版更改: 文档经过重新组织和撰写以鼓励使用新的
"EmailMessage"/"EmailPolicy" API。

"email" 包文档的内容:

* "email.message": 表示一封电子邮件信息

* "email.parser": 解析电子邮件信息

  * FeedParser API

  * Parser API

  * 附加说明

* "email.generator": 生成 MIME 文档

* "email.policy": Policy 对象

* "email.errors": 异常和缺陷类

* "email.headerregistry": 自定义标头对象

* "email.contentmanager": 管理 MIME 内容

  * Content Manager Instances

* "email": 示例

旧式 API:

* "email.message.Message": Representing an email message using the
  "compat32" API

* "email.mime": Creating email and MIME objects from scratch

* "email.header": Internationalized headers

* "email.charset": Representing character sets

* "email.encoders": 编码器

* "email.utils": 其他工具

* "email.iterators": 迭代器

参见:

  "smtplib" 模块
     SMTP (简单邮件传输协议) 客户端

  "poplib" 模块
     POP (邮局协议) 客户端

  "imaplib" 模块
     IMAP (互联网消息访问协议) 客户端

  "nntplib" 模块
     NNTP (网络新闻传输协议) 客户端

  "mailbox" 模块
     创建、读取和管理使用保存在磁盘中的多种标准格式的消息集的工具。

  "smtpd" 模块
     SMTP 服务器框架 (主要适用于测试)
