Doc/lib/librfc822.tex

\section{Built-in module \sectcode{rfc822}}
\stmodindex{rfc822}

This module defines a class, \code{Message}, which represents a
collection of ``email headers'' as defined by the Internet standard
RFC 822.  It is used in various contexts, usually to read such headers
from a file.

A \code{Message} instance is instantiated with an open file object as
parameter.  Instantiation reads headers from the file up to a blank
line and stores them in the instance; after instantiation, the file is
positioned directly after the blank line that terminates the headers.

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.

All header matching is done independent of upper or lower case;
e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield
the same result.

A \code{Message} instance has the following methods:

\begin{funcdesc}{rewindbody}{}
Seek to the start of the message body.  This only works if the file
object is seekable.
\end{funcdesc}

\begin{funcdesc}{getallmatchingheaders}{name}
Return a list of lines consisting of all headers whose header matches
\var{name}, 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}.
\end{funcdesc}

\begin{funcdesc}{getfirstmatchingheader}{name}
Return a list of lines comprising the first header matching
\var{name}, and its continuation line(s), if any.  Return \code{None}
if there is no header matching \var{name}.
\end{funcdesc}

\begin{funcdesc}{getrawheader}{name}
Return a single string consisting of the text after the colon in the
first header matching \var{name}.  This includes leading whitespace,
the trailing linefeed, and internal linefeeds and whitespace if there
any continuation line(s) were present.  Return \code{None} if there is
no header matching \var{name}.
\end{funcdesc}

\begin{funcdesc}{getheader}{name}
Like \code{getrawheader(\var{name})}, but strip leading and trailing
whitespace (but not internal whitespace).
\end{funcdesc}

\begin{funcdesc}{getaddr}{name}
Return a pair (full name, email address) parsed from the string
returned by \code{getheader(\var{name})}.  If no header matching
\var{name} exists, return \code{None, None}; otherwise both the full
name and the address are (possibly empty )strings.

Example: if \code{m}'s first \code{From} header contains the string
\code{'guido@cwi.nl (Guido van Rossum)'}, then
\code{m.getaddr('From')} will yield the pair
\code{('Guido van Rossum', 'guido\@cwi.nl')}.
If the header contained
\code{'Guido van Rossum <guido\@cwi.nl>'} instead, it would yield the
exact same result.
\end{funcdesc}

\begin{funcdesc}{getaddrlist}{name}
This is similar to \code{getaddr(\var{list})}, but parses a header
containing a list of email addresses (e.g. a \code{To} header) and
returns a list of (full name, email address) pairs (even if there was
only one address in the header).  If there is no header matching
\var{name}, return an empty list.

XXX The current version of this function is not really correct.  It
yields bogus results if a full name contains a comma.
\end{funcdesc}

\begin{funcdesc}{getdate}{name}
Retrieve a header using \code{getheader} and parse it into a 9-tuple
compatible with \code{time.kmtime()}.  If there is no header matching
\var{name}, or it is unparsable, return \code{None}.

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.
\end{funcdesc}

\code{Message} instances also support a read-only mapping interface.
In particular: \code{m[name]} is the same as \code{m.getheader(name)};
and \code{len(m)}, \code{m.has_key(name)}, \code{m.keys()},
\code{m.values()} and \code{m.items()} act as expected (and
consistently).

Finally, \code{Message} instances have two public instance variables:

\begin{datadesc}{headers}
A list containing the entire set of header lines, in the order in
which they were read.  Each line contains a trailing newline.  The
blank line terminating the headers is not contained in the list.
\end{datadesc}

\begin{datadesc}{fp}
The file object passed at instantiation time.
\end{datadesc}