Debian Codegraph @

Doc/library/email.contentmanager.rst

raw
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>`