email —- 电子邮件与 MIME 处理包

源码:Lib/email/init.py

The email package is a library for managing email messages. It isspecifically not designed to do any sending of email messages to SMTP(RFC 2821), NNTP, or other servers; those are functions of modules such assmtplib and nntplib. The email package attempts to be asRFC-compliant as possible, supporting RFC 5233 and RFC 6532, as well assuch MIME-related RFCs as RFC 2045, RFC 2046, RFC 2047, RFC 2183,and RFC 2231.

The overall structure of the email package can be divided into three majorcomponents, plus a fourth component that controls the behavior of the othercomponents.

The central component of the package is an "object model" that represents emailmessages. An application interacts with the package primarily through theobject model interface defined in the message sub-module. Theapplication can use this API to ask questions about an existing email, toconstruct a new email, or to add or remove email subcomponents that themselvesuse the same object model interface. That is, following the nature of emailmessages and their MIME subcomponents, the email object model is a treestructure of objects that all provide the EmailMessageAPI.

The other two major components of the package are the parser andthe generator. The parser takes the serialized version of anemail message (a stream of bytes) and converts it into a tree ofEmailMessage objects. The generator takes anEmailMessage and turns it back into a serialized bytestream. (The parser and generator also handle streams of text characters, butthis usage is discouraged as it is too easy to end up with messages that arenot valid in one way or another.)

The control component is the policy module. EveryEmailMessage, every generator, and everyparser has an associated policy object thatcontrols its behavior. Usually an application only needs to specify the policywhen an EmailMessage is created, either by directlyinstantiating an EmailMessage to create a new email,or by parsing an input stream using a parser. But the policy canbe changed when the message is serialized using a generator.This allows, for example, a generic email message to be parsed from disk, butto serialize it using standard SMTP settings when sending it to an emailserver.

The email package does its best to hide the details of the various governingRFCs from the application. Conceptually the application should be able totreat the email message as a structured tree of unicode text and binaryattachments, without having to worry about how these are represented whenserialized. In practice, however, it is often necessary to be aware of atleast some of the rules governing MIME messages and their structure,specifically the names and nature of the MIME "content types" and how theyidentify multipart documents. For the most part this knowledge should only berequired for more complex applications, and even then it should only be thehigh level structure in question, and not the details of how those structuresare represented. Since MIME content types are used widely in modern internetsoftware (not just email), this will be a familiar concept to many programmers.

The following sections describe the functionality of the email package.We start with the message object model, which is the primaryinterface an application will use, and follow that with theparser and generator components. Then we cover thepolicy controls, which completes the treatment of the maincomponents of the library.

The next three sections cover the exceptions the package may raise and thedefects (non-compliance with the RFCs) that the parser maydetect. Then we cover the headerregistry and thecontentmanager sub-components, which provide tools for doing moredetailed manipulation of headers and payloads, respectively. Both of thesecomponents contain features relevant to consuming and producing non-trivialmessages, but also document their extensibility APIs, which will be of interestto advanced applications.

Following those is a set of examples of using the fundamental parts of the APIscovered in the preceding sections.

The foregoing represent the modern (unicode friendly) API of the email package.The remaining sections, starting with the Messageclass, cover the legacy compat32 API that deals much moredirectly with the details of how email messages are represented. Thecompat32 API does not hide the details of the RFCs fromthe application, but for applications that need to operate at that level, theycan be useful tools. This documentation is also relevant for applications thatare still using the compat32 API for backwardcompatibility reasons.

在 3.6 版更改: Docs reorganized and rewritten to promote the newEmailMessage/EmailPolicyAPI.

Contents of the email package documentation:

• email.message: Representing an email message
• email.parser: Parsing email messages
  • FeedParser API
  • Parser API
  • Additional notes
• email.generator: Generating MIME documents
• email.policy: Policy Objects
• email.errors: 异常和缺陷类
• email.headerregistry: Custom Header Objects
• email.contentmanager: Managing MIME Content
  • Content Manager Instances
• email: 示例

Legacy 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: 迭代器

参见

• Module smtplib

• SMTP (Simple Mail Transport Protocol) client

• Module poplib

• POP (Post Office Protocol) client

• Module imaplib

• IMAP (Internet Message Access Protocol) client

• Module nntplib

• NNTP (Net News Transport Protocol) client

• Module mailbox

• Tools for creating, reading, and managing collections of messages on diskusing a variety standard formats.

• Module smtpd

• SMTP server framework (primarily useful for testing)