blob: f685e540d242e29bed4b66e6544d4e21594cd59f [file] [log] [blame]
R David Murraye1398f72012-05-27 17:17:53 -04001:mod:`email.message`: Representing an email message
2---------------------------------------------------
Georg Brandl116aa622007-08-15 14:28:22 +00003
4.. module:: email.message
5 :synopsis: The base class representing email messages.
6
7
8The central class in the :mod:`email` package is the :class:`Message` class,
9imported from the :mod:`email.message` module. It is the base class for the
10:mod:`email` object model. :class:`Message` provides the core functionality for
11setting and querying header fields, and for accessing message bodies.
12
13Conceptually, a :class:`Message` object consists of *headers* and *payloads*.
14Headers are :rfc:`2822` style field names and values where the field name and
15value are separated by a colon. The colon is not part of either the field name
16or the field value.
17
18Headers are stored and returned in case-preserving form but are matched
19case-insensitively. There may also be a single envelope header, also known as
20the *Unix-From* header or the ``From_`` header. The payload is either a string
21in the case of simple message objects or a list of :class:`Message` objects for
22MIME container documents (e.g. :mimetype:`multipart/\*` and
23:mimetype:`message/rfc822`).
24
25:class:`Message` objects provide a mapping style interface for accessing the
26message headers, and an explicit interface for accessing both the headers and
27the payload. It provides convenience methods for generating a flat text
28representation of the message object tree, for accessing commonly used header
29parameters, and for recursively walking over the object tree.
30
31Here are the methods of the :class:`Message` class:
32
33
34.. class:: Message()
35
36 The constructor takes no arguments.
37
38
Georg Brandl3f076d82009-05-17 11:28:33 +000039 .. method:: as_string(unixfrom=False, maxheaderlen=0)
Georg Brandl116aa622007-08-15 14:28:22 +000040
Benjamin Petersone41251e2008-04-25 01:59:09 +000041 Return the entire message flattened as a string. When optional *unixfrom*
42 is ``True``, the envelope header is included in the returned string.
R. David Murray101f2782010-01-10 19:18:27 +000043 *unixfrom* defaults to ``False``. Flattening the message may trigger
44 changes to the :class:`Message` if defaults need to be filled in to
45 complete the transformation to a string (for example, MIME boundaries may
46 be generated or modified).
Georg Brandl116aa622007-08-15 14:28:22 +000047
Benjamin Petersone41251e2008-04-25 01:59:09 +000048 Note that this method is provided as a convenience and may not always
R David Murray7dedcb42011-03-15 14:01:18 -040049 format the message the way you want. For example, by default it does
50 not do the mangling of lines that begin with ``From`` that is
51 required by the unix mbox format. For more flexibility, instantiate a
Georg Brandl3638e482009-04-27 16:46:17 +000052 :class:`~email.generator.Generator` instance and use its :meth:`flatten`
53 method directly. For example::
Georg Brandl116aa622007-08-15 14:28:22 +000054
Georg Brandl03124942008-06-10 15:50:56 +000055 from io import StringIO
Benjamin Petersone41251e2008-04-25 01:59:09 +000056 from email.generator import Generator
57 fp = StringIO()
R David Murray7dedcb42011-03-15 14:01:18 -040058 g = Generator(fp, mangle_from_=True, maxheaderlen=60)
Benjamin Petersone41251e2008-04-25 01:59:09 +000059 g.flatten(msg)
60 text = fp.getvalue()
Georg Brandl116aa622007-08-15 14:28:22 +000061
62
Benjamin Petersone41251e2008-04-25 01:59:09 +000063 .. method:: __str__()
Georg Brandl116aa622007-08-15 14:28:22 +000064
Benjamin Petersone41251e2008-04-25 01:59:09 +000065 Equivalent to ``as_string(unixfrom=True)``.
Georg Brandl116aa622007-08-15 14:28:22 +000066
67
Benjamin Petersone41251e2008-04-25 01:59:09 +000068 .. method:: is_multipart()
Georg Brandl116aa622007-08-15 14:28:22 +000069
Benjamin Petersone41251e2008-04-25 01:59:09 +000070 Return ``True`` if the message's payload is a list of sub-\
71 :class:`Message` objects, otherwise return ``False``. When
72 :meth:`is_multipart` returns False, the payload should be a string object.
Georg Brandl116aa622007-08-15 14:28:22 +000073
74
Benjamin Petersone41251e2008-04-25 01:59:09 +000075 .. method:: set_unixfrom(unixfrom)
Georg Brandl116aa622007-08-15 14:28:22 +000076
Benjamin Petersone41251e2008-04-25 01:59:09 +000077 Set the message's envelope header to *unixfrom*, which should be a string.
Georg Brandl116aa622007-08-15 14:28:22 +000078
79
Benjamin Petersone41251e2008-04-25 01:59:09 +000080 .. method:: get_unixfrom()
Georg Brandl116aa622007-08-15 14:28:22 +000081
Benjamin Petersone41251e2008-04-25 01:59:09 +000082 Return the message's envelope header. Defaults to ``None`` if the
83 envelope header was never set.
Georg Brandl116aa622007-08-15 14:28:22 +000084
85
Benjamin Petersone41251e2008-04-25 01:59:09 +000086 .. method:: attach(payload)
Georg Brandl116aa622007-08-15 14:28:22 +000087
Benjamin Petersone41251e2008-04-25 01:59:09 +000088 Add the given *payload* to the current payload, which must be ``None`` or
89 a list of :class:`Message` objects before the call. After the call, the
90 payload will always be a list of :class:`Message` objects. If you want to
91 set the payload to a scalar object (e.g. a string), use
92 :meth:`set_payload` instead.
Georg Brandl116aa622007-08-15 14:28:22 +000093
94
Georg Brandl3f076d82009-05-17 11:28:33 +000095 .. method:: get_payload(i=None, decode=False)
Georg Brandl116aa622007-08-15 14:28:22 +000096
Benjamin Petersond6313712008-07-31 16:23:04 +000097 Return the current payload, which will be a list of
Benjamin Petersone41251e2008-04-25 01:59:09 +000098 :class:`Message` objects when :meth:`is_multipart` is ``True``, or a
99 string when :meth:`is_multipart` is ``False``. If the payload is a list
100 and you mutate the list object, you modify the message's payload in place.
Georg Brandl116aa622007-08-15 14:28:22 +0000101
Benjamin Petersone41251e2008-04-25 01:59:09 +0000102 With optional argument *i*, :meth:`get_payload` will return the *i*-th
103 element of the payload, counting from zero, if :meth:`is_multipart` is
104 ``True``. An :exc:`IndexError` will be raised if *i* is less than 0 or
105 greater than or equal to the number of items in the payload. If the
106 payload is a string (i.e. :meth:`is_multipart` is ``False``) and *i* is
107 given, a :exc:`TypeError` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000108
Benjamin Petersone41251e2008-04-25 01:59:09 +0000109 Optional *decode* is a flag indicating whether the payload should be
110 decoded or not, according to the :mailheader:`Content-Transfer-Encoding`
111 header. When ``True`` and the message is not a multipart, the payload will
112 be decoded if this header's value is ``quoted-printable`` or ``base64``.
113 If some other encoding is used, or :mailheader:`Content-Transfer-Encoding`
114 header is missing, or if the payload has bogus base64 data, the payload is
R. David Murray96fd54e2010-10-08 15:55:28 +0000115 returned as-is (undecoded). In all cases the returned value is binary
116 data. If the message is a multipart and the *decode* flag is ``True``,
117 then ``None`` is returned.
118
119 When *decode* is ``False`` (the default) the body is returned as a string
120 without decoding the :mailheader:`Content-Transfer-Encoding`. However,
121 for a :mailheader:`Content-Transfer-Encoding` of 8bit, an attempt is made
Senthil Kumaran82270452010-10-15 13:29:33 +0000122 to decode the original bytes using the ``charset`` specified by the
123 :mailheader:`Content-Type` header, using the ``replace`` error handler.
124 If no ``charset`` is specified, or if the ``charset`` given is not
125 recognized by the email package, the body is decoded using the default
126 ASCII charset.
Georg Brandl116aa622007-08-15 14:28:22 +0000127
128
Georg Brandl3f076d82009-05-17 11:28:33 +0000129 .. method:: set_payload(payload, charset=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000130
Benjamin Petersone41251e2008-04-25 01:59:09 +0000131 Set the entire message object's payload to *payload*. It is the client's
132 responsibility to ensure the payload invariants. Optional *charset* sets
133 the message's default character set; see :meth:`set_charset` for details.
Georg Brandl116aa622007-08-15 14:28:22 +0000134
Benjamin Petersone41251e2008-04-25 01:59:09 +0000135 .. method:: set_charset(charset)
Georg Brandl116aa622007-08-15 14:28:22 +0000136
Benjamin Petersone41251e2008-04-25 01:59:09 +0000137 Set the character set of the payload to *charset*, which can either be a
Georg Brandl3638e482009-04-27 16:46:17 +0000138 :class:`~email.charset.Charset` instance (see :mod:`email.charset`), a
139 string naming a character set, or ``None``. If it is a string, it will
140 be converted to a :class:`~email.charset.Charset` instance. If *charset*
141 is ``None``, the ``charset`` parameter will be removed from the
R David Murraye3d09ff2011-03-15 17:41:13 -0400142 :mailheader:`Content-Type` header (the message will not be otherwise
143 modified). Anything else will generate a :exc:`TypeError`.
Georg Brandl116aa622007-08-15 14:28:22 +0000144
R David Murraye3d09ff2011-03-15 17:41:13 -0400145 If there is no existing :mailheader:`MIME-Version` header one will be
146 added. If there is no existing :mailheader:`Content-Type` header, one
147 will be added with a value of :mimetype:`text/plain`. Whether the
148 :mailheader:`Content-Type` header already exists or not, its ``charset``
149 parameter will be set to *charset.output_charset*. If
150 *charset.input_charset* and *charset.output_charset* differ, the payload
151 will be re-encoded to the *output_charset*. If there is no existing
152 :mailheader:`Content-Transfer-Encoding` header, then the payload will be
153 transfer-encoded, if needed, using the specified
154 :class:`~email.charset.Charset`, and a header with the appropriate value
155 will be added. If a :mailheader:`Content-Transfer-Encoding` header
156 already exists, the payload is assumed to already be correctly encoded
157 using that :mailheader:`Content-Transfer-Encoding` and is not modified.
Georg Brandl116aa622007-08-15 14:28:22 +0000158
Benjamin Petersone41251e2008-04-25 01:59:09 +0000159 .. method:: get_charset()
Georg Brandl116aa622007-08-15 14:28:22 +0000160
Georg Brandl3638e482009-04-27 16:46:17 +0000161 Return the :class:`~email.charset.Charset` instance associated with the
162 message's payload.
Georg Brandl116aa622007-08-15 14:28:22 +0000163
Benjamin Petersone41251e2008-04-25 01:59:09 +0000164 The following methods implement a mapping-like interface for accessing the
165 message's :rfc:`2822` headers. Note that there are some semantic differences
166 between these methods and a normal mapping (i.e. dictionary) interface. For
167 example, in a dictionary there are no duplicate keys, but here there may be
168 duplicate message headers. Also, in dictionaries there is no guaranteed
169 order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
170 headers are always returned in the order they appeared in the original
171 message, or were added to the message later. Any header deleted and then
172 re-added are always appended to the end of the header list.
Georg Brandl116aa622007-08-15 14:28:22 +0000173
Benjamin Petersone41251e2008-04-25 01:59:09 +0000174 These semantic differences are intentional and are biased toward maximal
175 convenience.
Georg Brandl116aa622007-08-15 14:28:22 +0000176
Benjamin Petersone41251e2008-04-25 01:59:09 +0000177 Note that in all cases, any envelope header present in the message is not
178 included in the mapping interface.
Georg Brandl116aa622007-08-15 14:28:22 +0000179
R. David Murray92532142011-01-07 23:25:30 +0000180 In a model generated from bytes, any header values that (in contravention of
181 the RFCs) contain non-ASCII bytes will, when retrieved through this
182 interface, be represented as :class:`~email.header.Header` objects with
183 a charset of `unknown-8bit`.
R. David Murray96fd54e2010-10-08 15:55:28 +0000184
Georg Brandl116aa622007-08-15 14:28:22 +0000185
Benjamin Petersone41251e2008-04-25 01:59:09 +0000186 .. method:: __len__()
Georg Brandl116aa622007-08-15 14:28:22 +0000187
Benjamin Petersone41251e2008-04-25 01:59:09 +0000188 Return the total number of headers, including duplicates.
Georg Brandl116aa622007-08-15 14:28:22 +0000189
190
Benjamin Petersone41251e2008-04-25 01:59:09 +0000191 .. method:: __contains__(name)
Georg Brandl116aa622007-08-15 14:28:22 +0000192
Benjamin Petersone41251e2008-04-25 01:59:09 +0000193 Return true if the message object has a field named *name*. Matching is
194 done case-insensitively and *name* should not include the trailing colon.
195 Used for the ``in`` operator, e.g.::
Georg Brandl116aa622007-08-15 14:28:22 +0000196
Benjamin Petersone41251e2008-04-25 01:59:09 +0000197 if 'message-id' in myMessage:
198 print('Message-ID:', myMessage['message-id'])
Georg Brandl116aa622007-08-15 14:28:22 +0000199
200
Benjamin Petersone41251e2008-04-25 01:59:09 +0000201 .. method:: __getitem__(name)
Georg Brandl116aa622007-08-15 14:28:22 +0000202
Benjamin Petersone41251e2008-04-25 01:59:09 +0000203 Return the value of the named header field. *name* should not include the
204 colon field separator. If the header is missing, ``None`` is returned; a
205 :exc:`KeyError` is never raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000206
Benjamin Petersone41251e2008-04-25 01:59:09 +0000207 Note that if the named field appears more than once in the message's
208 headers, exactly which of those field values will be returned is
209 undefined. Use the :meth:`get_all` method to get the values of all the
210 extant named headers.
Georg Brandl116aa622007-08-15 14:28:22 +0000211
212
Benjamin Petersone41251e2008-04-25 01:59:09 +0000213 .. method:: __setitem__(name, val)
Georg Brandl116aa622007-08-15 14:28:22 +0000214
Benjamin Petersone41251e2008-04-25 01:59:09 +0000215 Add a header to the message with field name *name* and value *val*. The
216 field is appended to the end of the message's existing fields.
Georg Brandl116aa622007-08-15 14:28:22 +0000217
Benjamin Petersone41251e2008-04-25 01:59:09 +0000218 Note that this does *not* overwrite or delete any existing header with the same
219 name. If you want to ensure that the new header is the only one present in the
220 message with field name *name*, delete the field first, e.g.::
Georg Brandl116aa622007-08-15 14:28:22 +0000221
Benjamin Petersone41251e2008-04-25 01:59:09 +0000222 del msg['subject']
223 msg['subject'] = 'Python roolz!'
Georg Brandl116aa622007-08-15 14:28:22 +0000224
225
Benjamin Petersone41251e2008-04-25 01:59:09 +0000226 .. method:: __delitem__(name)
Georg Brandl116aa622007-08-15 14:28:22 +0000227
Benjamin Petersone41251e2008-04-25 01:59:09 +0000228 Delete all occurrences of the field with name *name* from the message's
Georg Brandl3f076d82009-05-17 11:28:33 +0000229 headers. No exception is raised if the named field isn't present in the
230 headers.
Georg Brandl116aa622007-08-15 14:28:22 +0000231
232
Benjamin Petersone41251e2008-04-25 01:59:09 +0000233 .. method:: keys()
Georg Brandl116aa622007-08-15 14:28:22 +0000234
Benjamin Petersone41251e2008-04-25 01:59:09 +0000235 Return a list of all the message's header field names.
Georg Brandl116aa622007-08-15 14:28:22 +0000236
237
Benjamin Petersone41251e2008-04-25 01:59:09 +0000238 .. method:: values()
Georg Brandl116aa622007-08-15 14:28:22 +0000239
Benjamin Petersone41251e2008-04-25 01:59:09 +0000240 Return a list of all the message's field values.
Georg Brandl116aa622007-08-15 14:28:22 +0000241
242
Benjamin Petersone41251e2008-04-25 01:59:09 +0000243 .. method:: items()
Georg Brandl116aa622007-08-15 14:28:22 +0000244
Benjamin Petersone41251e2008-04-25 01:59:09 +0000245 Return a list of 2-tuples containing all the message's field headers and
246 values.
Georg Brandl116aa622007-08-15 14:28:22 +0000247
248
Georg Brandl3f076d82009-05-17 11:28:33 +0000249 .. method:: get(name, failobj=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000250
Benjamin Petersone41251e2008-04-25 01:59:09 +0000251 Return the value of the named header field. This is identical to
252 :meth:`__getitem__` except that optional *failobj* is returned if the
253 named header is missing (defaults to ``None``).
Georg Brandl116aa622007-08-15 14:28:22 +0000254
Benjamin Petersone41251e2008-04-25 01:59:09 +0000255 Here are some additional useful methods:
Georg Brandl116aa622007-08-15 14:28:22 +0000256
257
Georg Brandl3f076d82009-05-17 11:28:33 +0000258 .. method:: get_all(name, failobj=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000259
Benjamin Petersone41251e2008-04-25 01:59:09 +0000260 Return a list of all the values for the field named *name*. If there are
261 no such named headers in the message, *failobj* is returned (defaults to
262 ``None``).
Georg Brandl116aa622007-08-15 14:28:22 +0000263
264
Benjamin Petersone41251e2008-04-25 01:59:09 +0000265 .. method:: add_header(_name, _value, **_params)
Georg Brandl116aa622007-08-15 14:28:22 +0000266
Benjamin Petersone41251e2008-04-25 01:59:09 +0000267 Extended header setting. This method is similar to :meth:`__setitem__`
268 except that additional header parameters can be provided as keyword
269 arguments. *_name* is the header field to add and *_value* is the
270 *primary* value for the header.
Georg Brandl116aa622007-08-15 14:28:22 +0000271
Benjamin Petersone41251e2008-04-25 01:59:09 +0000272 For each item in the keyword argument dictionary *_params*, the key is
273 taken as the parameter name, with underscores converted to dashes (since
274 dashes are illegal in Python identifiers). Normally, the parameter will
275 be added as ``key="value"`` unless the value is ``None``, in which case
R. David Murray7ec754b2010-12-13 23:51:19 +0000276 only the key will be added. If the value contains non-ASCII characters,
277 it can be specified as a three tuple in the format
278 ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
279 charset to be used to encode the value, ``LANGUAGE`` can usually be set
Georg Brandlc8843502010-12-19 10:28:46 +0000280 to ``None`` or the empty string (see :rfc:`2231` for other possibilities),
R. David Murray7ec754b2010-12-13 23:51:19 +0000281 and ``VALUE`` is the string value containing non-ASCII code points. If
282 a three tuple is not passed and the value contains non-ASCII characters,
Georg Brandlc8843502010-12-19 10:28:46 +0000283 it is automatically encoded in :rfc:`2231` format using a ``CHARSET``
R. David Murray7ec754b2010-12-13 23:51:19 +0000284 of ``utf-8`` and a ``LANGUAGE`` of ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000285
Benjamin Petersone41251e2008-04-25 01:59:09 +0000286 Here's an example::
Georg Brandl116aa622007-08-15 14:28:22 +0000287
Benjamin Petersone41251e2008-04-25 01:59:09 +0000288 msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
Georg Brandl116aa622007-08-15 14:28:22 +0000289
Benjamin Petersone41251e2008-04-25 01:59:09 +0000290 This will add a header that looks like ::
Georg Brandl116aa622007-08-15 14:28:22 +0000291
Benjamin Petersone41251e2008-04-25 01:59:09 +0000292 Content-Disposition: attachment; filename="bud.gif"
Georg Brandl116aa622007-08-15 14:28:22 +0000293
Ezio Melottie130a522011-10-19 10:58:56 +0300294 An example with non-ASCII characters::
R. David Murray7ec754b2010-12-13 23:51:19 +0000295
296 msg.add_header('Content-Disposition', 'attachment',
297 filename=('iso-8859-1', '', 'Fußballer.ppt'))
298
299 Which produces ::
300
301 Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
302
Georg Brandl116aa622007-08-15 14:28:22 +0000303
Benjamin Petersone41251e2008-04-25 01:59:09 +0000304 .. method:: replace_header(_name, _value)
Georg Brandl116aa622007-08-15 14:28:22 +0000305
Benjamin Petersone41251e2008-04-25 01:59:09 +0000306 Replace a header. Replace the first header found in the message that
307 matches *_name*, retaining header order and field name case. If no
308 matching header was found, a :exc:`KeyError` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000309
Georg Brandl116aa622007-08-15 14:28:22 +0000310
Benjamin Petersone41251e2008-04-25 01:59:09 +0000311 .. method:: get_content_type()
Georg Brandl116aa622007-08-15 14:28:22 +0000312
Benjamin Petersone41251e2008-04-25 01:59:09 +0000313 Return the message's content type. The returned string is coerced to
314 lower case of the form :mimetype:`maintype/subtype`. If there was no
315 :mailheader:`Content-Type` header in the message the default type as given
316 by :meth:`get_default_type` will be returned. Since according to
317 :rfc:`2045`, messages always have a default type, :meth:`get_content_type`
318 will always return a value.
Georg Brandl116aa622007-08-15 14:28:22 +0000319
Benjamin Petersone41251e2008-04-25 01:59:09 +0000320 :rfc:`2045` defines a message's default type to be :mimetype:`text/plain`
321 unless it appears inside a :mimetype:`multipart/digest` container, in
322 which case it would be :mimetype:`message/rfc822`. If the
323 :mailheader:`Content-Type` header has an invalid type specification,
324 :rfc:`2045` mandates that the default type be :mimetype:`text/plain`.
Georg Brandl116aa622007-08-15 14:28:22 +0000325
Georg Brandl116aa622007-08-15 14:28:22 +0000326
Benjamin Petersone41251e2008-04-25 01:59:09 +0000327 .. method:: get_content_maintype()
Georg Brandl116aa622007-08-15 14:28:22 +0000328
Benjamin Petersone41251e2008-04-25 01:59:09 +0000329 Return the message's main content type. This is the :mimetype:`maintype`
330 part of the string returned by :meth:`get_content_type`.
Georg Brandl116aa622007-08-15 14:28:22 +0000331
Georg Brandl116aa622007-08-15 14:28:22 +0000332
Benjamin Petersone41251e2008-04-25 01:59:09 +0000333 .. method:: get_content_subtype()
Georg Brandl116aa622007-08-15 14:28:22 +0000334
Benjamin Petersone41251e2008-04-25 01:59:09 +0000335 Return the message's sub-content type. This is the :mimetype:`subtype`
336 part of the string returned by :meth:`get_content_type`.
Georg Brandl116aa622007-08-15 14:28:22 +0000337
Georg Brandl116aa622007-08-15 14:28:22 +0000338
Benjamin Petersone41251e2008-04-25 01:59:09 +0000339 .. method:: get_default_type()
Georg Brandl116aa622007-08-15 14:28:22 +0000340
Benjamin Petersone41251e2008-04-25 01:59:09 +0000341 Return the default content type. Most messages have a default content
342 type of :mimetype:`text/plain`, except for messages that are subparts of
343 :mimetype:`multipart/digest` containers. Such subparts have a default
344 content type of :mimetype:`message/rfc822`.
Georg Brandl116aa622007-08-15 14:28:22 +0000345
Georg Brandl116aa622007-08-15 14:28:22 +0000346
Benjamin Petersone41251e2008-04-25 01:59:09 +0000347 .. method:: set_default_type(ctype)
Georg Brandl116aa622007-08-15 14:28:22 +0000348
Benjamin Petersone41251e2008-04-25 01:59:09 +0000349 Set the default content type. *ctype* should either be
350 :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not
351 enforced. The default content type is not stored in the
352 :mailheader:`Content-Type` header.
Georg Brandl116aa622007-08-15 14:28:22 +0000353
Georg Brandl116aa622007-08-15 14:28:22 +0000354
Georg Brandl3f076d82009-05-17 11:28:33 +0000355 .. method:: get_params(failobj=None, header='content-type', unquote=True)
Georg Brandl116aa622007-08-15 14:28:22 +0000356
Benjamin Petersone41251e2008-04-25 01:59:09 +0000357 Return the message's :mailheader:`Content-Type` parameters, as a list.
358 The elements of the returned list are 2-tuples of key/value pairs, as
359 split on the ``'='`` sign. The left hand side of the ``'='`` is the key,
360 while the right hand side is the value. If there is no ``'='`` sign in
361 the parameter the value is the empty string, otherwise the value is as
362 described in :meth:`get_param` and is unquoted if optional *unquote* is
363 ``True`` (the default).
Georg Brandl116aa622007-08-15 14:28:22 +0000364
Benjamin Petersone41251e2008-04-25 01:59:09 +0000365 Optional *failobj* is the object to return if there is no
366 :mailheader:`Content-Type` header. Optional *header* is the header to
367 search instead of :mailheader:`Content-Type`.
Georg Brandl116aa622007-08-15 14:28:22 +0000368
Georg Brandl116aa622007-08-15 14:28:22 +0000369
Georg Brandl3f076d82009-05-17 11:28:33 +0000370 .. method:: get_param(param, failobj=None, header='content-type', unquote=True)
Georg Brandl116aa622007-08-15 14:28:22 +0000371
Benjamin Petersone41251e2008-04-25 01:59:09 +0000372 Return the value of the :mailheader:`Content-Type` header's parameter
373 *param* as a string. If the message has no :mailheader:`Content-Type`
374 header or if there is no such parameter, then *failobj* is returned
375 (defaults to ``None``).
Georg Brandl116aa622007-08-15 14:28:22 +0000376
Benjamin Petersone41251e2008-04-25 01:59:09 +0000377 Optional *header* if given, specifies the message header to use instead of
378 :mailheader:`Content-Type`.
Georg Brandl116aa622007-08-15 14:28:22 +0000379
Benjamin Petersone41251e2008-04-25 01:59:09 +0000380 Parameter keys are always compared case insensitively. The return value
381 can either be a string, or a 3-tuple if the parameter was :rfc:`2231`
382 encoded. When it's a 3-tuple, the elements of the value are of the form
383 ``(CHARSET, LANGUAGE, VALUE)``. Note that both ``CHARSET`` and
384 ``LANGUAGE`` can be ``None``, in which case you should consider ``VALUE``
385 to be encoded in the ``us-ascii`` charset. You can usually ignore
386 ``LANGUAGE``.
Georg Brandl116aa622007-08-15 14:28:22 +0000387
Benjamin Petersone41251e2008-04-25 01:59:09 +0000388 If your application doesn't care whether the parameter was encoded as in
389 :rfc:`2231`, you can collapse the parameter value by calling
Georg Brandl540b45c2009-04-27 16:45:26 +0000390 :func:`email.utils.collapse_rfc2231_value`, passing in the return value
Benjamin Petersone41251e2008-04-25 01:59:09 +0000391 from :meth:`get_param`. This will return a suitably decoded Unicode
R. David Murray7ec754b2010-12-13 23:51:19 +0000392 string when the value is a tuple, or the original string unquoted if it
Benjamin Petersone41251e2008-04-25 01:59:09 +0000393 isn't. For example::
Georg Brandl116aa622007-08-15 14:28:22 +0000394
Benjamin Petersone41251e2008-04-25 01:59:09 +0000395 rawparam = msg.get_param('foo')
Georg Brandl540b45c2009-04-27 16:45:26 +0000396 param = email.utils.collapse_rfc2231_value(rawparam)
Georg Brandl116aa622007-08-15 14:28:22 +0000397
Benjamin Petersone41251e2008-04-25 01:59:09 +0000398 In any case, the parameter value (either the returned string, or the
399 ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
400 to ``False``.
Georg Brandl116aa622007-08-15 14:28:22 +0000401
Georg Brandl116aa622007-08-15 14:28:22 +0000402
Georg Brandl3f076d82009-05-17 11:28:33 +0000403 .. method:: set_param(param, value, header='Content-Type', requote=True, charset=None, language='')
Georg Brandl116aa622007-08-15 14:28:22 +0000404
Benjamin Petersone41251e2008-04-25 01:59:09 +0000405 Set a parameter in the :mailheader:`Content-Type` header. If the
406 parameter already exists in the header, its value will be replaced with
407 *value*. If the :mailheader:`Content-Type` header as not yet been defined
408 for this message, it will be set to :mimetype:`text/plain` and the new
409 parameter value will be appended as per :rfc:`2045`.
Georg Brandl116aa622007-08-15 14:28:22 +0000410
Benjamin Petersone41251e2008-04-25 01:59:09 +0000411 Optional *header* specifies an alternative header to
412 :mailheader:`Content-Type`, and all parameters will be quoted as necessary
413 unless optional *requote* is ``False`` (the default is ``True``).
Georg Brandl116aa622007-08-15 14:28:22 +0000414
Benjamin Petersone41251e2008-04-25 01:59:09 +0000415 If optional *charset* is specified, the parameter will be encoded
416 according to :rfc:`2231`. Optional *language* specifies the RFC 2231
417 language, defaulting to the empty string. Both *charset* and *language*
418 should be strings.
Georg Brandl116aa622007-08-15 14:28:22 +0000419
Georg Brandl116aa622007-08-15 14:28:22 +0000420
Georg Brandl3f076d82009-05-17 11:28:33 +0000421 .. method:: del_param(param, header='content-type', requote=True)
Georg Brandl116aa622007-08-15 14:28:22 +0000422
Benjamin Petersone41251e2008-04-25 01:59:09 +0000423 Remove the given parameter completely from the :mailheader:`Content-Type`
424 header. The header will be re-written in place without the parameter or
425 its value. All values will be quoted as necessary unless *requote* is
426 ``False`` (the default is ``True``). Optional *header* specifies an
427 alternative to :mailheader:`Content-Type`.
Georg Brandl116aa622007-08-15 14:28:22 +0000428
Georg Brandl116aa622007-08-15 14:28:22 +0000429
Georg Brandl3f076d82009-05-17 11:28:33 +0000430 .. method:: set_type(type, header='Content-Type', requote=True)
Georg Brandl116aa622007-08-15 14:28:22 +0000431
Benjamin Petersone41251e2008-04-25 01:59:09 +0000432 Set the main type and subtype for the :mailheader:`Content-Type`
433 header. *type* must be a string in the form :mimetype:`maintype/subtype`,
434 otherwise a :exc:`ValueError` is raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000435
Benjamin Petersone41251e2008-04-25 01:59:09 +0000436 This method replaces the :mailheader:`Content-Type` header, keeping all
437 the parameters in place. If *requote* is ``False``, this leaves the
438 existing header's quoting as is, otherwise the parameters will be quoted
439 (the default).
Georg Brandl116aa622007-08-15 14:28:22 +0000440
Benjamin Petersone41251e2008-04-25 01:59:09 +0000441 An alternative header can be specified in the *header* argument. When the
442 :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version`
443 header is also added.
Georg Brandl116aa622007-08-15 14:28:22 +0000444
Georg Brandl116aa622007-08-15 14:28:22 +0000445
Georg Brandl3f076d82009-05-17 11:28:33 +0000446 .. method:: get_filename(failobj=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000447
Benjamin Petersone41251e2008-04-25 01:59:09 +0000448 Return the value of the ``filename`` parameter of the
449 :mailheader:`Content-Disposition` header of the message. If the header
450 does not have a ``filename`` parameter, this method falls back to looking
R. David Murray9ed34be2010-03-04 17:38:18 +0000451 for the ``name`` parameter on the :mailheader:`Content-Type` header. If
452 neither is found, or the header is missing, then *failobj* is returned.
453 The returned string will always be unquoted as per
454 :func:`email.utils.unquote`.
Georg Brandl116aa622007-08-15 14:28:22 +0000455
456
Georg Brandl3f076d82009-05-17 11:28:33 +0000457 .. method:: get_boundary(failobj=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000458
Benjamin Petersone41251e2008-04-25 01:59:09 +0000459 Return the value of the ``boundary`` parameter of the
460 :mailheader:`Content-Type` header of the message, or *failobj* if either
461 the header is missing, or has no ``boundary`` parameter. The returned
Georg Brandl540b45c2009-04-27 16:45:26 +0000462 string will always be unquoted as per :func:`email.utils.unquote`.
Georg Brandl116aa622007-08-15 14:28:22 +0000463
464
Benjamin Petersone41251e2008-04-25 01:59:09 +0000465 .. method:: set_boundary(boundary)
Georg Brandl116aa622007-08-15 14:28:22 +0000466
Benjamin Petersone41251e2008-04-25 01:59:09 +0000467 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
468 *boundary*. :meth:`set_boundary` will always quote *boundary* if
469 necessary. A :exc:`HeaderParseError` is raised if the message object has
470 no :mailheader:`Content-Type` header.
Georg Brandl116aa622007-08-15 14:28:22 +0000471
Benjamin Petersone41251e2008-04-25 01:59:09 +0000472 Note that using this method is subtly different than deleting the old
473 :mailheader:`Content-Type` header and adding a new one with the new
474 boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
475 the order of the :mailheader:`Content-Type` header in the list of
476 headers. However, it does *not* preserve any continuation lines which may
477 have been present in the original :mailheader:`Content-Type` header.
Georg Brandl116aa622007-08-15 14:28:22 +0000478
479
Georg Brandl3f076d82009-05-17 11:28:33 +0000480 .. method:: get_content_charset(failobj=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000481
Benjamin Petersone41251e2008-04-25 01:59:09 +0000482 Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
483 coerced to lower case. If there is no :mailheader:`Content-Type` header, or if
484 that header has no ``charset`` parameter, *failobj* is returned.
Georg Brandl116aa622007-08-15 14:28:22 +0000485
Benjamin Petersone41251e2008-04-25 01:59:09 +0000486 Note that this method differs from :meth:`get_charset` which returns the
Georg Brandl3638e482009-04-27 16:46:17 +0000487 :class:`~email.charset.Charset` instance for the default encoding of the message body.
Georg Brandl116aa622007-08-15 14:28:22 +0000488
Georg Brandl116aa622007-08-15 14:28:22 +0000489
Georg Brandl3f076d82009-05-17 11:28:33 +0000490 .. method:: get_charsets(failobj=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000491
Benjamin Petersone41251e2008-04-25 01:59:09 +0000492 Return a list containing the character set names in the message. If the
493 message is a :mimetype:`multipart`, then the list will contain one element
494 for each subpart in the payload, otherwise, it will be a list of length 1.
Georg Brandl116aa622007-08-15 14:28:22 +0000495
Benjamin Petersone41251e2008-04-25 01:59:09 +0000496 Each item in the list will be a string which is the value of the
497 ``charset`` parameter in the :mailheader:`Content-Type` header for the
498 represented subpart. However, if the subpart has no
499 :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of
500 the :mimetype:`text` main MIME type, then that item in the returned list
501 will be *failobj*.
Georg Brandl116aa622007-08-15 14:28:22 +0000502
503
Benjamin Petersone41251e2008-04-25 01:59:09 +0000504 .. method:: walk()
Georg Brandl116aa622007-08-15 14:28:22 +0000505
Benjamin Petersone41251e2008-04-25 01:59:09 +0000506 The :meth:`walk` method is an all-purpose generator which can be used to
507 iterate over all the parts and subparts of a message object tree, in
508 depth-first traversal order. You will typically use :meth:`walk` as the
509 iterator in a ``for`` loop; each iteration returns the next subpart.
Georg Brandl116aa622007-08-15 14:28:22 +0000510
Benjamin Petersone41251e2008-04-25 01:59:09 +0000511 Here's an example that prints the MIME type of every part of a multipart
512 message structure::
Georg Brandl116aa622007-08-15 14:28:22 +0000513
Benjamin Petersone41251e2008-04-25 01:59:09 +0000514 >>> for part in msg.walk():
515 ... print(part.get_content_type())
516 multipart/report
517 text/plain
518 message/delivery-status
519 text/plain
520 text/plain
521 message/rfc822
Georg Brandl116aa622007-08-15 14:28:22 +0000522
Benjamin Petersone41251e2008-04-25 01:59:09 +0000523 :class:`Message` objects can also optionally contain two instance attributes,
524 which can be used when generating the plain text of a MIME message.
Georg Brandl116aa622007-08-15 14:28:22 +0000525
526
Benjamin Petersone41251e2008-04-25 01:59:09 +0000527 .. attribute:: preamble
Georg Brandl116aa622007-08-15 14:28:22 +0000528
Benjamin Petersone41251e2008-04-25 01:59:09 +0000529 The format of a MIME document allows for some text between the blank line
530 following the headers, and the first multipart boundary string. Normally,
531 this text is never visible in a MIME-aware mail reader because it falls
532 outside the standard MIME armor. However, when viewing the raw text of
533 the message, or when viewing the message in a non-MIME aware reader, this
534 text can become visible.
Georg Brandl116aa622007-08-15 14:28:22 +0000535
Benjamin Petersone41251e2008-04-25 01:59:09 +0000536 The *preamble* attribute contains this leading extra-armor text for MIME
Georg Brandl3638e482009-04-27 16:46:17 +0000537 documents. When the :class:`~email.parser.Parser` discovers some text
538 after the headers but before the first boundary string, it assigns this
539 text to the message's *preamble* attribute. When the
540 :class:`~email.generator.Generator` is writing out the plain text
541 representation of a MIME message, and it finds the
Benjamin Petersone41251e2008-04-25 01:59:09 +0000542 message has a *preamble* attribute, it will write this text in the area
543 between the headers and the first boundary. See :mod:`email.parser` and
544 :mod:`email.generator` for details.
Georg Brandl116aa622007-08-15 14:28:22 +0000545
Benjamin Petersone41251e2008-04-25 01:59:09 +0000546 Note that if the message object has no preamble, the *preamble* attribute
547 will be ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000548
549
Benjamin Petersone41251e2008-04-25 01:59:09 +0000550 .. attribute:: epilogue
Georg Brandl116aa622007-08-15 14:28:22 +0000551
Benjamin Petersone41251e2008-04-25 01:59:09 +0000552 The *epilogue* attribute acts the same way as the *preamble* attribute,
553 except that it contains text that appears between the last boundary and
554 the end of the message.
Georg Brandl116aa622007-08-15 14:28:22 +0000555
Benjamin Petersone41251e2008-04-25 01:59:09 +0000556 You do not need to set the epilogue to the empty string in order for the
557 :class:`Generator` to print a newline at the end of the file.
Georg Brandl116aa622007-08-15 14:28:22 +0000558
559
Benjamin Petersone41251e2008-04-25 01:59:09 +0000560 .. attribute:: defects
Georg Brandl116aa622007-08-15 14:28:22 +0000561
Benjamin Petersone41251e2008-04-25 01:59:09 +0000562 The *defects* attribute contains a list of all the problems found when
563 parsing this message. See :mod:`email.errors` for a detailed description
564 of the possible parsing defects.