# `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()`。

## 内容管理器实例

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 中作为 暂定模块 添加