Skip to main content

19.1.7. email.contentmanager:管理MIME内容

源代码: Lib/email/contentmanager.py


3.6 新版功能: [1]

class email.contentmanager.ContentManager

内容管理器的基类。提供标准注册机制,以在MIME内容和其他表示之间注册转换器,以及 get_contentset_content 分派方法。

get_content(msg, *args, **kw)

查找基于 msgmimetype 的处理函数(参见下一段),调用它,传递所有参数,并返回调用的结果。期望的是,处理程序将从 msg 提取有效载荷,并返回编码关于提取的数据的信息的对象。

要找到处理程序,在注册表中查找以下键,停止与找到的第一个:

  • 表示完整MIME类型(maintype/subtype)的字符串

  • 表示 maintype 的字符串

  • 空字符串

如果这些键都不产生处理程序,请为完整的MIME类型提出 KeyError

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

如果 maintypemultipart,提出 TypeError;否则查找基于 obj 类型的处理函数(请参见下一段),在 msg 上调用 clear_content(),并调用处理函数,传递所有参数。期望处理程序将转换并将 obj 存储到 msg 中,可能对 msg 进行其他更改,例如添加各种MIME头以编码解释存储的数据所需的信息。

要找到处理程序,获取 objtyp = type(obj))的类型,并在注册表中查找以下键,停止与找到的第一个:

  • 类型本身(typ

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

  • 类型的名称(typ.__qualname__

  • 类型名称(typ.__name__)。

如果以上没有匹配,请重复上述对 MROtyp.__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()

19.1.7.1. 内容管理器实例

目前,电子邮件包只提供一个具体的内容管理器 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)
email.contentmanager.set_content(msg, <'list'>, subtype='mixed', disposition=None, filename=None, cid=None, params=None, headers=None)

msg 添加标题和有效内容:

添加具有 maintype/subtype 值的 Content-Type 头。

  • 对于 str,将MIME maintype 设置为 text,并将子类型设置为 subtype (如果指定)或 plain (如果不是)。

  • 对于 bytes,使用指定的 maintypesubtype,如果没有指定,则提出 TypeError

  • 对于 EmailMessage 对象,将主类型设置为 message,并将子类型设置为 subtype (如果已指定)或 rfc822 (如果未指定)。如果 subtypepartial,则引发错误(必须使用 bytes 对象来构造 message/partial 部件)。

  • 对于 <’list’>,其应该是 EmailMessage 对象的列表,将 maintype 设置为 multipart,并且如果指定,则将 subtype 设置为 subtype,如果不指定,则将 mixed 设置为 subtype。如果 <’list’> 中的消息部分有 MIME-Version 头,请删除它们。

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

如果设置了 cte,则使用指定的内容传输编码对有效载荷进行编码,并将 Content-Transfer-Endcoding 头设置为该值。 cte 的可能值是 quoted-printablebase647bit8bitbinary。如果输入不能以指定的编码进行编码(例如,为包含非ASCII值的输入指定 7bitcte),请提高 ValueError

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

  • 对于 EmailMessage,根据 RFC 2046,如果针对 subtype rfc822 请求 quoted-printablebase64cte,并且对于 subtype external-body 请求除 7bit 之外的任何 cte,则对于 EmailMessage,引起错误。对于 message/rfc822,如果未指定 cte,请使用 8bit。对于 subtype 的所有其他值,使用 7bit

注解

binarycte 实际上还不能正常工作。由 set_content 修改的 EmailMessage 对象是正确的,但 BytesGenerator 不能正确地序列化它。

如果设置了 disposition,则将其用作 Content-Disposition 头的值。如果未指定,并且指定了 filename,请添加值为 attachment 的头。如果未指定 disposition 且未指定 filename,请不要添加标题。 disposition 的唯一有效值是 attachmentinline

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

如果指定了 cid,请添加一个以 cid 作为其值的 Content-ID 头。

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

如果指定 headers 并且是 headername: headervalue 形式的字符串列表或 header 对象列表(通过具有 name 属性来区别于字符串),则将标题添加到 msg

脚注

[1]

最初添加在3.4作为 临时模块