19.1.3. email.generator：生成MIME文档

源代码： Lib / email / generator.py

最常见的任务之一是生成由消息对象结构表示的电子邮件消息的平面文本。如果要通过smtplib模块或nntplib模块发送消息，或在控制台上打印消息，则需要执行此操作。获取消息对象结构并产生平面文本文档是Generator类的工作。

再次，与email.parser模块一样，您不限于捆绑的生成器的功能；你可以自己写一个从头开始。然而，捆绑的生成器知道如何以符合标准的方式生成大多数电子邮件，应该处理MIME和非MIME电子邮件消息就好了，并且设计为从平面文本到消息结构通过Parser类，并返回平面文本，是幂等的（输入与输出相同）[1]。另一方面，在程序构建的Message上使用生成器可能会导致对Message对象进行更改，因为默认值已填充。

bytes输出可以使用BytesGenerator类生成。如果消息对象结构包含非ASCII字节，则此生成器的flatten()方法将发出原始字节。解析二进制消息，然后用BytesGenerator对其进行展平应该对于符合标准的消息是等幂的。

以下是从email.generator模块导入的Generator类的公共方法：

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

Generator类的构造函数采用一个名为outfp的file-like object作为参数。outfp必须支持write()方法，并可用作print()函数的输出文件。

Optional mangle_from_ is a flag that, when True, puts a > character in front of any line in the body that starts exactly as From, i.e. From后面跟着一个空格开头的行。这是唯一的保证可移植的方式，以避免这样的行被误认为是Unix邮箱格式的信封头分隔符（详情见为什么内容长度格式是）。mangle_from _默认为True，但如果您不在编写Unix邮箱格式文件，则可以将其设置为False。

可选maxheaderlen指定非连续标头的最长长度。当标题行长于maxheaderlen（以字符为单位，且制表符扩展为8个空格）时，标题将按照Header类中的定义进行拆分。设置为零以禁用标题换行。默认值为78，根据 RFC 2822推荐（但不是必需）。

policy关键字指定了一个控制生成器操作的多个方面的policy对象。如果未指定策略，则使用附加到传递到flatten的消息对象的策略。

在版本3.3中已更改：添加了政策关键字。

其他公共Generator方法是：

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

将根源于msg的消息对象结构的文本表示打印到创建Generator子部分被深度优先访问，并且生成的文本将被正确地MIME编码。

可选unixfrom是在根消息对象的第一个 RFC 2822头之前强制打印包络头定界符的标志。如果根对象没有包络头，那么将创建一个标准对象。默认情况下，设置为False可禁止打印信封定界符。

注意，对于子部分，不会打印任何包络头。

可选linesep指定用于终止输出中的行的行分隔符。如果指定，它将覆盖msg或Generator的policy指定的值。

因为字符串不能表示非ASCII字节，如果运行flatten时应用的策略已将cte_type设置为8bit，Generator将如同设置为7bit一样操作。这意味着使用具有8bit的内容传输编码的字节解析器解析的消息将转换为使用7bit Content-传输编码。头中的非ASCII字节为 RFC 2047，编码格式为unknown-8bit。

在版本3.2中更改：添加了对重新编码8bit邮件正文和lineep参数的支持。

clone(fp)

使用完全相同的选项返回此Generator实例的独立克隆。

write(s)

将字符串s写入底层文件对象，即outfp传递到Generator的构造函数。这为Generator实例提供了在print()函数中使用的足够文件类API。

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

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

BytesGenerator类的构造函数为一个参数采用了一个名为outfp的二进制file-like object。outfp必须支持接受二进制数据的write()方法。

Optional mangle_from_ is a flag that, when True, puts a > character in front of any line in the body that starts exactly as From, i.e. From后面跟着一个空格开头的行。这是唯一的保证可移植的方式，以避免这样的行被误认为是Unix邮箱格式的信封头分隔符（详情见为什么内容长度格式是）。mangle_from _默认为True，但如果您不在编写Unix邮箱格式文件，则可以将其设置为False。

可选maxheaderlen指定非连续标头的最长长度。当标题行长于maxheaderlen（以字符为单位，且制表符扩展为8个空格）时，标题将按照Header类中的定义进行拆分。设置为零以禁用标题换行。默认值为78，根据 RFC 2822推荐（但不是必需）。

policy关键字指定了一个控制生成器操作的多个方面的policy对象。如果未指定策略，则使用附加到传递到flatten的消息对象的策略。

在版本3.3中已更改：添加了政策关键字。

其他公共BytesGenerator方法是：

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

将根源于msg的消息对象结构的文本表示打印到创建BytesGenerator实例时指定的输出文件。子部分被深度优先访问，并且生成的文本将被正确地MIME编码。如果policy选项cte_type为8bit（默认值），则在原始解析的消息中设置了高位的任何字节修改将忠实地复制到输出。如果cte_type是7bit，则字节将根据需要使用ASCII兼容的内容传输编码进行转换。特别地，头部中的RFC无效非ASCII字节将使用MIME unknown-8bit字符集进行编码，从而使它们符合RFC。

如果尚未修改，则具有8位的内容传输编码的字节解析器解析的消息将重建为8位。

可选unixfrom是在根消息对象的第一个 RFC 2822头之前强制打印包络头定界符的标志。如果根对象没有包络头，那么将创建一个标准对象。默认情况下，设置为False可禁止打印信封定界符。

注意，对于子部分，不会打印任何包络头。

可选linesep指定用于终止输出中的行的行分隔符。如果指定，它将覆盖Generator或msg的policy指定的值。

clone(fp)

返回此BytesGenerator实例的独立克隆，具有完全相同的选项。

write(s)

将字符串s写入底层文件对象。s is encoded using the ASCII codec and written to the write method of the outfp outfp passed to the BytesGenerator‘s constructor. 这为BytesGenerator实例在print()函数中使用提供了足够的文件类API。

版本3.2中的新功能。

The email.generator module also provides a derived class, called DecodedGenerator which is like the Generator base class, except that non-text parts are substituted with a format string representing the part.

class email.generator.DecodedGenerator(outfp, mangle_from_=True, maxheaderlen=78, fmt=None)

此类派生自Generator遍历消息的所有子部分。如果子部分是主类型text，则它打印子部分的解码有效载荷。可选_mangle_from _和maxheaderlen与Generator基类相同。

如果子部件不是主类型text，则可选的fmt是使用的格式字符串，而不是消息有效内容。fmt使用以下关键字进行展开：%(keyword)s格式：

• type - 非文本部分的完整MIME类型
• maintype - 非文本部分的主要MIME类型
• subtype - 非文本部分的子MIME类型
• filename - 非文本部分的文件名
• description - 与非文本部分相关联的说明
• encoding - 非文本部分的内容传输编码

fmt的默认值为None，意思

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

脚注

[1]	此语句假定您对unixfrom参数使用适当的设置，并且设置maxheaderlen = 0（这将保留所有输入线路长度）。它也不是严格的真实，因为在许多情况下，头中的空格的运行折叠成单个空格。后者是一个最终将被修复的错误。