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