--- rest25/library/email.message.rst	2008-12-19 16:58:08.000000000 +0900
+++ rest262/library/email.message.rst	2009-04-15 11:13:50.000000000 +0900
@@ -1,545 +1,567 @@
+:mod:`email`: Representing an email message
+-------------------------------------------
+
 .. module:: email.message
    :synopsis: The base class representing email messages.
 
 
 The central class in the :mod:`email` package is the :class:`Message` class,
 imported from the :mod:`email.message` module.  It is the base class for the
 :mod:`email` object model.  :class:`Message` provides the core functionality for
 setting and querying header fields, and for accessing message bodies.
 
 Conceptually, a :class:`Message` object consists of *headers* and *payloads*.
 Headers are :rfc:`2822` style field names and values where the field name and
 value are separated by a colon.  The colon is not part of either the field name
 or the field value.
 
-Headers are stored and returned in case-preserving form but are matched case-
-insensitively.  There may also be a single envelope header, also known as the
-*Unix-From* header or the ``From_`` header.  The payload is either a string in
-the case of simple message objects or a list of :class:`Message` objects for
+Headers are stored and returned in case-preserving form but are matched
+case-insensitively.  There may also be a single envelope header, also known as
+the *Unix-From* header or the ``From_`` header.  The payload is either a string
+in the case of simple message objects or a list of :class:`Message` objects for
 MIME container documents (e.g. :mimetype:`multipart/\*` and
 :mimetype:`message/rfc822`).
 
 :class:`Message` objects provide a mapping style interface for accessing the
 message headers, and an explicit interface for accessing both the headers and
 the payload.  It provides convenience methods for generating a flat text
 representation of the message object tree, for accessing commonly used header
 parameters, and for recursively walking over the object tree.
 
 Here are the methods of the :class:`Message` class:
 
 
 .. class:: Message()
 
    The constructor takes no arguments.
 
 
-.. method:: Message.as_string([unixfrom])
+   .. method:: as_string([unixfrom])
 
-   Return the entire message flatten as a string.  When optional *unixfrom* is
-   ``True``, the envelope header is included in the returned string.  *unixfrom*
-   defaults to ``False``.
+      Return the entire message flattened as a string.  When optional *unixfrom*
+      is ``True``, the envelope header is included in the returned string.
+      *unixfrom* defaults to ``False``.
 
-   Note that this method is provided as a convenience and may not always format the
-   message the way you want.  For example, by default it mangles lines that begin
-   with ``From``.  For more flexibility, instantiate a :class:`Generator` instance
-   and use its :meth:`flatten` method directly.  For example::
+      Note that this method is provided as a convenience and may not always
+      format the message the way you want.  For example, by default it mangles
+      lines that begin with ``From``.  For more flexibility, instantiate a
+      :class:`Generator` instance and use its :meth:`flatten` method directly.
+      For example::
 
-      from cStringIO import StringIO
-      from email.generator import Generator
-      fp = StringIO()
-      g = Generator(fp, mangle_from_=False, maxheaderlen=60)
-      g.flatten(msg)
-      text = fp.getvalue()
+         from cStringIO import StringIO
+         from email.generator import Generator
+         fp = StringIO()
+         g = Generator(fp, mangle_from_=False, maxheaderlen=60)
+         g.flatten(msg)
+         text = fp.getvalue()
 
 
-.. method:: Message.__str__()
+   .. method:: __str__()
 
-   Equivalent to :meth:`as_string(unixfrom=True)`.
+      Equivalent to ``as_string(unixfrom=True)``.
 
 
-.. method:: Message.is_multipart()
+   .. method:: is_multipart()
 
-   Return ``True`` if the message's payload is a list of sub-\ :class:`Message`
-   objects, otherwise return ``False``.  When :meth:`is_multipart` returns False,
-   the payload should be a string object.
+      Return ``True`` if the message's payload is a list of sub-\
+      :class:`Message` objects, otherwise return ``False``.  When
+      :meth:`is_multipart` returns False, the payload should be a string object.
 
 
-.. method:: Message.set_unixfrom(unixfrom)
+   .. method:: set_unixfrom(unixfrom)
 
-   Set the message's envelope header to *unixfrom*, which should be a string.
+      Set the message's envelope header to *unixfrom*, which should be a string.
 
 
-.. method:: Message.get_unixfrom()
+   .. method:: get_unixfrom()
 
-   Return the message's envelope header.  Defaults to ``None`` if the envelope
-   header was never set.
+      Return the message's envelope header.  Defaults to ``None`` if the
+      envelope header was never set.
 
 
-.. method:: Message.attach(payload)
+   .. method:: attach(payload)
 
-   Add the given *payload* to the current payload, which must be ``None`` or a list
-   of :class:`Message` objects before the call. After the call, the payload will
-   always be a list of :class:`Message` objects.  If you want to set the payload to
-   a scalar object (e.g. a string), use :meth:`set_payload` instead.
+      Add the given *payload* to the current payload, which must be ``None`` or
+      a list of :class:`Message` objects before the call. After the call, the
+      payload will always be a list of :class:`Message` objects.  If you want to
+      set the payload to a scalar object (e.g. a string), use
+      :meth:`set_payload` instead.
 
 
-.. method:: Message.get_payload([i[, decode]])
+   .. method:: get_payload([i[, decode]])
 
-   Return a reference the current payload, which will be a list of :class:`Message`
-   objects when :meth:`is_multipart` is ``True``, or a string when
-   :meth:`is_multipart` is ``False``.  If the payload is a list and you mutate the
-   list object, you modify the message's payload in place.
+      Return the current payload, which will be a list of
+      :class:`Message` objects when :meth:`is_multipart` is ``True``, or a
+      string when :meth:`is_multipart` is ``False``.  If the payload is a list
+      and you mutate the list object, you modify the message's payload in place.
 
-   With optional argument *i*, :meth:`get_payload` will return the *i*-th element
-   of the payload, counting from zero, if :meth:`is_multipart` is ``True``.  An
-   :exc:`IndexError` will be raised if *i* is less than 0 or greater than or equal
-   to the number of items in the payload.  If the payload is a string (i.e.
-   :meth:`is_multipart` is ``False``) and *i* is given, a :exc:`TypeError` is
-   raised.
+      With optional argument *i*, :meth:`get_payload` will return the *i*-th
+      element of the payload, counting from zero, if :meth:`is_multipart` is
+      ``True``.  An :exc:`IndexError` will be raised if *i* is less than 0 or
+      greater than or equal to the number of items in the payload.  If the
+      payload is a string (i.e.  :meth:`is_multipart` is ``False``) and *i* is
+      given, a :exc:`TypeError` is raised.
 
-   Optional *decode* is a flag indicating whether the payload should be decoded or
-   not, according to the :mailheader:`Content-Transfer-Encoding` header. When
-   ``True`` and the message is not a multipart, the payload will be decoded if this
-   header's value is ``quoted-printable`` or ``base64``.  If some other encoding is
-   used, or :mailheader:`Content-Transfer-Encoding` header is missing, or if the
-   payload has bogus base64 data, the payload is returned as-is (undecoded).  If
-   the message is a multipart and the *decode* flag is ``True``, then ``None`` is
-   returned.  The default for *decode* is ``False``.
+      Optional *decode* is a flag indicating whether the payload should be
+      decoded or not, according to the :mailheader:`Content-Transfer-Encoding`
+      header. When ``True`` and the message is not a multipart, the payload will
+      be decoded if this header's value is ``quoted-printable`` or ``base64``.
+      If some other encoding is used, or :mailheader:`Content-Transfer-Encoding`
+      header is missing, or if the payload has bogus base64 data, the payload is
+      returned as-is (undecoded).  If the message is a multipart and the
+      *decode* flag is ``True``, then ``None`` is returned.  The default for
+      *decode* is ``False``.
 
 
-.. method:: Message.set_payload(payload[, charset])
+   .. method:: set_payload(payload[, charset])
 
-   Set the entire message object's payload to *payload*.  It is the client's
-   responsibility to ensure the payload invariants.  Optional *charset* sets the
-   message's default character set; see :meth:`set_charset` for details.
+      Set the entire message object's payload to *payload*.  It is the client's
+      responsibility to ensure the payload invariants.  Optional *charset* sets
+      the message's default character set; see :meth:`set_charset` for details.
 
-   .. versionchanged:: 2.2.2
-      *charset* argument added.
+      .. versionchanged:: 2.2.2
+         *charset* argument added.
 
 
-.. method:: Message.set_charset(charset)
+   .. method:: set_charset(charset)
 
-   Set the character set of the payload to *charset*, which can either be a
-   :class:`Charset` instance (see :mod:`email.charset`), a string naming a
-   character set, or ``None``.  If it is a string, it will be converted to a
-   :class:`Charset` instance.  If *charset* is ``None``, the ``charset`` parameter
-   will be removed from the :mailheader:`Content-Type` header. Anything else will
-   generate a :exc:`TypeError`.
+      Set the character set of the payload to *charset*, which can either be a
+      :class:`Charset` instance (see :mod:`email.charset`), a string naming a
+      character set, or ``None``.  If it is a string, it will be converted to a
+      :class:`Charset` instance.  If *charset* is ``None``, the ``charset``
+      parameter will be removed from the :mailheader:`Content-Type`
+      header. Anything else will generate a :exc:`TypeError`.
 
-   The message will be assumed to be of type :mimetype:`text/\*` encoded with
-   *charset.input_charset*.  It will be converted to *charset.output_charset* and
-   encoded properly, if needed, when generating the plain text representation of
-   the message.  MIME headers (:mailheader:`MIME-Version`,
-   :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will be
-   added as needed.
+      The message will be assumed to be of type :mimetype:`text/\*` encoded with
+      *charset.input_charset*.  It will be converted to *charset.output_charset*
+      and encoded properly, if needed, when generating the plain text
+      representation of the message.  MIME headers (:mailheader:`MIME-Version`,
+      :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will
+      be added as needed.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.get_charset()
+   .. method:: get_charset()
 
-   Return the :class:`Charset` instance associated with the message's payload.
+      Return the :class:`Charset` instance associated with the message's
+      payload.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
-The following methods implement a mapping-like interface for accessing the
-message's :rfc:`2822` headers.  Note that there are some semantic differences
-between these methods and a normal mapping (i.e. dictionary) interface.  For
-example, in a dictionary there are no duplicate keys, but here there may be
-duplicate message headers.  Also, in dictionaries there is no guaranteed order
-to the keys returned by :meth:`keys`, but in a :class:`Message` object, headers
-are always returned in the order they appeared in the original message, or were
-added to the message later.  Any header deleted and then re-added are always
-appended to the end of the header list.
+   The following methods implement a mapping-like interface for accessing the
+   message's :rfc:`2822` headers.  Note that there are some semantic differences
+   between these methods and a normal mapping (i.e. dictionary) interface.  For
+   example, in a dictionary there are no duplicate keys, but here there may be
+   duplicate message headers.  Also, in dictionaries there is no guaranteed
+   order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
+   headers are always returned in the order they appeared in the original
+   message, or were added to the message later.  Any header deleted and then
+   re-added are always appended to the end of the header list.
 
-These semantic differences are intentional and are biased toward maximal
-convenience.
+   These semantic differences are intentional and are biased toward maximal
+   convenience.
 
-Note that in all cases, any envelope header present in the message is not
-included in the mapping interface.
+   Note that in all cases, any envelope header present in the message is not
+   included in the mapping interface.
 
 
-.. method:: Message.__len__()
+   .. method:: __len__()
 
-   Return the total number of headers, including duplicates.
+      Return the total number of headers, including duplicates.
 
 
-.. method:: Message.__contains__(name)
+   .. method:: __contains__(name)
 
-   Return true if the message object has a field named *name*. Matching is done
-   case-insensitively and *name* should not include the trailing colon.  Used for
-   the ``in`` operator, e.g.::
+      Return true if the message object has a field named *name*. Matching is
+      done case-insensitively and *name* should not include the trailing colon.
+      Used for the ``in`` operator, e.g.::
 
-      if 'message-id' in myMessage:
-          print 'Message-ID:', myMessage['message-id']
+         if 'message-id' in myMessage:
+             print 'Message-ID:', myMessage['message-id']
 
 
-.. method:: Message.__getitem__(name)
+   .. method:: __getitem__(name)
 
-   Return the value of the named header field.  *name* should not include the colon
-   field separator.  If the header is missing, ``None`` is returned; a
-   :exc:`KeyError` is never raised.
+      Return the value of the named header field.  *name* should not include the
+      colon field separator.  If the header is missing, ``None`` is returned; a
+      :exc:`KeyError` is never raised.
 
-   Note that if the named field appears more than once in the message's headers,
-   exactly which of those field values will be returned is undefined.  Use the
-   :meth:`get_all` method to get the values of all the extant named headers.
+      Note that if the named field appears more than once in the message's
+      headers, exactly which of those field values will be returned is
+      undefined.  Use the :meth:`get_all` method to get the values of all the
+      extant named headers.
 
 
-.. method:: Message.__setitem__(name, val)
+   .. method:: __setitem__(name, val)
 
-   Add a header to the message with field name *name* and value *val*.  The field
-   is appended to the end of the message's existing fields.
+      Add a header to the message with field name *name* and value *val*.  The
+      field is appended to the end of the message's existing fields.
 
-   Note that this does *not* overwrite or delete any existing header with the same
-   name.  If you want to ensure that the new header is the only one present in the
-   message with field name *name*, delete the field first, e.g.::
+      Note that this does *not* overwrite or delete any existing header with the same
+      name.  If you want to ensure that the new header is the only one present in the
+      message with field name *name*, delete the field first, e.g.::
 
-      del msg['subject']
-      msg['subject'] = 'Python roolz!'
+         del msg['subject']
+         msg['subject'] = 'Python roolz!'
 
 
-.. method:: Message.__delitem__(name)
+   .. method:: __delitem__(name)
 
-   Delete all occurrences of the field with name *name* from the message's headers.
-   No exception is raised if the named field isn't present in the headers.
+      Delete all occurrences of the field with name *name* from the message's
+      headers.  No exception is raised if the named field isn't present in the headers.
 
 
-.. method:: Message.has_key(name)
+   .. method:: has_key(name)
 
-   Return true if the message contains a header field named *name*, otherwise
-   return false.
+      Return true if the message contains a header field named *name*, otherwise
+      return false.
 
 
-.. method:: Message.keys()
+   .. method:: keys()
 
-   Return a list of all the message's header field names.
+      Return a list of all the message's header field names.
 
 
-.. method:: Message.values()
+   .. method:: values()
 
-   Return a list of all the message's field values.
+      Return a list of all the message's field values.
 
 
-.. method:: Message.items()
+   .. method:: items()
 
-   Return a list of 2-tuples containing all the message's field headers and values.
+      Return a list of 2-tuples containing all the message's field headers and
+      values.
 
 
-.. method:: Message.get(name[, failobj])
+   .. method:: get(name[, failobj])
 
-   Return the value of the named header field.  This is identical to
-   :meth:`__getitem__` except that optional *failobj* is returned if the named
-   header is missing (defaults to ``None``).
+      Return the value of the named header field.  This is identical to
+      :meth:`__getitem__` except that optional *failobj* is returned if the
+      named header is missing (defaults to ``None``).
 
-Here are some additional useful methods:
+   Here are some additional useful methods:
 
 
-.. method:: Message.get_all(name[, failobj])
+   .. method:: get_all(name[, failobj])
 
-   Return a list of all the values for the field named *name*. If there are no such
-   named headers in the message, *failobj* is returned (defaults to ``None``).
+      Return a list of all the values for the field named *name*. If there are
+      no such named headers in the message, *failobj* is returned (defaults to
+      ``None``).
 
 
-.. method:: Message.add_header(_name, _value, **_params)
+   .. method:: add_header(_name, _value, **_params)
 
-   Extended header setting.  This method is similar to :meth:`__setitem__` except
-   that additional header parameters can be provided as keyword arguments.  *_name*
-   is the header field to add and *_value* is the *primary* value for the header.
+      Extended header setting.  This method is similar to :meth:`__setitem__`
+      except that additional header parameters can be provided as keyword
+      arguments.  *_name* is the header field to add and *_value* is the
+      *primary* value for the header.
 
-   For each item in the keyword argument dictionary *_params*, the key is taken as
-   the parameter name, with underscores converted to dashes (since dashes are
-   illegal in Python identifiers).  Normally, the parameter will be added as
-   ``key="value"`` unless the value is ``None``, in which case only the key will be
-   added.
+      For each item in the keyword argument dictionary *_params*, the key is
+      taken as the parameter name, with underscores converted to dashes (since
+      dashes are illegal in Python identifiers).  Normally, the parameter will
+      be added as ``key="value"`` unless the value is ``None``, in which case
+      only the key will be added.
 
-   Here's an example::
+      Here's an example::
 
-      msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
+         msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
 
-   This will add a header that looks like ::
+      This will add a header that looks like ::
 
-      Content-Disposition: attachment; filename="bud.gif"
+         Content-Disposition: attachment; filename="bud.gif"
 
 
-.. method:: Message.replace_header(_name, _value)
+   .. method:: replace_header(_name, _value)
 
-   Replace a header.  Replace the first header found in the message that matches
-   *_name*, retaining header order and field name case.  If no matching header was
-   found, a :exc:`KeyError` is raised.
+      Replace a header.  Replace the first header found in the message that
+      matches *_name*, retaining header order and field name case.  If no
+      matching header was found, a :exc:`KeyError` is raised.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.get_content_type()
+   .. method:: get_content_type()
 
-   Return the message's content type.  The returned string is coerced to lower case
-   of the form :mimetype:`maintype/subtype`.  If there was no
-   :mailheader:`Content-Type` header in the message the default type as given by
-   :meth:`get_default_type` will be returned.  Since according to :rfc:`2045`,
-   messages always have a default type, :meth:`get_content_type` will always return
-   a value.
+      Return the message's content type.  The returned string is coerced to
+      lower case of the form :mimetype:`maintype/subtype`.  If there was no
+      :mailheader:`Content-Type` header in the message the default type as given
+      by :meth:`get_default_type` will be returned.  Since according to
+      :rfc:`2045`, messages always have a default type, :meth:`get_content_type`
+      will always return a value.
 
-   :rfc:`2045` defines a message's default type to be :mimetype:`text/plain` unless
-   it appears inside a :mimetype:`multipart/digest` container, in which case it
-   would be :mimetype:`message/rfc822`.  If the :mailheader:`Content-Type` header
-   has an invalid type specification, :rfc:`2045` mandates that the default type be
-   :mimetype:`text/plain`.
+      :rfc:`2045` defines a message's default type to be :mimetype:`text/plain`
+      unless it appears inside a :mimetype:`multipart/digest` container, in
+      which case it would be :mimetype:`message/rfc822`.  If the
+      :mailheader:`Content-Type` header has an invalid type specification,
+      :rfc:`2045` mandates that the default type be :mimetype:`text/plain`.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.get_content_maintype()
+   .. method:: get_content_maintype()
 
-   Return the message's main content type.  This is the :mimetype:`maintype` part
-   of the string returned by :meth:`get_content_type`.
+      Return the message's main content type.  This is the :mimetype:`maintype`
+      part of the string returned by :meth:`get_content_type`.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.get_content_subtype()
+   .. method:: get_content_subtype()
 
-   Return the message's sub-content type.  This is the :mimetype:`subtype` part of
-   the string returned by :meth:`get_content_type`.
+      Return the message's sub-content type.  This is the :mimetype:`subtype`
+      part of the string returned by :meth:`get_content_type`.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.get_default_type()
+   .. method:: get_default_type()
 
-   Return the default content type.  Most messages have a default content type of
-   :mimetype:`text/plain`, except for messages that are subparts of
-   :mimetype:`multipart/digest` containers.  Such subparts have a default content
-   type of :mimetype:`message/rfc822`.
+      Return the default content type.  Most messages have a default content
+      type of :mimetype:`text/plain`, except for messages that are subparts of
+      :mimetype:`multipart/digest` containers.  Such subparts have a default
+      content type of :mimetype:`message/rfc822`.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.set_default_type(ctype)
+   .. method:: set_default_type(ctype)
 
-   Set the default content type.  *ctype* should either be :mimetype:`text/plain`
-   or :mimetype:`message/rfc822`, although this is not enforced.  The default
-   content type is not stored in the :mailheader:`Content-Type` header.
+      Set the default content type.  *ctype* should either be
+      :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not
+      enforced.  The default content type is not stored in the
+      :mailheader:`Content-Type` header.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.get_params([failobj[, header[, unquote]]])
+   .. method:: get_params([failobj[, header[, unquote]]])
 
-   Return the message's :mailheader:`Content-Type` parameters, as a list.  The
-   elements of the returned list are 2-tuples of key/value pairs, as split on the
-   ``'='`` sign.  The left hand side of the ``'='`` is the key, while the right
-   hand side is the value.  If there is no ``'='`` sign in the parameter the value
-   is the empty string, otherwise the value is as described in :meth:`get_param`
-   and is unquoted if optional *unquote* is ``True`` (the default).
+      Return the message's :mailheader:`Content-Type` parameters, as a list.
+      The elements of the returned list are 2-tuples of key/value pairs, as
+      split on the ``'='`` sign.  The left hand side of the ``'='`` is the key,
+      while the right hand side is the value.  If there is no ``'='`` sign in
+      the parameter the value is the empty string, otherwise the value is as
+      described in :meth:`get_param` and is unquoted if optional *unquote* is
+      ``True`` (the default).
 
-   Optional *failobj* is the object to return if there is no
-   :mailheader:`Content-Type` header.  Optional *header* is the header to search
-   instead of :mailheader:`Content-Type`.
+      Optional *failobj* is the object to return if there is no
+      :mailheader:`Content-Type` header.  Optional *header* is the header to
+      search instead of :mailheader:`Content-Type`.
 
-   .. versionchanged:: 2.2.2
-      *unquote* argument added.
+      .. versionchanged:: 2.2.2
+         *unquote* argument added.
 
 
-.. method:: Message.get_param(param[, failobj[, header[, unquote]]])
+   .. method:: get_param(param[, failobj[, header[, unquote]]])
 
-   Return the value of the :mailheader:`Content-Type` header's parameter *param* as
-   a string.  If the message has no :mailheader:`Content-Type` header or if there
-   is no such parameter, then *failobj* is returned (defaults to ``None``).
+      Return the value of the :mailheader:`Content-Type` header's parameter
+      *param* as a string.  If the message has no :mailheader:`Content-Type`
+      header or if there is no such parameter, then *failobj* is returned
+      (defaults to ``None``).
 
-   Optional *header* if given, specifies the message header to use instead of
-   :mailheader:`Content-Type`.
+      Optional *header* if given, specifies the message header to use instead of
+      :mailheader:`Content-Type`.
 
-   Parameter keys are always compared case insensitively.  The return value can
-   either be a string, or a 3-tuple if the parameter was :rfc:`2231` encoded.  When
-   it's a 3-tuple, the elements of the value are of the form ``(CHARSET, LANGUAGE,
-   VALUE)``.  Note that both ``CHARSET`` and ``LANGUAGE`` can be ``None``, in which
-   case you should consider ``VALUE`` to be encoded in the ``us-ascii`` charset.
-   You can usually ignore ``LANGUAGE``.
+      Parameter keys are always compared case insensitively.  The return value
+      can either be a string, or a 3-tuple if the parameter was :rfc:`2231`
+      encoded.  When it's a 3-tuple, the elements of the value are of the form
+      ``(CHARSET, LANGUAGE, VALUE)``.  Note that both ``CHARSET`` and
+      ``LANGUAGE`` can be ``None``, in which case you should consider ``VALUE``
+      to be encoded in the ``us-ascii`` charset.  You can usually ignore
+      ``LANGUAGE``.
 
-   If your application doesn't care whether the parameter was encoded as in
-   :rfc:`2231`, you can collapse the parameter value by calling
-   :func:`email.Utils.collapse_rfc2231_value`, passing in the return value from
-   :meth:`get_param`.  This will return a suitably decoded Unicode string whn the
-   value is a tuple, or the original string unquoted if it isn't.  For example::
+      If your application doesn't care whether the parameter was encoded as in
+      :rfc:`2231`, you can collapse the parameter value by calling
+      :func:`email.utils.collapse_rfc2231_value`, passing in the return value
+      from :meth:`get_param`.  This will return a suitably decoded Unicode
+      string whn the value is a tuple, or the original string unquoted if it
+      isn't.  For example::
 
-      rawparam = msg.get_param('foo')
-      param = email.Utils.collapse_rfc2231_value(rawparam)
+         rawparam = msg.get_param('foo')
+         param = email.utils.collapse_rfc2231_value(rawparam)
 
-   In any case, the parameter value (either the returned string, or the ``VALUE``
-   item in the 3-tuple) is always unquoted, unless *unquote* is set to ``False``.
+      In any case, the parameter value (either the returned string, or the
+      ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
+      to ``False``.
 
-   .. versionchanged:: 2.2.2
-      *unquote* argument added, and 3-tuple return value possible.
+      .. versionchanged:: 2.2.2
+         *unquote* argument added, and 3-tuple return value possible.
 
 
-.. method:: Message.set_param(param, value[, header[, requote[, charset[, language]]]])
+   .. method:: set_param(param, value[, header[, requote[, charset[, language]]]])
 
-   Set a parameter in the :mailheader:`Content-Type` header.  If the parameter
-   already exists in the header, its value will be replaced with *value*.  If the
-   :mailheader:`Content-Type` header as not yet been defined for this message, it
-   will be set to :mimetype:`text/plain` and the new parameter value will be
-   appended as per :rfc:`2045`.
+      Set a parameter in the :mailheader:`Content-Type` header.  If the
+      parameter already exists in the header, its value will be replaced with
+      *value*.  If the :mailheader:`Content-Type` header as not yet been defined
+      for this message, it will be set to :mimetype:`text/plain` and the new
+      parameter value will be appended as per :rfc:`2045`.
 
-   Optional *header* specifies an alternative header to :mailheader:`Content-Type`,
-   and all parameters will be quoted as necessary unless optional *requote* is
-   ``False`` (the default is ``True``).
+      Optional *header* specifies an alternative header to
+      :mailheader:`Content-Type`, and all parameters will be quoted as necessary
+      unless optional *requote* is ``False`` (the default is ``True``).
 
-   If optional *charset* is specified, the parameter will be encoded according to
-   :rfc:`2231`. Optional *language* specifies the RFC 2231 language, defaulting to
-   the empty string.  Both *charset* and *language* should be strings.
+      If optional *charset* is specified, the parameter will be encoded
+      according to :rfc:`2231`. Optional *language* specifies the RFC 2231
+      language, defaulting to the empty string.  Both *charset* and *language*
+      should be strings.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.del_param(param[, header[, requote]])
+   .. method:: del_param(param[, header[, requote]])
 
-   Remove the given parameter completely from the :mailheader:`Content-Type`
-   header.  The header will be re-written in place without the parameter or its
-   value.  All values will be quoted as necessary unless *requote* is ``False``
-   (the default is ``True``).  Optional *header* specifies an alternative to
-   :mailheader:`Content-Type`.
+      Remove the given parameter completely from the :mailheader:`Content-Type`
+      header.  The header will be re-written in place without the parameter or
+      its value.  All values will be quoted as necessary unless *requote* is
+      ``False`` (the default is ``True``).  Optional *header* specifies an
+      alternative to :mailheader:`Content-Type`.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.set_type(type[, header][, requote])
+   .. method:: set_type(type[, header][, requote])
 
-   Set the main type and subtype for the :mailheader:`Content-Type` header. *type*
-   must be a string in the form :mimetype:`maintype/subtype`, otherwise a
-   :exc:`ValueError` is raised.
+      Set the main type and subtype for the :mailheader:`Content-Type`
+      header. *type* must be a string in the form :mimetype:`maintype/subtype`,
+      otherwise a :exc:`ValueError` is raised.
 
-   This method replaces the :mailheader:`Content-Type` header, keeping all the
-   parameters in place.  If *requote* is ``False``, this leaves the existing
-   header's quoting as is, otherwise the parameters will be quoted (the default).
+      This method replaces the :mailheader:`Content-Type` header, keeping all
+      the parameters in place.  If *requote* is ``False``, this leaves the
+      existing header's quoting as is, otherwise the parameters will be quoted
+      (the default).
 
-   An alternative header can be specified in the *header* argument. When the
-   :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` header is
-   also added.
+      An alternative header can be specified in the *header* argument. When the
+      :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version`
+      header is also added.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.get_filename([failobj])
+   .. method:: get_filename([failobj])
 
-   Return the value of the ``filename`` parameter of the
-   :mailheader:`Content-Disposition` header of the message.  If the header does not
-   have a ``filename`` parameter, this method falls back to looking for the
-   ``name`` parameter.  If neither is found, or the header is missing, then
-   *failobj* is returned.  The returned string will always be unquoted as per
-   :meth:`Utils.unquote`.
+      Return the value of the ``filename`` parameter of the
+      :mailheader:`Content-Disposition` header of the message.  If the header
+      does not have a ``filename`` parameter, this method falls back to looking
+      for the ``name`` parameter.  If neither is found, or the header is
+      missing, then *failobj* is returned.  The returned string will always be
+      unquoted as per :func:`email.utils.unquote`.
 
 
-.. method:: Message.get_boundary([failobj])
+   .. method:: get_boundary([failobj])
 
-   Return the value of the ``boundary`` parameter of the :mailheader:`Content-Type`
-   header of the message, or *failobj* if either the header is missing, or has no
-   ``boundary`` parameter.  The returned string will always be unquoted as per
-   :meth:`Utils.unquote`.
+      Return the value of the ``boundary`` parameter of the
+      :mailheader:`Content-Type` header of the message, or *failobj* if either
+      the header is missing, or has no ``boundary`` parameter.  The returned
+      string will always be unquoted as per :func:`email.utils.unquote`.
 
 
-.. method:: Message.set_boundary(boundary)
+   .. method:: set_boundary(boundary)
 
-   Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
-   *boundary*.  :meth:`set_boundary` will always quote *boundary* if necessary.  A
-   :exc:`HeaderParseError` is raised if the message object has no
-   :mailheader:`Content-Type` header.
+      Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
+      *boundary*.  :meth:`set_boundary` will always quote *boundary* if
+      necessary.  A :exc:`HeaderParseError` is raised if the message object has
+      no :mailheader:`Content-Type` header.
 
-   Note that using this method is subtly different than deleting the old
-   :mailheader:`Content-Type` header and adding a new one with the new boundary via
-   :meth:`add_header`, because :meth:`set_boundary` preserves the order of the
-   :mailheader:`Content-Type` header in the list of headers. However, it does *not*
-   preserve any continuation lines which may have been present in the original
-   :mailheader:`Content-Type` header.
+      Note that using this method is subtly different than deleting the old
+      :mailheader:`Content-Type` header and adding a new one with the new
+      boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
+      the order of the :mailheader:`Content-Type` header in the list of
+      headers. However, it does *not* preserve any continuation lines which may
+      have been present in the original :mailheader:`Content-Type` header.
 
 
-.. method:: Message.get_content_charset([failobj])
+   .. method:: get_content_charset([failobj])
 
-   Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
-   coerced to lower case.  If there is no :mailheader:`Content-Type` header, or if
-   that header has no ``charset`` parameter, *failobj* is returned.
+      Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
+      coerced to lower case.  If there is no :mailheader:`Content-Type` header, or if
+      that header has no ``charset`` parameter, *failobj* is returned.
 
-   Note that this method differs from :meth:`get_charset` which returns the
-   :class:`Charset` instance for the default encoding of the message body.
+      Note that this method differs from :meth:`get_charset` which returns the
+      :class:`Charset` instance for the default encoding of the message body.
 
-   .. versionadded:: 2.2.2
+      .. versionadded:: 2.2.2
 
 
-.. method:: Message.get_charsets([failobj])
+   .. method:: get_charsets([failobj])
 
-   Return a list containing the character set names in the message.  If the message
-   is a :mimetype:`multipart`, then the list will contain one element for each
-   subpart in the payload, otherwise, it will be a list of length 1.
+      Return a list containing the character set names in the message.  If the
+      message is a :mimetype:`multipart`, then the list will contain one element
+      for each subpart in the payload, otherwise, it will be a list of length 1.
 
-   Each item in the list will be a string which is the value of the ``charset``
-   parameter in the :mailheader:`Content-Type` header for the represented subpart.
-   However, if the subpart has no :mailheader:`Content-Type` header, no ``charset``
-   parameter, or is not of the :mimetype:`text` main MIME type, then that item in
-   the returned list will be *failobj*.
+      Each item in the list will be a string which is the value of the
+      ``charset`` parameter in the :mailheader:`Content-Type` header for the
+      represented subpart.  However, if the subpart has no
+      :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of
+      the :mimetype:`text` main MIME type, then that item in the returned list
+      will be *failobj*.
 
 
-.. method:: Message.walk()
+   .. method:: walk()
 
-   The :meth:`walk` method is an all-purpose generator which can be used to iterate
-   over all the parts and subparts of a message object tree, in depth-first
-   traversal order.  You will typically use :meth:`walk` as the iterator in a
-   ``for`` loop; each iteration returns the next subpart.
+      The :meth:`walk` method is an all-purpose generator which can be used to
+      iterate over all the parts and subparts of a message object tree, in
+      depth-first traversal order.  You will typically use :meth:`walk` as the
+      iterator in a ``for`` loop; each iteration returns the next subpart.
 
-   Here's an example that prints the MIME type of every part of a multipart message
-   structure::
+      Here's an example that prints the MIME type of every part of a multipart
+      message structure::
 
-      >>> for part in msg.walk():
-      ...     print part.get_content_type()
-      multipart/report
-      text/plain
-      message/delivery-status
-      text/plain
-      text/plain
-      message/rfc822
+         >>> for part in msg.walk():
+         ...     print part.get_content_type()
+         multipart/report
+         text/plain
+         message/delivery-status
+         text/plain
+         text/plain
+         message/rfc822
 
-.. versionchanged:: 2.5
-   The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
-   :meth:`get_subtype` were removed.
+   .. versionchanged:: 2.5
+      The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
+      :meth:`get_subtype` were removed.
 
-:class:`Message` objects can also optionally contain two instance attributes,
-which can be used when generating the plain text of a MIME message.
+   :class:`Message` objects can also optionally contain two instance attributes,
+   which can be used when generating the plain text of a MIME message.
 
 
-.. data:: preamble
+   .. attribute:: preamble
 
-   The format of a MIME document allows for some text between the blank line
-   following the headers, and the first multipart boundary string. Normally, this
-   text is never visible in a MIME-aware mail reader because it falls outside the
-   standard MIME armor.  However, when viewing the raw text of the message, or when
-   viewing the message in a non-MIME aware reader, this text can become visible.
+      The format of a MIME document allows for some text between the blank line
+      following the headers, and the first multipart boundary string. Normally,
+      this text is never visible in a MIME-aware mail reader because it falls
+      outside the standard MIME armor.  However, when viewing the raw text of
+      the message, or when viewing the message in a non-MIME aware reader, this
+      text can become visible.
 
-   The *preamble* attribute contains this leading extra-armor text for MIME
-   documents.  When the :class:`Parser` discovers some text after the headers but
-   before the first boundary string, it assigns this text to the message's
-   *preamble* attribute.  When the :class:`Generator` is writing out the plain text
-   representation of a MIME message, and it finds the message has a *preamble*
-   attribute, it will write this text in the area between the headers and the first
-   boundary.  See :mod:`email.parser` and :mod:`email.generator` for details.
+      The *preamble* attribute contains this leading extra-armor text for MIME
+      documents.  When the :class:`Parser` discovers some text after the headers
+      but before the first boundary string, it assigns this text to the
+      message's *preamble* attribute.  When the :class:`Generator` is writing
+      out the plain text representation of a MIME message, and it finds the
+      message has a *preamble* attribute, it will write this text in the area
+      between the headers and the first boundary.  See :mod:`email.parser` and
+      :mod:`email.generator` for details.
 
-   Note that if the message object has no preamble, the *preamble* attribute will
-   be ``None``.
+      Note that if the message object has no preamble, the *preamble* attribute
+      will be ``None``.
 
 
-.. data:: epilogue
+   .. attribute:: epilogue
 
-   The *epilogue* attribute acts the same way as the *preamble* attribute, except
-   that it contains text that appears between the last boundary and the end of the
-   message.
+      The *epilogue* attribute acts the same way as the *preamble* attribute,
+      except that it contains text that appears between the last boundary and
+      the end of the message.
 
-   .. versionchanged:: 2.5
-      You do not need to set the epilogue to the empty string in order for the
-      :class:`Generator` to print a newline at the end of the file.
+      .. versionchanged:: 2.5
+         You do not need to set the epilogue to the empty string in order for the
+         :class:`Generator` to print a newline at the end of the file.
 
 
-.. data:: defects
+   .. attribute:: defects
 
-   The *defects* attribute contains a list of all the problems found when parsing
-   this message.  See :mod:`email.errors` for a detailed description of the
-   possible parsing defects.
+      The *defects* attribute contains a list of all the problems found when
+      parsing this message.  See :mod:`email.errors` for a detailed description
+      of the possible parsing defects.
 
-   .. versionadded:: 2.4
+      .. versionadded:: 2.4
 
