18.1.3. email.generator：生成 MIME 文档

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

同样，与email.parser模块一样，您不仅限于 Binding 生成器的Function；您可以自己从头开始写一个。但是，Binding 的生成器知道如何以符合标准的方式生成大多数电子邮件，应该能够很好地处理 MIME 和非 MIME 电子邮件，并且其设计目的是使从纯文本passParser类转换为消息结构，以及返回纯文本，是幂等的(Importing 与输出相同)[1]。另一方面，在程序构造的Message上使用生成器可能会导致Message对象发生更改，因为默认值已填写。

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

• • class * email.generator. Generator(* outfp * [，* mangle_from_ * [，* maxheaderlen *]])
  • Generator类的构造函数将一个名为* outfp *的文件状对象用作参数。 * outfp *必须支持write()方法，并且可用作 Python 扩展打印语句中的输出文件。

可选的* mangle_from_ *是一个标志，当True时，会将>字符放在正文中以From开头的任何行的前面，即From，然后在行的开头加一个空格。这是唯一避免这种行被误认为 Unix 邮箱格式信封头分隔符的可移植方式(有关详细信息，请参见为什么内容长度格式不正确)。 * mangle_from_ *默认为True，但是如果您不编写 Unix 邮箱格式文件，则可能希望将其设置为False。

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

其他公共Generator方法是：

• flatten(* msg * [，* unixfrom *])
  • 将以* msg *为根的消息对象结构的文本表示打印到创建Generator实例时指定的输出文件。深度优先访问子部分，并且所生成的文本将正确进行 MIME 编码。

可选的* unixfrom *是一个标志，用于强制在根消息对象的第一个 RFC 2822Headers 之前打印信封 Headers 定界符。如果根对象没有信封头，则会制作一个标准的信封头。默认情况下，将其设置为False以禁止打印信封定界符。

请注意，对于子部件，不会打印任何信封标题。

版本 2.2.2 中的新Function。

• clone(* fp *)
  • 返回具有完全相同选项的此Generator实例的独立克隆。

版本 2.2.2 中的新Function。

• write(* s *)
  • 将字符串* s 写入基础文件对象，即传递给Generator的构造函数的 outfp *。这为Generator实例提供了足够的类似于文件的 API，可在扩展打印语句中使用。

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

email.generator模块还提供了一个称为DecodedGenerator的派生类，该类类似于GeneratorBase Class，只是非* text *部分用表示该部分的格式字符串代替。

• • class * email.generator. DecodedGenerator(* outfp * [，* mangle_from_ * [，* maxheaderlen * [，* fmt *]]])
  • 从Generator派生的此类遍历消息的所有子部分。如果子部分的主要类型为* text ，那么它将打印该子部分的解码后的有效载荷。可选 mangle_from 和 maxheaderlen *与GeneratorBase Class 相同。

如果子部分不是主要类型* text ，则可选 fmt *是用于代替消息有效负载的格式字符串。 * fmt *使用以下%(keyword)s1 格式的关键字扩展：

• type –非* text *部分的完整 MIME 类型

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

• subtype –非* text *部分的 Sub-MIME 类型

• filename –非* text *部分的文件名

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

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

• fmt *的默认值为None，这意味着

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

版本 2.2.2 中的新Function。

在版本 2.5 中进行了更改：先前弃用的方法call()已删除。

Footnotes

• [1]
  • 该语句假定您为unixfrom参数使用了适当的设置，并且设置了 maxheaderlen = 0(将保留 Importing 行的长度)。这也不是严格正确的，因为在许多情况下，Headers 中的空白行会折叠为单个空格。后者是一个错误，finally将得到修复。