[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / module-email.Message.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-email.Parser.html" />
<link rel="prev" href="module-email.html" />
<link rel="parent" href="module-email.html" />
<link rel="next" href="node581.html" />
<meta name='aesop' content='information' />
<title>12.2.1 Representing an email message</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="12.2 email  "
  href="module-email.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="12.2 email  "
  href="module-email.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="12.2.1.1 Deprecated methods"
  href="node581.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-email.html">12.2 email  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-email.html">12.2 email  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node581.html">12.2.1.1 Deprecated methods</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0014210000000000000000">
12.2.1 Representing an email message</A>
</H2>
<A NAME="module-email.Message"></A>

<P>
The central class in the <tt class="module">email</tt> package is the
<tt class="class">Message</tt> class; it is the base class for the <tt class="module">email</tt>
object model.  <tt class="class">Message</tt> provides the core functionality for
setting and querying header fields, and for accessing message bodies.

<P>
Conceptually, a <tt class="class">Message</tt> object consists of <em>headers</em> and
<em>payloads</em>.  Headers are <a class="rfc" id='rfcref-90805' xml:id='rfcref-90805'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> 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.

<P>
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 <em>Unix-From</em> header or the
<code>From_</code> header.  The payload is either a string in the case of
simple message objects or a list of <tt class="class">Message</tt> objects for
MIME container documents (e.g. <span class="mimetype">multipart/*</span> and
<span class="mimetype">message/rfc822</span>).

<P>
<tt class="class">Message</tt> 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.

<P>
Here are the methods of the <tt class="class">Message</tt> class:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3829' xml:id='l2h-3829' class="class">Message</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
The constructor takes no arguments.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3830' xml:id='l2h-3830' class="method">as_string</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>unixfrom</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return the entire message flatten as a string.  When optional
<var>unixfrom</var> is <code>True</code>, the envelope header is included in the
returned string.  <var>unixfrom</var> defaults to <code>False</code>.

<P>
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 <code>From </code>.  For more flexibility, instantiate a
<tt class="class">Generator</tt> instance and use its
<tt class="method">flatten()</tt> method directly.  For example:

<P>
<div class="verbatim"><pre>
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()
</pre></div>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3831' xml:id='l2h-3831' class="method">__str__</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Equivalent to <tt class="method">as_string(unixfrom=True)</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3832' xml:id='l2h-3832' class="method">is_multipart</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return <code>True</code> if the message's payload is a list of
sub-<tt class="class">Message</tt> objects, otherwise return <code>False</code>.  When
<tt class="method">is_multipart()</tt> returns False, the payload should be a string
object.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3833' xml:id='l2h-3833' class="method">set_unixfrom</tt></b>(</nobr></td>
  <td><var>unixfrom</var>)</td></tr></table></dt>
<dd>
Set the message's envelope header to <var>unixfrom</var>, which should be a string.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3834' xml:id='l2h-3834' class="method">get_unixfrom</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the message's envelope header.  Defaults to <code>None</code> if the
envelope header was never set.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3835' xml:id='l2h-3835' class="method">attach</tt></b>(</nobr></td>
  <td><var>payload</var>)</td></tr></table></dt>
<dd>
Add the given <var>payload</var> to the current payload, which must be
<code>None</code> or a list of <tt class="class">Message</tt> objects before the call.
After the call, the payload will always be a list of <tt class="class">Message</tt>
objects.  If you want to set the payload to a scalar object (e.g. a
string), use <tt class="method">set_payload()</tt> instead.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3836' xml:id='l2h-3836' class="method">get_payload</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>i</var><big>[</big><var>, decode</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return a reference the current payload, which will be a list of
<tt class="class">Message</tt> objects when <tt class="method">is_multipart()</tt> is <code>True</code>, or a
string when <tt class="method">is_multipart()</tt> is <code>False</code>.  If the
payload is a list and you mutate the list object, you modify the
message's payload in place.

<P>
With optional argument <var>i</var>, <tt class="method">get_payload()</tt> will return the
<var>i</var>-th element of the payload, counting from zero, if
<tt class="method">is_multipart()</tt> is <code>True</code>.  An <tt class="exception">IndexError</tt>
will be raised if <var>i</var> 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. <tt class="method">is_multipart()</tt> is <code>False</code>) and <var>i</var> is given, a
<tt class="exception">TypeError</tt> is raised.

<P>
Optional <var>decode</var> is a flag indicating whether the payload should be
decoded or not, according to the <span class="mailheader">Content-Transfer-Encoding:</span> header.
When <code>True</code> and the message is not a multipart, the payload will be
decoded if this header's value is "<tt class="samp">quoted-printable</tt>" or
"<tt class="samp">base64</tt>".  If some other encoding is used, or
<span class="mailheader">Content-Transfer-Encoding:</span> 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
<var>decode</var> flag is <code>True</code>, then <code>None</code> is returned.  The
default for <var>decode</var> is <code>False</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3837' xml:id='l2h-3837' class="method">set_payload</tt></b>(</nobr></td>
  <td><var>payload</var><big>[</big><var>, charset</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Set the entire message object's payload to <var>payload</var>.  It is the
client's responsibility to ensure the payload invariants.  Optional
<var>charset</var> sets the message's default character set; see
<tt class="method">set_charset()</tt> for details.

<P>

<span class="versionnote">Changed in version 2.2.2:
<var>charset</var> argument added.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3838' xml:id='l2h-3838' class="method">set_charset</tt></b>(</nobr></td>
  <td><var>charset</var>)</td></tr></table></dt>
<dd>
Set the character set of the payload to <var>charset</var>, which can
either be a <tt class="class">Charset</tt> instance (see <tt class="module"><a href="module-email.Charset.html">email.Charset</a></tt>), a
string naming a character set,
or <code>None</code>.  If it is a string, it will be converted to a
<tt class="class">Charset</tt> instance.  If <var>charset</var> is <code>None</code>, the
<code>charset</code> parameter will be removed from the
<span class="mailheader">Content-Type:</span> header. Anything else will generate a
<tt class="exception">TypeError</tt>.

<P>
The message will be assumed to be of type <span class="mimetype">text/*</span> encoded with
<code>charset.input_charset</code>.  It will be converted to
<code>charset.output_charset</code>
and encoded properly, if needed, when generating the plain text
representation of the message.  MIME headers
(<span class="mailheader">MIME-Version:</span>, <span class="mailheader">Content-Type:</span>,
<span class="mailheader">Content-Transfer-Encoding:</span>) will be added as needed.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3839' xml:id='l2h-3839' class="method">get_charset</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the <tt class="class">Charset</tt> instance associated with the message's payload.

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
The following methods implement a mapping-like interface for accessing
the message's <a class="rfc" id='rfcref-90807' xml:id='rfcref-90807'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> 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
<tt class="method">keys()</tt>, but in a <tt class="class">Message</tt> 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.

<P>
These semantic differences are intentional and are biased toward
maximal convenience.

<P>
Note that in all cases, any envelope header present in the message is
not included in the mapping interface.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3840' xml:id='l2h-3840' class="method">__len__</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the total number of headers, including duplicates.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3841' xml:id='l2h-3841' class="method">__contains__</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return true if the message object has a field named <var>name</var>.
Matching is done case-insensitively and <var>name</var> should not include the
trailing colon.  Used for the <code>in</code> operator,
e.g.:

<P>
<div class="verbatim"><pre>
if 'message-id' in myMessage:
    print 'Message-ID:', myMessage['message-id']
</pre></div>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3842' xml:id='l2h-3842' class="method">__getitem__</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return the value of the named header field.  <var>name</var> should not
include the colon field separator.  If the header is missing,
<code>None</code> is returned; a <tt class="exception">KeyError</tt> is never raised.

<P>
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 <tt class="method">get_all()</tt> method to get the values of all
the extant named headers.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3843' xml:id='l2h-3843' class="method">__setitem__</tt></b>(</nobr></td>
  <td><var>name, val</var>)</td></tr></table></dt>
<dd>
Add a header to the message with field name <var>name</var> and value
<var>val</var>.  The field is appended to the end of the message's existing
fields.

<P>
Note that this does <em>not</em> 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
<var>name</var>, delete the field first, e.g.:

<P>
<div class="verbatim"><pre>
del msg['subject']
msg['subject'] = 'Python roolz!'
</pre></div>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3844' xml:id='l2h-3844' class="method">__delitem__</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Delete all occurrences of the field with name <var>name</var> from the
message's headers.  No exception is raised if the named field isn't
present in the headers.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3845' xml:id='l2h-3845' class="method">has_key</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return true if the message contains a header field named <var>name</var>,
otherwise return false.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3846' xml:id='l2h-3846' class="method">keys</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a list of all the message's header field names.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3847' xml:id='l2h-3847' class="method">values</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a list of all the message's field values.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3848' xml:id='l2h-3848' class="method">items</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a list of 2-tuples containing all the message's field headers
and values.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3849' xml:id='l2h-3849' class="method">get</tt></b>(</nobr></td>
  <td><var>name</var><big>[</big><var>, failobj</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return the value of the named header field.  This is identical to
<tt class="method">__getitem__()</tt> except that optional <var>failobj</var> is returned
if the named header is missing (defaults to <code>None</code>).
</dl>

<P>
Here are some additional useful methods:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3850' xml:id='l2h-3850' class="method">get_all</tt></b>(</nobr></td>
  <td><var>name</var><big>[</big><var>, failobj</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return a list of all the values for the field named <var>name</var>.
If there are no such named headers in the message, <var>failobj</var> is
returned (defaults to <code>None</code>).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3851' xml:id='l2h-3851' class="method">add_header</tt></b>(</nobr></td>
  <td><var>_name, _value, **_params</var>)</td></tr></table></dt>
<dd>
Extended header setting.  This method is similar to
<tt class="method">__setitem__()</tt> except that additional header parameters can be
provided as keyword arguments.  <var>_name</var> is the header field to add
and <var>_value</var> is the <em>primary</em> value for the header.

<P>
For each item in the keyword argument dictionary <var>_params</var>, 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 <code>key="value"</code> unless the value is
<code>None</code>, in which case only the key will be added.

<P>
Here's an example:

<P>
<div class="verbatim"><pre>
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
</pre></div>

<P>
This will add a header that looks like

<P>
<div class="verbatim"><pre>
Content-Disposition: attachment; filename="bud.gif"
</pre></div>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3852' xml:id='l2h-3852' class="method">replace_header</tt></b>(</nobr></td>
  <td><var>_name, _value</var>)</td></tr></table></dt>
<dd>
Replace a header.  Replace the first header found in the message that
matches <var>_name</var>, retaining header order and field name case.  If
no matching header was found, a <tt class="exception">KeyError</tt> is raised.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3853' xml:id='l2h-3853' class="method">get_content_type</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the message's content type.  The returned string is coerced to
lower case of the form <span class="mimetype">maintype/subtype</span>.  If there was no
<span class="mailheader">Content-Type:</span> header in the message the default type as
given by <tt class="method">get_default_type()</tt> will be returned.  Since
according to <a class="rfc" id='rfcref-90809' xml:id='rfcref-90809'
href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>, messages always have a default type,
<tt class="method">get_content_type()</tt> will always return a value.

<P>
<a class="rfc" id='rfcref-90811' xml:id='rfcref-90811'
href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a> defines a message's default type to be
<span class="mimetype">text/plain</span> unless it appears inside a
<span class="mimetype">multipart/digest</span> container, in which case it would be
<span class="mimetype">message/rfc822</span>.  If the <span class="mailheader">Content-Type:</span> header
has an invalid type specification, <a class="rfc" id='rfcref-90813' xml:id='rfcref-90813'
href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a> mandates that the
default type be <span class="mimetype">text/plain</span>.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3854' xml:id='l2h-3854' class="method">get_content_maintype</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the message's main content type.  This is the
<span class="mimetype">maintype</span> part of the string returned by
<tt class="method">get_content_type()</tt>.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3855' xml:id='l2h-3855' class="method">get_content_subtype</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the message's sub-content type.  This is the <span class="mimetype">subtype</span>
part of the string returned by <tt class="method">get_content_type()</tt>.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3856' xml:id='l2h-3856' class="method">get_default_type</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the default content type.  Most messages have a default content
type of <span class="mimetype">text/plain</span>, except for messages that are subparts
of <span class="mimetype">multipart/digest</span> containers.  Such subparts have a
default content type of <span class="mimetype">message/rfc822</span>.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3857' xml:id='l2h-3857' class="method">set_default_type</tt></b>(</nobr></td>
  <td><var>ctype</var>)</td></tr></table></dt>
<dd>
Set the default content type.  <var>ctype</var> should either be
<span class="mimetype">text/plain</span> or <span class="mimetype">message/rfc822</span>, although this is
not enforced.  The default content type is not stored in the
<span class="mailheader">Content-Type:</span> header.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3858' xml:id='l2h-3858' class="method">get_params</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>failobj</var><big>[</big><var>,
    header</var><big>[</big><var>, unquote</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return the message's <span class="mailheader">Content-Type:</span> parameters, as a list.  The
elements of the returned list are 2-tuples of key/value pairs, as
split on the "<tt class="character">=</tt>" sign.  The left hand side of the
"<tt class="character">=</tt>" is the key, while the right hand side is the value.  If
there is no "<tt class="character">=</tt>" sign in the parameter the value is the empty
string, otherwise the value is as described in <tt class="method">get_param()</tt> and is
unquoted if optional <var>unquote</var> is <code>True</code> (the default).

<P>
Optional <var>failobj</var> is the object to return if there is no
<span class="mailheader">Content-Type:</span> header.  Optional <var>header</var> is the header to
search instead of <span class="mailheader">Content-Type:</span>.

<P>

<span class="versionnote">Changed in version 2.2.2:
<var>unquote</var> argument added.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3859' xml:id='l2h-3859' class="method">get_param</tt></b>(</nobr></td>
  <td><var>param</var><big>[</big><var>,
    failobj</var><big>[</big><var>, header</var><big>[</big><var>, unquote</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return the value of the <span class="mailheader">Content-Type:</span> header's parameter
<var>param</var> as a string.  If the message has no <span class="mailheader">Content-Type:</span>
header or if there is no such parameter, then <var>failobj</var> is
returned (defaults to <code>None</code>).

<P>
Optional <var>header</var> if given, specifies the message header to use
instead of <span class="mailheader">Content-Type:</span>.

<P>
Parameter keys are always compared case insensitively.  The return
value can either be a string, or a 3-tuple if the parameter was
<a class="rfc" id='rfcref-90815' xml:id='rfcref-90815'
href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a> encoded.  When it's a 3-tuple, the elements of the value are of
the form <code>(CHARSET, LANGUAGE, VALUE)</code>.  Note that both <code>CHARSET</code> and
<code>LANGUAGE</code> can be <code>None</code>, in which case you should consider
<code>VALUE</code> to be encoded in the <code>us-ascii</code> charset.  You can
usually ignore <code>LANGUAGE</code>.

<P>
If your application doesn't care whether the parameter was encoded as in
<a class="rfc" id='rfcref-90817' xml:id='rfcref-90817'
href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>, you can collapse the parameter value by calling
<tt class="function">email.Utils.collapse_rfc2231_value()</tt>, passing in the return value
from <tt class="method">get_param()</tt>.  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:

<P>
<div class="verbatim"><pre>
rawparam = msg.get_param('foo')
param = email.Utils.collapse_rfc2231_value(rawparam)
</pre></div>

<P>
In any case, the parameter value (either the returned string, or the
<code>VALUE</code> item in the 3-tuple) is always unquoted, unless
<var>unquote</var> is set to <code>False</code>.

<P>

<span class="versionnote">Changed in version 2.2.2:
<var>unquote</var> argument added, and 3-tuple return value
possible.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3860' xml:id='l2h-3860' class="method">set_param</tt></b>(</nobr></td>
  <td><var>param, value</var><big>[</big><var>,
    header</var><big>[</big><var>, requote</var><big>[</big><var>, charset</var><big>[</big><var>, language</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>

<P>
Set a parameter in the <span class="mailheader">Content-Type:</span> header.  If the
parameter already exists in the header, its value will be replaced
with <var>value</var>.  If the <span class="mailheader">Content-Type:</span> header as not yet
been defined for this message, it will be set to <span class="mimetype">text/plain</span>
and the new parameter value will be appended as per <a class="rfc" id='rfcref-90819' xml:id='rfcref-90819'
href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>.

<P>
Optional <var>header</var> specifies an alternative header to
<span class="mailheader">Content-Type:</span>, and all parameters will be quoted as
necessary unless optional <var>requote</var> is <code>False</code> (the default
is <code>True</code>).

<P>
If optional <var>charset</var> is specified, the parameter will be encoded
according to <a class="rfc" id='rfcref-90821' xml:id='rfcref-90821'
href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>. Optional <var>language</var> specifies the RFC
2231 language, defaulting to the empty string.  Both <var>charset</var> and
<var>language</var> should be strings.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3861' xml:id='l2h-3861' class="method">del_param</tt></b>(</nobr></td>
  <td><var>param</var><big>[</big><var>, header</var><big>[</big><var>,
    requote</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Remove the given parameter completely from the
<span class="mailheader">Content-Type:</span> header.  The header will be re-written in
place without the parameter or its value.  All values will be quoted
as necessary unless <var>requote</var> is <code>False</code> (the default is
<code>True</code>).  Optional <var>header</var> specifies an alternative to
<span class="mailheader">Content-Type:</span>.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3862' xml:id='l2h-3862' class="method">set_type</tt></b>(</nobr></td>
  <td><var>type</var><big>[</big><var>, header</var><big>]</big><var></var><big>[</big><var>,
    requote</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Set the main type and subtype for the <span class="mailheader">Content-Type:</span>
header. <var>type</var> must be a string in the form
<span class="mimetype">maintype/subtype</span>, otherwise a <tt class="exception">ValueError</tt> is
raised.

<P>
This method replaces the <span class="mailheader">Content-Type:</span> header, keeping all
the parameters in place.  If <var>requote</var> is <code>False</code>, this
leaves the existing header's quoting as is, otherwise the parameters
will be quoted (the default).

<P>
An alternative header can be specified in the <var>header</var> argument.
When the <span class="mailheader">Content-Type:</span> header is set a
<span class="mailheader">MIME-Version:</span> header is also added.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3863' xml:id='l2h-3863' class="method">get_filename</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return the value of the <code>filename</code> parameter of the
<span class="mailheader">Content-Disposition:</span> header of the message, or <var>failobj</var> if
either the header is missing, or has no <code>filename</code> parameter.
The returned string will always be unquoted as per
<tt class="method">Utils.unquote()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3864' xml:id='l2h-3864' class="method">get_boundary</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return the value of the <code>boundary</code> parameter of the
<span class="mailheader">Content-Type:</span> header of the message, or <var>failobj</var> if either
the header is missing, or has no <code>boundary</code> parameter.  The
returned string will always be unquoted as per
<tt class="method">Utils.unquote()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3865' xml:id='l2h-3865' class="method">set_boundary</tt></b>(</nobr></td>
  <td><var>boundary</var>)</td></tr></table></dt>
<dd>
Set the <code>boundary</code> parameter of the <span class="mailheader">Content-Type:</span>
header to <var>boundary</var>.  <tt class="method">set_boundary()</tt> will always quote
<var>boundary</var> if necessary.  A <tt class="exception">HeaderParseError</tt> is raised
if the message object has no <span class="mailheader">Content-Type:</span> header.

<P>
Note that using this method is subtly different than deleting the old
<span class="mailheader">Content-Type:</span> header and adding a new one with the new boundary
via <tt class="method">add_header()</tt>, because <tt class="method">set_boundary()</tt> preserves the
order of the <span class="mailheader">Content-Type:</span> header in the list of headers.
However, it does <em>not</em> preserve any continuation lines which may
have been present in the original <span class="mailheader">Content-Type:</span> header.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3866' xml:id='l2h-3866' class="method">get_content_charset</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return the <code>charset</code> parameter of the <span class="mailheader">Content-Type:</span>
header, coerced to lower case.  If there is no
<span class="mailheader">Content-Type:</span> header, or if that header has no
<code>charset</code> parameter, <var>failobj</var> is returned.

<P>
Note that this method differs from <tt class="method">get_charset()</tt> which
returns the <tt class="class">Charset</tt> instance for the default encoding of the
message body.

<P>

<span class="versionnote">New in version 2.2.2.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3867' xml:id='l2h-3867' class="method">get_charsets</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>failobj</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return a list containing the character set names in the message.  If
the message is a <span class="mimetype">multipart</span>, then the list will contain one
element for each subpart in the payload, otherwise, it will be a list
of length 1.

<P>
Each item in the list will be a string which is the value of the
<code>charset</code> parameter in the <span class="mailheader">Content-Type:</span> header for the
represented subpart.  However, if the subpart has no
<span class="mailheader">Content-Type:</span> header, no <code>charset</code> parameter, or is not of
the <span class="mimetype">text</span> main MIME type, then that item in the returned list
will be <var>failobj</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3868' xml:id='l2h-3868' class="method">walk</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
The <tt class="method">walk()</tt> 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
<tt class="method">walk()</tt> as the iterator in a <code>for</code> loop; each
iteration returns the next subpart.

<P>
Here's an example that prints the MIME type of every part of a
multipart message structure:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; for part in msg.walk():
...     print part.get_content_type()
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
</pre></div>
</dl>

<P>
<tt class="class">Message</tt> objects can also optionally contain two instance
attributes, which can be used when generating the plain text of a MIME
message.

<P>
<dl><dt><b><tt id='l2h-3869' xml:id='l2h-3869'>preamble</tt></b></dt>
<dd>
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.

<P>
The <var>preamble</var> attribute contains this leading extra-armor text
for MIME documents.  When the <tt class="class">Parser</tt> discovers some text after
the headers but before the first boundary string, it assigns this text
to the message's <var>preamble</var> attribute.  When the <tt class="class">Generator</tt>
is writing out the plain text representation of a MIME message, and it
finds the message has a <var>preamble</var> attribute, it will write this
text in the area between the headers and the first boundary.  See
<tt class="module"><a href="module-email.Parser.html">email.Parser</a></tt> and <tt class="module"><a href="module-email.Generator.html">email.Generator</a></tt> for details.

<P>
Note that if the message object has no preamble, the
<var>preamble</var> attribute will be <code>None</code>.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-3870' xml:id='l2h-3870'>epilogue</tt></b></dt>
<dd>
The <var>epilogue</var> attribute acts the same way as the <var>preamble</var>
attribute, except that it contains text that appears between the last
boundary and the end of the message.

<P>
One note: when generating the flat text for a <span class="mimetype">multipart</span>
message that has no <var>epilogue</var> (using the standard
<tt class="class">Generator</tt> class), no newline is added after the closing
boundary line.  If the message object has an <var>epilogue</var> and its
value does not start with a newline, a newline is printed after the
closing boundary.  This seems a little clumsy, but it makes the most
practical sense.  The upshot is that if you want to ensure that a
newline get printed after your closing <span class="mimetype">multipart</span> boundary,
set the <var>epilogue</var> to the empty string.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-3871' xml:id='l2h-3871'>defects</tt></b></dt>
<dd>
The <var>defects</var> attribute contains a list of all the problems found when
parsing this message.  See <tt class="module"><a href="module-email.Errors.html">email.Errors</a></tt> for a detailed description
of the possible parsing defects.

<P>

<span class="versionnote">New in version 2.4.</span>

</dd></dl>

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="node581.html">12.2.1.1 Deprecated methods</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="12.2 email  "
  href="module-email.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="12.2 email  "
  href="module-email.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="12.2.1.1 Deprecated methods"
  href="node581.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-email.html">12.2 email  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-email.html">12.2 email  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node581.html">12.2.1.1 Deprecated methods</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>