email

2.2版本中的新功能。

该email软件包是用于管理电子邮件消息的库，包括MIME和其他基于RFC 2822的消息文档。它涵括大部分功能在一些较旧的标准模块，例如rfc822，mimetools，multifile，和其他非标准包如mimecntl。它并不是专门用来发送电子邮件到SMTP（RFC 2821），NNTP或其他服务器的; 这些是诸如smtplib和的模块的功能nntplib。所述email包试图像RFC兼容尽可能，除了支持对RFC 2822，例如MIME相关的RFC如RFC 2045，RFC 2046，RFC 2047，和RFC 2231。

该email软件包的主要特色是它将电子邮件内部对象模型表示的电子邮件消息分解并生成。使用该email软件包的应用程序主要处理对象; 您可以将子对象添加到消息中，从消息中删除子对象，完全重新排列内容等。有一个单独的解析器和一个单独的生成器，用于处理从平面文本到对象模型的转换，然后返回到再次平面文字。对于一些常见的MIME对象类型，还有一些方便的子类，以及一些可用于提取和分析消息字段值以及创建RFC兼容日期等常见任务的其他实用程序。

以下部分描述了该email软件包的功能。顺序遵循一种在应用程序中应该普遍的进程：电子邮件从文件或其他来源读取为平面文本，解析文本以生成电子邮件消息的对象结构，操纵此结构，最后，对象树被重新绘制成平面文本。

用整块布来制作物体结构是完全可行的 - 即完全从头开始。从那里，可以采取与上面类似的进展。

此外还包括了email软件包提供的所有类和模块的详细规范，使用该email软件包时可能遇到的异常类，一些辅助实用程序以及一些示例。对于旧版mimelib软件包或旧版软件包的用户email，提供了有关差异和移植的部分。

该内容email包的文档：

• 18.1.1。email.message：代表电子邮件
• 18.1.2。email.parser：解析电子邮件
  • 18.1.2.1。FeedParser API
  • 18.1.2.2。解析器类API
  • 18.1.2.3。补充笔记
• 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：其他实用程序
• 10年1月18日。email.iterators：迭代器
• 11年1月18日。email： 例子

12.包装历史

此表描述了电子邮件包的发行历史记录，对应于发行该包的Python版本。对于本文档来说，当您看到关于更改或添加版本的备注时，这些参考是指已进行更改的Python版本，而不是电子邮件包版本。该表还描述了每个软件包版本的Python兼容性。

以下是email版本4和版本3 之间的主要区别：

• 所有模块已根据PEP 8标准重新命名。例如，版本3模块在版本4中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中已弃用的方法已被删除。这些措施包括Generator.__call__()，Message.get_type()，Message.get_main_type()，Message.get_subtype()。
• 已为RFC 2231支持添加了修复程序，可以为Message.get_param和朋友更改某些返回类型。在某些情况下，用于返回3元组的值现在返回简单字符串（具体来说，如果所有扩展参数段都未编码，则没有预期的语言和字符集指定，因此返回类型现在是简单的字符串）。此外，编码和未编码的片段都使用％解码。这种解码现在只能用于编码的段。

以下是email版本3和版本2 之间的主要区别：

• 该FeedParser课程被引入，并且该Parser课程是按照该课程实施的FeedParser。因此，所有解析都是非严格的，解析将尽最大努力永远不会引发异常。解析消息时发现的问题存储在消息的缺陷属性中。
• DeprecationWarning在第2版中引发的API的所有方面都已被删除。这些包括_encoder参数给MIMEText构造函数，所述Message.add_payload()方法中，所述Utils.dump_address_pair()功能，以及功能Utils.decode()和Utils.encode()。
• 新DeprecationWarning■找被添加到：Generator.__call__()，Message.get_type()，Message.get_main_type()，Message.get_subtype()，和严格的参数传递给Parser类。这些预计将在未来的版本中被删除。
• 对2.3之前的Pythons的支持已被删除。

以下是email版本2和版本1 之间的区别：

• 在email.Header和email.Charset模块已被添加。
• Message实例的pickle格式已经改变。由于这从来没有（也没有）正式定义，所以这不被认为是落后的不相容性。但是，如果您的应用程序使用pickle和unpickle Message实例，请注意，在email版本2中，Message实例现在具有私有变量_charset和_default_type。
• Message该类中的几个方法已被弃用，或者其签名已更改。此外，许多新的方法已被添加。有关Message详细信息，请参阅该课程的文档。这些更改应完全向后兼容。
• 面对message / rfc822内容类型，对象结构发生了变化。在email版本1中，这种类型将由标量负载表示，即容器消息的is_multipart()返回值为false，get_payload()不是列表对象，而是单个Message实例。此结构与该包的其余部分不一致，因此message / rfc822内容类型的对象表示已更改。在email2版本里，容器不会返回True从is_multipart()，并且get_payload()返回一个包含一个列表Message项。请注意，这是一个向后兼容性无法完全维护的地方。但是，如果您已经测试了返回类型get_payload()，你应该没问题。你只需要确保你的代码不会在内容类型为message / rfc822的容器上执行set_payload()一个Message实例。
• 该Parser构造函数的严格论证，并将其parse()和parsestr()方法留起了headersonly说法。在严格的标志也被加入到功能email.message_from_file()和email.message_from_string()。
• Generator.__call__()已弃用; Generator.flatten改为使用。该Generator班也发展了这种clone()方法。
• 模块中的DecodedGenerator类email.generator已添加。
• 中间基类MIMENonMultipart和MIMEMultipart已被添加，并且在类层次插入大多数其他MIME相关派生类。
• 构造函数的_encoder参数MIMEText已被弃用。编码现在基于_charset参数隐式发生。
• 中的以下功能email.Utils模块已弃用：dump_address_pairs()，decode()，和encode()。以下功能已经被添加到模块：make_msgid()，decode_rfc2231()，encode_rfc2231()，和decode_params()。
• 非公开功能email.Iterators._structure()被添加。

13.与之不同 mimelib

这个email软件包最初是作为一个名为mimelib的独立库建立的。已经进行了更改，以便方法名称更加一致，并且已添加或删除了一些方法或模块。一些方法的语义也发生了变化。大多数情况下，包中mimelib仍有可用的任何功能email，尽管通常采用不同的方式。mimelib软件包和email软件包之间的向后兼容性不是优先事项。

这里的之间的差异的简要说明mimelib和email包装，以提示沿着如何移植你的应用程序。

当然，这两个软件包之间最明显的区别在于软件包名称已更改为email。另外，顶级套餐有以下不同之处：

• messageFromString()已更名为message_from_string()。
• messageFromFile()已更名为message_from_file()。

这Message门课有以下不同之处：

• 该方法asString()已重命名为as_string()。
• 该方法ismultipart()已重命名为is_multipart()。
• 该get_payload()方法增加了解码可选参数。
• 该方法getall()已重命名为get_all()。
• 该方法addheader()已重命名为add_header()。
• 该方法gettype()已重命名为get_type()。
• 该方法getmaintype()已重命名为get_main_type()。
• 该方法getsubtype()已重命名为get_subtype()。
• 该方法getparams()已重命名为get_params()。此外，getparams()返回一个字符串列表，get_params()返回一个2元组列表，实际上是参数的键/值对，在'='符号上分开。
• 该方法getparam()已重命名为get_param()。
• 该方法getcharsets()已重命名为get_charsets()。
• 该方法getfilename()已重命名为get_filename()。
• 该方法getboundary()已重命名为get_boundary()。
• 该方法setboundary()已重命名为set_boundary()。
• 该方法getdecodedpayload()被删除。要获得类似的功能，请将值1传递给方法的解码标志get_payload()。
• 该方法getpayloadastext()被删除。模块中的DecodedGenerator类支持类似的功能email.generator。
• 该方法getbodyastext()被删除。您可以通过typed_subpart_iterator()在email.iterators模块中创建迭代器来获得类似的功能。

该Parser班在其公共接口没有差别。它确实有一些额外的智能来识别消息/传送状态类型消息，它表示为Message包含Message传送状态通知[1]中每个标题块的单独子部分的实例。

该Generator班在其公共接口没有差别。email.generator虽然模块中有一个新类，但DecodedGenerator它提供了以前在该Message.getpayloadastext()方法中可用的大部分功能。

以下模块和类已更改：

• 在MIMEBase类的构造函数参数_major和_minor已更改为_maintype和_subtype分别。
• 该Image级/模块已更名为MIMEImage。该_minor争论已更名为_subtype。
• 该Text级/模块已更名为MIMEText。该_minor争论已更名为_subtype。
• 该MessageRFC822级/模块已更名为MIMEMessage。请注意，早期版本mimelib称为此类/模块RFC822，但rfc822在某些不区分大小写的文件系统上与Python标准库模块发生冲突。此外，MIMEMessage该类现在代表具有主类型消息的任何类型的MIME 消息。它需要一个可选参数_subtype用于设置MIME子类型。_subtype默认为rfc822。

mimelib在其提供的一些实用功能address和date模块。所有这些功能都已移至email.utils模块。

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

注