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 折叠。

如果可选的* 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(默认值),请使用与传递给flattenMessageEmailMessage对象关联的策略来控制消息的生成。有关_policy *控制的详细信息,请参见email.policy

3.2 版中的新Function。

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

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

如果policy选项cte_type8bit(默认值),则将原始已解析消息中未修改的所有 Headers 复制到输出,并复制具有原始位高位的任何字节,并保留非 ASCII * Content -具有它们的任何身体部位的-Transfer-Encoding 。如果cte_type7bit,请使用与 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 *中指定的值。

为方便起见,EmailMessage提供了方法as_bytes()bytes(aMessage)(又称bytes()),它们简化了消息对象的序列化二进制表示形式的生成。有关更多详细信息,请参见email.message

由于字符串不能表示二进制数据,因此Generator类必须将其平展为 ASCII 兼容格式的任何消息中的任何二进制数据转换为,将它们转换为 ASCII 兼容* Content-Transfer_Encoding *。使用电子邮件 RFC 的术语,您可以将其视为Generator序列化为不是“ 8 位干净”的 I/O 流。换句话说,大多数应用程序都希望使用BytesGenerator而不是Generator

如果可选的* 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(默认值),请使用与传递给flattenMessageEmailMessage对象关联的策略来控制消息的生成。有关_policy *控制的详细信息,请参见email.policy

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

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

如果policy选项cte_type8bit,则生成消息,就像该选项设置为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 *参数的支持。

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

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

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

如果* fmt None,请使用以下默认 fmt *:

Note

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

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

Footnotes

首页