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；否则，根据对象类型查找处理函数（见下一段），调用 clear_content() 对 msg，并调用处理函数，传递所有参数。预期处理函数将转换并存储 obj 到 msg，可能还会对 msg 进行其他更改，例如添加各种 MIME 头以对解释存储数据所需的信息进行编码。

要查找处理函数，获取 obj 的类型 (typ = type(obj))，并在注册表中查找以下键，从找到的第一个键停止

  • 类型本身 (typ)

  • 类型的完全限定名 (typ.__module__ + '.' + typ.__qualname__)。

  • 类型的限定名 (typ.__qualname__)

  • 类型的名称 (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()。

内容管理器实例

目前，电子邮件包仅提供一个具体的内容管理器，raw_data_manager，尽管未来可能会添加更多内容管理器。 raw_data_manager 是 content_manager，由 EmailPolicy 及其派生类提供。

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 上调用，则引发 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 值的输入指定 7bit 的 cte），则引发 ValueError。

  • 对于 str 对象，如果未设置 cte，则使用启发式方法确定最紧凑的编码。

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

注意

cte 的 binary 实际上尚未正常工作。EmailMessage 对象由 set_content 修改后是正确的，但 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。

脚注