email.generator：生成MIME文档

源代码： Lib / email / generator.py

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

与email.parser模块，您不仅限于捆绑发电机的功能;你可以自己写一个从头开始。Howeverthe捆绑的生成器知道如何在符合标准的路径中生成大多数电子邮件，应该正确处理MIME和非MIME电子邮件消息，并且设计为面向字节的解析和生成操作是逆的，假设相同的非转换policy用于两者。那就是通过解析序列化的字节流BytesParserclass然后使用BytesGenerator重新生成serializedbyte流应该产生与输入[1]相同的输出。（另一方面，在程序构造的EmailMessage上使用生成器可能会导致EmailMessage对象变为默认值。）

Generator class可用于将消息展平为文本（反对二进制）序列化表示，但由于Unicode无法直接表示二进制数据，因此必须使用标准电子邮件RFCContent Transfer Encoding技术将消息转换为仅包含ASCII字符的内容。为不是“8位清洁”的传输通道编码电子邮件.

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

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

如果选择mangle_from_是True，请放一个>身体中任何以正确字符串"From "， 那是From在一行的开头跟一个空格。mangle_from_默认值为mangle_from_设置policy（这是True为了compat32政策和False为了所有其他人）.mangle_from_用于在unix mboxformat中存储消息时使用（参见mailbox以及为什么内容长度格式不好）.

如果maxheaderlen不是None，重新折叠任何长篇maxheaderlen，或者如果0，不要重新包装任何标题。如果manheaderlen是None（默认值），请根据policy设置

来包装标题和其他消息行.policy指定，使用该策略来控制消息生成。如果policy是None（默认值），请使用与Message或EmailMessage关联的策略传递给flatten控制消息的生成。看到email.policy有关policycontrols.

版本3.2.

改版3.3：添加了policy关键词。

版本3.6更改：的默认行为mangle_from_和maxheaderlen参数是遵循政策的.

flatten（msg, unixfrom=False, linesep=None）

打印消息对象结构的文本表示rootedat msg创建BytesGenerator实例时指定的输出文件.

如果policy选项cte_type是8bit（默认值），将原始parsedmessage中尚未修改的任何头文件复制到输出中，其中任何字节的高位设置都按原件复制，并保留非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-compliant .

如果unixfrom是True，在mailbox的第一个之前打印Unix邮箱格式（见RFC 5322 根消息对象的标头。如果根对象没有包络头，则制作一个标准的。默认为False。注意，对于子部件，没有打印信封标题.

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

clone（fp）中指定的值

返回一个独立的克隆BytesGenerator实例具有完全相同的选项设置，而fp作为新的outfp.

write（s）

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

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

因为字符串不能表示二进制数据，所以Generatorclass必须将任何二进制数据转换为ASCII兼容格式的任何二进制数据，方法是将它们转换为兼容ASCII的Content-Transfer_Encoding。使用emailRFCs的术语，您可以将其视为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 "开头的正文中，即From在一行的开头跟一个空格。mangle_from_默认值为mangle_from_设置policy（这是True为了compat32政策和False为了所有其他人）.mangle_from_用于在unix mboxformat中存储消息时使用（参见mailbox以及为什么内容长度格式不好）.

如果maxheaderlen不是None，重新折叠任何长篇maxheaderlen，或者如果0，不要重新包装任何标题。如果manheaderlen是None（默认值），请根据policy设置

来包装标题和其他消息行.policy指定，使用该策略来控制消息生成。如果policy是None（默认值），请使用与Message或EmailMessage关联的策略传递给flatten控制消息的生成。看到email.policy有关policycontrols.

改版3.3：添加了policy关键词。

版本3.6更改：的默认行为mangle_from_和maxheaderlen参数是遵循政策的.

flatten（msg, unixfrom=False, linesep=None）

打印消息对象结构的文本表示rootedat msg创建Generator实例时指定的输出文件.

如果policy选项cte_type是8bit，则生成消息为如果选项设置为7bit。（这是必需的，因为字符串不能表示非ASCII字节。）使用与ASCII兼容的Content-Transfer-Encoding，根据需要使用高位设置转换任何字节。也就是说，将非ASCII Cotnent-Transfer-Encoding（Content-Transfer-Encoding: 8bit）的部分转换为兼容ASCII的Content-Transfer-Encoding，并使用MIME ///编码标头中的RFC无效非ASCII字节unknown-8bit字符集，从而使它们符合RFC-compliant .

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

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

中指定的值更改版本3.2：添加了对重新编码的支持8bit消息体，和linesep论证

clone// (fp )

使用相同的选项返回此Generator实例的独立克隆，并将fp作为新的outfp.

write（s）

写s write的方法outfp传递给Generator的构造函数。这为Generator功能print()//中使用的

实例提供了足够的文件类API，为方便起见，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 – 主MIME非text部分的类型
• subtype – 非text部分的子MIME类型
• filename – 非文件名text部分
• description – 与非text部分相关的描述
• encoding – 非text部分

的内容传输编码如果fmt是None，请使用以下默认值fmt：

“[非文本（％（type）s）部分消息省略，文件名％（filename）s]“

可选_mangle_from_和maxheaderlen与Generator基类相同.

脚注