cpython/Doc/library/email.message.rst

549 lines
23 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
: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=False, maxheaderlen=0)
2007-08-15 11:28:22 -03:00
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``. Flattening the message may trigger
changes to the :class:`Message` if defaults need to be filled in to
complete the transformation to a string (for example, MIME boundaries may
be generated or modified).
2007-08-15 11:28:22 -03:00
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:`~email.generator.Generator` instance and use its :meth:`flatten`
method directly. For example::
2007-08-15 11:28:22 -03:00
2008-06-10 12:50:56 -03:00
from io import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=False, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()
2007-08-15 11:28:22 -03:00
.. method:: __str__()
2007-08-15 11:28:22 -03:00
Equivalent to ``as_string(unixfrom=True)``.
2007-08-15 11:28:22 -03:00
.. method:: is_multipart()
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: set_unixfrom(unixfrom)
2007-08-15 11:28:22 -03:00
Set the message's envelope header to *unixfrom*, which should be a string.
2007-08-15 11:28:22 -03:00
.. method:: get_unixfrom()
2007-08-15 11:28:22 -03:00
Return the message's envelope header. Defaults to ``None`` if the
envelope header was never set.
2007-08-15 11:28:22 -03:00
.. method:: attach(payload)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: get_payload(i=None, decode=False)
2007-08-15 11:28:22 -03:00
Merged revisions 65209-65216,65225-65226,65233,65239,65246-65247,65255-65256 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r65209 | raymond.hettinger | 2008-07-23 19:08:18 -0500 (Wed, 23 Jul 2008) | 1 line Finish-up the partial conversion from int to Py_ssize_t for deque indices and length. ........ r65210 | raymond.hettinger | 2008-07-23 19:53:49 -0500 (Wed, 23 Jul 2008) | 1 line Parse to the correct datatype. ........ r65211 | benjamin.peterson | 2008-07-23 21:27:46 -0500 (Wed, 23 Jul 2008) | 1 line fix spacing ........ r65212 | benjamin.peterson | 2008-07-23 21:31:28 -0500 (Wed, 23 Jul 2008) | 1 line fix markup ........ r65213 | benjamin.peterson | 2008-07-23 21:45:37 -0500 (Wed, 23 Jul 2008) | 1 line add some documentation for 2to3 ........ r65214 | raymond.hettinger | 2008-07-24 00:38:48 -0500 (Thu, 24 Jul 2008) | 1 line Finish conversion from int to Py_ssize_t. ........ r65215 | raymond.hettinger | 2008-07-24 02:04:55 -0500 (Thu, 24 Jul 2008) | 1 line Convert from long to Py_ssize_t. ........ r65216 | georg.brandl | 2008-07-24 02:09:21 -0500 (Thu, 24 Jul 2008) | 2 lines Fix indentation. ........ r65225 | benjamin.peterson | 2008-07-25 11:55:37 -0500 (Fri, 25 Jul 2008) | 1 line teach .bzrignore about doc tools ........ r65226 | benjamin.peterson | 2008-07-25 12:02:11 -0500 (Fri, 25 Jul 2008) | 1 line document default value for fillvalue ........ r65233 | raymond.hettinger | 2008-07-25 13:43:33 -0500 (Fri, 25 Jul 2008) | 1 line Issue 1592: Better error reporting for operations on closed shelves. ........ r65239 | benjamin.peterson | 2008-07-25 16:59:53 -0500 (Fri, 25 Jul 2008) | 1 line fix indentation ........ r65246 | andrew.kuchling | 2008-07-26 08:08:19 -0500 (Sat, 26 Jul 2008) | 1 line This sentence continues to bug me; rewrite it for the second time ........ r65247 | andrew.kuchling | 2008-07-26 08:09:06 -0500 (Sat, 26 Jul 2008) | 1 line Remove extra words ........ r65255 | skip.montanaro | 2008-07-26 19:49:02 -0500 (Sat, 26 Jul 2008) | 3 lines Close issue 3437 - missing state change when Allow lines are processed. Adds test cases which use Allow: as well. ........ r65256 | skip.montanaro | 2008-07-26 19:50:41 -0500 (Sat, 26 Jul 2008) | 2 lines note robotparser bug fix. ........
2008-07-31 13:23:04 -03:00
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.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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``.
2007-08-15 11:28:22 -03:00
.. method:: set_payload(payload, charset=None)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: set_charset(charset)
2007-08-15 11:28:22 -03:00
Set the character set of the payload to *charset*, which can either be a
:class:`~email.charset.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:`~email.charset.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`.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: get_charset()
2007-08-15 11:28:22 -03:00
Return the :class:`~email.charset.Charset` instance associated with the
message's payload.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
These semantic differences are intentional and are biased toward maximal
convenience.
2007-08-15 11:28:22 -03:00
Note that in all cases, any envelope header present in the message is not
included in the mapping interface.
2007-08-15 11:28:22 -03:00
.. method:: __len__()
2007-08-15 11:28:22 -03:00
Return the total number of headers, including duplicates.
2007-08-15 11:28:22 -03:00
.. method:: __contains__(name)
2007-08-15 11:28:22 -03:00
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.::
2007-08-15 11:28:22 -03:00
if 'message-id' in myMessage:
print('Message-ID:', myMessage['message-id'])
2007-08-15 11:28:22 -03:00
.. method:: __getitem__(name)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: __setitem__(name, val)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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.::
2007-08-15 11:28:22 -03:00
del msg['subject']
msg['subject'] = 'Python roolz!'
2007-08-15 11:28:22 -03:00
.. method:: __delitem__(name)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: Message.__contains__(name)
2007-08-15 11:28:22 -03:00
Return true if the message contains a header field named *name*, otherwise
return false.
2007-08-15 11:28:22 -03:00
.. method:: keys()
2007-08-15 11:28:22 -03:00
Return a list of all the message's header field names.
2007-08-15 11:28:22 -03:00
.. method:: values()
2007-08-15 11:28:22 -03:00
Return a list of all the message's field values.
2007-08-15 11:28:22 -03:00
.. method:: items()
2007-08-15 11:28:22 -03:00
Return a list of 2-tuples containing all the message's field headers and
values.
2007-08-15 11:28:22 -03:00
.. method:: get(name, failobj=None)
2007-08-15 11:28:22 -03:00
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``).
2007-08-15 11:28:22 -03:00
Here are some additional useful methods:
2007-08-15 11:28:22 -03:00
.. method:: get_all(name, failobj=None)
2007-08-15 11:28:22 -03:00
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``).
2007-08-15 11:28:22 -03:00
.. method:: add_header(_name, _value, **_params)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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. If the value contains non-ASCII characters,
it can be specified as a three tuple in the format
``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
charset to be used to encode the value, ``LANGUAGE`` can usually be set
to ``None`` or the empty string (see :RFC:`2231` for other possibilities),
and ``VALUE`` is the string value containing non-ASCII code points. If
a three tuple is not passed and the value contains non-ASCII characters,
it is automatically encoded in :RFC`2231` format using a ``CHARSET``
of ``utf-8`` and a ``LANGUAGE`` of ``None``.
2007-08-15 11:28:22 -03:00
Here's an example::
2007-08-15 11:28:22 -03:00
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
2007-08-15 11:28:22 -03:00
This will add a header that looks like ::
2007-08-15 11:28:22 -03:00
Content-Disposition: attachment; filename="bud.gif"
2007-08-15 11:28:22 -03:00
An example with with non-ASCII characters::
msg.add_header('Content-Disposition', 'attachment',
filename=('iso-8859-1', '', 'Fußballer.ppt'))
Which produces ::
Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
2007-08-15 11:28:22 -03:00
.. method:: replace_header(_name, _value)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: get_content_type()
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
: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`.
2007-08-15 11:28:22 -03:00
.. method:: get_content_maintype()
2007-08-15 11:28:22 -03:00
Return the message's main content type. This is the :mimetype:`maintype`
part of the string returned by :meth:`get_content_type`.
2007-08-15 11:28:22 -03:00
.. method:: get_content_subtype()
2007-08-15 11:28:22 -03:00
Return the message's sub-content type. This is the :mimetype:`subtype`
part of the string returned by :meth:`get_content_type`.
2007-08-15 11:28:22 -03:00
.. method:: get_default_type()
2007-08-15 11:28:22 -03:00
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`.
2007-08-15 11:28:22 -03:00
.. method:: set_default_type(ctype)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: get_params(failobj=None, header='content-type', unquote=True)
2007-08-15 11:28:22 -03:00
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).
2007-08-15 11:28:22 -03:00
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`.
2007-08-15 11:28:22 -03:00
.. method:: get_param(param, failobj=None, header='content-type', unquote=True)
2007-08-15 11:28:22 -03:00
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``).
2007-08-15 11:28:22 -03:00
Optional *header* if given, specifies the message header to use instead of
:mailheader:`Content-Type`.
2007-08-15 11:28:22 -03:00
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``.
2007-08-15 11:28:22 -03:00
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 when the value is a tuple, or the original string unquoted if it
isn't. For example::
2007-08-15 11:28:22 -03:00
rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)
2007-08-15 11:28:22 -03:00
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``.
2007-08-15 11:28:22 -03:00
.. method:: set_param(param, value, header='Content-Type', requote=True, charset=None, language='')
2007-08-15 11:28:22 -03:00
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`.
2007-08-15 11:28:22 -03:00
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``).
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: del_param(param, header='content-type', requote=True)
2007-08-15 11:28:22 -03:00
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`.
2007-08-15 11:28:22 -03:00
.. method:: set_type(type, header='Content-Type', requote=True)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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).
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: get_filename(failobj=None)
2007-08-15 11:28:22 -03:00
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 on the :mailheader:`Content-Type` header. 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`.
2007-08-15 11:28:22 -03:00
.. method:: get_boundary(failobj=None)
2007-08-15 11:28:22 -03:00
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`.
2007-08-15 11:28:22 -03:00
.. method:: set_boundary(boundary)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. method:: get_content_charset(failobj=None)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
Note that this method differs from :meth:`get_charset` which returns the
:class:`~email.charset.Charset` instance for the default encoding of the message body.
2007-08-15 11:28:22 -03:00
.. method:: get_charsets(failobj=None)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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*.
2007-08-15 11:28:22 -03:00
.. method:: walk()
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
Here's an example that prints the MIME type of every part of a multipart
message structure::
2007-08-15 11:28:22 -03:00
>>> for part in msg.walk():
... print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
2007-08-15 11:28:22 -03:00
:class:`Message` objects can also optionally contain two instance attributes,
which can be used when generating the plain text of a MIME message.
2007-08-15 11:28:22 -03:00
.. attribute:: preamble
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
The *preamble* attribute contains this leading extra-armor text for MIME
documents. When the :class:`~email.parser.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:`~email.generator.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.
2007-08-15 11:28:22 -03:00
Note that if the message object has no preamble, the *preamble* attribute
will be ``None``.
2007-08-15 11:28:22 -03:00
.. attribute:: epilogue
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. attribute:: defects
2007-08-15 11:28:22 -03:00
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.