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 是 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 类型）。如果在 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，否则设置为 plain。

  • 对于 bytes，请使用指定的 maintype 和 subtype，如果没有指定，则引发 TypeError 异常。

  • 对于 EmailMessage 对象，将 maintype 设置为 message，如果指定了子类型，则将其设置为 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，则使用启发式方法来确定最紧凑的编码。

  • 对于 EmailMessage，根据 RFC 2046，如果请求将 cte 设置为 quoted-printable 或 base64 且 subtype 为 rfc822，则引发错误；对于 subtype 为 external-body，如果 cte 不是 7bit，则引发错误。对于 message/rfc822，如果未指定 cte，则使用 8bit。对于 subtype 的所有其他值，请使用 7bit。

注意

cte 为 binary 实际上尚未正确工作。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。

脚注