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 标头来编码需要用来解释所存储数据的信息。

要找到处理程序,将获取 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()

内容管理器实例

Currently the email package provides only one concrete content manager, raw_data_manager, although more may be added in the future. raw_data_manager is the content_manager provided by EmailPolicy and its derivatives.

email.contentmanager.raw_data_manager

This content manager provides only a minimum interface beyond that provided by Message itself: it deals only with text, raw byte strings, and Message objects. Nevertheless, it provides significant advantages compared to the base API: get_content on a text part will return a unicode string without the application needing to manually decode it, set_content provides a rich set of options for controlling the headers added to a part and controlling the content transfer encoding, and it enables the use of the various add_ methods, thereby simplifying the creation of multipart messages.

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

Return the payload of the part as either a string (for text parts), an EmailMessage object (for message/rfc822 parts), or a bytes object (for all other non-multipart types). Raise a KeyError if called on a multipart. If the part is a text part and errors is specified, use it as the error handler when decoding the payload to unicode. The default error handler is 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)

Add headers and payload to msg:

Add a Content-Type header with a maintype/subtype value.

  • For str, set the MIME maintype to text, and set the subtype to subtype if it is specified, or plain if it is not.

  • For bytes, use the specified maintype and subtype, or raise a TypeError if they are not specified.

  • For EmailMessage objects, set the maintype to message, and set the subtype to subtype if it is specified or rfc822 if it is not. If subtype is partial, raise an error (bytes objects must be used to construct message/partial parts).

If charset is provided (which is valid only for str), encode the string to bytes using the specified character set. The default is utf-8. If the specified charset is a known alias for a standard MIME charset name, use the standard charset instead.

If cte is set, encode the payload using the specified content transfer encoding, and set the Content-Transfer-Encoding header to that value. Possible values for cte are quoted-printable, base64, 7bit, 8bit, and binary. If the input cannot be encoded in the specified encoding (for example, specifying a cte of 7bit for an input that contains non-ASCII values), raise a ValueError.

  • For str objects, if cte is not set use heuristics to determine the most compact encoding.

  • For EmailMessage, per RFC 2046, raise an error if a cte of quoted-printable or base64 is requested for subtype rfc822, and for any cte other than 7bit for subtype external-body. For message/rfc822, use 8bit if cte is not specified. For all other values of subtype, use 7bit.

備註

A cte of binary does not actually work correctly yet. The EmailMessage object as modified by set_content is correct, but BytesGenerator does not serialize it correctly.

If disposition is set, use it as the value of the Content-Disposition header. If not specified, and filename is specified, add the header with the value attachment. If disposition is not specified and filename is also not specified, do not add the header. The only valid values for disposition are attachment and inline.

If filename is specified, use it as the value of the filename parameter of the Content-Disposition header.

If cid is specified, add a Content-ID header with cid as its value.

If params is specified, iterate its items method and use the resulting (key, value) pairs to set additional parameters on the Content-Type header.

If headers is specified and is a list of strings of the form headername: headervalue or a list of header objects (distinguished from strings by having a name attribute), add the headers to msg.

备注

1

最初在 3.4 中作为 暂定模块 添加