mirror of https://github.com/python/cpython
199 lines
8.8 KiB
ReStructuredText
199 lines
8.8 KiB
ReStructuredText
: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>`
|