[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / message-objects.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="addresslist-objects.html" />
<link rel="prev" href="module-rfc822.html" />
<link rel="parent" href="module-rfc822.html" />
<link rel="next" href="addresslist-objects.html" />
<meta name='aesop' content='information' />
<title>12.11.1 Message Objects </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.11 rfc822  "
  href="module-rfc822.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.11 rfc822  "
  href="module-rfc822.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.11.2 AddressList Objects"
  href="addresslist-objects.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-rfc822.html">12.11 rfc822  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-rfc822.html">12.11 rfc822  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="addresslist-objects.html">12.11.2 AddressList Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION00141110000000000000000"></A><A NAME="message-objects"></A>
<BR>
12.11.1 Message Objects 
</H2>

<P>
A <tt class="class">Message</tt> instance has the following methods:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4084' xml:id='l2h-4084' class="method">rewindbody</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Seek to the start of the message body.  This only works if the file
object is seekable.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4085' xml:id='l2h-4085' class="method">isheader</tt></b>(</nobr></td>
  <td><var>line</var>)</td></tr></table></dt>
<dd>
Returns a line's canonicalized fieldname (the dictionary key that will
be used to index it) if the line is a legal <a class="rfc" id='rfcref-91201' xml:id='rfcref-91201'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> header; otherwise
returns <code>None</code> (implying that parsing should stop here and the
line be pushed back on the input stream).  It is sometimes useful to
override this method in a subclass.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4086' xml:id='l2h-4086' class="method">islast</tt></b>(</nobr></td>
  <td><var>line</var>)</td></tr></table></dt>
<dd>
Return true if the given line is a delimiter on which Message should
stop.  The delimiter line is consumed, and the file object's read
location positioned immediately after it.  By default this method just
checks that the line is blank, but you can override it in a subclass.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4087' xml:id='l2h-4087' class="method">iscomment</tt></b>(</nobr></td>
  <td><var>line</var>)</td></tr></table></dt>
<dd>
Return <code>True</code> if the given line should be ignored entirely, just skipped.
By default this is a stub that always returns <code>False</code>, but you can
override it in a subclass.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4088' xml:id='l2h-4088' class="method">getallmatchingheaders</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return a list of lines consisting of all headers matching
<var>name</var>, if any.  Each physical line, whether it is a continuation
line or not, is a separate list item.  Return the empty list if no
header matches <var>name</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4089' xml:id='l2h-4089' class="method">getfirstmatchingheader</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return a list of lines comprising the first header matching
<var>name</var>, and its continuation line(s), if any.  Return
<code>None</code> if there is no header matching <var>name</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4090' xml:id='l2h-4090' class="method">getrawheader</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return a single string consisting of the text after the colon in the
first header matching <var>name</var>.  This includes leading whitespace,
the trailing linefeed, and internal linefeeds and whitespace if there
any continuation line(s) were present.  Return <code>None</code> if there is
no header matching <var>name</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4091' xml:id='l2h-4091' class="method">getheader</tt></b>(</nobr></td>
  <td><var>name</var><big>[</big><var>, default</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Like <code>getrawheader(<var>name</var>)</code>, but strip leading and trailing
whitespace.  Internal whitespace is not stripped.  The optional
<var>default</var> argument can be used to specify a different default to
be returned when there is no header matching <var>name</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4092' xml:id='l2h-4092' class="method">get</tt></b>(</nobr></td>
  <td><var>name</var><big>[</big><var>, default</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
An alias for <tt class="method">getheader()</tt>, to make the interface more compatible 
with regular dictionaries.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4093' xml:id='l2h-4093' class="method">getaddr</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return a pair <code>(<var>full name</var>, <var>email address</var>)</code> parsed
from the string returned by <code>getheader(<var>name</var>)</code>.  If no
header matching <var>name</var> exists, return <code>(None, None)</code>;
otherwise both the full name and the address are (possibly empty)
strings.

<P>
Example: If <var>m</var>'s first <span class="mailheader">From:</span> header contains the
string <code>'jack@cwi.nl (Jack Jansen)'</code>, then
<code>m.getaddr('From')</code> will yield the pair
<code>('Jack Jansen', 'jack@cwi.nl')</code>.
If the header contained
<code>'Jack Jansen &lt;jack@cwi.nl&gt;'</code> instead, it would yield the
exact same result.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4094' xml:id='l2h-4094' class="method">getaddrlist</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
This is similar to <code>getaddr(<var>list</var>)</code>, but parses a header
containing a list of email addresses (e.g. a <span class="mailheader">To:</span> header) and
returns a list of <code>(<var>full name</var>, <var>email address</var>)</code> pairs
(even if there was only one address in the header).  If there is no
header matching <var>name</var>, return an empty list.

<P>
If multiple headers exist that match the named header (e.g. if there
are several <span class="mailheader">Cc:</span> headers), all are parsed for addresses.
Any continuation lines the named headers contain are also parsed.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4095' xml:id='l2h-4095' class="method">getdate</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Retrieve a header using <tt class="method">getheader()</tt> and parse it into a 9-tuple
compatible with <tt class="function">time.mktime()</tt>; note that fields 6, 7, and 8 
are not usable.  If there is no header matching
<var>name</var>, or it is unparsable, return <code>None</code>.

<P>
Date parsing appears to be a black art, and not all mailers adhere to
the standard.  While it has been tested and found correct on a large
collection of email from many sources, it is still possible that this
function may occasionally yield an incorrect result.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4096' xml:id='l2h-4096' class="method">getdate_tz</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Retrieve a header using <tt class="method">getheader()</tt> and parse it into a
10-tuple; the first 9 elements will make a tuple compatible with
<tt class="function">time.mktime()</tt>, and the 10th is a number giving the offset
of the date's timezone from UTC.  Note that fields 6, 7, and 8 
are not usable.  Similarly to <tt class="method">getdate()</tt>, if
there is no header matching <var>name</var>, or it is unparsable, return
<code>None</code>. 
</dl>

<P>
<tt class="class">Message</tt> instances also support a limited mapping interface.
In particular: <code><var>m</var>[name]</code> is like
<code><var>m</var>.getheader(name)</code> but raises <tt class="exception">KeyError</tt> if
there is no matching header; and <code>len(<var>m</var>)</code>,
<code><var>m</var>.get(<var>name</var><big>[</big>, <var>default</var><big>]</big>)</code>,
<code><var>m</var>.has_key(<var>name</var>)</code>, <code><var>m</var>.keys()</code>,
<code><var>m</var>.values()</code> <code><var>m</var>.items()</code>, and
<code><var>m</var>.setdefault(<var>name</var><big>[</big>, <var>default</var><big>]</big>)</code> act as
expected, with the one difference that <tt class="method">setdefault()</tt> uses
an empty string as the default value.  <tt class="class">Message</tt> instances
also support the mapping writable interface <code><var>m</var>[name] =
value</code> and <code>del <var>m</var>[name]</code>.  <tt class="class">Message</tt> objects do not
support the <tt class="method">clear()</tt>, <tt class="method">copy()</tt>, <tt class="method">popitem()</tt>, or
<tt class="method">update()</tt> methods of the mapping interface.  (Support for
<tt class="method">get()</tt> and <tt class="method">setdefault()</tt> was only added in Python
2.2.)

<P>
Finally, <tt class="class">Message</tt> instances have some public instance variables:

<P>
<dl><dt><b><tt id='l2h-4097' xml:id='l2h-4097' class="member">headers</tt></b></dt>
<dd>
A list containing the entire set of header lines, in the order in
which they were read (except that setitem calls may disturb this
order). Each line contains a trailing newline.  The
blank line terminating the headers is not contained in the list.
</dl>

<P>
<dl><dt><b><tt id='l2h-4098' xml:id='l2h-4098' class="member">fp</tt></b></dt>
<dd>
The file or file-like object passed at instantiation time.  This can
be used to read the message content.
</dl>

<P>
<dl><dt><b><tt id='l2h-4099' xml:id='l2h-4099' class="member">unixfrom</tt></b></dt>
<dd>
The <span class="Unix">Unix</span> "<tt class="samp">From&nbsp;</tt>" line, if the message had one, or an empty
string.  This is needed to regenerate the message in some contexts,
such as an <code>mbox</code>-style mailbox file.
</dl>

<P>

<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.11 rfc822  "
  href="module-rfc822.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.11 rfc822  "
  href="module-rfc822.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.11.2 AddressList Objects"
  href="addresslist-objects.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-rfc822.html">12.11 rfc822  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-rfc822.html">12.11 rfc822  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="addresslist-objects.html">12.11.2 AddressList Objects</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>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="addresslist-objects.html" />
	13	<link rel="prev" href="module-rfc822.html" />
	14	<link rel="parent" href="module-rfc822.html" />
	15	<link rel="next" href="addresslist-objects.html" />
	16	<meta name='aesop' content='information' />
	17	<title>12.11.1 Message Objects </title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="12.11 rfc822 "
	25	href="module-rfc822.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="12.11 rfc822 "
	28	href="module-rfc822.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="12.11.2 AddressList Objects"
	31	href="addresslist-objects.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="module-rfc822.html">12.11 rfc822 </A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-rfc822.html">12.11 rfc822 </A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="addresslist-objects.html">12.11.2 AddressList Objects</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION00141110000000000000000"></A><A NAME="message-objects"></A>
	56	<BR>
	57	12.11.1 Message Objects
	58	</H2>
	59
	60	<P>
	61	A <tt class="class">Message</tt> instance has the following methods:
	62
	63	<P>
	64	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
65	<td><nobr><b><tt id='l2h-4084' xml:id='l2h-4084' class="method">rewindbody</tt></b>(</nobr></td>
66	<td><var></var>)</td></tr></table></dt>
67	<dd>
68	Seek to the start of the message body. This only works if the file
69	object is seekable.
70	</dl>
71
72	<P>
73	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
74	<td><nobr><b><tt id='l2h-4085' xml:id='l2h-4085' class="method">isheader</tt></b>(</nobr></td>
75	<td><var>line</var>)</td></tr></table></dt>
76	<dd>
77	Returns a line's canonicalized fieldname (the dictionary key that will
78	be used to index it) if the line is a legal <a class="rfc" id='rfcref-91201' xml:id='rfcref-91201'
79	href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> header; otherwise
80	returns <code>None</code> (implying that parsing should stop here and the
81	line be pushed back on the input stream). It is sometimes useful to
82	override this method in a subclass.
83	</dl>
84
85	<P>
86	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
87	<td><nobr><b><tt id='l2h-4086' xml:id='l2h-4086' class="method">islast</tt></b>(</nobr></td>
88	<td><var>line</var>)</td></tr></table></dt>
89	<dd>
90	Return true if the given line is a delimiter on which Message should
91	stop. The delimiter line is consumed, and the file object's read
92	location positioned immediately after it. By default this method just
93	checks that the line is blank, but you can override it in a subclass.
94	</dl>
95
96	<P>
97	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
98	<td><nobr><b><tt id='l2h-4087' xml:id='l2h-4087' class="method">iscomment</tt></b>(</nobr></td>
99	<td><var>line</var>)</td></tr></table></dt>
100	<dd>
101	Return <code>True</code> if the given line should be ignored entirely, just skipped.
102	By default this is a stub that always returns <code>False</code>, but you can
103	override it in a subclass.
104	</dl>
105
106	<P>
107	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
108	<td><nobr><b><tt id='l2h-4088' xml:id='l2h-4088' class="method">getallmatchingheaders</tt></b>(</nobr></td>
109	<td><var>name</var>)</td></tr></table></dt>
110	<dd>
111	Return a list of lines consisting of all headers matching
112	<var>name</var>, if any. Each physical line, whether it is a continuation
113	line or not, is a separate list item. Return the empty list if no
114	header matches <var>name</var>.
115	</dl>
116
117	<P>
118	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
119	<td><nobr><b><tt id='l2h-4089' xml:id='l2h-4089' class="method">getfirstmatchingheader</tt></b>(</nobr></td>
120	<td><var>name</var>)</td></tr></table></dt>
121	<dd>
122	Return a list of lines comprising the first header matching
123	<var>name</var>, and its continuation line(s), if any. Return
124	<code>None</code> if there is no header matching <var>name</var>.
125	</dl>
126
127	<P>
128	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
129	<td><nobr><b><tt id='l2h-4090' xml:id='l2h-4090' class="method">getrawheader</tt></b>(</nobr></td>
130	<td><var>name</var>)</td></tr></table></dt>
131	<dd>
132	Return a single string consisting of the text after the colon in the
133	first header matching <var>name</var>. This includes leading whitespace,
134	the trailing linefeed, and internal linefeeds and whitespace if there
135	any continuation line(s) were present. Return <code>None</code> if there is
136	no header matching <var>name</var>.
137	</dl>
138
139	<P>
140	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
141	<td><nobr><b><tt id='l2h-4091' xml:id='l2h-4091' class="method">getheader</tt></b>(</nobr></td>
142	<td><var>name</var><big>[</big><var>, default</var><big>]</big><var></var>)</td></tr></table></dt>
143	<dd>
144	Like <code>getrawheader(<var>name</var>)</code>, but strip leading and trailing
145	whitespace. Internal whitespace is not stripped. The optional
146	<var>default</var> argument can be used to specify a different default to
147	be returned when there is no header matching <var>name</var>.
148	</dl>
149
150	<P>
151	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
152	<td><nobr><b><tt id='l2h-4092' xml:id='l2h-4092' class="method">get</tt></b>(</nobr></td>
153	<td><var>name</var><big>[</big><var>, default</var><big>]</big><var></var>)</td></tr></table></dt>
154	<dd>
155	An alias for <tt class="method">getheader()</tt>, to make the interface more compatible
156	with regular dictionaries.
157	</dl>
158
159	<P>
160	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
161	<td><nobr><b><tt id='l2h-4093' xml:id='l2h-4093' class="method">getaddr</tt></b>(</nobr></td>
162	<td><var>name</var>)</td></tr></table></dt>
163	<dd>
164	Return a pair <code>(<var>full name</var>, <var>email address</var>)</code> parsed
165	from the string returned by <code>getheader(<var>name</var>)</code>. If no
166	header matching <var>name</var> exists, return <code>(None, None)</code>;
167	otherwise both the full name and the address are (possibly empty)
168	strings.
169
170	<P>
171	Example: If <var>m</var>'s first <span class="mailheader">From:</span> header contains the
172	string <code>'jack@cwi.nl (Jack Jansen)'</code>, then
173	<code>m.getaddr('From')</code> will yield the pair
174	<code>('Jack Jansen', 'jack@cwi.nl')</code>.
175	If the header contained
176	<code>'Jack Jansen <jack@cwi.nl>'</code> instead, it would yield the
177	exact same result.
178	</dl>
179
180	<P>
181	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
182	<td><nobr><b><tt id='l2h-4094' xml:id='l2h-4094' class="method">getaddrlist</tt></b>(</nobr></td>
183	<td><var>name</var>)</td></tr></table></dt>
184	<dd>
185	This is similar to <code>getaddr(<var>list</var>)</code>, but parses a header
186	containing a list of email addresses (e.g. a <span class="mailheader">To:</span> header) and
187	returns a list of <code>(<var>full name</var>, <var>email address</var>)</code> pairs
188	(even if there was only one address in the header). If there is no
189	header matching <var>name</var>, return an empty list.
190
191	<P>
192	If multiple headers exist that match the named header (e.g. if there
193	are several <span class="mailheader">Cc:</span> headers), all are parsed for addresses.
194	Any continuation lines the named headers contain are also parsed.
195	</dl>
196
197	<P>
198	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
199	<td><nobr><b><tt id='l2h-4095' xml:id='l2h-4095' class="method">getdate</tt></b>(</nobr></td>
200	<td><var>name</var>)</td></tr></table></dt>
201	<dd>
202	Retrieve a header using <tt class="method">getheader()</tt> and parse it into a 9-tuple
203	compatible with <tt class="function">time.mktime()</tt>; note that fields 6, 7, and 8
204	are not usable. If there is no header matching
205	<var>name</var>, or it is unparsable, return <code>None</code>.
206
207	<P>
208	Date parsing appears to be a black art, and not all mailers adhere to
209	the standard. While it has been tested and found correct on a large
210	collection of email from many sources, it is still possible that this
211	function may occasionally yield an incorrect result.
212	</dl>
213
214	<P>
215	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
216	<td><nobr><b><tt id='l2h-4096' xml:id='l2h-4096' class="method">getdate_tz</tt></b>(</nobr></td>
217	<td><var>name</var>)</td></tr></table></dt>
218	<dd>
219	Retrieve a header using <tt class="method">getheader()</tt> and parse it into a
220	10-tuple; the first 9 elements will make a tuple compatible with
221	<tt class="function">time.mktime()</tt>, and the 10th is a number giving the offset
222	of the date's timezone from UTC. Note that fields 6, 7, and 8
223	are not usable. Similarly to <tt class="method">getdate()</tt>, if
224	there is no header matching <var>name</var>, or it is unparsable, return
225	<code>None</code>.
226	</dl>
227
228	<P>
229	<tt class="class">Message</tt> instances also support a limited mapping interface.
230	In particular: <code><var>m</var>[name]</code> is like
231	<code><var>m</var>.getheader(name)</code> but raises <tt class="exception">KeyError</tt> if
232	there is no matching header; and <code>len(<var>m</var>)</code>,
233	<code><var>m</var>.get(<var>name</var><big>[</big>, <var>default</var><big>]</big>)</code>,
234	<code><var>m</var>.has_key(<var>name</var>)</code>, <code><var>m</var>.keys()</code>,
235	<code><var>m</var>.values()</code> <code><var>m</var>.items()</code>, and
236	<code><var>m</var>.setdefault(<var>name</var><big>[</big>, <var>default</var><big>]</big>)</code> act as
237	expected, with the one difference that <tt class="method">setdefault()</tt> uses
238	an empty string as the default value. <tt class="class">Message</tt> instances
239	also support the mapping writable interface <code><var>m</var>[name] =
240	value</code> and <code>del <var>m</var>[name]</code>. <tt class="class">Message</tt> objects do not
241	support the <tt class="method">clear()</tt>, <tt class="method">copy()</tt>, <tt class="method">popitem()</tt>, or
242	<tt class="method">update()</tt> methods of the mapping interface. (Support for
243	<tt class="method">get()</tt> and <tt class="method">setdefault()</tt> was only added in Python
244	2.2.)
245
246	<P>
247	Finally, <tt class="class">Message</tt> instances have some public instance variables:
248
249	<P>
250	<dl><dt><b><tt id='l2h-4097' xml:id='l2h-4097' class="member">headers</tt></b></dt>
251	<dd>
252	A list containing the entire set of header lines, in the order in
253	which they were read (except that setitem calls may disturb this
254	order). Each line contains a trailing newline. The
255	blank line terminating the headers is not contained in the list.
256	</dl>
257
258	<P>
259	<dl><dt><b><tt id='l2h-4098' xml:id='l2h-4098' class="member">fp</tt></b></dt>
260	<dd>
261	The file or file-like object passed at instantiation time. This can
262	be used to read the message content.
263	</dl>
264
265	<P>
266	<dl><dt><b><tt id='l2h-4099' xml:id='l2h-4099' class="member">unixfrom</tt></b></dt>
267	<dd>
268	The <span class="Unix">Unix</span> "<tt class="samp">From </tt>" line, if the message had one, or an empty
269	string. This is needed to regenerate the message in some contexts,
270	such as an <code>mbox</code>-style mailbox file.
271	</dl>
272
273	<P>
274
275	<DIV CLASS="navigation">
276	<div class='online-navigation'>
277	<p></p><hr />
278	<table align="center" width="100%" cellpadding="0" cellspacing="2">
279	<tr>
280	<td class='online-navigation'><a rel="prev" title="12.11 rfc822 "
281	href="module-rfc822.html"><img src='../icons/previous.png'
282	border='0' height='32' alt='Previous Page' width='32' /></A></td>
283	<td class='online-navigation'><a rel="parent" title="12.11 rfc822 "
284	href="module-rfc822.html"><img src='../icons/up.png'
285	border='0' height='32' alt='Up One Level' width='32' /></A></td>
286	<td class='online-navigation'><a rel="next" title="12.11.2 AddressList Objects"
287	href="addresslist-objects.html"><img src='../icons/next.png'
288	border='0' height='32' alt='Next Page' width='32' /></A></td>
289	<td align="center" width="100%">Python Library Reference</td>
290	<td class='online-navigation'><a rel="contents" title="Table of Contents"
291	href="contents.html"><img src='../icons/contents.png'
292	border='0' height='32' alt='Contents' width='32' /></A></td>
293	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
294	border='0' height='32' alt='Module Index' width='32' /></a></td>
295	<td class='online-navigation'><a rel="index" title="Index"
296	href="genindex.html"><img src='../icons/index.png'
297	border='0' height='32' alt='Index' width='32' /></A></td>
298	</tr></table>
299	<div class='online-navigation'>
300	<b class="navlabel">Previous:</b>
301	<a class="sectref" rel="prev" href="module-rfc822.html">12.11 rfc822 </A>
302	<b class="navlabel">Up:</b>
303	<a class="sectref" rel="parent" href="module-rfc822.html">12.11 rfc822 </A>
304	<b class="navlabel">Next:</b>
305	<a class="sectref" rel="next" href="addresslist-objects.html">12.11.2 AddressList Objects</A>
306	</div>
307	</div>
308	<hr />
309	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
310	</DIV>
311	<!--End of Navigation Panel-->
312	<ADDRESS>
313	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
314	</ADDRESS>
315	</BODY>
316	</HTML>