<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>12.5 rfc822 --
Parse RFC 822 mail headers</TITLE>
<META NAME="description" CONTENT="12.5 rfc822 --
Parse RFC 822 mail headers">
<META NAME="keywords" CONTENT="lib">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="lib.css">
<LINK REL="next" HREF="module-mimetools.html">
<LINK REL="previous" HREF="module-formatter.html">
<LINK REL="up" HREF="netdata.html">
<LINK REL="next" HREF="message-objects.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="message-objects.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="netdata.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="writer-impls.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="message-objects.html">12.5.1 Message Objects</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="netdata.html">12. Internet Data Handling</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="writer-impls.html">12.4.4 Writer Implementations</A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0014500000000000000000">
12.5 <tt class=module>rfc822</tt> --
         Parse RFC 822 mail headers</A>
</H1>

<P>


<P>
This module defines a class, <tt class=class>Message</tt>, which represents a
collection of ``email headers'' as defined by the Internet standard
<span class=rfc><a name="rfcref-42727"
href="http://info.internet.isi.edu/in-notes/rfc/files/rfc822.txt">RFC 822</a></span>.  It is used in various contexts, usually to read such
headers from a file.  This module also defines a helper class 
<tt class=class>AddressList</tt> for parsing <span class=rfc><a name="rfcref-42729"
href="http://info.internet.isi.edu/in-notes/rfc/files/rfc822.txt">RFC 822</a></span> addresses.

<P>
Note that there's a separate module to read Unix, MH, and MMDF
style mailbox files: <tt class=module><a href="module-mailbox.html">mailbox</a></tt><a name="l2h-1975"></a>.

<P>
<dl><dt><b><a name="l2h-1970"><tt class=class>Message</tt></a></b> (<var>file</var><big>[</big><var>, seekable</var><big>]</big>)
<dd>
A <tt class=class>Message</tt> instance is instantiated with an input object as
parameter.  Message relies only on the input object having a
<tt class=method>readline()</tt> method; in particular, ordinary file objects
qualify.  Instantiation reads headers from the input object up to a
delimiter line (normally a blank line) and stores them in the
instance.

<P>
This class can work with any input object that supports a
<tt class=method>readline()</tt> method.  If the input object has seek and tell
capability, the <tt class=method>rewindbody()</tt> method will work; also, illegal
lines will be pushed back onto the input stream.  If the input object
lacks seek but has an <tt class=method>unread()</tt> method that can push back a
line of input, <tt class=class>Message</tt> will use that to push back illegal
lines.  Thus this class can be used to parse messages coming from a
buffered stream.

<P>
The optional <var>seekable</var> argument is provided as a workaround for
certain stdio libraries in which <tt class=cfunction>tell()</tt> discards buffered
data before discovering that the <tt class=cfunction>lseek()</tt> system call
doesn't work.  For maximum portability, you should set the seekable
argument to zero to prevent that initial <tt class=method>tell()</tt> when passing
in an unseekable object such as a a file object created from a socket
object.

<P>
Input lines as read from the file may either be terminated by CR-LF or
by a single linefeed; a terminating CR-LF is replaced by a single
linefeed before the line is stored.

<P>
All header matching is done independent of upper or lower case;
e.g. <tt><var>m</var>['From']</tt>, <tt><var>m</var>['from']</tt> and
<tt><var>m</var>['FROM']</tt> all yield the same result.
</dl>

<P>
<dl><dt><b><a name="l2h-1971"><tt class=class>AddressList</tt></a></b> (<var>field</var>)
<dd>
You may instantiate the AddresssList helper class using a single
string parameter, a comma-separated list of <span class=rfc><a name="rfcref-42732"
href="http://info.internet.isi.edu/in-notes/rfc/files/rfc822.txt">RFC 822</a></span> addresses to be
parsed.  (The parameter <tt>None</tt> yields an empty list.)
</dl>

<P>
<dl><dt><b><a name="l2h-1972"><tt class=function>parsedate</tt></a></b> (<var>date</var>)
<dd>
Attempts to parse a date according to the rules in <span class=rfc><a name="rfcref-42734"
href="http://info.internet.isi.edu/in-notes/rfc/files/rfc822.txt">RFC 822</a></span>.
however, some mailers don't follow that format as specified, so
<tt class=function>parsedate()</tt> tries to guess correctly in such cases. 
<var>date</var> is a string containing an <span class=rfc><a name="rfcref-42736"
href="http://info.internet.isi.edu/in-notes/rfc/files/rfc822.txt">RFC 822</a></span> date, such as 
<tt>'Mon, 20 Nov 1995 19:12:08 -0500'</tt>.  If it succeeds in parsing
the date, <tt class=function>parsedate()</tt> returns a 9-tuple that can be passed
directly to <tt class=function>time.mktime()</tt>; otherwise <tt>None</tt> will be
returned.  
</dl>

<P>
<dl><dt><b><a name="l2h-1973"><tt class=function>parsedate_tz</tt></a></b> (<var>date</var>)
<dd>
Performs the same function as <tt class=function>parsedate()</tt>, but returns
either <tt>None</tt> or a 10-tuple; the first 9 elements make up a tuple
that can be passed directly to <tt class=function>time.mktime()</tt>, and the tenth
is the offset of the date's timezone from UTC (which is the official
term for Greenwich Mean Time).  (Note that the sign of the timezone
offset is the opposite of the sign of the <tt>time.timezone</tt>variable for the same timezone; the latter variable follows the
POSIX standard while this module follows <span class=rfc><a name="rfcref-42738"
href="http://info.internet.isi.edu/in-notes/rfc/files/rfc822.txt">RFC 822</a></span>.)  If the input
string has no timezone, the last element of the tuple returned is
<tt>None</tt>.
</dl>

<P>
<dl><dt><b><a name="l2h-1974"><tt class=function>mktime_tz</tt></a></b> (<var>tuple</var>)
<dd>
Turn a 10-tuple as returned by <tt class=function>parsedate_tz()</tt> into a UTC
timestamp.  It the timezone item in the tuple is <tt>None</tt>, assume
local time.  Minor deficiency: this first interprets the first 8
elements as a local time and then compensates for the timezone
difference; this may yield a slight error around daylight savings time
switch dates.  Not enough to worry about for common use.
</dl>

<P>

<p><hr>
<!--Table of Child-Links-->


<UL>
<LI><A NAME="tex2html3368"
 HREF="message-objects.html">12.5.1 Message Objects </A>
<LI><A NAME="tex2html3369"
 HREF="addresslist-objects.html">12.5.2 AddressList Objects </A>
</UL>
<!--End of Table of Child-Links-->
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="message-objects.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="netdata.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="writer-impls.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="message-objects.html">12.5.1 Message Objects</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="netdata.html">12. Internet Data Handling</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="writer-impls.html">12.4.4 Writer Implementations</A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
