email.generator ：生成MIME文档

源代码： Lib/email/generator.py

最常见的任务之一是生成由消息对象结构表示的电子邮件消息的平面（序列化）版本。如果您想通过 smtplib.SMTP.sendmail() 或 nntplib 模块，或在控制台上打印消息。采用消息对象结构并生成序列化表示是生成器类的工作。

如同 email.parser 模块，您不局限于捆绑生成器的功能；您可以从头开始编写一个。然而，捆绑的生成器知道如何以符合标准的方式生成大多数电子邮件，应该处理好mime和非mime电子邮件，并且设计成以字节为导向的解析和生成操作是反向的，假设相同的非转换 policy 用于两者。也就是说，通过 BytesParser 类，然后使用 BytesGenerator 应生成与输入相同的输出 1. （另一方面，在 EmailMessage 由程序构造可能导致 EmailMessage 对象作为默认值填充。）

这个 Generator 类可用于将消息扁平化为文本（而不是二进制）序列化表示，但由于Unicode不能直接表示二进制数据，因此必须使用标准的电子邮件RFC内容传输编码技术将消息转换为仅包含ASCII字符的内容，以便为T编码电子邮件消息。在非“8位干净”的通道上传输。

以适应SMIME签名消息的可重复处理 Generator 禁用类型的消息部分的头折叠 multipart/signed 以及所有子部分。

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

返回A BytesGenerator 对象，该对象将写入提供给 flatten() 方法或提供给 write() 方法，以 file-like object 超额生产计划 . 超额生产计划 必须支持 write 接受二进制数据的方法。

如果可选 mangle_from_ 是 True 放一个 > 正文中以精确字符串开头的任何行前面的字符 "From " ，那就是 From 后面是行首的空格。 mangle_from_ 默认为 mangle_from_ 设置 policy （这是 True 对于 compat32 政策与 False 对于所有其他人）。 mangle_from_ 当消息以unix mbox格式存储时使用（请参见 mailbox 和 WHY THE CONTENT-LENGTH FORMAT IS BAD ）

如果 麦克海德伦 不是 None ，重新折叠长度超过 麦克海德伦 ，或者，如果 0 ，不要重新封装任何邮件头。如果 曼赫德伦 是 None （默认）、换行头和其他消息行根据 policy 设置。

如果 policy 已指定，请使用该策略控制消息生成。如果 policy 是 None （默认值）使用与 Message 或 EmailMessage 传递给的对象 flatten 控制消息生成。见 email.policy 有关什么的详细信息 policy 控制。

3.2 新版功能.

在 3.3 版更改: 增加了 policy 关键字。

在 3.6 版更改: 的默认行为 mangle_from_ 和 麦克海德伦 参数将遵循策略。

flatten(msg, unixfrom=False, linesep=None)

打印根位于的消息对象结构的文本表示形式 msg 到指定的输出文件 BytesGenerator 实例已创建。

如果 policy 选项 cte_type 是 8bit （默认值），复制原始已解析消息中未修改为输出的任何头，并像原始值一样复制高位集的任何字节，并保留非ASCII Content-Transfer-Encoding 任何拥有它们的身体部位。如果 cte_type 是 7bit ，根据需要使用与ASCII兼容的高位集转换字节 Content-Transfer-Encoding . 也就是说，用非ASCII转换部件 Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit ）与ASCII兼容 Content-Transfer-Encoding ，并使用mime对头中的rfc无效非ascii字节进行编码。 unknown-8bit 字符集，从而使它们符合RFC。

如果 unixfrom 是 True ，打印Unix邮箱格式使用的信封头分隔符（请参见 mailbox ）在 RFC 5322 根消息对象的头。如果根对象没有信封头，则创建一个标准的。默认值为 False . 请注意，对于子部分，从来没有打印过信封头。

如果 linesep 不是 None ，将其用作扁平消息所有行之间的分隔符。如果 linesep 是 None （默认值），使用 policy .

clone(fp)

返回此的独立复制 BytesGenerator 具有完全相同选项设置的实例，以及 fp 作为新的 超额生产计划 .

write(s)

编码 s 使用 ASCII 编解码器和 surrogateescape 错误处理程序，并将其传递给 写 方法 超额生产计划 传递给 BytesGenerator 的构造函数。

为了方便起见， EmailMessage 提供方法 as_bytes() 和 bytes(aMessage) （又名 __bytes__() ，这简化了消息对象的序列化二进制表示的生成。有关详细信息，请参阅 email.message .

因为字符串不能表示二进制数据，所以 Generator 类必须将它展开的任何消息中的任何二进制数据转换为与ASCII兼容的格式，方法是将它们转换为与ASCII兼容的格式。 Content-Transfer_Encoding . 使用电子邮件RFC的术语，您可以将其视为 Generator 串行化到一个不是“8位干净”的I/O流。换句话说，大多数应用程序都希望使用 BytesGenerator 而不是 Generator .

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

返回A Generator 对象，该对象将写入提供给 flatten() 方法或提供给 write() 方法，以 file-like object 超额生产计划 . 超额生产计划 必须支持 write 接受字符串数据的方法。

如果可选 mangle_from_ 是 True 放一个 > 正文中以精确字符串开头的任何行前面的字符 "From " ，那就是 From 后面是行首的空格。 mangle_from_ 默认为 mangle_from_ 设置 policy （这是 True 对于 compat32 政策与 False 对于所有其他人）。 mangle_from_ 当消息以unix mbox格式存储时使用（请参见 mailbox 和 WHY THE CONTENT-LENGTH FORMAT IS BAD ）

如果 麦克海德伦 不是 None ，重新折叠长度超过 麦克海德伦 ，或者，如果 0 ，不要重新封装任何邮件头。如果 曼赫德伦 是 None （默认）、换行头和其他消息行根据 policy 设置。

如果 policy 已指定，请使用该策略控制消息生成。如果 policy 是 None （默认值）使用与 Message 或 EmailMessage 传递给的对象 flatten 控制消息生成。见 email.policy 有关什么的详细信息 policy 控制。

在 3.3 版更改: 增加了 policy 关键字。

在 3.6 版更改: 的默认行为 mangle_from_ 和 麦克海德伦 参数将遵循策略。

flatten(msg, unixfrom=False, linesep=None)

打印根位于的消息对象结构的文本表示形式 msg 到指定的输出文件 Generator 实例已创建。

如果 policy 选项 cte_type 是 8bit ，生成消息，就好像选项设置为 7bit . （这是必需的，因为字符串不能代表非ASCII字节。）根据需要使用与ASCII兼容的高位集转换任何字节。 Content-Transfer-Encoding . 也就是说，用非ASCII转换部件 Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit ）与ASCII兼容 Content-Transfer-Encoding ，并使用mime对头中的rfc无效非ascii字节进行编码。 unknown-8bit 字符集，从而使它们符合RFC。

如果 unixfrom 是 True ，打印Unix邮箱格式使用的信封头分隔符（请参见 mailbox ）在 RFC 5322 根消息对象的头。如果根对象没有信封头，则创建一个标准的。默认值为 False . 请注意，对于子部分，从来没有打印过信封头。

如果 linesep 不是 None ，将其用作扁平消息所有行之间的分隔符。如果 linesep 是 None （默认值），使用 policy .

在 3.2 版更改: 添加了对重新编码的支持 8bit 消息主体，以及 linesep 参数。

clone(fp)

返回此的独立复制 Generator 具有完全相同选项的实例，以及 fp 作为新的 超额生产计划 .

write(s)

写 s 到 写 方法 超额生产计划 传递给 Generator 的构造函数。这为 Generator 要在中使用的实例 print() 功能。

为了方便起见， EmailMessage 提供方法 as_string() 和 str(aMessage) （又名 __str__() ，这简化了消息对象的格式化字符串表示的生成。有关详细信息，请参阅 email.message .

这个 email.generator 模块还提供派生类， DecodedGenerator ，就像 Generator 基类，除了-text 部分不是序列化的，而是在输出流中由一个字符串表示，该字符串由一个填充了有关部分信息的模板派生。

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

行为像 Generator ，除了传递给 Generator.flatten() ，如果子部分是主要类型 text ，打印子部分的解码有效载荷，如果主类型不是 text ，而不是打印它填充字符串 fmt 使用部件中的信息并打印结果填充字符串。

填写 fmt 执行 fmt % part_info 在哪里 part_info 是由以下键和值组成的字典：

  • type --非的完整mime类型-text 部分

  • maintype --非的主MIME类型-text 部分

  • subtype --非的子MIME类型-text 部分

  • filename --非的文件名-text 部分

  • description --与非关联的描述-text 部分

  • encoding --非内容传输编码-text 部分

如果 fmt 是 None ，使用以下默认值 fmt ：

“ [Non-text (%(type)s) part of message omitted, filename %(filename)s] “

可选的 _mangle_from_ 和 麦克海德伦 和一样 Generator 基类。

脚注

1

此语句假定使用适当的设置 unixfrom 而且没有 policy 需要自动调整的设置（例如， refold_source 必须是 none ，这就是 not 默认值）。这也不是100%正确的，因为如果消息不符合RFC标准，那么在解析错误恢复过程中，偶尔会丢失有关准确原始文本的信息。在可能的情况下，我们的目标是修复后一种边缘情况。