rest25/library/email.message.rst => rest262/library/email.message.rst
n1+:mod:`email`: Representing an email message
2+-------------------------------------------
3+ 
1.. module:: email.message
2   :synopsis: The base class representing email messages.
3
4
5The central class in the :mod:`email` package is the :class:`Message` class,
6imported from the :mod:`email.message` module.  It is the base class for the
7:mod:`email` object model.  :class:`Message` provides the core functionality for
8setting and querying header fields, and for accessing message bodies.
9
10Conceptually, a :class:`Message` object consists of *headers* and *payloads*.
11Headers are :rfc:`2822` style field names and values where the field name and
12value are separated by a colon.  The colon is not part of either the field name
13or the field value.
14
n15-Headers are stored and returned in case-preserving form but are matched case-
n18+Headers are stored and returned in case-preserving form but are matched
16-insensitively.  There may also be a single envelope header, also known as the
19+case-insensitively.  There may also be a single envelope header, also known as
17-*Unix-From* header or the ``From_`` header.  The payload is either a string in
20+the *Unix-From* header or the ``From_`` header.  The payload is either a string
18-the case of simple message objects or a list of :class:`Message` objects for
21+in the case of simple message objects or a list of :class:`Message` objects for
19MIME container documents (e.g. :mimetype:`multipart/\*` and
20:mimetype:`message/rfc822`).
21
22:class:`Message` objects provide a mapping style interface for accessing the
23message headers, and an explicit interface for accessing both the headers and
24the payload.  It provides convenience methods for generating a flat text
25representation of the message object tree, for accessing commonly used header
26parameters, and for recursively walking over the object tree.
28Here are the methods of the :class:`Message` class:
29
30
31.. class:: Message()
32
33   The constructor takes no arguments.
34
35
n36-.. method:: Message.as_string([unixfrom])
n39+   .. method:: as_string([unixfrom])
37
n38-   Return the entire message flatten as a string.  When optional *unixfrom* is
n41+      Return the entire message flattened as a string.  When optional *unixfrom*
39-   ``True``, the envelope header is included in the returned string.  *unixfrom*
42+      is ``True``, the envelope header is included in the returned string.
40-   defaults to ``False``.
43+      *unixfrom* defaults to ``False``.
41
n42-   Note that this method is provided as a convenience and may not always format the
n45+      Note that this method is provided as a convenience and may not always
43-   message the way you want.  For example, by default it mangles lines that begin
46+      format the message the way you want.  For example, by default it mangles
44-   with ``From``.  For more flexibility, instantiate a :class:`Generator` instance
47+      lines that begin with ``From``.  For more flexibility, instantiate a
45-   and use its :meth:`flatten` method directly.  For example::
48+      :class:`Generator` instance and use its :meth:`flatten` method directly.
49+      For example::
46
n47-      from cStringIO import StringIO
n51+         from cStringIO import StringIO
48-      from email.generator import Generator
52+         from email.generator import Generator
49-      fp = StringIO()
53+         fp = StringIO()
50-      g = Generator(fp, mangle_from_=False, maxheaderlen=60)
54+         g = Generator(fp, mangle_from_=False, maxheaderlen=60)
51-      g.flatten(msg)
55+         g.flatten(msg)
52-      text = fp.getvalue()
56+         text = fp.getvalue()
53
54
n55-.. method:: Message.__str__()
n59+   .. method:: __str__()
56
n57-   Equivalent to :meth:`as_string(unixfrom=True)`.
n61+      Equivalent to ``as_string(unixfrom=True)``.
58
59
n60-.. method:: Message.is_multipart()
n64+   .. method:: is_multipart()
61
n62-   Return ``True`` if the message's payload is a list of sub-\ :class:`Message`
n66+      Return ``True`` if the message's payload is a list of sub-\
63-   objects, otherwise return ``False``.  When :meth:`is_multipart` returns False,
67+      :class:`Message` objects, otherwise return ``False``.  When
64-   the payload should be a string object.
68+      :meth:`is_multipart` returns False, the payload should be a string object.
65
66
n67-.. method:: Message.set_unixfrom(unixfrom)
n71+   .. method:: set_unixfrom(unixfrom)
68
n69-   Set the message's envelope header to *unixfrom*, which should be a string.
n73+      Set the message's envelope header to *unixfrom*, which should be a string.
70
71
n72-.. method:: Message.get_unixfrom()
n76+   .. method:: get_unixfrom()
73
n74-   Return the message's envelope header.  Defaults to ``None`` if the envelope
n78+      Return the message's envelope header.  Defaults to ``None`` if the
75-   header was never set.
79+      envelope header was never set.
76
77
n78-.. method:: Message.attach(payload)
n82+   .. method:: attach(payload)
79
n80-   Add the given *payload* to the current payload, which must be ``None`` or a list
n84+      Add the given *payload* to the current payload, which must be ``None`` or
81-   of :class:`Message` objects before the call. After the call, the payload will
85+      a list of :class:`Message` objects before the call. After the call, the
82-   always be a list of :class:`Message` objects.  If you want to set the payload to
86+      payload will always be a list of :class:`Message` objects.  If you want to
83-   a scalar object (e.g. a string), use :meth:`set_payload` instead.
87+      set the payload to a scalar object (e.g. a string), use
88+      :meth:`set_payload` instead.
84
85
n86-.. method:: Message.get_payload([i[, decode]])
n91+   .. method:: get_payload([i[, decode]])
87
n88-   Return a reference the current payload, which will be a list of :class:`Message`
n93+      Return the current payload, which will be a list of
89-   objects when :meth:`is_multipart` is ``True``, or a string when
94+      :class:`Message` objects when :meth:`is_multipart` is ``True``, or a
90-   :meth:`is_multipart` is ``False``.  If the payload is a list and you mutate the
95+      string when :meth:`is_multipart` is ``False``.  If the payload is a list
91-   list object, you modify the message's payload in place.
96+      and you mutate the list object, you modify the message's payload in place.
92
n93-   With optional argument *i*, :meth:`get_payload` will return the *i*-th element
n98+      With optional argument *i*, :meth:`get_payload` will return the *i*-th
94-   of the payload, counting from zero, if :meth:`is_multipart` is ``True``.  An
99+      element of the payload, counting from zero, if :meth:`is_multipart` is
95-   :exc:`IndexError` will be raised if *i* is less than 0 or greater than or equal
100+      ``True``.  An :exc:`IndexError` will be raised if *i* is less than 0 or
96-   to the number of items in the payload.  If the payload is a string (i.e.
101+      greater than or equal to the number of items in the payload.  If the
97-   :meth:`is_multipart` is ``False``) and *i* is given, a :exc:`TypeError` is
102+      payload is a string (i.e.  :meth:`is_multipart` is ``False``) and *i* is
98-   raised.
103+      given, a :exc:`TypeError` is raised.
99
n100-   Optional *decode* is a flag indicating whether the payload should be decoded or
n105+      Optional *decode* is a flag indicating whether the payload should be
101-   not, according to the :mailheader:`Content-Transfer-Encoding` header. When
106+      decoded or not, according to the :mailheader:`Content-Transfer-Encoding`
102-   ``True`` and the message is not a multipart, the payload will be decoded if this
107+      header. When ``True`` and the message is not a multipart, the payload will
103-   header's value is ``quoted-printable`` or ``base64``.  If some other encoding is
108+      be decoded if this header's value is ``quoted-printable`` or ``base64``.
104-   used, or :mailheader:`Content-Transfer-Encoding` header is missing, or if the
109+      If some other encoding is used, or :mailheader:`Content-Transfer-Encoding`
105-   payload has bogus base64 data, the payload is returned as-is (undecoded).  If
110+      header is missing, or if the payload has bogus base64 data, the payload is
106-   the message is a multipart and the *decode* flag is ``True``, then ``None`` is
111+      returned as-is (undecoded).  If the message is a multipart and the
107-   returned.  The default for *decode* is ``False``.
112+      *decode* flag is ``True``, then ``None`` is returned.  The default for
113+      *decode* is ``False``.
108
109
n110-.. method:: Message.set_payload(payload[, charset])
n116+   .. method:: set_payload(payload[, charset])
111
n112-   Set the entire message object's payload to *payload*.  It is the client's
n118+      Set the entire message object's payload to *payload*.  It is the client's
113-   responsibility to ensure the payload invariants.  Optional *charset* sets the
119+      responsibility to ensure the payload invariants.  Optional *charset* sets
114-   message's default character set; see :meth:`set_charset` for details.
120+      the message's default character set; see :meth:`set_charset` for details.
115
n116-   .. versionchanged:: 2.2.2
n122+      .. versionchanged:: 2.2.2
117-      *charset* argument added.
123+         *charset* argument added.
118
119
n120-.. method:: Message.set_charset(charset)
n126+   .. method:: set_charset(charset)
121
n122-   Set the character set of the payload to *charset*, which can either be a
n128+      Set the character set of the payload to *charset*, which can either be a
123-   :class:`Charset` instance (see :mod:`email.charset`), a string naming a
129+      :class:`Charset` instance (see :mod:`email.charset`), a string naming a
124-   character set, or ``None``.  If it is a string, it will be converted to a
130+      character set, or ``None``.  If it is a string, it will be converted to a
125-   :class:`Charset` instance.  If *charset* is ``None``, the ``charset`` parameter
131+      :class:`Charset` instance.  If *charset* is ``None``, the ``charset``
126-   will be removed from the :mailheader:`Content-Type` header. Anything else will
132+      parameter will be removed from the :mailheader:`Content-Type`
127-   generate a :exc:`TypeError`.
133+      header. Anything else will generate a :exc:`TypeError`.
128
n129-   The message will be assumed to be of type :mimetype:`text/\*` encoded with
n135+      The message will be assumed to be of type :mimetype:`text/\*` encoded with
130-   *charset.input_charset*.  It will be converted to *charset.output_charset* and
136+      *charset.input_charset*.  It will be converted to *charset.output_charset*
131-   encoded properly, if needed, when generating the plain text representation of
137+      and encoded properly, if needed, when generating the plain text
132-   the message.  MIME headers (:mailheader:`MIME-Version`,
138+      representation of the message.  MIME headers (:mailheader:`MIME-Version`,
133-   :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will be
139+      :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will
134-   added as needed.
140+      be added as needed.
135
n136-   .. versionadded:: 2.2.2
n142+      .. versionadded:: 2.2.2
137
138
n139-.. method:: Message.get_charset()
n145+   .. method:: get_charset()
140
n141-   Return the :class:`Charset` instance associated with the message's payload.
n147+      Return the :class:`Charset` instance associated with the message's
148+      payload.
142
n143-   .. versionadded:: 2.2.2
n150+      .. versionadded:: 2.2.2
144
n145-The following methods implement a mapping-like interface for accessing the
n152+   The following methods implement a mapping-like interface for accessing the
146-message's :rfc:`2822` headers.  Note that there are some semantic differences
153+   message's :rfc:`2822` headers.  Note that there are some semantic differences
147-between these methods and a normal mapping (i.e. dictionary) interface.  For
154+   between these methods and a normal mapping (i.e. dictionary) interface.  For
148-example, in a dictionary there are no duplicate keys, but here there may be
155+   example, in a dictionary there are no duplicate keys, but here there may be
149-duplicate message headers.  Also, in dictionaries there is no guaranteed order
156+   duplicate message headers.  Also, in dictionaries there is no guaranteed
150-to the keys returned by :meth:`keys`, but in a :class:`Message` object, headers
157+   order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
151-are always returned in the order they appeared in the original message, or were
158+   headers are always returned in the order they appeared in the original
152-added to the message later.  Any header deleted and then re-added are always
159+   message, or were added to the message later.  Any header deleted and then
153-appended to the end of the header list.
160+   re-added are always appended to the end of the header list.
154
n155-These semantic differences are intentional and are biased toward maximal
n162+   These semantic differences are intentional and are biased toward maximal
156-convenience.
163+   convenience.
157
n158-Note that in all cases, any envelope header present in the message is not
n165+   Note that in all cases, any envelope header present in the message is not
159-included in the mapping interface.
166+   included in the mapping interface.
160
161
n162-.. method:: Message.__len__()
n169+   .. method:: __len__()
163
n164-   Return the total number of headers, including duplicates.
n171+      Return the total number of headers, including duplicates.
165
166
n167-.. method:: Message.__contains__(name)
n174+   .. method:: __contains__(name)
168
n169-   Return true if the message object has a field named *name*. Matching is done
n176+      Return true if the message object has a field named *name*. Matching is
170-   case-insensitively and *name* should not include the trailing colon.  Used for
177+      done case-insensitively and *name* should not include the trailing colon.
171-   the ``in`` operator, e.g.::
178+      Used for the ``in`` operator, e.g.::
172
n173-      if 'message-id' in myMessage:
n180+         if 'message-id' in myMessage:
174-          print 'Message-ID:', myMessage['message-id']
181+             print 'Message-ID:', myMessage['message-id']
175
176
n177-.. method:: Message.__getitem__(name)
n184+   .. method:: __getitem__(name)
178
n179-   Return the value of the named header field.  *name* should not include the colon
n186+      Return the value of the named header field.  *name* should not include the
180-   field separator.  If the header is missing, ``None`` is returned; a
187+      colon field separator.  If the header is missing, ``None`` is returned; a
181-   :exc:`KeyError` is never raised.
188+      :exc:`KeyError` is never raised.
182
n183-   Note that if the named field appears more than once in the message's headers,
n190+      Note that if the named field appears more than once in the message's
184-   exactly which of those field values will be returned is undefined.  Use the
191+      headers, exactly which of those field values will be returned is
185-   :meth:`get_all` method to get the values of all the extant named headers.
192+      undefined.  Use the :meth:`get_all` method to get the values of all the
193+      extant named headers.
186
187
n188-.. method:: Message.__setitem__(name, val)
n196+   .. method:: __setitem__(name, val)
189
n190-   Add a header to the message with field name *name* and value *val*.  The field
n198+      Add a header to the message with field name *name* and value *val*.  The
191-   is appended to the end of the message's existing fields.
199+      field is appended to the end of the message's existing fields.
192
n193-   Note that this does *not* overwrite or delete any existing header with the same
n201+      Note that this does *not* overwrite or delete any existing header with the same
194-   name.  If you want to ensure that the new header is the only one present in the
202+      name.  If you want to ensure that the new header is the only one present in the
195-   message with field name *name*, delete the field first, e.g.::
203+      message with field name *name*, delete the field first, e.g.::
196
n197-      del msg['subject']
n205+         del msg['subject']
198-      msg['subject'] = 'Python roolz!'
206+         msg['subject'] = 'Python roolz!'
199
200
n201-.. method:: Message.__delitem__(name)
n209+   .. method:: __delitem__(name)
202
n203-   Delete all occurrences of the field with name *name* from the message's headers.
n211+      Delete all occurrences of the field with name *name* from the message's
204-   No exception is raised if the named field isn't present in the headers.
212+      headers.  No exception is raised if the named field isn't present in the headers.
205
206
n207-.. method:: Message.has_key(name)
n215+   .. method:: has_key(name)
208
n209-   Return true if the message contains a header field named *name*, otherwise
n217+      Return true if the message contains a header field named *name*, otherwise
210-   return false.
218+      return false.
211
212
n213-.. method:: Message.keys()
n221+   .. method:: keys()
214
n215-   Return a list of all the message's header field names.
n223+      Return a list of all the message's header field names.
216
217
n218-.. method:: Message.values()
n226+   .. method:: values()
219
n220-   Return a list of all the message's field values.
n228+      Return a list of all the message's field values.
221
222
n223-.. method:: Message.items()
n231+   .. method:: items()
224
n225-   Return a list of 2-tuples containing all the message's field headers and values.
n233+      Return a list of 2-tuples containing all the message's field headers and
234+      values.
226
227
n228-.. method:: Message.get(name[, failobj])
n237+   .. method:: get(name[, failobj])
229
n230-   Return the value of the named header field.  This is identical to
n239+      Return the value of the named header field.  This is identical to
231-   :meth:`__getitem__` except that optional *failobj* is returned if the named
240+      :meth:`__getitem__` except that optional *failobj* is returned if the
232-   header is missing (defaults to ``None``).
241+      named header is missing (defaults to ``None``).
233
n234-Here are some additional useful methods:
n243+   Here are some additional useful methods:
235
236
n237-.. method:: Message.get_all(name[, failobj])
n246+   .. method:: get_all(name[, failobj])
238
n239-   Return a list of all the values for the field named *name*. If there are no such
n248+      Return a list of all the values for the field named *name*. If there are
240-   named headers in the message, *failobj* is returned (defaults to ``None``).
249+      no such named headers in the message, *failobj* is returned (defaults to
250+      ``None``).
241
242
n243-.. method:: Message.add_header(_name, _value, **_params)
n253+   .. method:: add_header(_name, _value, **_params)
244
n245-   Extended header setting.  This method is similar to :meth:`__setitem__` except
n255+      Extended header setting.  This method is similar to :meth:`__setitem__`
246-   that additional header parameters can be provided as keyword arguments.  *_name*
256+      except that additional header parameters can be provided as keyword
247-   is the header field to add and *_value* is the *primary* value for the header.
257+      arguments.  *_name* is the header field to add and *_value* is the
258+      *primary* value for the header.
248
n249-   For each item in the keyword argument dictionary *_params*, the key is taken as
n260+      For each item in the keyword argument dictionary *_params*, the key is
250-   the parameter name, with underscores converted to dashes (since dashes are
261+      taken as the parameter name, with underscores converted to dashes (since
251-   illegal in Python identifiers).  Normally, the parameter will be added as
262+      dashes are illegal in Python identifiers).  Normally, the parameter will
252-   ``key="value"`` unless the value is ``None``, in which case only the key will be
263+      be added as ``key="value"`` unless the value is ``None``, in which case
253-   added.
264+      only the key will be added.
254
n255-   Here's an example::
n266+      Here's an example::
256
n257-      msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
n268+         msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
258
n259-   This will add a header that looks like ::
n270+      This will add a header that looks like ::
260
n261-      Content-Disposition: attachment; filename="bud.gif"
n272+         Content-Disposition: attachment; filename="bud.gif"
262
263
n264-.. method:: Message.replace_header(_name, _value)
n275+   .. method:: replace_header(_name, _value)
265
n266-   Replace a header.  Replace the first header found in the message that matches
n277+      Replace a header.  Replace the first header found in the message that
267-   *_name*, retaining header order and field name case.  If no matching header was
278+      matches *_name*, retaining header order and field name case.  If no
268-   found, a :exc:`KeyError` is raised.
279+      matching header was found, a :exc:`KeyError` is raised.
269
n270-   .. versionadded:: 2.2.2
n281+      .. versionadded:: 2.2.2
271
272
n273-.. method:: Message.get_content_type()
n284+   .. method:: get_content_type()
274
n275-   Return the message's content type.  The returned string is coerced to lower case
n286+      Return the message's content type.  The returned string is coerced to
276-   of the form :mimetype:`maintype/subtype`.  If there was no
287+      lower case of the form :mimetype:`maintype/subtype`.  If there was no
277-   :mailheader:`Content-Type` header in the message the default type as given by
288+      :mailheader:`Content-Type` header in the message the default type as given
278-   :meth:`get_default_type` will be returned.  Since according to :rfc:`2045`,
289+      by :meth:`get_default_type` will be returned.  Since according to
279-   messages always have a default type, :meth:`get_content_type` will always return
290+      :rfc:`2045`, messages always have a default type, :meth:`get_content_type`
280-   a value.
291+      will always return a value.
281
n282-   :rfc:`2045` defines a message's default type to be :mimetype:`text/plain` unless
n293+      :rfc:`2045` defines a message's default type to be :mimetype:`text/plain`
283-   it appears inside a :mimetype:`multipart/digest` container, in which case it
294+      unless it appears inside a :mimetype:`multipart/digest` container, in
284-   would be :mimetype:`message/rfc822`.  If the :mailheader:`Content-Type` header
295+      which case it would be :mimetype:`message/rfc822`.  If the
285-   has an invalid type specification, :rfc:`2045` mandates that the default type be
296+      :mailheader:`Content-Type` header has an invalid type specification,
286-   :mimetype:`text/plain`.
297+      :rfc:`2045` mandates that the default type be :mimetype:`text/plain`.
287
n288-   .. versionadded:: 2.2.2
n299+      .. versionadded:: 2.2.2
289
290
n291-.. method:: Message.get_content_maintype()
n302+   .. method:: get_content_maintype()
292
n293-   Return the message's main content type.  This is the :mimetype:`maintype` part
n304+      Return the message's main content type.  This is the :mimetype:`maintype`
294-   of the string returned by :meth:`get_content_type`.
305+      part of the string returned by :meth:`get_content_type`.
295
n296-   .. versionadded:: 2.2.2
n307+      .. versionadded:: 2.2.2
297
298
n299-.. method:: Message.get_content_subtype()
n310+   .. method:: get_content_subtype()
300
n301-   Return the message's sub-content type.  This is the :mimetype:`subtype` part of
n312+      Return the message's sub-content type.  This is the :mimetype:`subtype`
302-   the string returned by :meth:`get_content_type`.
313+      part of the string returned by :meth:`get_content_type`.
303
n304-   .. versionadded:: 2.2.2
n315+      .. versionadded:: 2.2.2
305
306
n307-.. method:: Message.get_default_type()
n318+   .. method:: get_default_type()
308
n309-   Return the default content type.  Most messages have a default content type of
n320+      Return the default content type.  Most messages have a default content
310-   :mimetype:`text/plain`, except for messages that are subparts of
321+      type of :mimetype:`text/plain`, except for messages that are subparts of
311-   :mimetype:`multipart/digest` containers.  Such subparts have a default content
322+      :mimetype:`multipart/digest` containers.  Such subparts have a default
312-   type of :mimetype:`message/rfc822`.
323+      content type of :mimetype:`message/rfc822`.
313
n314-   .. versionadded:: 2.2.2
n325+      .. versionadded:: 2.2.2
315
316
n317-.. method:: Message.set_default_type(ctype)
n328+   .. method:: set_default_type(ctype)
318
n319-   Set the default content type.  *ctype* should either be :mimetype:`text/plain`
n330+      Set the default content type.  *ctype* should either be
320-   or :mimetype:`message/rfc822`, although this is not enforced.  The default
331+      :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not
321-   content type is not stored in the :mailheader:`Content-Type` header.
332+      enforced.  The default content type is not stored in the
333+      :mailheader:`Content-Type` header.
322
n323-   .. versionadded:: 2.2.2
n335+      .. versionadded:: 2.2.2
324
325
n326-.. method:: Message.get_params([failobj[, header[, unquote]]])
n338+   .. method:: get_params([failobj[, header[, unquote]]])
327
n328-   Return the message's :mailheader:`Content-Type` parameters, as a list.  The
n340+      Return the message's :mailheader:`Content-Type` parameters, as a list.
329-   elements of the returned list are 2-tuples of key/value pairs, as split on the
341+      The elements of the returned list are 2-tuples of key/value pairs, as
330-   ``'='`` sign.  The left hand side of the ``'='`` is the key, while the right
342+      split on the ``'='`` sign.  The left hand side of the ``'='`` is the key,
331-   hand side is the value.  If there is no ``'='`` sign in the parameter the value
343+      while the right hand side is the value.  If there is no ``'='`` sign in
332-   is the empty string, otherwise the value is as described in :meth:`get_param`
344+      the parameter the value is the empty string, otherwise the value is as
333-   and is unquoted if optional *unquote* is ``True`` (the default).
345+      described in :meth:`get_param` and is unquoted if optional *unquote* is
346+      ``True`` (the default).
334
n335-   Optional *failobj* is the object to return if there is no
n348+      Optional *failobj* is the object to return if there is no
336-   :mailheader:`Content-Type` header.  Optional *header* is the header to search
349+      :mailheader:`Content-Type` header.  Optional *header* is the header to
337-   instead of :mailheader:`Content-Type`.
350+      search instead of :mailheader:`Content-Type`.
338
n339-   .. versionchanged:: 2.2.2
n352+      .. versionchanged:: 2.2.2
340-      *unquote* argument added.
353+         *unquote* argument added.
341
342
n343-.. method:: Message.get_param(param[, failobj[, header[, unquote]]])
n356+   .. method:: get_param(param[, failobj[, header[, unquote]]])
344
n345-   Return the value of the :mailheader:`Content-Type` header's parameter *param* as
n358+      Return the value of the :mailheader:`Content-Type` header's parameter
346-   a string.  If the message has no :mailheader:`Content-Type` header or if there
359+      *param* as a string.  If the message has no :mailheader:`Content-Type`
347-   is no such parameter, then *failobj* is returned (defaults to ``None``).
360+      header or if there is no such parameter, then *failobj* is returned
361+      (defaults to ``None``).
348
n349-   Optional *header* if given, specifies the message header to use instead of
n363+      Optional *header* if given, specifies the message header to use instead of
350-   :mailheader:`Content-Type`.
364+      :mailheader:`Content-Type`.
351
n352-   Parameter keys are always compared case insensitively.  The return value can
n366+      Parameter keys are always compared case insensitively.  The return value
353-   either be a string, or a 3-tuple if the parameter was :rfc:`2231` encoded.  When
367+      can either be a string, or a 3-tuple if the parameter was :rfc:`2231`
354-   it's a 3-tuple, the elements of the value are of the form ``(CHARSET, LANGUAGE,
368+      encoded.  When it's a 3-tuple, the elements of the value are of the form
355-   VALUE)``.  Note that both ``CHARSET`` and ``LANGUAGE`` can be ``None``, in which
369+      ``(CHARSET, LANGUAGE, VALUE)``.  Note that both ``CHARSET`` and
356-   case you should consider ``VALUE`` to be encoded in the ``us-ascii`` charset.
370+      ``LANGUAGE`` can be ``None``, in which case you should consider ``VALUE``
357-   You can usually ignore ``LANGUAGE``.
371+      to be encoded in the ``us-ascii`` charset.  You can usually ignore
372+      ``LANGUAGE``.
358
n359-   If your application doesn't care whether the parameter was encoded as in
n374+      If your application doesn't care whether the parameter was encoded as in
360-   :rfc:`2231`, you can collapse the parameter value by calling
375+      :rfc:`2231`, you can collapse the parameter value by calling
361-   :func:`email.Utils.collapse_rfc2231_value`, passing in the return value from
376+      :func:`email.utils.collapse_rfc2231_value`, passing in the return value
362-   :meth:`get_param`.  This will return a suitably decoded Unicode string whn the
377+      from :meth:`get_param`.  This will return a suitably decoded Unicode
363-   value is a tuple, or the original string unquoted if it isn't.  For example::
378+      string whn the value is a tuple, or the original string unquoted if it
379+      isn't.  For example::
364
n365-      rawparam = msg.get_param('foo')
n381+         rawparam = msg.get_param('foo')
366-      param = email.Utils.collapse_rfc2231_value(rawparam)
382+         param = email.utils.collapse_rfc2231_value(rawparam)
367
n368-   In any case, the parameter value (either the returned string, or the ``VALUE``
n384+      In any case, the parameter value (either the returned string, or the
369-   item in the 3-tuple) is always unquoted, unless *unquote* is set to ``False``.
385+      ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
386+      to ``False``.
370
n371-   .. versionchanged:: 2.2.2
n388+      .. versionchanged:: 2.2.2
372-      *unquote* argument added, and 3-tuple return value possible.
389+         *unquote* argument added, and 3-tuple return value possible.
373
374
n375-.. method:: Message.set_param(param, value[, header[, requote[, charset[, language]]]])
n392+   .. method:: set_param(param, value[, header[, requote[, charset[, language]]]])
376
n377-   Set a parameter in the :mailheader:`Content-Type` header.  If the parameter
n394+      Set a parameter in the :mailheader:`Content-Type` header.  If the
378-   already exists in the header, its value will be replaced with *value*.  If the
395+      parameter already exists in the header, its value will be replaced with
379-   :mailheader:`Content-Type` header as not yet been defined for this message, it
396+      *value*.  If the :mailheader:`Content-Type` header as not yet been defined
380-   will be set to :mimetype:`text/plain` and the new parameter value will be
397+      for this message, it will be set to :mimetype:`text/plain` and the new
381-   appended as per :rfc:`2045`.
398+      parameter value will be appended as per :rfc:`2045`.
382
n383-   Optional *header* specifies an alternative header to :mailheader:`Content-Type`,
n400+      Optional *header* specifies an alternative header to
384-   and all parameters will be quoted as necessary unless optional *requote* is
401+      :mailheader:`Content-Type`, and all parameters will be quoted as necessary
385-   ``False`` (the default is ``True``).
402+      unless optional *requote* is ``False`` (the default is ``True``).
386
n387-   If optional *charset* is specified, the parameter will be encoded according to
n404+      If optional *charset* is specified, the parameter will be encoded
388-   :rfc:`2231`. Optional *language* specifies the RFC 2231 language, defaulting to
405+      according to :rfc:`2231`. Optional *language* specifies the RFC 2231
389-   the empty string.  Both *charset* and *language* should be strings.
406+      language, defaulting to the empty string.  Both *charset* and *language*
407+      should be strings.
390
n391-   .. versionadded:: 2.2.2
n409+      .. versionadded:: 2.2.2
392
393
n394-.. method:: Message.del_param(param[, header[, requote]])
n412+   .. method:: del_param(param[, header[, requote]])
395
n396-   Remove the given parameter completely from the :mailheader:`Content-Type`
n414+      Remove the given parameter completely from the :mailheader:`Content-Type`
397-   header.  The header will be re-written in place without the parameter or its
415+      header.  The header will be re-written in place without the parameter or
398-   value.  All values will be quoted as necessary unless *requote* is ``False``
416+      its value.  All values will be quoted as necessary unless *requote* is
399-   (the default is ``True``).  Optional *header* specifies an alternative to
417+      ``False`` (the default is ``True``).  Optional *header* specifies an
400-   :mailheader:`Content-Type`.
418+      alternative to :mailheader:`Content-Type`.
401
n402-   .. versionadded:: 2.2.2
n420+      .. versionadded:: 2.2.2
403
404
n405-.. method:: Message.set_type(type[, header][, requote])
n423+   .. method:: set_type(type[, header][, requote])
406
n407-   Set the main type and subtype for the :mailheader:`Content-Type` header. *type*
n425+      Set the main type and subtype for the :mailheader:`Content-Type`
408-   must be a string in the form :mimetype:`maintype/subtype`, otherwise a
426+      header. *type* must be a string in the form :mimetype:`maintype/subtype`,
409-   :exc:`ValueError` is raised.
427+      otherwise a :exc:`ValueError` is raised.
410
n411-   This method replaces the :mailheader:`Content-Type` header, keeping all the
n429+      This method replaces the :mailheader:`Content-Type` header, keeping all
412-   parameters in place.  If *requote* is ``False``, this leaves the existing
430+      the parameters in place.  If *requote* is ``False``, this leaves the
413-   header's quoting as is, otherwise the parameters will be quoted (the default).
431+      existing header's quoting as is, otherwise the parameters will be quoted
432+      (the default).
414
n415-   An alternative header can be specified in the *header* argument. When the
n434+      An alternative header can be specified in the *header* argument. When the
416-   :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` header is
435+      :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version`
417-   also added.
436+      header is also added.
418
n419-   .. versionadded:: 2.2.2
n438+      .. versionadded:: 2.2.2
420
421
n422-.. method:: Message.get_filename([failobj])
n441+   .. method:: get_filename([failobj])
423
n424-   Return the value of the ``filename`` parameter of the
n443+      Return the value of the ``filename`` parameter of the
425-   :mailheader:`Content-Disposition` header of the message.  If the header does not
444+      :mailheader:`Content-Disposition` header of the message.  If the header
426-   have a ``filename`` parameter, this method falls back to looking for the
445+      does not have a ``filename`` parameter, this method falls back to looking
427-   ``name`` parameter.  If neither is found, or the header is missing, then
446+      for the ``name`` parameter.  If neither is found, or the header is
428-   *failobj* is returned.  The returned string will always be unquoted as per
447+      missing, then *failobj* is returned.  The returned string will always be
429-   :meth:`Utils.unquote`.
448+      unquoted as per :func:`email.utils.unquote`.
430
431
n432-.. method:: Message.get_boundary([failobj])
n451+   .. method:: get_boundary([failobj])
433
n434-   Return the value of the ``boundary`` parameter of the :mailheader:`Content-Type`
n453+      Return the value of the ``boundary`` parameter of the
435-   header of the message, or *failobj* if either the header is missing, or has no
454+      :mailheader:`Content-Type` header of the message, or *failobj* if either
436-   ``boundary`` parameter.  The returned string will always be unquoted as per
455+      the header is missing, or has no ``boundary`` parameter.  The returned
437-   :meth:`Utils.unquote`.
456+      string will always be unquoted as per :func:`email.utils.unquote`.
438
439
n440-.. method:: Message.set_boundary(boundary)
n459+   .. method:: set_boundary(boundary)
441
n442-   Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
n461+      Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
443-   *boundary*.  :meth:`set_boundary` will always quote *boundary* if necessary.  A
462+      *boundary*.  :meth:`set_boundary` will always quote *boundary* if
444-   :exc:`HeaderParseError` is raised if the message object has no
463+      necessary.  A :exc:`HeaderParseError` is raised if the message object has
445-   :mailheader:`Content-Type` header.
464+      no :mailheader:`Content-Type` header.
446
n447-   Note that using this method is subtly different than deleting the old
n466+      Note that using this method is subtly different than deleting the old
448-   :mailheader:`Content-Type` header and adding a new one with the new boundary via
467+      :mailheader:`Content-Type` header and adding a new one with the new
449-   :meth:`add_header`, because :meth:`set_boundary` preserves the order of the
468+      boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
450-   :mailheader:`Content-Type` header in the list of headers. However, it does *not*
469+      the order of the :mailheader:`Content-Type` header in the list of
451-   preserve any continuation lines which may have been present in the original
470+      headers. However, it does *not* preserve any continuation lines which may
452-   :mailheader:`Content-Type` header.
471+      have been present in the original :mailheader:`Content-Type` header.
453
454
n455-.. method:: Message.get_content_charset([failobj])
n474+   .. method:: get_content_charset([failobj])
456
n457-   Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
n476+      Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
458-   coerced to lower case.  If there is no :mailheader:`Content-Type` header, or if
477+      coerced to lower case.  If there is no :mailheader:`Content-Type` header, or if
459-   that header has no ``charset`` parameter, *failobj* is returned.
478+      that header has no ``charset`` parameter, *failobj* is returned.
460
n461-   Note that this method differs from :meth:`get_charset` which returns the
n480+      Note that this method differs from :meth:`get_charset` which returns the
462-   :class:`Charset` instance for the default encoding of the message body.
481+      :class:`Charset` instance for the default encoding of the message body.
463
n464-   .. versionadded:: 2.2.2
n483+      .. versionadded:: 2.2.2
465
466
n467-.. method:: Message.get_charsets([failobj])
n486+   .. method:: get_charsets([failobj])
468
n469-   Return a list containing the character set names in the message.  If the message
n488+      Return a list containing the character set names in the message.  If the
470-   is a :mimetype:`multipart`, then the list will contain one element for each
489+      message is a :mimetype:`multipart`, then the list will contain one element
471-   subpart in the payload, otherwise, it will be a list of length 1.
490+      for each subpart in the payload, otherwise, it will be a list of length 1.
472
n473-   Each item in the list will be a string which is the value of the ``charset``
n492+      Each item in the list will be a string which is the value of the
474-   parameter in the :mailheader:`Content-Type` header for the represented subpart.
493+      ``charset`` parameter in the :mailheader:`Content-Type` header for the
475-   However, if the subpart has no :mailheader:`Content-Type` header, no ``charset``
494+      represented subpart.  However, if the subpart has no
476-   parameter, or is not of the :mimetype:`text` main MIME type, then that item in
495+      :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of
477-   the returned list will be *failobj*.
496+      the :mimetype:`text` main MIME type, then that item in the returned list
497+      will be *failobj*.
478
479
n480-.. method:: Message.walk()
n500+   .. method:: walk()
481
n482-   The :meth:`walk` method is an all-purpose generator which can be used to iterate
n502+      The :meth:`walk` method is an all-purpose generator which can be used to
483-   over all the parts and subparts of a message object tree, in depth-first
503+      iterate over all the parts and subparts of a message object tree, in
484-   traversal order.  You will typically use :meth:`walk` as the iterator in a
504+      depth-first traversal order.  You will typically use :meth:`walk` as the
485-   ``for`` loop; each iteration returns the next subpart.
505+      iterator in a ``for`` loop; each iteration returns the next subpart.
486
n487-   Here's an example that prints the MIME type of every part of a multipart message
n507+      Here's an example that prints the MIME type of every part of a multipart
488-   structure::
508+      message structure::
489
n490-      >>> for part in msg.walk():
n510+         >>> for part in msg.walk():
491-      ...     print part.get_content_type()
511+         ...     print part.get_content_type()
492-      multipart/report
512+         multipart/report
493-      text/plain
513+         text/plain
494-      message/delivery-status
514+         message/delivery-status
495-      text/plain
515+         text/plain
496-      text/plain
516+         text/plain
497-      message/rfc822
517+         message/rfc822
498- 
499-.. versionchanged:: 2.5
500-   The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
501-   :meth:`get_subtype` were removed.
502- 
503-:class:`Message` objects can also optionally contain two instance attributes,
504-which can be used when generating the plain text of a MIME message.
505- 
506- 
507-.. data:: preamble
508- 
509-   The format of a MIME document allows for some text between the blank line
510-   following the headers, and the first multipart boundary string. Normally, this
511-   text is never visible in a MIME-aware mail reader because it falls outside the
512-   standard MIME armor.  However, when viewing the raw text of the message, or when
513-   viewing the message in a non-MIME aware reader, this text can become visible.
514- 
515-   The *preamble* attribute contains this leading extra-armor text for MIME
516-   documents.  When the :class:`Parser` discovers some text after the headers but
517-   before the first boundary string, it assigns this text to the message's
518-   *preamble* attribute.  When the :class:`Generator` is writing out the plain text
519-   representation of a MIME message, and it finds the message has a *preamble*
520-   attribute, it will write this text in the area between the headers and the first
521-   boundary.  See :mod:`email.parser` and :mod:`email.generator` for details.
522- 
523-   Note that if the message object has no preamble, the *preamble* attribute will
524-   be ``None``.
525- 
526- 
527-.. data:: epilogue
528- 
529-   The *epilogue* attribute acts the same way as the *preamble* attribute, except
530-   that it contains text that appears between the last boundary and the end of the
531-   message.
532
533   .. versionchanged:: 2.5
n520+      The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
521+      :meth:`get_subtype` were removed.
522+ 
523+   :class:`Message` objects can also optionally contain two instance attributes,
524+   which can be used when generating the plain text of a MIME message.
525+ 
526+ 
527+   .. attribute:: preamble
528+ 
529+      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.
535+ 
536+      The *preamble* attribute contains this leading extra-armor text for MIME
537+      documents.  When the :class:`Parser` discovers some text after the headers
538+      but before the first boundary string, it assigns this text to the
539+      message's *preamble* attribute.  When the :class:`Generator` is writing
540+      out the plain text representation of a MIME message, and it finds the
541+      message has a *preamble* attribute, it will write this text in the area
542+      between the headers and the first boundary.  See :mod:`email.parser` and
543+      :mod:`email.generator` for details.
544+ 
545+      Note that if the message object has no preamble, the *preamble* attribute
546+      will be ``None``.
547+ 
548+ 
549+   .. attribute:: epilogue
550+ 
551+      The *epilogue* attribute acts the same way as the *preamble* attribute,
552+      except that it contains text that appears between the last boundary and
553+      the end of the message.
554+ 
555+      .. versionchanged:: 2.5
534-      You do not need to set the epilogue to the empty string in order for the
556+         You do not need to set the epilogue to the empty string in order for the
535-      :class:`Generator` to print a newline at the end of the file.
557+         :class:`Generator` to print a newline at the end of the file.
536
537
n538-.. data:: defects
n560+   .. attribute:: defects
539
n540-   The *defects* attribute contains a list of all the problems found when parsing
n562+      The *defects* attribute contains a list of all the problems found when
541-   this message.  See :mod:`email.errors` for a detailed description of the
563+      parsing this message.  See :mod:`email.errors` for a detailed description
542-   possible parsing defects.
564+      of the possible parsing defects.
543
t544-   .. versionadded:: 2.4
t566+      .. versionadded:: 2.4
545
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op