1.. _compat32_message:
2
3:mod:`email.message.Message`: Representing an email message using the :data:`~email.policy.compat32` API
4--------------------------------------------------------------------------------------------------------
5
6.. module:: email.message
7   :synopsis: The base class representing email messages in a fashion
8              backward compatible with Python 3.2
9   :noindex:
10
11
12The :class:`Message` class is very similar to the
13:class:`~email.message.EmailMessage` class, without the methods added by that
14class, and with the default behavior of certain other methods being slightly
15different.  We also document here some methods that, while supported by the
16:class:`~email.message.EmailMessage` class, are not recommended unless you are
17dealing with legacy code.
18
19The philosophy and structure of the two classes is otherwise the same.
20
21This document describes the behavior under the default (for :class:`Message`)
22policy :attr:`~email.policy.Compat32`.  If you are going to use another policy,
23you should be using the :class:`~email.message.EmailMessage` class instead.
24
25An email message consists of *headers* and a *payload*.  Headers must be
26:rfc:`5322` style names and values, where the field name and value are
27separated by a colon.  The colon is not part of either the field name or the
28field value.  The payload may be a simple text message, or a binary object, or
29a structured sequence of sub-messages each with their own set of headers and
30their own payload.  The latter type of payload is indicated by the message
31having a MIME type such as :mimetype:`multipart/\*` or
32:mimetype:`message/rfc822`.
33
34The conceptual model provided by a :class:`Message` object is that of an
35ordered dictionary of headers with additional methods for accessing both
36specialized information from the headers, for accessing the payload, for
37generating a serialized version of the message, and for recursively walking
38over the object tree.  Note that duplicate headers are supported but special
39methods must be used to access them.
40
41The :class:`Message` pseudo-dictionary is indexed by the header names, which
42must be ASCII values.  The values of the dictionary are strings that are
43supposed to contain only ASCII characters; there is some special handling for
44non-ASCII input, but it doesn't always produce the correct results.  Headers
45are stored and returned in case-preserving form, but field names are matched
46case-insensitively.  There may also be a single envelope header, also known as
47the *Unix-From* header or the ``From_`` header.  The *payload* is either a
48string or bytes, in the case of simple message objects, or a list of
49:class:`Message` objects, for MIME container documents (e.g.
50:mimetype:`multipart/\*` and :mimetype:`message/rfc822`).
51
52Here are the methods of the :class:`Message` class:
53
54
55.. class:: Message(policy=compat32)
56
57   If *policy* is specified (it must be an instance of a :mod:`~email.policy`
58   class) use the rules it specifies to update and serialize the representation
59   of the message.  If *policy* is not set, use the :class:`compat32
60   <email.policy.Compat32>` policy, which maintains backward compatibility with
61   the Python 3.2 version of the email package.  For more information see the
62   :mod:`~email.policy` documentation.
63
64   .. versionchanged:: 3.3 The *policy* keyword argument was added.
65
66
67   .. method:: as_string(unixfrom=False, maxheaderlen=0, policy=None)
68
69      Return the entire message flattened as a string.  When optional *unixfrom*
70      is true, the envelope header is included in the returned string.
71      *unixfrom* defaults to ``False``.  For backward compatibility reasons,
72      *maxheaderlen* defaults to ``0``, so if you want a different value you
73      must override it explicitly (the value specified for *max_line_length* in
74      the policy will be ignored by this method).  The *policy* argument may be
75      used to override the default policy obtained from the message instance.
76      This can be used to control some of the formatting produced by the
77      method, since the specified *policy* will be passed to the ``Generator``.
78
79      Flattening the message may trigger changes to the :class:`Message` if
80      defaults need to be filled in to complete the transformation to a string
81      (for example, MIME boundaries may be generated or modified).
82
83      Note that this method is provided as a convenience and may not always
84      format the message the way you want.  For example, by default it does
85      not do the mangling of lines that begin with ``From`` that is
86      required by the unix mbox format.  For more flexibility, instantiate a
87      :class:`~email.generator.Generator` instance and use its
88      :meth:`~email.generator.Generator.flatten` method directly.  For example::
89
90         from io import StringIO
91         from email.generator import Generator
92         fp = StringIO()
93         g = Generator(fp, mangle_from_=True, maxheaderlen=60)
94         g.flatten(msg)
95         text = fp.getvalue()
96
97      If the message object contains binary data that is not encoded according
98      to RFC standards, the non-compliant data will be replaced by unicode
99      "unknown character" code points.  (See also :meth:`.as_bytes` and
100      :class:`~email.generator.BytesGenerator`.)
101
102      .. versionchanged:: 3.4 the *policy* keyword argument was added.
103
104
105   .. method:: __str__()
106
107      Equivalent to :meth:`.as_string()`.  Allows ``str(msg)`` to produce a
108      string containing the formatted message.
109
110
111   .. method:: as_bytes(unixfrom=False, policy=None)
112
113      Return the entire message flattened as a bytes object.  When optional
114      *unixfrom* is true, the envelope header is included in the returned
115      string.  *unixfrom* defaults to ``False``.  The *policy* argument may be
116      used to override the default policy obtained from the message instance.
117      This can be used to control some of the formatting produced by the
118      method, since the specified *policy* will be passed to the
119      ``BytesGenerator``.
120
121      Flattening the message may trigger changes to the :class:`Message` if
122      defaults need to be filled in to complete the transformation to a string
123      (for example, MIME boundaries may be generated or modified).
124
125      Note that this method is provided as a convenience and may not always
126      format the message the way you want.  For example, by default it does
127      not do the mangling of lines that begin with ``From`` that is
128      required by the unix mbox format.  For more flexibility, instantiate a
129      :class:`~email.generator.BytesGenerator` instance and use its
130      :meth:`~email.generator.BytesGenerator.flatten` method directly.
131      For example::
132
133         from io import BytesIO
134         from email.generator import BytesGenerator
135         fp = BytesIO()
136         g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
137         g.flatten(msg)
138         text = fp.getvalue()
139
140      .. versionadded:: 3.4
141
142
143   .. method:: __bytes__()
144
145      Equivalent to :meth:`.as_bytes()`.  Allows ``bytes(msg)`` to produce a
146      bytes object containing the formatted message.
147
148      .. versionadded:: 3.4
149
150
151   .. method:: is_multipart()
152
153      Return ``True`` if the message's payload is a list of
154      sub-\ :class:`Message` objects, otherwise return ``False``.  When
155      :meth:`is_multipart` returns ``False``, the payload should be a string
156      object (which might be a CTE encoded binary payload).  (Note that
157      :meth:`is_multipart` returning ``True`` does not necessarily mean that
158      "msg.get_content_maintype() == 'multipart'" will return the ``True``.
159      For example, ``is_multipart`` will return ``True`` when the
160      :class:`Message` is of type ``message/rfc822``.)
161
162
163   .. method:: set_unixfrom(unixfrom)
164
165      Set the message's envelope header to *unixfrom*, which should be a string.
166
167
168   .. method:: get_unixfrom()
169
170      Return the message's envelope header.  Defaults to ``None`` if the
171      envelope header was never set.
172
173
174   .. method:: attach(payload)
175
176      Add the given *payload* to the current payload, which must be ``None`` or
177      a list of :class:`Message` objects before the call. After the call, the
178      payload will always be a list of :class:`Message` objects.  If you want to
179      set the payload to a scalar object (e.g. a string), use
180      :meth:`set_payload` instead.
181
182      This is a legacy method.  On the
183      :class:`~email.emailmessage.EmailMessage` class its functionality is
184      replaced by :meth:`~email.message.EmailMessage.set_content` and the
185      related ``make`` and ``add`` methods.
186
187
188   .. method:: get_payload(i=None, decode=False)
189
190      Return the current payload, which will be a list of
191      :class:`Message` objects when :meth:`is_multipart` is ``True``, or a
192      string when :meth:`is_multipart` is ``False``.  If the payload is a list
193      and you mutate the list object, you modify the message's payload in place.
194
195      With optional argument *i*, :meth:`get_payload` will return the *i*-th
196      element of the payload, counting from zero, if :meth:`is_multipart` is
197      ``True``.  An :exc:`IndexError` will be raised if *i* is less than 0 or
198      greater than or equal to the number of items in the payload.  If the
199      payload is a string (i.e.  :meth:`is_multipart` is ``False``) and *i* is
200      given, a :exc:`TypeError` is raised.
201
202      Optional *decode* is a flag indicating whether the payload should be
203      decoded or not, according to the :mailheader:`Content-Transfer-Encoding`
204      header. When ``True`` and the message is not a multipart, the payload will
205      be decoded if this header's value is ``quoted-printable`` or ``base64``.
206      If some other encoding is used, or :mailheader:`Content-Transfer-Encoding`
207      header is missing, the payload is
208      returned as-is (undecoded).  In all cases the returned value is binary
209      data.  If the message is a multipart and the *decode* flag is ``True``,
210      then ``None`` is returned.  If the payload is base64 and it was not
211      perfectly formed (missing padding, characters outside the base64
212      alphabet), then an appropriate defect will be added to the message's
213      defect property (:class:`~email.errors.InvalidBase64PaddingDefect` or
214      :class:`~email.errors.InvalidBase64CharactersDefect`, respectively).
215
216      When *decode* is ``False`` (the default) the body is returned as a string
217      without decoding the :mailheader:`Content-Transfer-Encoding`.  However,
218      for a :mailheader:`Content-Transfer-Encoding` of 8bit, an attempt is made
219      to decode the original bytes using the ``charset`` specified by the
220      :mailheader:`Content-Type` header, using the ``replace`` error handler.
221      If no ``charset`` is specified, or if the ``charset`` given is not
222      recognized by the email package, the body is decoded using the default
223      ASCII charset.
224
225      This is a legacy method.  On the
226      :class:`~email.emailmessage.EmailMessage` class its functionality is
227      replaced by :meth:`~email.message.EmailMessage.get_content` and
228      :meth:`~email.message.EmailMessage.iter_parts`.
229
230
231   .. method:: set_payload(payload, charset=None)
232
233      Set the entire message object's payload to *payload*.  It is the client's
234      responsibility to ensure the payload invariants.  Optional *charset* sets
235      the message's default character set; see :meth:`set_charset` for details.
236
237      This is a legacy method.  On the
238      :class:`~email.emailmessage.EmailMessage` class its functionality is
239      replaced by :meth:`~email.message.EmailMessage.set_content`.
240
241
242   .. method:: set_charset(charset)
243
244      Set the character set of the payload to *charset*, which can either be a
245      :class:`~email.charset.Charset` instance (see :mod:`email.charset`), a
246      string naming a character set, or ``None``.  If it is a string, it will
247      be converted to a :class:`~email.charset.Charset` instance.  If *charset*
248      is ``None``, the ``charset`` parameter will be removed from the
249      :mailheader:`Content-Type` header (the message will not be otherwise
250      modified).  Anything else will generate a :exc:`TypeError`.
251
252      If there is no existing :mailheader:`MIME-Version` header one will be
253      added.  If there is no existing :mailheader:`Content-Type` header, one
254      will be added with a value of :mimetype:`text/plain`.  Whether the
255      :mailheader:`Content-Type` header already exists or not, its ``charset``
256      parameter will be set to *charset.output_charset*.   If
257      *charset.input_charset* and *charset.output_charset* differ, the payload
258      will be re-encoded to the *output_charset*.  If there is no existing
259      :mailheader:`Content-Transfer-Encoding` header, then the payload will be
260      transfer-encoded, if needed, using the specified
261      :class:`~email.charset.Charset`, and a header with the appropriate value
262      will be added.  If a :mailheader:`Content-Transfer-Encoding` header
263      already exists, the payload is assumed to already be correctly encoded
264      using that :mailheader:`Content-Transfer-Encoding` and is not modified.
265
266      This is a legacy method.  On the
267      :class:`~email.emailmessage.EmailMessage` class its functionality is
268      replaced by the *charset* parameter of the
269      :meth:`email.emailmessage.EmailMessage.set_content` method.
270
271
272   .. method:: get_charset()
273
274      Return the :class:`~email.charset.Charset` instance associated with the
275      message's payload.
276
277      This is a legacy method.  On the
278      :class:`~email.emailmessage.EmailMessage` class it always returns
279      ``None``.
280
281
282   The following methods implement a mapping-like interface for accessing the
283   message's :rfc:`2822` headers.  Note that there are some semantic differences
284   between these methods and a normal mapping (i.e. dictionary) interface.  For
285   example, in a dictionary there are no duplicate keys, but here there may be
286   duplicate message headers.  Also, in dictionaries there is no guaranteed
287   order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
288   headers are always returned in the order they appeared in the original
289   message, or were added to the message later.  Any header deleted and then
290   re-added are always appended to the end of the header list.
291
292   These semantic differences are intentional and are biased toward maximal
293   convenience.
294
295   Note that in all cases, any envelope header present in the message is not
296   included in the mapping interface.
297
298   In a model generated from bytes, any header values that (in contravention of
299   the RFCs) contain non-ASCII bytes will, when retrieved through this
300   interface, be represented as :class:`~email.header.Header` objects with
301   a charset of `unknown-8bit`.
302
303
304   .. method:: __len__()
305
306      Return the total number of headers, including duplicates.
307
308
309   .. method:: __contains__(name)
310
311      Return ``True`` if the message object has a field named *name*. Matching is
312      done case-insensitively and *name* should not include the trailing colon.
313      Used for the ``in`` operator, e.g.::
314
315           if 'message-id' in myMessage:
316              print('Message-ID:', myMessage['message-id'])
317
318
319   .. method:: __getitem__(name)
320
321      Return the value of the named header field.  *name* should not include the
322      colon field separator.  If the header is missing, ``None`` is returned; a
323      :exc:`KeyError` is never raised.
324
325      Note that if the named field appears more than once in the message's
326      headers, exactly which of those field values will be returned is
327      undefined.  Use the :meth:`get_all` method to get the values of all the
328      extant named headers.
329
330
331   .. method:: __setitem__(name, val)
332
333      Add a header to the message with field name *name* and value *val*.  The
334      field is appended to the end of the message's existing fields.
335
336      Note that this does *not* overwrite or delete any existing header with the same
337      name.  If you want to ensure that the new header is the only one present in the
338      message with field name *name*, delete the field first, e.g.::
339
340         del msg['subject']
341         msg['subject'] = 'Python roolz!'
342
343
344   .. method:: __delitem__(name)
345
346      Delete all occurrences of the field with name *name* from the message's
347      headers.  No exception is raised if the named field isn't present in the
348      headers.
349
350
351   .. method:: keys()
352
353      Return a list of all the message's header field names.
354
355
356   .. method:: values()
357
358      Return a list of all the message's field values.
359
360
361   .. method:: items()
362
363      Return a list of 2-tuples containing all the message's field headers and
364      values.
365
366
367   .. method:: get(name, failobj=None)
368
369      Return the value of the named header field.  This is identical to
370      :meth:`__getitem__` except that optional *failobj* is returned if the
371      named header is missing (defaults to ``None``).
372
373   Here are some additional useful methods:
374
375
376   .. method:: get_all(name, failobj=None)
377
378      Return a list of all the values for the field named *name*. If there are
379      no such named headers in the message, *failobj* is returned (defaults to
380      ``None``).
381
382
383   .. method:: add_header(_name, _value, **_params)
384
385      Extended header setting.  This method is similar to :meth:`__setitem__`
386      except that additional header parameters can be provided as keyword
387      arguments.  *_name* is the header field to add and *_value* is the
388      *primary* value for the header.
389
390      For each item in the keyword argument dictionary *_params*, the key is
391      taken as the parameter name, with underscores converted to dashes (since
392      dashes are illegal in Python identifiers).  Normally, the parameter will
393      be added as ``key="value"`` unless the value is ``None``, in which case
394      only the key will be added.  If the value contains non-ASCII characters,
395      it can be specified as a three tuple in the format
396      ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
397      charset to be used to encode the value, ``LANGUAGE`` can usually be set
398      to ``None`` or the empty string (see :rfc:`2231` for other possibilities),
399      and ``VALUE`` is the string value containing non-ASCII code points.  If
400      a three tuple is not passed and the value contains non-ASCII characters,
401      it is automatically encoded in :rfc:`2231` format using a ``CHARSET``
402      of ``utf-8`` and a ``LANGUAGE`` of ``None``.
403
404      Here's an example::
405
406         msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
407
408      This will add a header that looks like ::
409
410         Content-Disposition: attachment; filename="bud.gif"
411
412      An example with non-ASCII characters::
413
414         msg.add_header('Content-Disposition', 'attachment',
415                        filename=('iso-8859-1', '', 'Fußballer.ppt'))
416
417      Which produces ::
418
419         Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
420
421
422   .. method:: replace_header(_name, _value)
423
424      Replace a header.  Replace the first header found in the message that
425      matches *_name*, retaining header order and field name case.  If no
426      matching header was found, a :exc:`KeyError` is raised.
427
428
429   .. method:: get_content_type()
430
431      Return the message's content type.  The returned string is coerced to
432      lower case of the form :mimetype:`maintype/subtype`.  If there was no
433      :mailheader:`Content-Type` header in the message the default type as given
434      by :meth:`get_default_type` will be returned.  Since according to
435      :rfc:`2045`, messages always have a default type, :meth:`get_content_type`
436      will always return a value.
437
438      :rfc:`2045` defines a message's default type to be :mimetype:`text/plain`
439      unless it appears inside a :mimetype:`multipart/digest` container, in
440      which case it would be :mimetype:`message/rfc822`.  If the
441      :mailheader:`Content-Type` header has an invalid type specification,
442      :rfc:`2045` mandates that the default type be :mimetype:`text/plain`.
443
444
445   .. method:: get_content_maintype()
446
447      Return the message's main content type.  This is the :mimetype:`maintype`
448      part of the string returned by :meth:`get_content_type`.
449
450
451   .. method:: get_content_subtype()
452
453      Return the message's sub-content type.  This is the :mimetype:`subtype`
454      part of the string returned by :meth:`get_content_type`.
455
456
457   .. method:: get_default_type()
458
459      Return the default content type.  Most messages have a default content
460      type of :mimetype:`text/plain`, except for messages that are subparts of
461      :mimetype:`multipart/digest` containers.  Such subparts have a default
462      content type of :mimetype:`message/rfc822`.
463
464
465   .. method:: set_default_type(ctype)
466
467      Set the default content type.  *ctype* should either be
468      :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not
469      enforced.  The default content type is not stored in the
470      :mailheader:`Content-Type` header.
471
472
473   .. method:: get_params(failobj=None, header='content-type', unquote=True)
474
475      Return the message's :mailheader:`Content-Type` parameters, as a list.
476      The elements of the returned list are 2-tuples of key/value pairs, as
477      split on the ``'='`` sign.  The left hand side of the ``'='`` is the key,
478      while the right hand side is the value.  If there is no ``'='`` sign in
479      the parameter the value is the empty string, otherwise the value is as
480      described in :meth:`get_param` and is unquoted if optional *unquote* is
481      ``True`` (the default).
482
483      Optional *failobj* is the object to return if there is no
484      :mailheader:`Content-Type` header.  Optional *header* is the header to
485      search instead of :mailheader:`Content-Type`.
486
487      This is a legacy method.  On the
488      :class:`~email.emailmessage.EmailMessage` class its functionality is
489      replaced by the *params* property of the individual header objects
490      returned by the header access methods.
491
492
493   .. method:: get_param(param, failobj=None, header='content-type', unquote=True)
494
495      Return the value of the :mailheader:`Content-Type` header's parameter
496      *param* as a string.  If the message has no :mailheader:`Content-Type`
497      header or if there is no such parameter, then *failobj* is returned
498      (defaults to ``None``).
499
500      Optional *header* if given, specifies the message header to use instead of
501      :mailheader:`Content-Type`.
502
503      Parameter keys are always compared case insensitively.  The return value
504      can either be a string, or a 3-tuple if the parameter was :rfc:`2231`
505      encoded.  When it's a 3-tuple, the elements of the value are of the form
506      ``(CHARSET, LANGUAGE, VALUE)``.  Note that both ``CHARSET`` and
507      ``LANGUAGE`` can be ``None``, in which case you should consider ``VALUE``
508      to be encoded in the ``us-ascii`` charset.  You can usually ignore
509      ``LANGUAGE``.
510
511      If your application doesn't care whether the parameter was encoded as in
512      :rfc:`2231`, you can collapse the parameter value by calling
513      :func:`email.utils.collapse_rfc2231_value`, passing in the return value
514      from :meth:`get_param`.  This will return a suitably decoded Unicode
515      string when the value is a tuple, or the original string unquoted if it
516      isn't.  For example::
517
518         rawparam = msg.get_param('foo')
519         param = email.utils.collapse_rfc2231_value(rawparam)
520
521      In any case, the parameter value (either the returned string, or the
522      ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
523      to ``False``.
524
525      This is a legacy method.  On the
526      :class:`~email.emailmessage.EmailMessage` class its functionality is
527      replaced by the *params* property of the individual header objects
528      returned by the header access methods.
529
530
531   .. method:: set_param(param, value, header='Content-Type', requote=True, \
532                         charset=None, language='', replace=False)
533
534      Set a parameter in the :mailheader:`Content-Type` header.  If the
535      parameter already exists in the header, its value will be replaced with
536      *value*.  If the :mailheader:`Content-Type` header as not yet been defined
537      for this message, it will be set to :mimetype:`text/plain` and the new
538      parameter value will be appended as per :rfc:`2045`.
539
540      Optional *header* specifies an alternative header to
541      :mailheader:`Content-Type`, and all parameters will be quoted as necessary
542      unless optional *requote* is ``False`` (the default is ``True``).
543
544      If optional *charset* is specified, the parameter will be encoded
545      according to :rfc:`2231`. Optional *language* specifies the RFC 2231
546      language, defaulting to the empty string.  Both *charset* and *language*
547      should be strings.
548
549      If *replace* is ``False`` (the default) the header is moved to the
550      end of the list of headers.  If *replace* is ``True``, the header
551      will be updated in place.
552
553      .. versionchanged:: 3.4 ``replace`` keyword was added.
554
555
556   .. method:: del_param(param, header='content-type', requote=True)
557
558      Remove the given parameter completely from the :mailheader:`Content-Type`
559      header.  The header will be re-written in place without the parameter or
560      its value.  All values will be quoted as necessary unless *requote* is
561      ``False`` (the default is ``True``).  Optional *header* specifies an
562      alternative to :mailheader:`Content-Type`.
563
564
565   .. method:: set_type(type, header='Content-Type', requote=True)
566
567      Set the main type and subtype for the :mailheader:`Content-Type`
568      header. *type* must be a string in the form :mimetype:`maintype/subtype`,
569      otherwise a :exc:`ValueError` is raised.
570
571      This method replaces the :mailheader:`Content-Type` header, keeping all
572      the parameters in place.  If *requote* is ``False``, this leaves the
573      existing header's quoting as is, otherwise the parameters will be quoted
574      (the default).
575
576      An alternative header can be specified in the *header* argument. When the
577      :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version`
578      header is also added.
579
580      This is a legacy method.  On the
581      :class:`~email.emailmessage.EmailMessage` class its functionality is
582      replaced by the ``make_`` and ``add_`` methods.
583
584
585   .. method:: get_filename(failobj=None)
586
587      Return the value of the ``filename`` parameter of the
588      :mailheader:`Content-Disposition` header of the message.  If the header
589      does not have a ``filename`` parameter, this method falls back to looking
590      for the ``name`` parameter on the :mailheader:`Content-Type` header.  If
591      neither is found, or the header is missing, then *failobj* is returned.
592      The returned string will always be unquoted as per
593      :func:`email.utils.unquote`.
594
595
596   .. method:: get_boundary(failobj=None)
597
598      Return the value of the ``boundary`` parameter of the
599      :mailheader:`Content-Type` header of the message, or *failobj* if either
600      the header is missing, or has no ``boundary`` parameter.  The returned
601      string will always be unquoted as per :func:`email.utils.unquote`.
602
603
604   .. method:: set_boundary(boundary)
605
606      Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
607      *boundary*.  :meth:`set_boundary` will always quote *boundary* if
608      necessary.  A :exc:`~email.errors.HeaderParseError` is raised if the
609      message object has no :mailheader:`Content-Type` header.
610
611      Note that using this method is subtly different than deleting the old
612      :mailheader:`Content-Type` header and adding a new one with the new
613      boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
614      the order of the :mailheader:`Content-Type` header in the list of
615      headers. However, it does *not* preserve any continuation lines which may
616      have been present in the original :mailheader:`Content-Type` header.
617
618
619   .. method:: get_content_charset(failobj=None)
620
621      Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
622      coerced to lower case.  If there is no :mailheader:`Content-Type` header, or if
623      that header has no ``charset`` parameter, *failobj* is returned.
624
625      Note that this method differs from :meth:`get_charset` which returns the
626      :class:`~email.charset.Charset` instance for the default encoding of the message body.
627
628
629   .. method:: get_charsets(failobj=None)
630
631      Return a list containing the character set names in the message.  If the
632      message is a :mimetype:`multipart`, then the list will contain one element
633      for each subpart in the payload, otherwise, it will be a list of length 1.
634
635      Each item in the list will be a string which is the value of the
636      ``charset`` parameter in the :mailheader:`Content-Type` header for the
637      represented subpart.  However, if the subpart has no
638      :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of
639      the :mimetype:`text` main MIME type, then that item in the returned list
640      will be *failobj*.
641
642
643   .. method:: get_content_disposition()
644
645      Return the lowercased value (without parameters) of the message's
646      :mailheader:`Content-Disposition` header if it has one, or ``None``.  The
647      possible values for this method are *inline*, *attachment* or ``None``
648      if the message follows :rfc:`2183`.
649
650      .. versionadded:: 3.5
651
652   .. method:: walk()
653
654      The :meth:`walk` method is an all-purpose generator which can be used to
655      iterate over all the parts and subparts of a message object tree, in
656      depth-first traversal order.  You will typically use :meth:`walk` as the
657      iterator in a ``for`` loop; each iteration returns the next subpart.
658
659      Here's an example that prints the MIME type of every part of a multipart
660      message structure:
661
662      .. testsetup::
663
664         import email
665         from email import message_from_binary_file
666         from os.path import join, dirname
667         lib_dir = dirname(dirname(email.__file__))
668         file_path = join(lib_dir, 'test/test_email/data/msg_16.txt')
669         with open(file_path, 'rb') as f:
670             msg = message_from_binary_file(f)
671         from email.iterators import _structure
672
673      .. doctest::
674
675         >>> for part in msg.walk():
676         ...     print(part.get_content_type())
677         multipart/report
678         text/plain
679         message/delivery-status
680         text/plain
681         text/plain
682         message/rfc822
683         text/plain
684
685      ``walk`` iterates over the subparts of any part where
686      :meth:`is_multipart` returns ``True``, even though
687      ``msg.get_content_maintype() == 'multipart'`` may return ``False``.  We
688      can see this in our example by making use of the ``_structure`` debug
689      helper function:
690
691      .. doctest::
692
693         >>> for part in msg.walk():
694         ...     print(part.get_content_maintype() == 'multipart',
695         ...           part.is_multipart())
696         True True
697         False False
698         False True
699         False False
700         False False
701         False True
702         False False
703         >>> _structure(msg)
704         multipart/report
705             text/plain
706             message/delivery-status
707                 text/plain
708                 text/plain
709             message/rfc822
710                 text/plain
711
712      Here the ``message`` parts are not ``multiparts``, but they do contain
713      subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends
714      into the subparts.
715
716
717   :class:`Message` objects can also optionally contain two instance attributes,
718   which can be used when generating the plain text of a MIME message.
719
720
721   .. attribute:: preamble
722
723      The format of a MIME document allows for some text between the blank line
724      following the headers, and the first multipart boundary string. Normally,
725      this text is never visible in a MIME-aware mail reader because it falls
726      outside the standard MIME armor.  However, when viewing the raw text of
727      the message, or when viewing the message in a non-MIME aware reader, this
728      text can become visible.
729
730      The *preamble* attribute contains this leading extra-armor text for MIME
731      documents.  When the :class:`~email.parser.Parser` discovers some text
732      after the headers but before the first boundary string, it assigns this
733      text to the message's *preamble* attribute.  When the
734      :class:`~email.generator.Generator` is writing out the plain text
735      representation of a MIME message, and it finds the
736      message has a *preamble* attribute, it will write this text in the area
737      between the headers and the first boundary.  See :mod:`email.parser` and
738      :mod:`email.generator` for details.
739
740      Note that if the message object has no preamble, the *preamble* attribute
741      will be ``None``.
742
743
744   .. attribute:: epilogue
745
746      The *epilogue* attribute acts the same way as the *preamble* attribute,
747      except that it contains text that appears between the last boundary and
748      the end of the message.
749
750      You do not need to set the epilogue to the empty string in order for the
751      :class:`~email.generator.Generator` to print a newline at the end of the
752      file.
753
754
755   .. attribute:: defects
756
757      The *defects* attribute contains a list of all the problems found when
758      parsing this message.  See :mod:`email.errors` for a detailed description
759      of the possible parsing defects.
760