| 1 |
:mod:`!email.contentmanager`: Managing MIME Content |
| 2 |
--------------------------------------------------- |
| 3 |
|
| 4 |
.. module:: email.contentmanager |
| 5 |
:synopsis: Storing and Retrieving Content from MIME Parts |
| 6 |
|
| 7 |
.. moduleauthor:: R. David Murray <[email protected]> |
| 8 |
.. sectionauthor:: R. David Murray <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/email/contentmanager.py` |
| 11 |
|
| 12 |
------------ |
| 13 |
|
| 14 |
.. versionadded:: 3.6 [1]_ |
| 15 |
|
| 16 |
|
| 17 |
.. class:: ContentManager() |
| 18 |
|
| 19 |
Base class for content managers. Provides the standard registry mechanisms |
| 20 |
to register converters between MIME content and other representations, as |
| 21 |
well as the ``get_content`` and ``set_content`` dispatch methods. |
| 22 |
|
| 23 |
|
| 24 |
.. method:: get_content(msg, *args, **kw) |
| 25 |
|
| 26 |
Look up a handler function based on the ``mimetype`` of *msg* (see next |
| 27 |
paragraph), call it, passing through all arguments, and return the result |
| 28 |
of the call. The expectation is that the handler will extract the |
| 29 |
payload from *msg* and return an object that encodes information about |
| 30 |
the extracted data. |
| 31 |
|
| 32 |
To find the handler, look for the following keys in the registry, |
| 33 |
stopping with the first one found: |
| 34 |
|
| 35 |
* the string representing the full MIME type (``maintype/subtype``) |
| 36 |
* the string representing the ``maintype`` |
| 37 |
* the empty string |
| 38 |
|
| 39 |
If none of these keys produce a handler, raise a :exc:`KeyError` for the |
| 40 |
full MIME type. |
| 41 |
|
| 42 |
|
| 43 |
.. method:: set_content(msg, obj, *args, **kw) |
| 44 |
|
| 45 |
If the ``maintype`` is ``multipart``, raise a :exc:`TypeError`; otherwise |
| 46 |
look up a handler function based on the type of *obj* (see next |
| 47 |
paragraph), call :meth:`~email.message.EmailMessage.clear_content` on the |
| 48 |
*msg*, and call the handler function, passing through all arguments. The |
| 49 |
expectation is that the handler will transform and store *obj* into |
| 50 |
*msg*, possibly making other changes to *msg* as well, such as adding |
| 51 |
various MIME headers to encode information needed to interpret the stored |
| 52 |
data. |
| 53 |
|
| 54 |
To find the handler, obtain the type of *obj* (``typ = type(obj)``), and |
| 55 |
look for the following keys in the registry, stopping with the first one |
| 56 |
found: |
| 57 |
|
| 58 |
* the type itself (``typ``) |
| 59 |
* the type's fully qualified name (``typ.__module__ + '.' + |
| 60 |
typ.__qualname__``). |
| 61 |
* the type's :attr:`qualname <type.__qualname__>` (``typ.__qualname__``) |
| 62 |
* the type's :attr:`name <type.__name__>` (``typ.__name__``). |
| 63 |
|
| 64 |
If none of the above match, repeat all of the checks above for each of |
| 65 |
the types in the :term:`MRO` (:attr:`typ.__mro__ <type.__mro__>`). |
| 66 |
Finally, if no other key |
| 67 |
yields a handler, check for a handler for the key ``None``. If there is |
| 68 |
no handler for ``None``, raise a :exc:`KeyError` for the fully |
| 69 |
qualified name of the type. |
| 70 |
|
| 71 |
Also add a :mailheader:`MIME-Version` header if one is not present (see |
| 72 |
also :class:`.MIMEPart`). |
| 73 |
|
| 74 |
|
| 75 |
.. method:: add_get_handler(key, handler) |
| 76 |
|
| 77 |
Record the function *handler* as the handler for *key*. For the possible |
| 78 |
values of *key*, see :meth:`get_content`. |
| 79 |
|
| 80 |
|
| 81 |
.. method:: add_set_handler(typekey, handler) |
| 82 |
|
| 83 |
Record *handler* as the function to call when an object of a type |
| 84 |
matching *typekey* is passed to :meth:`set_content`. For the possible |
| 85 |
values of *typekey*, see :meth:`set_content`. |
| 86 |
|
| 87 |
|
| 88 |
Content Manager Instances |
| 89 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 90 |
|
| 91 |
Currently the email package provides only one concrete content manager, |
| 92 |
:data:`raw_data_manager`, although more may be added in the future. |
| 93 |
:data:`raw_data_manager` is the |
| 94 |
:attr:`~email.policy.EmailPolicy.content_manager` provided by |
| 95 |
:attr:`~email.policy.EmailPolicy` and its derivatives. |
| 96 |
|
| 97 |
|
| 98 |
.. data:: raw_data_manager |
| 99 |
|
| 100 |
This content manager provides only a minimum interface beyond that provided |
| 101 |
by :class:`~email.message.Message` itself: it deals only with text, raw |
| 102 |
byte strings, and :class:`~email.message.Message` objects. Nevertheless, it |
| 103 |
provides significant advantages compared to the base API: ``get_content`` on |
| 104 |
a text part will return a unicode string without the application needing to |
| 105 |
manually decode it, ``set_content`` provides a rich set of options for |
| 106 |
controlling the headers added to a part and controlling the content transfer |
| 107 |
encoding, and it enables the use of the various ``add_`` methods, thereby |
| 108 |
simplifying the creation of multipart messages. |
| 109 |
|
| 110 |
.. method:: get_content(msg, errors='replace') |
| 111 |
|
| 112 |
Return the payload of the part as either a string (for ``text`` parts), an |
| 113 |
:class:`~email.message.EmailMessage` object (for ``message/rfc822`` |
| 114 |
parts), or a ``bytes`` object (for all other non-multipart types). Raise |
| 115 |
a :exc:`KeyError` if called on a ``multipart``. If the part is a |
| 116 |
``text`` part and *errors* is specified, use it as the error handler when |
| 117 |
decoding the payload to unicode. The default error handler is |
| 118 |
``replace``. |
| 119 |
|
| 120 |
.. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8', \ |
| 121 |
cte=None, \ |
| 122 |
disposition=None, filename=None, cid=None, \ |
| 123 |
params=None, headers=None) |
| 124 |
set_content(msg, <'bytes'>, maintype, subtype, cte="base64", \ |
| 125 |
disposition=None, filename=None, cid=None, \ |
| 126 |
params=None, headers=None) |
| 127 |
set_content(msg, <'EmailMessage'>, cte=None, \ |
| 128 |
disposition=None, filename=None, cid=None, \ |
| 129 |
params=None, headers=None) |
| 130 |
|
| 131 |
Add headers and payload to *msg*: |
| 132 |
|
| 133 |
Add a :mailheader:`Content-Type` header with a ``maintype/subtype`` |
| 134 |
value. |
| 135 |
|
| 136 |
* For ``str``, set the MIME ``maintype`` to ``text``, and set the |
| 137 |
subtype to *subtype* if it is specified, or ``plain`` if it is not. |
| 138 |
* For ``bytes``, use the specified *maintype* and *subtype*, or |
| 139 |
raise a :exc:`TypeError` if they are not specified. |
| 140 |
* For :class:`~email.message.EmailMessage` objects, set the maintype |
| 141 |
to ``message``, and set the subtype to *subtype* if it is |
| 142 |
specified or ``rfc822`` if it is not. If *subtype* is |
| 143 |
``partial``, raise an error (``bytes`` objects must be used to |
| 144 |
construct ``message/partial`` parts). |
| 145 |
|
| 146 |
If *charset* is provided (which is valid only for ``str``), encode the |
| 147 |
string to bytes using the specified character set. The default is |
| 148 |
``utf-8``. If the specified *charset* is a known alias for a standard |
| 149 |
MIME charset name, use the standard charset instead. |
| 150 |
|
| 151 |
If *cte* is set, encode the payload using the specified content transfer |
| 152 |
encoding, and set the :mailheader:`Content-Transfer-Encoding` header to |
| 153 |
that value. Possible values for *cte* are ``quoted-printable``, |
| 154 |
``base64``, ``7bit``, ``8bit``, and ``binary``. If the input cannot be |
| 155 |
encoded in the specified encoding (for example, specifying a *cte* of |
| 156 |
``7bit`` for an input that contains non-ASCII values), raise a |
| 157 |
:exc:`ValueError`. |
| 158 |
|
| 159 |
* For ``str`` objects, if *cte* is not set use heuristics to |
| 160 |
determine the most compact encoding. Prior to encoding, |
| 161 |
:meth:`str.splitlines` is used to normalize all line boundaries, |
| 162 |
ensuring that each line of the payload is terminated by the |
| 163 |
current policy's :data:`~email.policy.Policy.linesep` property |
| 164 |
(even if the original string did not end with one). |
| 165 |
* For ``bytes`` objects, *cte* is taken to be base64 if not set, |
| 166 |
and the aforementioned newline translation is not performed. |
| 167 |
* For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise |
| 168 |
an error if a *cte* of ``quoted-printable`` or ``base64`` is |
| 169 |
requested for *subtype* ``rfc822``, and for any *cte* other than |
| 170 |
``7bit`` for *subtype* ``external-body``. For |
| 171 |
``message/rfc822``, use ``8bit`` if *cte* is not specified. For |
| 172 |
all other values of *subtype*, use ``7bit``. |
| 173 |
|
| 174 |
.. note:: A *cte* of ``binary`` does not actually work correctly yet. |
| 175 |
The ``EmailMessage`` object as modified by ``set_content`` is |
| 176 |
correct, but :class:`~email.generator.BytesGenerator` does not |
| 177 |
serialize it correctly. |
| 178 |
|
| 179 |
If *disposition* is set, use it as the value of the |
| 180 |
:mailheader:`Content-Disposition` header. If not specified, and |
| 181 |
*filename* is specified, add the header with the value ``attachment``. |
| 182 |
If *disposition* is not specified and *filename* is also not specified, |
| 183 |
do not add the header. The only valid values for *disposition* are |
| 184 |
``attachment`` and ``inline``. |
| 185 |
|
| 186 |
If *filename* is specified, use it as the value of the ``filename`` |
| 187 |
parameter of the :mailheader:`Content-Disposition` header. |
| 188 |
|
| 189 |
If *cid* is specified, add a :mailheader:`Content-ID` header with |
| 190 |
*cid* as its value. |
| 191 |
|
| 192 |
If *params* is specified, iterate its ``items`` method and use the |
| 193 |
resulting ``(key, value)`` pairs to set additional parameters on the |
| 194 |
:mailheader:`Content-Type` header. |
| 195 |
|
| 196 |
If *headers* is specified and is a list of strings of the form |
| 197 |
``headername: headervalue`` or a list of ``header`` objects |
| 198 |
(distinguished from strings by having a ``name`` attribute), add the |
| 199 |
headers to *msg*. |
| 200 |
|
| 201 |
|
| 202 |
.. rubric:: Footnotes |
| 203 |
|
| 204 |
.. [1] Originally added in 3.4 as a :term:`provisional module <provisional |
| 205 |
package>` |