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 内容类型被广泛应用于现代因特网软件（而非只是电子邮件），因此这对许多程序员来说将是很熟悉的概念。

以下小节描述了 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: 表示一封电子邮件信息
  • EmailMessage
    • EmailMessage.as_string()
    • EmailMessage.__str__()
    • EmailMessage.as_bytes()
    • EmailMessage.__bytes__()
    • EmailMessage.is_multipart()
    • EmailMessage.set_unixfrom()
    • EmailMessage.get_unixfrom()
    • EmailMessage.__len__()
    • EmailMessage.__contains__()
    • EmailMessage.__getitem__()
    • EmailMessage.__setitem__()
    • EmailMessage.__delitem__()
    • EmailMessage.keys()
    • EmailMessage.values()
    • EmailMessage.items()
    • EmailMessage.get()
    • EmailMessage.get_all()
    • EmailMessage.add_header()
    • EmailMessage.replace_header()
    • EmailMessage.get_content_type()
    • EmailMessage.get_content_maintype()
    • EmailMessage.get_content_subtype()
    • EmailMessage.get_default_type()
    • EmailMessage.set_default_type()
    • EmailMessage.set_param()
    • EmailMessage.del_param()
    • EmailMessage.get_filename()
    • EmailMessage.get_boundary()
    • EmailMessage.set_boundary()
    • EmailMessage.get_content_charset()
    • EmailMessage.get_charsets()
    • EmailMessage.is_attachment()
    • EmailMessage.get_content_disposition()
    • EmailMessage.walk()
    • EmailMessage.get_body()
    • EmailMessage.iter_attachments()
    • EmailMessage.iter_parts()
    • EmailMessage.get_content()
    • EmailMessage.set_content()
    • EmailMessage.make_related()
    • EmailMessage.make_alternative()
    • EmailMessage.make_mixed()
    • EmailMessage.add_related()
    • EmailMessage.add_alternative()
    • EmailMessage.add_attachment()
    • EmailMessage.clear()
    • EmailMessage.clear_content()
    • EmailMessage.preamble
    • EmailMessage.epilogue
    • EmailMessage.defects
  • MIMEPart
• email.parser: 解析电子邮件信息
  • FeedParser API
    • BytesFeedParser
      • BytesFeedParser.feed()
      • BytesFeedParser.close()
    • FeedParser
  • Parser API
    • BytesParser
      • BytesParser.parse()
      • BytesParser.parsebytes()
    • BytesHeaderParser
    • Parser
      • Parser.parse()
      • Parser.parsestr()
    • HeaderParser
    • message_from_bytes()
    • message_from_binary_file()
    • message_from_string()
    • message_from_file()
  • 附加说明
• email.generator: 生成 MIME 文档
  • BytesGenerator
    • BytesGenerator.flatten()
    • BytesGenerator.clone()
    • BytesGenerator.write()
  • Generator
    • Generator.flatten()
    • Generator.clone()
    • Generator.write()
  • DecodedGenerator
• email.policy: Policy 对象
  • Policy
    • Policy.max_line_length
    • Policy.linesep
    • Policy.cte_type
    • Policy.raise_on_defect
    • Policy.mangle_from_
    • Policy.message_factory
    • Policy.clone()
    • Policy.handle_defect()
    • Policy.register_defect()
    • Policy.header_max_count()
    • Policy.header_source_parse()
    • Policy.header_store_parse()
    • Policy.header_fetch_parse()
    • Policy.fold()
    • Policy.fold_binary()
  • EmailPolicy
    • EmailPolicy.utf8
    • EmailPolicy.refold_source
    • EmailPolicy.header_factory
    • EmailPolicy.content_manager
    • EmailPolicy.header_max_count()
    • EmailPolicy.header_source_parse()
    • EmailPolicy.header_store_parse()
    • EmailPolicy.header_fetch_parse()
    • EmailPolicy.fold()
    • EmailPolicy.fold_binary()
  • default
  • SMTP
  • SMTPUTF8
  • HTTP
  • strict
  • Compat32
    • Compat32.mangle_from_
    • Compat32.header_source_parse()
    • Compat32.header_store_parse()
    • Compat32.header_fetch_parse()
    • Compat32.fold()
    • Compat32.fold_binary()
  • compat32
• email.errors: 异常和缺陷类
  • MessageError
  • MessageParseError
  • HeaderParseError
  • BoundaryError
  • MultipartConversionError
  • MessageDefect
  • HeaderDefect
• email.headerregistry: 自定义标头对象
  • BaseHeader
    • BaseHeader.name
    • BaseHeader.defects
    • BaseHeader.max_count
    • BaseHeader.fold()
  • UnstructuredHeader
  • DateHeader
    • DateHeader.datetime
  • AddressHeader
    • AddressHeader.groups
    • AddressHeader.addresses
  • SingleAddressHeader
    • SingleAddressHeader.address
  • MIMEVersionHeader
    • MIMEVersionHeader.version
    • MIMEVersionHeader.major
    • MIMEVersionHeader.minor
  • ParameterizedMIMEHeader
    • ParameterizedMIMEHeader.params
  • ContentTypeHeader
    • ContentTypeHeader.content_type
    • ContentTypeHeader.maintype
    • ContentTypeHeader.subtype
  • ContentDispositionHeader
    • ContentDispositionHeader.content_disposition
  • ContentTransferEncoding
    • ContentTransferEncoding.cte
  • HeaderRegistry
    • HeaderRegistry.map_to_type()
    • HeaderRegistry.__getitem__()
    • HeaderRegistry.__call__()
  • Address
    • Address.display_name
    • Address.username
    • Address.domain
    • Address.addr_spec
    • Address.__str__()
  • Group
    • Group.display_name
    • Group.addresses
    • Group.__str__()
• email.contentmanager: 管理 MIME 内容
  • ContentManager
    • ContentManager.get_content()
    • ContentManager.set_content()
    • ContentManager.add_get_handler()
    • ContentManager.add_set_handler()
  • 内容管理器实例
    • raw_data_manager
    • get_content()
    • set_content()
• email: 示例

旧式 API:

• email.message.Message: 使用 compat32 API 来表示电子邮件消息
  • Message
    • Message.as_string()
    • Message.__str__()
    • Message.as_bytes()
    • Message.__bytes__()
    • Message.is_multipart()
    • Message.set_unixfrom()
    • Message.get_unixfrom()
    • Message.attach()
    • Message.get_payload()
    • Message.set_payload()
    • Message.set_charset()
    • Message.get_charset()
    • Message.__len__()
    • Message.__contains__()
    • Message.__getitem__()
    • Message.__setitem__()
    • Message.__delitem__()
    • Message.keys()
    • Message.values()
    • Message.items()
    • Message.get()
    • Message.get_all()
    • Message.add_header()
    • Message.replace_header()
    • Message.get_content_type()
    • Message.get_content_maintype()
    • Message.get_content_subtype()
    • Message.get_default_type()
    • Message.set_default_type()
    • Message.get_params()
    • Message.get_param()
    • Message.set_param()
    • Message.del_param()
    • Message.set_type()
    • Message.get_filename()
    • Message.get_boundary()
    • Message.set_boundary()
    • Message.get_content_charset()
    • Message.get_charsets()
    • Message.get_content_disposition()
    • Message.walk()
    • Message.preamble
    • Message.epilogue
    • Message.defects
• email.mime: 从头创建电子邮件和 MIME 对象
  • MIMEBase
  • MIMENonMultipart
  • MIMEMultipart
  • MIMEApplication
  • MIMEAudio
  • MIMEImage
  • MIMEMessage
  • MIMEText
• email.header: 国际化标头
  • Header
    • Header.append()
    • Header.encode()
    • Header.__str__()
    • Header.__eq__()
    • Header.__ne__()
  • decode_header()
  • make_header()
• email.charset: 表示字符集
  • Charset
    • Charset.input_charset
    • Charset.header_encoding
    • Charset.body_encoding
    • Charset.output_charset
    • Charset.input_codec
    • Charset.output_codec
    • Charset.get_body_encoding()
    • Charset.get_output_charset()
    • Charset.header_encode()
    • Charset.header_encode_lines()
    • Charset.body_encode()
    • Charset.__str__()
    • Charset.__eq__()
    • Charset.__ne__()
  • add_charset()
  • add_alias()
  • add_codec()
• email.encoders: 编码器
  • encode_quopri()
  • encode_base64()
  • encode_7or8bit()
  • encode_noop()
• email.utils: 其他工具
  • localtime()
  • make_msgid()
  • quote()
  • unquote()
  • parseaddr()
  • formataddr()
  • getaddresses()
  • parsedate()
  • parsedate_tz()
  • parsedate_to_datetime()
  • mktime_tz()
  • formatdate()
  • format_datetime()
  • decode_rfc2231()
  • encode_rfc2231()
  • collapse_rfc2231_value()
  • decode_params()
• email.iterators: 迭代器
  • body_line_iterator()
  • typed_subpart_iterator()
  • _structure()

参见

smtplib 模块

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

poplib 模块

POP (邮局协议) 客户端

imaplib 模块

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

mailbox 模块

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