mirror of
https://github.com/python/cpython.git
synced 2025-08-03 08:34:29 +00:00
29d1bc0842
This is a wholesale reorganization and editing of the email documentation to make the new API the standard one, and the old API the 'legacy' one. The default is still the compat32 policy, for backward compatibility. We will change that eventually.
203 lines
9.4 KiB
ReStructuredText
203 lines
9.4 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.4 as a :term:`provisional module <provisional package>`.
|
|
|
|
.. versionchanged:: 3.6 provisional status removed.
|
|
|
|
|
|
.. 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)
|
|
set_content(msg, <'list'>, subtype='mixed', \
|
|
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).
|
|
* For *<'list'>*, which should be a list of
|
|
:class:`~email.message.EmailMessage` objects, set the ``maintype``
|
|
to ``multipart``, and the ``subtype`` to *subtype* if it is
|
|
specified, and ``mixed`` if it is not. If the message parts in
|
|
the *<'list'>* have :mailheader:`MIME-Version` headers, remove
|
|
them.
|
|
|
|
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-Endcoding` 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*.
|