# `email` --- 电子邮件与 MIME 处理包

源代码: Lib/email/__init__.py

The `email` package is a library for managing email messages. It is specifically not designed to do any sending of email messages to SMTP (RFC 2821), NNTP, or other servers; those are functions of modules such as `smtplib`. The `email` package attempts to be as RFC-compliant as possible, supporting RFC 5322 and RFC 6532, as well as such MIME-related RFCs as RFC 2045, RFC 2046, RFC 2047, RFC 2183, and 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 内容类型被广泛应用于现代因特网软件（而非只是电子邮件），因此这对许多程序员来说将是很熟悉的概念。

The following sections describe the functionality of the `email` package. We start with the `message` object model, which is the primary interface an application will use, and follow that with the `parser` and `generator` components. Then we cover the `policy` controls, which completes the treatment of the main components of the library.

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

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

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

在 3.6 版本发生变更: 文档经过重新组织和撰写以鼓励使用新的 `EmailMessage`/`EmailPolicy` API.

Contents of the `email` package documentation:

- `email.message`: 表示电子邮件消息
- `email.parser`: 解析电子邮件消息
  - FeedParser API
  - Parser API
  - 附加说明
- `email.generator`: 生成 MIME 文档
- `email.policy`: 策略对象
- `email.errors`: 异常和缺陷类
- `email.headerregistry`: 自定义标头对象
- `email.contentmanager`: 管理 MIME 内容
  - 内容管理器实例
- `email`: 示例

旧式 API:

- `email.message.Message`: 使用 `compat32` API 来表示电子邮件消息
- `email.mime`: 从头创建电子邮件和 MIME 对象
- `email.header`: 国际化标头
- `email.charset`: 表示字符集
- `email.encoders`: 编码器
- `email.utils`: 杂项工具
- `email.iterators`: 迭代器

参见

`smtplib` 模块

  SMTP (简单邮件传输协议) 客户端

`poplib` 模块

  POP (邮局协议) 客户端

`imaplib` 模块

  IMAP (互联网消息访问协议) 客户端

`mailbox` 模块

  使用多种标准格式来创建、读取和管理磁盘上的消息集的工具。