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 <rdmurray (a] bitdance.com> 8 .. sectionauthor:: R. David Murray <rdmurray (a] bitdance.com> 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 qualname (``typ.__qualname__``) 62 * the type's 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` (``typ.__mro__``). Finally, if no other key 66 yields a handler, check for a handler for the key ``None``. If there is 67 no handler for ``None``, raise a :exc:`KeyError` for the fully 68 qualified name of the type. 69 70 Also add a :mailheader:`MIME-Version` header if one is not present (see 71 also :class:`.MIMEPart`). 72 73 74 .. method:: add_get_handler(key, handler) 75 76 Record the function *handler* as the handler for *key*. For the possible 77 values of *key*, see :meth:`get_content`. 78 79 80 .. method:: add_set_handler(typekey, handler) 81 82 Record *handler* as the function to call when an object of a type 83 matching *typekey* is passed to :meth:`set_content`. For the possible 84 values of *typekey*, see :meth:`set_content`. 85 86 87 Content Manager Instances 88 ~~~~~~~~~~~~~~~~~~~~~~~~~ 89 90 Currently the email package provides only one concrete content manager, 91 :data:`raw_data_manager`, although more may be added in the future. 92 :data:`raw_data_manager` is the 93 :attr:`~email.policy.EmailPolicy.content_manager` provided by 94 :attr:`~email.policy.EmailPolicy` and its derivatives. 95 96 97 .. data:: raw_data_manager 98 99 This content manager provides only a minimum interface beyond that provided 100 by :class:`~email.message.Message` itself: it deals only with text, raw 101 byte strings, and :class:`~email.message.Message` objects. Nevertheless, it 102 provides significant advantages compared to the base API: ``get_content`` on 103 a text part will return a unicode string without the application needing to 104 manually decode it, ``set_content`` provides a rich set of options for 105 controlling the headers added to a part and controlling the content transfer 106 encoding, and it enables the use of the various ``add_`` methods, thereby 107 simplifying the creation of multipart messages. 108 109 .. method:: get_content(msg, errors='replace') 110 111 Return the payload of the part as either a string (for ``text`` parts), an 112 :class:`~email.message.EmailMessage` object (for ``message/rfc822`` 113 parts), or a ``bytes`` object (for all other non-multipart types). Raise 114 a :exc:`KeyError` if called on a ``multipart``. If the part is a 115 ``text`` part and *errors* is specified, use it as the error handler when 116 decoding the payload to unicode. The default error handler is 117 ``replace``. 118 119 .. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8' \ 120 cte=None, \ 121 disposition=None, filename=None, cid=None, \ 122 params=None, headers=None) 123 set_content(msg, <'bytes'>, maintype, subtype, cte="base64", \ 124 disposition=None, filename=None, cid=None, \ 125 params=None, headers=None) 126 set_content(msg, <'EmailMessage'>, cte=None, \ 127 disposition=None, filename=None, cid=None, \ 128 params=None, headers=None) 129 set_content(msg, <'list'>, subtype='mixed', \ 130 disposition=None, filename=None, cid=None, \ 131 params=None, headers=None) 132 133 Add headers and payload to *msg*: 134 135 Add a :mailheader:`Content-Type` header with a ``maintype/subtype`` 136 value. 137 138 * For ``str``, set the MIME ``maintype`` to ``text``, and set the 139 subtype to *subtype* if it is specified, or ``plain`` if it is not. 140 * For ``bytes``, use the specified *maintype* and *subtype*, or 141 raise a :exc:`TypeError` if they are not specified. 142 * For :class:`~email.message.EmailMessage` objects, set the maintype 143 to ``message``, and set the subtype to *subtype* if it is 144 specified or ``rfc822`` if it is not. If *subtype* is 145 ``partial``, raise an error (``bytes`` objects must be used to 146 construct ``message/partial`` parts). 147 * For *<'list'>*, which should be a list of 148 :class:`~email.message.EmailMessage` objects, set the ``maintype`` 149 to ``multipart``, and the ``subtype`` to *subtype* if it is 150 specified, and ``mixed`` if it is not. If the message parts in 151 the *<'list'>* have :mailheader:`MIME-Version` headers, remove 152 them. 153 154 If *charset* is provided (which is valid only for ``str``), encode the 155 string to bytes using the specified character set. The default is 156 ``utf-8``. If the specified *charset* is a known alias for a standard 157 MIME charset name, use the standard charset instead. 158 159 If *cte* is set, encode the payload using the specified content transfer 160 encoding, and set the :mailheader:`Content-Transfer-Endcoding` header to 161 that value. Possible values for *cte* are ``quoted-printable``, 162 ``base64``, ``7bit``, ``8bit``, and ``binary``. If the input cannot be 163 encoded in the specified encoding (for example, specifying a *cte* of 164 ``7bit`` for an input that contains non-ASCII values), raise a 165 :exc:`ValueError`. 166 167 * For ``str`` objects, if *cte* is not set use heuristics to 168 determine the most compact encoding. 169 * For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise 170 an error if a *cte* of ``quoted-printable`` or ``base64`` is 171 requested for *subtype* ``rfc822``, and for any *cte* other than 172 ``7bit`` for *subtype* ``external-body``. For 173 ``message/rfc822``, use ``8bit`` if *cte* is not specified. For 174 all other values of *subtype*, use ``7bit``. 175 176 .. note:: A *cte* of ``binary`` does not actually work correctly yet. 177 The ``EmailMessage`` object as modified by ``set_content`` is 178 correct, but :class:`~email.generator.BytesGenerator` does not 179 serialize it correctly. 180 181 If *disposition* is set, use it as the value of the 182 :mailheader:`Content-Disposition` header. If not specified, and 183 *filename* is specified, add the header with the value ``attachment``. 184 If *disposition* is not specified and *filename* is also not specified, 185 do not add the header. The only valid values for *disposition* are 186 ``attachment`` and ``inline``. 187 188 If *filename* is specified, use it as the value of the ``filename`` 189 parameter of the :mailheader:`Content-Disposition` header. 190 191 If *cid* is specified, add a :mailheader:`Content-ID` header with 192 *cid* as its value. 193 194 If *params* is specified, iterate its ``items`` method and use the 195 resulting ``(key, value)`` pairs to set additional parameters on the 196 :mailheader:`Content-Type` header. 197 198 If *headers* is specified and is a list of strings of the form 199 ``headername: headervalue`` or a list of ``header`` objects 200 (distinguished from strings by having a ``name`` attribute), add the 201 headers to *msg*. 202 203 204 .. rubric:: Footnotes 205 206 .. [1] Oringally added in 3.4 as a :term:`provisional module <provisional 207 package>` 208
