email.contentmanager：管理 MIME 内容

源代码： Lib/email/contentmanager.py

在 3.6 版本加入： [1]

class email.contentmanager.ContentManager

内容管理器的基类。提供了标准的注册机制，用于注册 MIME 内容和其他表示形式之间的转换器，以及 get_content 和 set_content 派发方法。

get_content(msg, *args, **kw)

根据 msg 的 mimetype（见下一段）查找一个处理函数，调用它，并透传所有参数，然后返回调用的结果。期望处理函数会从 msg 中提取有效载荷，并返回一个编码了所提取数据信息的对象。

为了找到处理函数，将在注册表中查找以下键，找到第一个即停止：

  • 表示完整 MIME 类型（maintype/subtype）的字符串

  • 表示 maintype 的字符串

  • 空字符串

如果这些键都找不到处理函数，则针对完整的 MIME 类型引发 KeyError。

set_content(msg, obj, *args, **kw)

如果 maintype 是 multipart，则引发 TypeError；否则，根据 obj 的类型查找处理函数（见下一段），在 msg 上调用 clear_content()，然后调用该处理函数，并透传所有参数。期望处理函数会转换 obj 并将其存储到 msg 中，可能还会对 msg 做其他更改，例如添加各种 MIME 标头来编码解释所存数据所需的信息。

为了找到处理函数，先获取 obj 的类型（typ = type(obj)），然后在注册表中查找以下键，找到第一个即停止：

  • 类型本身（typ）

  • 类型的完全限定名称（typ.__module__ + '.' + typ.__qualname__）。

  • 类型的 qualname (typ.__qualname__)

  • 类型的 name (typ.__name__)。

如果以上都没有匹配项，则对 MRO（typ.__mro__）中的每个类型重复上述所有检查。最后，如果没有其他键能找到处理函数，则检查键 None 是否有处理函数。如果 None 也没有处理函数，则针对类型的完全限定名称引发 KeyError。

如果 MIME-Version 标头不存在，也会添加它（另请参阅 MIMEPart）。

add_get_handler(key, handler)

将函数 handler 记录为 key 的处理函数。关于 key 的可能值，请参见 get_content()。

add_set_handler(typekey, handler)

将 handler 记录为当匹配 typekey 类型的对象被传递给 set_content() 时要调用的函数。关于 typekey 的可能值，请参见 set_content()。

内容管理器实例

目前，email 包仅提供一个具体的内容管理器 raw_data_manager，但将来可能会添加更多。raw_data_manager 是 EmailPolicy 及其派生类提供的 content_manager。

email.contentmanager.raw_data_manager

此内容管理器仅在 Message 本身提供的功能之上提供了一个最小接口：它只处理文本、原始字节串和 Message 对象。尽管如此，与基本 API 相比，它提供了显著的优势：对文本部分调用 get_content 将返回一个 Unicode 字符串，应用程序无需手动解码；set_content 提供了一组丰富的选项，用于控制添加到部件的标头和内容传输编码；它还支持使用各种 add_ 方法，从而简化了多部件消息的创建。

email.contentmanager.get_content(msg, errors='replace')

将部件的有效载荷作为字符串（对于 text 部件）、EmailMessage 对象（对于 message/rfc822 部件）或 bytes 对象（对于所有其他非 multipart 类型）返回。如果在 multipart 上调用，则引发 KeyError。如果部件是 text 类型且指定了 errors，则在将有效载荷解码为 Unicode 时使用它作为错误处理程序。默认的错误处理程序是 replace。

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

向 msg 添加标头和有效载荷：

添加一个值为 maintype/subtype 的 Content-Type 标头。

  • 对于 str，将 MIME maintype 设为 text，如果指定了 subtype，则将其设为 subtype，否则设为 plain。

  • 对于 bytes，使用指定的 maintype 和 subtype，如果未指定，则引发 TypeError。

  • 对于 EmailMessage 对象，将 maintype 设为 message，如果指定了 subtype 则设为 subtype，否则设为 rfc822。如果 subtype 为 partial，则引发错误（必须使用 bytes 对象来构造 message/partial 部件）。

如果提供了 charset（仅对 str 有效），则使用指定的字符集将字符串编码为字节。默认值为 utf-8。如果指定的 charset 是标准 MIME 字符集名称的已知别名，则使用标准字符集。

如果设置了 cte，则使用指定的内容传输编码对有效载荷进行编码，并将 Content-Transfer-Encoding 标头设置为该值。cte 的可能值为 quoted-printable、base64、7bit、8bit 和 binary。如果输入无法使用指定的编码进行编码（例如，为包含非 ASCII 值的输入指定 cte 为 7bit），则引发 ValueError。

  • 对于 str 对象，如果未设置 cte，则使用启发式方法确定最紧凑的编码。在编码之前，会使用 str.splitlines() 来规范化所有行边界，确保有效载荷的每一行都以当前策略的 linesep 属性结尾（即使原始字符串不是以换行符结尾）。

  • 对于 bytes 对象，如果未设置，cte 将默认为 base64，并且不执行上述的换行符转换。

  • 对于 EmailMessage，根据 RFC 2046，如果为 subtype rfc822 请求了 quoted-printable 或 base64 的 cte，或者为 subtype external-body 请求了除 7bit 之外的任何 cte，则会引发错误。对于 message/rfc822，如果未指定 cte，则使用 8bit。对于所有其他 subtype 值，使用 7bit。

备注

binary 的 cte 尚未能正确工作。经 set_content 修改后的 EmailMessage 对象是正确的，但 BytesGenerator 无法正确地序列化它。

如果设置了 disposition，则将其用作 Content-Disposition 标头的值。如果未指定但指定了 filename，则添加值为 attachment 的该标头。如果 disposition 和 filename 均未指定，则不添加该标头。disposition 的唯一有效值为 attachment 和 inline。

如果指定了 filename，则将其用作 Content-Disposition 标头的 filename 参数值。

如果指定了 cid，则添加一个 Content-ID 标头，其值为 cid。

如果指定了 params，则迭代其 items 方法，并使用生成的 (key, value) 对在 Content-Type 标头上设置附加参数。

如果指定了 headers，并且它是一个形如 headername: headervalue 的字符串列表，或者是一个 header 对象列表（通过具有 name 属性与字符串区分），则将这些标头添加到 msg。

脚注