"email.contentmanager": Managing MIME Content
*********************************************

**Source code:** Lib/email/contentmanager.py

======================================================================

Added in version 3.6: [1]

class email.contentmanager.ContentManager

   Base class for content managers.  Provides the standard registry
   mechanisms to register converters between MIME content and other
   representations, as well as the "get_content" and "set_content"
   dispatch methods.

   get_content(msg, *args, **kw)

      Look up a handler function based on the "mimetype" of *msg* (see
      next paragraph), call it, passing through all arguments, and
      return the result of the call.  The expectation is that the
      handler will extract the payload from *msg* and return an object
      that encodes information about the extracted data.

      To find the handler, look for the following keys in the
      registry, stopping with the first one found:

      * the string representing the full MIME type
        ("maintype/subtype")

      * the string representing the "maintype"

      * the empty string

      If none of these keys produce a handler, raise a "KeyError" for
      the full MIME type.

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

      If the "maintype" is "multipart", raise a "TypeError"; otherwise
      look up a handler function based on the type of *obj* (see next
      paragraph), call "clear_content()" on the *msg*, and call the
      handler function, passing through all arguments.  The
      expectation is that the handler will transform and store *obj*
      into *msg*, possibly making other changes to *msg* as well, such
      as adding various MIME headers to encode information needed to
      interpret the stored data.

      To find the handler, obtain the type of *obj* ("typ =
      type(obj)"), and look for the following keys in the registry,
      stopping with the first one found:

      * the type itself ("typ")

      * the type's fully qualified name ("typ.__module__ + '.' +
        typ.__qualname__").

      * the type's "qualname" ("typ.__qualname__")

      * the type's "name" ("typ.__name__").

      If none of the above match, repeat all of the checks above for
      each of the types in the *MRO* ("typ.__mro__"). Finally, if no
      other key yields a handler, check for a handler for the key
      "None".  If there is no handler for "None", raise a "KeyError"
      for the fully qualified name of the type.

      Also add a *MIME-Version* header if one is not present (see also
      "MIMEPart").

   add_get_handler(key, handler)

      Record the function *handler* as the handler for *key*.  For the
      possible values of *key*, see "get_content()".

   add_set_handler(typekey, handler)

      Record *handler* as the function to call when an object of a
      type matching *typekey* is passed to "set_content()".  For the
      possible values of *typekey*, see "set_content()".


Content Manager Instances
=========================

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.  Prior to encoding,
        "str.splitlines()" is used to normalize all line boundaries,
        ensuring that each line of the payload is terminated by the
        current policy's "linesep" property (even if the original
        string did not end with one).

      * For "bytes" objects, *cte* is taken to be base64 if not set,
        and the aforementioned newline translation is not performed.

      * 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".

      Catatan:

        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*.

-[ Footnotes ]-

[1] Originally added in 3.4 as a *provisional module*
