ꦫꦣꦺꦤ꧀ꦄꦤ꧀ꦠꦱꦺꦤ

PATH: usr / share / doc / python3-docs / html / _sources / library

:mod:`email.contentmanager`: Managing MIME Content
--------------------------------------------------

.. module:: email.contentmanager
   :synopsis: Storing and Retrieving Content from MIME Parts

.. moduleauthor:: R. David Murray <rdmurray@bitdance.com>
.. sectionauthor:: R. David Murray <rdmurray@bitdance.com>

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

------------

.. versionadded:: 3.6 [1]_

.. class:: 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.

.. method:: 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 :exc:`KeyError` for the
      full MIME type.

.. method:: set_content(msg, obj, *args, **kw)

If the ``maintype`` is ``multipart``, raise a :exc:`TypeError`; otherwise
      look up a handler function based on the type of *obj* (see next
      paragraph), call :meth:`~email.message.EmailMessage.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 :term:`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 :exc:`KeyError` for the fully
      qualified name of the type.

Also add a :mailheader:`MIME-Version` header if one is not present (see
      also :class:`.MIMEPart`).

.. method:: add_get_handler(key, handler)

Record the function *handler* as the handler for *key*.  For the possible
      values of *key*, see :meth:`get_content`.

.. method:: add_set_handler(typekey, handler)

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

Content Manager Instances
~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. data:: raw_data_manager

This content manager provides only a minimum interface beyond that provided
   by :class:`~email.message.Message` itself:  it deals only with text, raw
   byte strings, and :class:`~email.message.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.

.. method:: get_content(msg, errors='replace')

Return the payload of the part as either a string (for ``text`` parts), an
      :class:`~email.message.EmailMessage` object (for ``message/rfc822``
      parts), or a ``bytes`` object (for all other non-multipart types).  Raise
      a :exc:`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``.

.. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8' \
                           cte=None, \
                           disposition=None, filename=None, cid=None, \
                           params=None, headers=None)
               set_content(msg, <'bytes'>, maintype, subtype, cte="base64", \
                           disposition=None, filename=None, cid=None, \
                           params=None, headers=None)
               set_content(msg, <'EmailMessage'>, cte=None, \
                           disposition=None, filename=None, cid=None, \
                           params=None, headers=None)

Add headers and payload to *msg*:

Add a :mailheader:`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 :exc:`TypeError` if they are not specified.
           * For :class:`~email.message.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 :mailheader:`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
       :exc:`ValueError`.

* For ``str`` objects, if *cte* is not set use heuristics to
              determine the most compact encoding.
            * For :class:`~email.message.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``.

.. note:: A *cte* of ``binary`` does not actually work correctly yet.
          The ``EmailMessage`` object as modified by ``set_content`` is
          correct, but :class:`~email.generator.BytesGenerator` does not
          serialize it correctly.

If *disposition* is set, use it as the value of the
       :mailheader:`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 :mailheader:`Content-Disposition` header.

If *cid* is specified, add a :mailheader:`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
       :mailheader:`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*.

.. rubric:: Footnotes

.. [1] Originally added in 3.4 as a :term:`provisional module <provisional
       package>`

[+] ..
[-] crypt.rst.txt [edit]
[-] logging.handlers.rst.txt [edit]
[-] __main__.rst.txt [edit]
[-] pty.rst.txt [edit]
[-] email.rst.txt [edit]
[-] traceback.rst.txt [edit]
[-] fileinput.rst.txt [edit]
[-] xml.sax.reader.rst.txt [edit]
[-] curses.rst.txt [edit]
[-] copy.rst.txt [edit]
[-] aifc.rst.txt [edit]
[-] xmlrpc.client.rst.txt [edit]
[-] pydoc.rst.txt [edit]
[-] asyncio-eventloops.rst.txt [edit]
[-] uuid.rst.txt [edit]
[-] functional.rst.txt [edit]
[-] posix.rst.txt [edit]
[-] hashlib.rst.txt [edit]
[-] cmd.rst.txt [edit]
[-] nntplib.rst.txt [edit]
[-] python.rst.txt [edit]
[-] types.rst.txt [edit]
[-] exceptions.rst.txt [edit]
[-] tracemalloc.rst.txt [edit]
[-] othergui.rst.txt [edit]
[-] xml.dom.pulldom.rst.txt [edit]
[-] inspect.rst.txt [edit]
[-] asyncio-stream.rst.txt [edit]
[-] i18n.rst.txt [edit]
[-] concurrent.rst.txt [edit]
[-] imghdr.rst.txt [edit]
[-] spwd.rst.txt [edit]
[-] os.path.rst.txt [edit]
[-] email.message.rst.txt [edit]
[-] random.rst.txt [edit]
[-] fileformats.rst.txt [edit]
[-] faulthandler.rst.txt [edit]
[-] parser.rst.txt [edit]
[-] stat.rst.txt [edit]
[-] code.rst.txt [edit]
[-] email.headerregistry.rst.txt [edit]
[-] timeit.rst.txt [edit]
[-] optparse.rst.txt [edit]
[-] smtplib.rst.txt [edit]
[-] filesys.rst.txt [edit]
[-] email.mime.rst.txt [edit]
[-] itertools.rst.txt [edit]
[-] sys.rst.txt [edit]
[-] bdb.rst.txt [edit]
[-] stringprep.rst.txt [edit]
[-] asyncio-subprocess.rst.txt [edit]
[-] decimal.rst.txt [edit]
[-] unicodedata.rst.txt [edit]
[-] intro.rst.txt [edit]
[-] constants.rst.txt [edit]
[-] xmlrpc.rst.txt [edit]
[-] grp.rst.txt [edit]
[-] pickle.rst.txt [edit]
[-] mmap.rst.txt [edit]
[-] debug.rst.txt [edit]
[-] unittest.mock-examples.rst.txt [edit]
[-] undoc.rst.txt [edit]
[-] functools.rst.txt [edit]
[-] ssl.rst.txt [edit]
[-] locale.rst.txt [edit]
[-] secrets.rst.txt [edit]
[-] pprint.rst.txt [edit]
[-] email.header.rst.txt [edit]
[-] email.contentmanager.rst.txt [edit]
[-] _thread.rst.txt [edit]
[-] errno.rst.txt [edit]
[-] sunau.rst.txt [edit]
[-] syslog.rst.txt [edit]
[-] tkinter.ttk.rst.txt [edit]
[-] distribution.rst.txt [edit]
[-] pdb.rst.txt [edit]
[-] distutils.rst.txt [edit]
[-] dummy_threading.rst.txt [edit]
[-] text.rst.txt [edit]
[-] socketserver.rst.txt [edit]
[-] _dummy_thread.rst.txt [edit]
[-] persistence.rst.txt [edit]
[-] asyncio-eventloop.rst.txt [edit]
[-] collections.abc.rst.txt [edit]
[-] fnmatch.rst.txt [edit]
[-] quopri.rst.txt [edit]
[-] http.server.rst.txt [edit]
[-] keyword.rst.txt [edit]
[-] xml.dom.rst.txt [edit]
[-] cgi.rst.txt [edit]
[-] heapq.rst.txt [edit]
[-] email.iterators.rst.txt [edit]
[-] io.rst.txt [edit]
[-] curses.panel.rst.txt [edit]
[-] winreg.rst.txt [edit]
[-] urllib.parse.rst.txt [edit]
[-] unix.rst.txt [edit]
[-] getpass.rst.txt [edit]
[-] sched.rst.txt [edit]
[-] socket.rst.txt [edit]
[-] pipes.rst.txt [edit]
[-] email.compat32-message.rst.txt [edit]
[-] asyncio-sync.rst.txt [edit]
[-] modulefinder.rst.txt [edit]
[-] html.entities.rst.txt [edit]
[-] ctypes.rst.txt [edit]
[-] pyexpat.rst.txt [edit]
[-] pyclbr.rst.txt [edit]
[-] html.rst.txt [edit]
[-] test.rst.txt [edit]
[-] markup.rst.txt [edit]
[-] doctest.rst.txt [edit]
[-] csv.rst.txt [edit]
[-] colorsys.rst.txt [edit]
[-] xml.sax.rst.txt [edit]
[-] zlib.rst.txt [edit]
[-] subprocess.rst.txt [edit]
[-] base64.rst.txt [edit]
[-] platform.rst.txt [edit]
[-] binascii.rst.txt [edit]
[-] http.rst.txt [edit]
[-] nis.rst.txt [edit]
[-] statistics.rst.txt [edit]
[-] sqlite3.rst.txt [edit]
[-] json.rst.txt [edit]
[-] gzip.rst.txt [edit]
[-] netdata.rst.txt [edit]
[-] pkgutil.rst.txt [edit]
[-] linecache.rst.txt [edit]
[-] cgitb.rst.txt [edit]
[-] archiving.rst.txt [edit]
[-] argparse.rst.txt [edit]
[-] wsgiref.rst.txt [edit]
[-] tokenize.rst.txt [edit]
[-] mm.rst.txt [edit]
[-] telnetlib.rst.txt [edit]
[-] ossaudiodev.rst.txt [edit]
[-] tk.rst.txt [edit]
[-] string.rst.txt [edit]
[-] misc.rst.txt [edit]
[-] marshal.rst.txt [edit]
[-] email.encoders.rst.txt [edit]
[-] array.rst.txt [edit]
[-] queue.rst.txt [edit]
[-] copyreg.rst.txt [edit]
[-] atexit.rst.txt [edit]
[-] signal.rst.txt [edit]
[-] collections.rst.txt [edit]
[-] tkinter.scrolledtext.rst.txt [edit]
[-] tempfile.rst.txt [edit]
[-] codeop.rst.txt [edit]
[-] threading.rst.txt [edit]
[-] enum.rst.txt [edit]
[-] imp.rst.txt [edit]
[-] crypto.rst.txt [edit]
[-] bisect.rst.txt [edit]
[-] dbm.rst.txt [edit]
[-] formatter.rst.txt [edit]
[-] language.rst.txt [edit]
[-] trace.rst.txt [edit]
[-] tkinter.tix.rst.txt [edit]
[-] smtpd.rst.txt [edit]
[-] asyncio-task.rst.txt [edit]
[-] abc.rst.txt [edit]
[-] gettext.rst.txt [edit]
[-] concurrency.rst.txt [edit]
[-] allos.rst.txt [edit]
[-] xml.sax.utils.rst.txt [edit]
[-] tty.rst.txt [edit]
[-] mailcap.rst.txt [edit]
[-] msvcrt.rst.txt [edit]
[-] reprlib.rst.txt [edit]
[-] development.rst.txt [edit]
[-] contextlib.rst.txt [edit]
[-] configparser.rst.txt [edit]
[-] symbol.rst.txt [edit]
[-] shlex.rst.txt [edit]
[-] tabnanny.rst.txt [edit]
[-] asyncio-dev.rst.txt [edit]
[-] py_compile.rst.txt [edit]
[-] uu.rst.txt [edit]
[-] logging.rst.txt [edit]
[-] runpy.rst.txt [edit]
[-] pathlib.rst.txt [edit]
[-] os.rst.txt [edit]
[-] urllib.request.rst.txt [edit]
[-] html.parser.rst.txt [edit]
[-] bz2.rst.txt [edit]
[-] binhex.rst.txt [edit]
[-] time.rst.txt [edit]
[-] zipapp.rst.txt [edit]
[-] fcntl.rst.txt [edit]
[-] tkinter.rst.txt [edit]
[-] glob.rst.txt [edit]
[-] email.policy.rst.txt [edit]
[-] pwd.rst.txt [edit]
[-] numeric.rst.txt [edit]
[-] winsound.rst.txt [edit]
[-] urllib.robotparser.rst.txt [edit]
[-] selectors.rst.txt [edit]
[-] xdrlib.rst.txt [edit]
[-] webbrowser.rst.txt [edit]
[-] zipfile.rst.txt [edit]
[-] ipc.rst.txt [edit]
[-] mailbox.rst.txt [edit]
[-] plistlib.rst.txt [edit]
[-] getopt.rst.txt [edit]
[-] concurrent.futures.rst.txt [edit]
[-] symtable.rst.txt [edit]
[-] rlcompleter.rst.txt [edit]
[-] __future__.rst.txt [edit]
[-] asynchat.rst.txt [edit]
[-] audioop.rst.txt [edit]
[-] compileall.rst.txt [edit]
[-] unittest.mock.rst.txt [edit]
[-] dis.rst.txt [edit]
[-] index.rst.txt [edit]
[-] logging.config.rst.txt [edit]
[-] gc.rst.txt [edit]
[-] shutil.rst.txt [edit]
[-] sndhdr.rst.txt [edit]
[-] ipaddress.rst.txt [edit]
[-] asyncio-queue.rst.txt [edit]
[-] curses.ascii.rst.txt [edit]
[-] builtins.rst.txt [edit]
[-] calendar.rst.txt [edit]
[-] sysconfig.rst.txt [edit]
[-] token.rst.txt [edit]
[-] xml.dom.minidom.rst.txt [edit]
[-] textwrap.rst.txt [edit]
[-] importlib.rst.txt [edit]
[-] fpectl.rst.txt [edit]
[-] mimetypes.rst.txt [edit]
[-] netrc.rst.txt [edit]
[-] fractions.rst.txt [edit]
[-] select.rst.txt [edit]
[-] lzma.rst.txt [edit]
[-] math.rst.txt [edit]
[-] frameworks.rst.txt [edit]
[-] ftplib.rst.txt [edit]
[-] macpath.rst.txt [edit]
[-] numbers.rst.txt [edit]
[-] xml.etree.elementtree.rst.txt [edit]
[-] pickletools.rst.txt [edit]
[-] asyncore.rst.txt [edit]
[-] warnings.rst.txt [edit]
[-] resource.rst.txt [edit]
[-] unittest.rst.txt [edit]
[-] datetime.rst.txt [edit]
[-] asyncio-protocol.rst.txt [edit]
[-] urllib.rst.txt [edit]
[-] superseded.rst.txt [edit]
[-] email.generator.rst.txt [edit]
[-] ensurepip.rst.txt [edit]
[-] ast.rst.txt [edit]
[-] modules.rst.txt [edit]
[-] venv.rst.txt [edit]
[-] internet.rst.txt [edit]
[-] chunk.rst.txt [edit]
[-] asyncio.rst.txt [edit]
[-] turtle.rst.txt [edit]
[-] struct.rst.txt [edit]
[-] profile.rst.txt [edit]
[-] urllib.error.rst.txt [edit]
[-] http.cookiejar.rst.txt [edit]
[-] tarfile.rst.txt [edit]
[-] http.cookies.rst.txt [edit]
[-] multiprocessing.rst.txt [edit]
[-] msilib.rst.txt [edit]
[-] xmlrpc.server.rst.txt [edit]
[-] termios.rst.txt [edit]
[-] 2to3.rst.txt [edit]
[-] windows.rst.txt [edit]
[-] email.examples.rst.txt [edit]
[-] readline.rst.txt [edit]
[-] binary.rst.txt [edit]
[-] shelve.rst.txt [edit]
[-] re.rst.txt [edit]
[-] xml.sax.handler.rst.txt [edit]
[-] hmac.rst.txt [edit]
[-] datatypes.rst.txt [edit]
[-] typing.rst.txt [edit]
[-] custominterp.rst.txt [edit]
[-] email.charset.rst.txt [edit]
[-] email.util.rst.txt [edit]
[-] zipimport.rst.txt [edit]
[-] cmath.rst.txt [edit]
[-] idle.rst.txt [edit]
[-] operator.rst.txt [edit]
[-] site.rst.txt [edit]
[-] email.parser.rst.txt [edit]
[-] functions.rst.txt [edit]
[-] poplib.rst.txt [edit]
[-] filecmp.rst.txt [edit]
[-] codecs.rst.txt [edit]
[-] imaplib.rst.txt [edit]
[-] stdtypes.rst.txt [edit]
[-] difflib.rst.txt [edit]
[-] weakref.rst.txt [edit]
[-] http.client.rst.txt [edit]
[-] email.errors.rst.txt [edit]
[-] xml.rst.txt [edit]
[-] wave.rst.txt [edit]