--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/email.message.rst Fri Jul 31 15:01:17 2009 +0100
@@ -0,0 +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
+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:: as_string([unixfrom])
+
+ 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::
+
+ 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:: __str__()
+
+ Equivalent to ``as_string(unixfrom=True)``.
+
+
+ .. 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.
+
+
+ .. method:: set_unixfrom(unixfrom)
+
+ Set the message's envelope header to *unixfrom*, which should be a string.
+
+
+ .. method:: get_unixfrom()
+
+ Return the message's envelope header. Defaults to ``None`` if the
+ envelope header was never set.
+
+
+ .. 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.
+
+
+ .. method:: get_payload([i[, decode]])
+
+ 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.
+
+ 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:: 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.
+
+ .. versionchanged:: 2.2.2
+ *charset* argument added.
+
+
+ .. 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`.
+
+ 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
+
+
+ .. method:: get_charset()
+
+ Return the :class:`Charset` instance associated with the message's
+ payload.
+
+ .. 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.
+
+ 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.
+
+
+ .. method:: __len__()
+
+ Return the total number of headers, including duplicates.
+
+
+ .. 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.::
+
+ if 'message-id' in myMessage:
+ print 'Message-ID:', myMessage['message-id']
+
+
+ .. 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.
+
+ 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:: __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.
+
+ 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!'
+
+
+ .. 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.
+
+
+ .. method:: has_key(name)
+
+ Return true if the message contains a header field named *name*, otherwise
+ return false.
+
+
+ .. method:: keys()
+
+ Return a list of all the message's header field names.
+
+
+ .. method:: values()
+
+ Return a list of all the message's field values.
+
+
+ .. method:: items()
+
+ Return a list of 2-tuples containing all the message's field headers and
+ values.
+
+
+ .. 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``).
+
+ Here are some additional useful methods:
+
+
+ .. 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``).
+
+
+ .. 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.
+
+ 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::
+
+ msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
+
+ This will add a header that looks like ::
+
+ Content-Disposition: attachment; filename="bud.gif"
+
+
+ .. 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.
+
+ .. versionadded:: 2.2.2
+
+
+ .. 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.
+
+ :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
+
+
+ .. 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`.
+
+ .. versionadded:: 2.2.2
+
+
+ .. 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`.
+
+ .. versionadded:: 2.2.2
+
+
+ .. 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`.
+
+ .. versionadded:: 2.2.2
+
+
+ .. 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.
+
+ .. versionadded:: 2.2.2
+
+
+ .. 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).
+
+ 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.
+
+
+ .. 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``).
+
+ 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``.
+
+ 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)
+
+ 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.
+
+
+ .. 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`.
+
+ 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.
+
+ .. versionadded:: 2.2.2
+
+
+ .. 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`.
+
+ .. versionadded:: 2.2.2
+
+
+ .. 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.
+
+ 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.
+
+ .. versionadded:: 2.2.2
+
+
+ .. 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`.
+
+
+ .. 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`.
+
+
+ .. 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.
+
+ 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:: 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.
+
+ 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
+
+
+ .. 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.
+
+ 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:: 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.
+
+ 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
+
+ .. 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.
+
+
+ .. 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 *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``.
+
+
+ .. 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.
+
+ .. 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.
+
+
+ .. 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.
+
+ .. versionadded:: 2.4
+