email.generator：生成 MIME 文档

源代码： Lib/email/generator.py

---

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

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

Generator类可用于将消息扁平化为文本(与二进制相反)序列化表示形式，但是由于 Unicode 无法直接表示二进制数据，因此必须使用标准电子邮件 RFC 将消息转换为仅包含 ASCII 字符的内容内容传输编码技术，用于对电子邮件消息进行编码，以pass“ 8 位不干净”的通道进行传输。

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

• • class * email.generator. BytesGenerator(* outfp ， mangle_from_ = None ， maxheaderlen = None ，**，* policy = None *)
  • 返回一个BytesGenerator对象，该对象会将提供给flatten()方法的任何消息或提供给write()方法的任何代理转义编码的文本写入file-like object * outfp *。 * outfp *必须支持接受二进制数据的write方法。

如果可选的* mangle_from_ *为True，则在正文中以精确字符串"From "开头的>字符(即From)，然后在行首添加一个空格。 * 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 版中的新Function。

在版本 3.3 中进行了更改：添加了* policy *关键字。

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

• flatten(* msg ， unixfrom = False ， linesep = None *)
  • 将以* msg *为根的消息对象结构的文本表示打印到创建BytesGenerator实例时指定的输出文件。

如果policy选项cte_type为8bit(默认值)，则将原始已解析消息中未修改的所有 Headers 复制到输出，并复制具有原始位高位的任何字节，并保留非 ASCII * Content -具有它们的任何身体部位的-Transfer-Encoding 。如果cte_type是7bit，请使用与 ASCII 兼容的 Content-Transfer-Encoding *，根据需要转换设置了高位的字节。也就是说，将非 ASCII * Content-Transfer-Encoding ( Content-Transfer-Encoding：8bit )的部分转换为与 ASCII 兼容的 Content-Transfer-Encoding *，并在 Headers 中编码 RFC 无效的非 ASCII 字节使用 MIME unknown-8bit字符集，从而使其符合 RFC。

如果* unixfrom *为True，则在根消息对象的 RFC 5322头标中的第一个 Headers 之前打印 Unix 邮箱格式(请参见mailbox)使用的信封头定界符。如果根对象没有信封 Headers，则制作一个标准的 Headers。默认值为False。请注意，对于子部件，不会打印任何信封标题。

如果* linesep 不是None，请将其用作拼合消息的所有行之间的分隔符。如果 linesep 为None(默认值)，请使用 policy *中指定的值。

• clone(* fp *)

  • 返回具有完全相同的选项设置的BytesGenerator实例的独立克隆，并将* fp 作为新的 outfp *。

• write(* s *)

  • 使用ASCII编解码器和surrogateescape错误处理程序对* s 进行编码，并将其传递给传递给BytesGenerator的构造函数的 outfp 的 write *方法。

为方便起见，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()方法的任何文本写入file-like object * outfp *。 * outfp *必须支持write接受字符串数据的方法。

如果可选的* mangle_from_ *为True，则在正文中以精确字符串"From "开头的>字符(即From)，然后在行首添加一个空格。 * 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 *，并在 Headers 中编码 RFC 无效的非 ASCII 字节使用 MIME unknown-8bit字符集，从而使其符合 RFC。

如果* unixfrom *为True，则在根消息对象的 RFC 5322头标中的第一个 Headers 之前打印 Unix 邮箱格式(请参见mailbox)使用的信封头定界符。如果根对象没有信封 Headers，则制作一个标准的 Headers。默认值为False。请注意，对于子部件，不会打印任何信封标题。

如果* linesep 不是None，请将其用作拼合消息的所有行之间的分隔符。如果 linesep 为None(默认值)，请使用 policy *中指定的值。

在版本 3.2 中进行了更改：增加了对重新编码8bit消息正文和* linesep *参数的支持。

• clone(* fp *)

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

• write(* s *)

  • 将* s 写入传递给Generator的构造函数的 outfp 的 write *方法。这为print()函数中使用的Generator实例提供了足够的类似于文件的 API。

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

email.generator模块还提供了一个派生类DecodedGenerator，它类似于GeneratorBase Class，除了不对非* text *部分进行序列化，而是在输出流中用从填充有信息的模板派生的字符串表示关于部分。

• • class * email.generator. DecodedGenerator(* outfp ， mangle_from_ = None ， maxheaderlen = None ， fmt = None ，**，* policy = None *)
  • 就像Generator一样，除了传递给Generator.flatten()的消息的任何子部分外，如果子部分的主要类型为* text ，则打印该子部分的解码后的有效载荷，并且如果主要类型不是 text ，则不打印使用 Component 中的信息填充字符串 fmt *并打印生成的填充字符串。

要填写* fmt *，请执行fmt % part_info，其中part_info是由以下键和值组成的字典：

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

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

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

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

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

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

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

可选的* mangle_from 和 maxheaderlen *与GeneratorBase Class 相同。

Footnotes

• [1]
  • 该语句假定您为unixfrom使用了适当的设置，并且没有policy设置要求进行自动调整(例如refold_source必须为none，这不是*默认值)。这也不是 100％正确，因为如果消息不符合 RFC 标准，则在解析错误恢复期间有时会丢失有关确切原始文本的信息。一个目标是在可能的情况下解决这些后继情况。