18.1。 email - 电子邮件和MIME处理包

New in version 2.2.

电子邮件包是用于管理电子邮件（包括MIME和其他 基于RFC 2822的邮件文档）的库。它包含多个旧标准模块中的大部分功能，例如rfc822，mimetools，multifile和其他非标准软件包 mimecntl 。专门用于向SMTP（ RFC 2821），NNTP或其他服务器发送电子邮件的具体不那些是诸如smtplib和nntplib的模块的功能。The email package attempts to be as RFC-compliant as possible, supporting in addition to RFC 2822, such MIME-related RFCs as RFC 2045, RFC 2046, RFC 2047, and RFC 2231.

The primary distinguishing feature of the email package is that it splits the parsing and generating of email messages from the internal object model representation of email.使用电子邮件包的应用程序主要处理对象；您可以向消息添加子对象，从消息中删除子对象，完全重新排列内容等。有一个单独的解析器和一个单独的生成器，它处理从平面文本到对象模型的转换，然后再次返回到平面文本。还有一些常见MIME对象类型的方便子类，以及一些其他常用任务，例如提取和解析消息字段值，创建符合RFC的日期等。

以下部分描述了电子邮件包的功能。排序遵循在应用中应该是常见的进展：电子邮件消息从文件或其他来源读取为平面文本，解析文本以生成电子邮件消息的对象结构，此结构被操纵，最后，对象树被渲染成平面文本。

从整个布料中产生物体结构是完全可行的 - 即完全从头开始。从那里可以像上面那样采取类似的进展。

还包括电子邮件包提供的所有类和模块的详细规范，您可能在使用电子邮件包时遇到的异常类，一些辅助工具和一些例子。对于较旧的mimelib软件包或旧版本的电子邮件软件包的用户，提供了有关差异和移植的部分。

电子邮件包文档的内容：

• 18.1.1。 email.message：表示电子邮件
• 18.1.2。 email.parser：解析电子邮件
  • 18.1.2.1。 FeedParser API
  • 18.1.2.2. Parser class API
  • 18.1.2.3. Additional notes
• 18.1.3。 email.generator：生成MIME文档
• 18.1.4。 email.mime：从头开始创建电子邮件和MIME对象
• 18.1.5。 email.header：国际化标头
• 18.1.6。 email.charset：表示字符集
• 18.1.7。 email.encoders：编码器
• 18.1.8。 email.errors：异常和缺陷类
• 18.1.9。 email.utils：其他工具
• 18.1.10。 email.iterators：迭代器
• 18.1.11. email: Examples

See also

Module smtplib

SMTP协议客户端

Module nntplib

NNTP协议客户端

18.1.12. Package History

该表描述了与发行包的Python版本对应的电子邮件包的发行历史记录。为了本文档的目的，当您看到关于更改或添加的版本的注释时，这些引用指的是更改的Python版本，不是电子邮件包版本。该表还描述了每个版本的包的Python兼容性。

email version	distributed with	compatible with
1.x	Python 2.2.0 to Python 2.2.1	no longer supported
2.5	Python 2.2.2+ and Python 2.3	Python 2.1 to 2.5
3.0	Python 2.4	Python 2.3 to 2.5
4.0	Python 2.5	Python 2.3 to 2.5

以下是电子邮件版本4和版本3之间的主要区别：

• 所有模块已根据 PEP 8标准重新命名。例如，在版本4中将版本3模块email.Message重命名为email.message。

• 添加了一个新的子包email.mime，所有版本3 email.MIME *模块已重命名，位于email.mime子包中。例如，版本3模块email.MIMEText已重命名为email.mime.text。

  请注意，版本3的名称将继续工作，直到Python 2.6。

• 添加了email.mime.application模块，其中包含MIMEApplication类。

• 在第3版中已弃用的方法已被删除。These include Generator.__call__(), Message.get_type(), Message.get_main_type(), Message.get_subtype().

• 已经为 RFC 2231支持添加了修正，可以更改Message.get_param和朋友的一些返回类型。在某些情况下，用于返回3元组的值现在返回简单的字符串（具体来说，如果所有扩展参数段都未被编码，则不需要语言和字符集，因此返回类型现在是一个简单的字符串）。此外，％-decoding曾经被编码和未编码的段完成；此解码现在仅对编码段完成。

以下是电子邮件版本3和版本2之间的主要区别：

• 引入了FeedParser类，并且Parser类是根据FeedParser实现的。因此，所有解析都是非严格的，解析将尽力避免引发异常。分析消息时发现的问题存储在消息的缺陷属性中。
• 版本2中引发DeprecationWarning的API的所有方面已被删除。These include the _encoder argument to the MIMEText constructor, the Message.add_payload() method, the Utils.dump_address_pair() function, and the functions Utils.decode() and Utils.encode().
• New DeprecationWarnings have been added to: Generator.__call__(), Message.get_type(), Message.get_main_type(), Message.get_subtype(), and the strict argument to the Parser class. These are expected to be removed in future versions.
• 支持超过2.3的Pythons已被删除。

以下是电子邮件版本2和版本1之间的区别：

• 添加了email.Header和email.Charset模块。

• Message实例的泡菜格式已更改。既然这是从来没有（但仍然没有）正式定义，这不被认为是后向不兼容性。However if your application pickles and unpickles Message instances, be aware that in email version 2, Message instances now have private variables _charset and _default_type.

• Message类中的几个方法已被弃用，或者其签名已更改。另外，还增加了许多新的方法。有关详细信息，请参阅Message类的文档。这些更改应该完全向后兼容。

• 对象结构已经在message / rfc822内容类型的表面上发生了变化。在email版本1中，这种类型将由标量有效载荷表示，即容器消息的is_multipart()返回false，get_payload()不是一个列表对象，而是一个Message实例。

  这个结构与包的其余部分不一致，所以message / rfc822内容类型的对象表示被改变了。In email version 2, the container does return True from is_multipart(), and get_payload() returns a list containing a single Message item.

  Note that this is one place that backward compatibility could not be completely maintained. However, if you’re already testing the return type of get_payload(), you should be fine. You just need to make sure your code doesn’t do a set_payload() with a Message instance on a container with a content type of message/rfc822.

• The Parser constructor’s strict argument was added, and its parse() and parsestr() methods grew a headersonly argument. The strict flag was also added to functions email.message_from_file() and email.message_from_string().

• Generator.__call__() is deprecated; use Generator.flatten instead. The Generator class has also grown the clone() method.

• The DecodedGenerator class in the email.generator module was added.

• The intermediate base classes MIMENonMultipart and MIMEMultipart have been added, and interposed in the class hierarchy for most of the other MIME-related derived classes.

• The _encoder argument to the MIMEText constructor has been deprecated. Encoding now happens implicitly based on the _charset argument.

• The following functions in the email.Utils module have been deprecated: dump_address_pairs(), decode(), and encode(). The following functions have been added to the module: make_msgid(), decode_rfc2231(), encode_rfc2231(), and decode_params().

• The non-public function email.Iterators._structure() was added.

18.1.13. Differences from mimelib

The email package was originally prototyped as a separate library called mimelib. Changes have been made so that method names are more consistent, and some methods or modules have either been added or removed. The semantics of some of the methods have also changed. For the most part, any functionality available in mimelib is still available in the email package, albeit often in a different way. Backward compatibility between the mimelib package and the email package was not a priority.

Here is a brief description of the differences between the mimelib and the email packages, along with hints on how to port your applications.

Of course, the most visible difference between the two packages is that the package name has been changed to email. In addition, the top-level package has the following differences:

• messageFromString() has been renamed to message_from_string().
• messageFromFile() has been renamed to message_from_file().

The Message class has the following differences:

• The method asString() was renamed to as_string().
• The method ismultipart() was renamed to is_multipart().
• The get_payload() method has grown a decode optional argument.
• The method getall() was renamed to get_all().
• The method addheader() was renamed to add_header().
• The method gettype() was renamed to get_type().
• The method getmaintype() was renamed to get_main_type().
• The method getsubtype() was renamed to get_subtype().
• The method getparams() was renamed to get_params(). Also, whereas getparams() returned a list of strings, get_params() returns a list of 2-tuples, effectively the key/value pairs of the parameters, split on the '=' sign.
• The method getparam() was renamed to get_param().
• The method getcharsets() was renamed to get_charsets().
• The method getfilename() was renamed to get_filename().
• The method getboundary() was renamed to get_boundary().
• The method setboundary() was renamed to set_boundary().
• The method getdecodedpayload() was removed. To get similar functionality, pass the value 1 to the decode flag of the get_payload() method.
• The method getpayloadastext() was removed. Similar functionality is supported by the DecodedGenerator class in the email.generator module.
• The method getbodyastext() was removed. You can get similar functionality by creating an iterator with typed_subpart_iterator() in the email.iterators module.

The Parser class has no differences in its public interface. It does have some additional smarts to recognize message/delivery-status type messages, which it represents as a Message instance containing separate Message subparts for each header block in the delivery status notification [1].

The Generator class has no differences in its public interface. There is a new class in the email.generator module though, called DecodedGenerator which provides most of the functionality previously available in the Message.getpayloadastext() method.

The following modules and classes have been changed:

• The MIMEBase class constructor arguments _major and _minor have changed to _maintype and _subtype respectively.

• The Image class/module has been renamed to MIMEImage. The _minor argument has been renamed to _subtype.

• The Text class/module has been renamed to MIMEText. The _minor argument has been renamed to _subtype.

• The MessageRFC822 class/module has been renamed to MIMEMessage. Note that an earlier version of mimelib called this class/module RFC822, but that clashed with the Python standard library module rfc822 on some case-insensitive file systems.

  Also, the MIMEMessage class now represents any kind of MIME message with main type message. It takes an optional argument _subtype which is used to set the MIME subtype. _subtype defaults to rfc822.

mimelib provided some utility functions in its address and date modules. All of these functions have been moved to the email.utils module.

The MsgReader class/module has been removed. Its functionality is most closely supported in the body_line_iterator() function in the email.iterators module.

Footnotes

[1]	Delivery Status Notifications (DSN) are defined in RFC 1894.