email.generator：生成 MIME 文档 — Python 文档

email.generator：生成 MIME 文档

源代码： :source:`Lib/email/generator.py`

---

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

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

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

为了适应 SMIME 签名消息的可重现处理，Generator 禁用了类型为 multipart/signed 的消息部分和所有子部分的标头折叠。

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

返回一个 BytesGenerator 对象，该对象会将提供给 flatten() 方法的任何消息或提供给 write() 方法的任何代理转义编码文本写入到类文件对象 outfp。 outfp 必须支持接受二进制数据的 write 方法。

如果可选的 mangle_from_ 是 True，则在正文中以确切字符串 "From " 开头的任何行前面放置一个 > 字符，即 [ X160X] 在一行的开头跟一个空格。 mangle_from_ 默认为 policy 的 mangle_from_ 设置的值（对于 compat32 策略是 True 和False 对于所有其他人）。 mangle_from_ 适用于以 unix mbox 格式存储消息的情况（请参阅 mailbox 和 为什么内容长度格式不好）。

如果 maxheaderlen 不是 None，重新折叠任何长于 maxheaderlen 的标题行，或者如果 0，不要重新包装任何标题。 如果 manheaderlen 为 None（默认），则根据 policy 设置包装标题和其他消息行。

如果指定了 policy，则使用该策略来控制消息生成。 如果 policy 是 None（默认值），则使用与传递给 flatten 的 Message 或 EmailMessage 对象关联的策略来控制消息的生成。 有关 policy 控制内容的详细信息，请参阅 email.policy。

3.2 版中的新功能。

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

3.6 版更改： mangle_from_ 和 maxheaderlen 参数的默认行为是遵循策略。

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 unknown-8bit 字符集在标头中编码 RFC 无效的非 ASCII 字节，从而使它们符合 RFC。

如果 unixfrom 是 True，则在 的第一个之前打印 Unix 邮箱格式（参见 mailbox）使用的信封头分隔符]RFC 5322 根消息对象的标头。 如果根对象没有信封头，则制作一个标准的。 默认值为 False。 请注意，对于子部分，永远不会打印信封标题。

如果 linesep 不是 None，则将其用作平展消息所有行之间的分隔符。 如果 linesep 是 None（默认值），请使用 policy 中指定的值。

clone(fp)

返回此 BytesGenerator 实例的独立克隆，具有完全相同的选项设置，以及 fp 作为新的 outfp。

write(s)

使用 ASCII 编解码器和 surrogateescape 错误处理程序对 s 进行编码，并将其传递给 outfp 的 write 方法传递给 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)

返回一个 Generator 对象，该对象会将提供给 flatten() 方法的任何消息或提供给 write() 方法的任何文本写入 ]类文件对象 outfp。 outfp 必须支持接受字符串数据的 write 方法。

如果可选的 mangle_from_ 是 True，则在正文中以确切字符串 "From " 开头的任何行前面放置一个 > 字符，即 [ X160X] 在一行的开头跟一个空格。 mangle_from_ 默认为 policy 的 mangle_from_ 设置的值（对于 compat32 策略是 True 和False 对于所有其他人）。 mangle_from_ 适用于以 unix mbox 格式存储消息的情况（请参阅 mailbox 和 为什么内容长度格式不好）。

如果 maxheaderlen 不是 None，重新折叠任何长于 maxheaderlen 的标题行，或者如果 0，不要重新包装任何标题。 如果 manheaderlen 为 None（默认），则根据 policy 设置包装标题和其他消息行。

如果指定了 policy，则使用该策略来控制消息生成。 如果 policy 是 None（默认值），则使用与传递给 flatten 的 Message 或 EmailMessage 对象关联的策略来控制消息的生成。 有关 policy 控制内容的详细信息，请参阅 email.policy。

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

3.6 版更改： mangle_from_ 和 maxheaderlen 参数的默认行为是遵循策略。

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 unknown-8bit 字符集在标头中编码 RFC 无效的非 ASCII 字节，从而使它们符合 RFC。

如果 unixfrom 是 True，则在 的第一个之前打印 Unix 邮箱格式（参见 mailbox）使用的信封头分隔符]RFC 5322 根消息对象的标头。 如果根对象没有信封头，则制作一个标准的。 默认值为 False。 请注意，对于子部分，永远不会打印信封标题。

如果 linesep 不是 None，则将其用作平展消息所有行之间的分隔符。 如果 linesep 是 None（默认值），请使用 policy 中指定的值。

3.2 版更改： 添加了对重新编码 8bit 消息正文和 linesep 参数的支持。

clone(fp)

返回具有完全相同选项的此 Generator 实例的独立克隆，并将 fp 作为新的 outfp。

write(s)

将 s 写入传递给 Generator 的构造函数的 outfp 的 write 方法。 这为 Generator 实例提供了足够的类似文件的 API，以便在 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 – 非 text 部分的完整 MIME 类型

• maintype – 非 text 部分的主要 MIME 类型

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

• filename – 非 文本 部分的文件名

• description – 与非 文本 部分相关的描述

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

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

“[消息的非文本 (%(type)s) 部分省略，文件名 %(filename)s]”

可选的 _mangle_from_ 和 maxheaderlen 与 Generator 基类一样。

脚注

1

此声明假定您对 unixfrom 使用适当的设置，并且没有 policy 设置调用自动调整（例如，refold_source 必须是 none ]，这是 不是 的默认值）。 这也不是 100% 正确，因为如果消息不符合 RFC 标准，那么在解析错误恢复期间，有关准确原始文本的信息偶尔会丢失。 目标是在可能的情况下修复这些后一种边缘情况。