Skip to main content

19.1.3. email.generator:生成MIME文档

源代码: Lib/email/generator.py


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

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

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

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

返回 BytesGenerator 对象,它将向 flatten() 方法提供的任何消息或提供给 write() 方法的任何代理转义编码文本写入 file-like object outfpoutfp 必须支持接受二进制数据的 write 方法。

如果可选的 mangle_from_True,则将 > 字符放在主体中以精确字符串 "From " 开头的任何行的前面,即 From 后面紧跟一行开头的空格。 mangle_from_ 默认为 policymangle_from_ 设置的值(对于 compat32 策略是 True,对于所有其他策略是 False)。 mangle_from_ 用于当消息以unix mbox格式存储时(请参阅 mailbox为什么内容长度格式是坏的)。

如果 maxheaderlen 不是 None,则重新折叠长于 maxheaderlen 的任何标题行,或者如果 0,则不重新包装任何标题。如果 manheaderlenNone (默认值),根据 policy 设置包装标题和其他消息行。

如果指定了 policy,请使用该策略控制消息生成。如果 policyNone (默认值),请使用与传递给 flattenMessageEmailMessage 对象关联的策略来控制消息生成。有关 policy 控制的详细信息,请参阅 email.policy

3.2 新版功能.

在 3.3 版更改: 添加了 policy 关键字。

在 3.6 版更改: mangle_from_maxheaderlen 参数的默认行为是遵循策略。

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

将根源于 msg 的消息对象结构的文本表示打印到创建 BytesGenerator 实例时指定的输出文件。

如果 policy 选项 cte_type8bit (默认),则将原始解析的消息中未修改的任何头部复制到输出中,将任何字节的高位设置为原始形式,并保留非ASCII Content-Transfer-Encoding 任何身体部位有它们。如果 cte_type7bit,则使用ASCII兼容的 Content-Transfer-Encoding 将需要的高位置位的字节转换。也就是说,将具有非ASCII Cotnent-Transfer-EncodingContent-Transfer-Encoding: 8bit)的部分转换为ASCII兼容性 Content-Transfer-Encoding,并使用MIME unknown-8bit 字符集在报头中编码RFC无效的非ASCII字节,从而使它们符合RFC。

如果 unixfromTrue,则在根消息对象的第一个 RFC 5322 头之前打印由Unix邮箱格式(请参阅 mailbox)使用的包络头定界符。如果根对象没有信封头,制作一个标准的。默认值为 False。请注意,对于子部分,不会打印任何包络头。

如果 linesep 不是 None,请使用它作为扁平消息的所有行之间的分隔符。如果 linesepNone (默认值),请使用 policy 中指定的值。

clone(fp)

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

write(s)

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

为了方便,EmailMessage 提供了方法 as_bytes()bytes(aMessage) (a.k.a. __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 outfpoutfp 必须支持接受字符串数据的 write 方法。

如果可选的 mangle_from_True,则将 > 字符放在主体中以精确字符串 "From " 开头的任何行的前面,即 From 后面紧跟一行开头的空格。 mangle_from_ 默认为 policymangle_from_ 设置的值(对于 compat32 策略是 True,对于所有其他策略是 False)。 mangle_from_ 用于当消息以unix mbox格式存储时(请参阅 mailbox为什么内容长度格式是坏的)。

如果 maxheaderlen 不是 None,则重新折叠长于 maxheaderlen 的任何标题行,或者如果 0,则不重新包装任何标题。如果 manheaderlenNone (默认值),根据 policy 设置包装标题和其他消息行。

如果指定了 policy,请使用该策略控制消息生成。如果 policyNone (默认值),请使用与传递给 flattenMessageEmailMessage 对象关联的策略来控制消息生成。有关 policy 控制的详细信息,请参阅 email.policy

在 3.3 版更改: 添加了 policy 关键字。

在 3.6 版更改: mangle_from_maxheaderlen 参数的默认行为是遵循策略。

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

将根源于 msg 的消息对象结构的文本表示打印到创建 Generator 实例时指定的输出文件。

如果 policy 选项 cte_type8bit,则生成消息,如同该选项设置为 7bit。 (这是必需的,因为字符串不能表示非ASCII字节。)使用ASCII兼容的 Content-Transfer-Encoding 转换任何具有高位设置的字节。也就是说,将具有非ASCII Cotnent-Transfer-EncodingContent-Transfer-Encoding: 8bit)的部分转换为ASCII兼容性 Content-Transfer-Encoding,并使用MIME unknown-8bit 字符集在报头中编码RFC无效的非ASCII字节,从而使它们符合RFC。

如果 unixfromTrue,则在根消息对象的第一个 RFC 5322 头之前打印由Unix邮箱格式(请参阅 mailbox)使用的包络头定界符。如果根对象没有信封头,制作一个标准的。默认值为 False。请注意,对于子部分,不会打印任何包络头。

如果 linesep 不是 None,请使用它作为扁平消息的所有行之间的分隔符。如果 linesepNone (默认值),请使用 policy 中指定的值。

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

clone(fp)

返回具有完全相同选项的此 Generator 实例的独立克隆,以及作为新 outfpfp

write(s)

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

为了方便起见,EmailMessage 提供了方法 as_string()str(aMessage) (a.k.a. __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 - 非text 零件的文件名

  • description - 与非text 零件相关的说明

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

如果 fmtNone,请使用以下默认 fmt

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

可选的 _mangle_from_maxheaderlenGenerator 基类一样。

脚注

[1]

此语句假定您对 unixfrom 使用适当的设置,并且没有要求自动调整的 policy 设置(例如,refold_source 必须是 none,这是默认的 not)。它也不是100%true,因为如果消息不符合RFC标准,偶尔地,关于确切的原始文本的信息在解析错误恢复期间丢失。这是一个目标,在可能的情况下修复这些后边缘情况。