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@bitdance.com> 8.. sectionauthor:: R. David Murray <rdmurray@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 87Content Manager Instances 88~~~~~~~~~~~~~~~~~~~~~~~~~ 89 90Currently 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 130 Add headers and payload to *msg*: 131 132 Add a :mailheader:`Content-Type` header with a ``maintype/subtype`` 133 value. 134 135 * For ``str``, set the MIME ``maintype`` to ``text``, and set the 136 subtype to *subtype* if it is specified, or ``plain`` if it is not. 137 * For ``bytes``, use the specified *maintype* and *subtype*, or 138 raise a :exc:`TypeError` if they are not specified. 139 * For :class:`~email.message.EmailMessage` objects, set the maintype 140 to ``message``, and set the subtype to *subtype* if it is 141 specified or ``rfc822`` if it is not. If *subtype* is 142 ``partial``, raise an error (``bytes`` objects must be used to 143 construct ``message/partial`` parts). 144 145 If *charset* is provided (which is valid only for ``str``), encode the 146 string to bytes using the specified character set. The default is 147 ``utf-8``. If the specified *charset* is a known alias for a standard 148 MIME charset name, use the standard charset instead. 149 150 If *cte* is set, encode the payload using the specified content transfer 151 encoding, and set the :mailheader:`Content-Transfer-Encoding` header to 152 that value. Possible values for *cte* are ``quoted-printable``, 153 ``base64``, ``7bit``, ``8bit``, and ``binary``. If the input cannot be 154 encoded in the specified encoding (for example, specifying a *cte* of 155 ``7bit`` for an input that contains non-ASCII values), raise a 156 :exc:`ValueError`. 157 158 * For ``str`` objects, if *cte* is not set use heuristics to 159 determine the most compact encoding. 160 * For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise 161 an error if a *cte* of ``quoted-printable`` or ``base64`` is 162 requested for *subtype* ``rfc822``, and for any *cte* other than 163 ``7bit`` for *subtype* ``external-body``. For 164 ``message/rfc822``, use ``8bit`` if *cte* is not specified. For 165 all other values of *subtype*, use ``7bit``. 166 167 .. note:: A *cte* of ``binary`` does not actually work correctly yet. 168 The ``EmailMessage`` object as modified by ``set_content`` is 169 correct, but :class:`~email.generator.BytesGenerator` does not 170 serialize it correctly. 171 172 If *disposition* is set, use it as the value of the 173 :mailheader:`Content-Disposition` header. If not specified, and 174 *filename* is specified, add the header with the value ``attachment``. 175 If *disposition* is not specified and *filename* is also not specified, 176 do not add the header. The only valid values for *disposition* are 177 ``attachment`` and ``inline``. 178 179 If *filename* is specified, use it as the value of the ``filename`` 180 parameter of the :mailheader:`Content-Disposition` header. 181 182 If *cid* is specified, add a :mailheader:`Content-ID` header with 183 *cid* as its value. 184 185 If *params* is specified, iterate its ``items`` method and use the 186 resulting ``(key, value)`` pairs to set additional parameters on the 187 :mailheader:`Content-Type` header. 188 189 If *headers* is specified and is a list of strings of the form 190 ``headername: headervalue`` or a list of ``header`` objects 191 (distinguished from strings by having a ``name`` attribute), add the 192 headers to *msg*. 193 194 195.. rubric:: Footnotes 196 197.. [1] Originally added in 3.4 as a :term:`provisional module <provisional 198 package>` 199