337 lines
14 KiB
TeX
337 lines
14 KiB
TeX
\section{\module{rfc822} ---
|
|
Parse RFC 2822 mail headers}
|
|
|
|
\declaremodule{standard}{rfc822}
|
|
\modulesynopsis{Parse \rfc{2822} style mail messages.}
|
|
|
|
\deprecated{2.3}{The \refmodule{email} package should be used in
|
|
preference to the \module{rfc822} module. This
|
|
module is present only to maintain backward
|
|
compatibility.}
|
|
|
|
This module defines a class, \class{Message}, which represents an
|
|
``email message'' as defined by the Internet standard
|
|
\rfc{2822}.\footnote{This module originally conformed to \rfc{822},
|
|
hence the name. Since then, \rfc{2822} has been released as an
|
|
update to \rfc{822}. This module should be considered
|
|
\rfc{2822}-conformant, especially in cases where the
|
|
syntax or semantics have changed since \rfc{822}.} Such messages
|
|
consist of a collection of message headers, and a message body. This
|
|
module also defines a helper class
|
|
\class{AddressList} for parsing \rfc{2822} addresses. Please refer to
|
|
the RFC for information on the specific syntax of \rfc{2822} messages.
|
|
|
|
The \refmodule{mailbox}\refstmodindex{mailbox} module provides classes
|
|
to read mailboxes produced by various end-user mail programs.
|
|
|
|
\begin{classdesc}{Message}{file\optional{, seekable}}
|
|
A \class{Message} instance is instantiated with an input object as
|
|
parameter. Message relies only on the input object having a
|
|
\method{readline()} 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. The message body, following the headers, is not consumed.
|
|
|
|
This class can work with any input object that supports a
|
|
\method{readline()} method. If the input object has seek and tell
|
|
capability, the \method{rewindbody()} method will work; also, illegal
|
|
lines will be pushed back onto the input stream. If the input object
|
|
lacks seek but has an \method{unread()} method that can push back a
|
|
line of input, \class{Message} will use that to push back illegal
|
|
lines. Thus this class can be used to parse messages coming from a
|
|
buffered stream.
|
|
|
|
The optional \var{seekable} argument is provided as a workaround for
|
|
certain stdio libraries in which \cfunction{tell()} discards buffered
|
|
data before discovering that the \cfunction{lseek()} system call
|
|
doesn't work. For maximum portability, you should set the seekable
|
|
argument to zero to prevent that initial \method{tell()} when passing
|
|
in an unseekable object such as a a file object created from a socket
|
|
object.
|
|
|
|
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{\var{m}['From']}, \code{\var{m}['from']} and
|
|
\code{\var{m}['FROM']} all yield the same result.
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{AddressList}{field}
|
|
You may instantiate the \class{AddressList} helper class using a single
|
|
string parameter, a comma-separated list of \rfc{2822} addresses to be
|
|
parsed. (The parameter \code{None} yields an empty list.)
|
|
\end{classdesc}
|
|
|
|
\begin{funcdesc}{quote}{str}
|
|
Return a new string with backslashes in \var{str} replaced by two
|
|
backslashes and double quotes replaced by backslash-double quote.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{unquote}{str}
|
|
Return a new string which is an \emph{unquoted} version of \var{str}.
|
|
If \var{str} ends and begins with double quotes, they are stripped
|
|
off. Likewise if \var{str} ends and begins with angle brackets, they
|
|
are stripped off.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{parseaddr}{address}
|
|
Parse \var{address}, which should be the value of some
|
|
address-containing field such as \mailheader{To} or \mailheader{Cc},
|
|
into its constituent ``realname'' and ``email address'' parts.
|
|
Returns a tuple of that information, unless the parse fails, in which
|
|
case a 2-tuple \code{(None, None)} is returned.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{dump_address_pair}{pair}
|
|
The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
|
|
\code{(\var{realname}, \var{email_address})} and returns the string
|
|
value suitable for a \mailheader{To} or \mailheader{Cc} header. If
|
|
the first element of \var{pair} is false, then the second element is
|
|
returned unmodified.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{parsedate}{date}
|
|
Attempts to parse a date according to the rules in \rfc{2822}.
|
|
however, some mailers don't follow that format as specified, so
|
|
\function{parsedate()} tries to guess correctly in such cases.
|
|
\var{date} is a string containing an \rfc{2822} date, such as
|
|
\code{'Mon, 20 Nov 1995 19:12:08 -0500'}. If it succeeds in parsing
|
|
the date, \function{parsedate()} returns a 9-tuple that can be passed
|
|
directly to \function{time.mktime()}; otherwise \code{None} will be
|
|
returned. Note that fields 6, 7, and 8 of the result tuple are not
|
|
usable.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{parsedate_tz}{date}
|
|
Performs the same function as \function{parsedate()}, but returns
|
|
either \code{None} or a 10-tuple; the first 9 elements make up a tuple
|
|
that can be passed directly to \function{time.mktime()}, 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 \code{time.timezone}
|
|
variable for the same timezone; the latter variable follows the
|
|
\POSIX{} standard while this module follows \rfc{2822}.) If the input
|
|
string has no timezone, the last element of the tuple returned is
|
|
\code{None}. Note that fields 6, 7, and 8 of the result tuple are not
|
|
usable.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mktime_tz}{tuple}
|
|
Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC
|
|
timestamp. If the timezone item in the tuple is \code{None}, 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.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seemodule{email}{Comprehensive email handling package; supercedes
|
|
the \module{rfc822} module.}
|
|
\seemodule{mailbox}{Classes to read various mailbox formats produced
|
|
by end-user mail programs.}
|
|
\seemodule{mimetools}{Subclass of \class{rfc822.Message} that
|
|
handles MIME encoded messages.}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{Message Objects \label{message-objects}}
|
|
|
|
A \class{Message} instance has the following methods:
|
|
|
|
\begin{methoddesc}{rewindbody}{}
|
|
Seek to the start of the message body. This only works if the file
|
|
object is seekable.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{isheader}{line}
|
|
Returns a line's canonicalized fieldname (the dictionary key that will
|
|
be used to index it) if the line is a legal \rfc{2822} header; otherwise
|
|
returns \code{None} (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.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{islast}{line}
|
|
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.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{iscomment}{line}
|
|
Return \code{True} if the given line should be ignored entirely, just skipped.
|
|
By default this is a stub that always returns \code{False}, but you can
|
|
override it in a subclass.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getallmatchingheaders}{name}
|
|
Return a list of lines consisting of all headers matching
|
|
\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{methoddesc}
|
|
|
|
\begin{methoddesc}{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{methoddesc}
|
|
|
|
\begin{methoddesc}{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{methoddesc}
|
|
|
|
\begin{methoddesc}{getheader}{name\optional{, default}}
|
|
Like \code{getrawheader(\var{name})}, but strip leading and trailing
|
|
whitespace. Internal whitespace is not stripped. The optional
|
|
\var{default} argument can be used to specify a different default to
|
|
be returned when there is no header matching \var{name}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{get}{name\optional{, default}}
|
|
An alias for \method{getheader()}, to make the interface more compatible
|
|
with regular dictionaries.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getaddr}{name}
|
|
Return a pair \code{(\var{full name}, \var{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 \var{m}'s first \mailheader{From} header contains the
|
|
string \code{'jack@cwi.nl (Jack Jansen)'}, then
|
|
\code{m.getaddr('From')} will yield the pair
|
|
\code{('Jack Jansen', 'jack@cwi.nl')}.
|
|
If the header contained
|
|
\code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the
|
|
exact same result.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getaddrlist}{name}
|
|
This is similar to \code{getaddr(\var{list})}, but parses a header
|
|
containing a list of email addresses (e.g.\ a \mailheader{To} header) and
|
|
returns a list of \code{(\var{full name}, \var{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.
|
|
|
|
If multiple headers exist that match the named header (e.g. if there
|
|
are several \mailheader{Cc} headers), all are parsed for addresses.
|
|
Any continuation lines the named headers contain are also parsed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getdate}{name}
|
|
Retrieve a header using \method{getheader()} and parse it into a 9-tuple
|
|
compatible with \function{time.mktime()}; note that fields 6, 7, and 8
|
|
are not usable. 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{methoddesc}
|
|
|
|
\begin{methoddesc}{getdate_tz}{name}
|
|
Retrieve a header using \method{getheader()} and parse it into a
|
|
10-tuple; the first 9 elements will make a tuple compatible with
|
|
\function{time.mktime()}, 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 \method{getdate()}, if
|
|
there is no header matching \var{name}, or it is unparsable, return
|
|
\code{None}.
|
|
\end{methoddesc}
|
|
|
|
\class{Message} instances also support a limited mapping interface.
|
|
In particular: \code{\var{m}[name]} is like
|
|
\code{\var{m}.getheader(name)} but raises \exception{KeyError} if
|
|
there is no matching header; and \code{len(\var{m})},
|
|
\code{\var{m}.get(name\optional{, deafult})},
|
|
\code{\var{m}.has_key(name)}, \code{\var{m}.keys()},
|
|
\code{\var{m}.values()} \code{\var{m}.items()}, and
|
|
\code{\var{m}.setdefault(name\optional{, default})} act as expected,
|
|
with the one difference that \method{get()} and \method{setdefault()}
|
|
use an empty string as the default value. \class{Message} instances
|
|
also support the mapping writable interface \code{\var{m}[name] =
|
|
value} and \code{del \var{m}[name]}. \class{Message} objects do not
|
|
support the \method{clear()}, \method{copy()}, \method{popitem()}, or
|
|
\method{update()} methods of the mapping interface. (Support for
|
|
\method{get()} and \method{setdefault()} was only added in Python
|
|
2.2.)
|
|
|
|
Finally, \class{Message} instances have some public instance variables:
|
|
|
|
\begin{memberdesc}{headers}
|
|
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.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{fp}
|
|
The file or file-like object passed at instantiation time. This can
|
|
be used to read the message content.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{unixfrom}
|
|
The \UNIX{} \samp{From~} 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}-style mailbox file.
|
|
\end{memberdesc}
|
|
|
|
|
|
\subsection{AddressList Objects \label{addresslist-objects}}
|
|
|
|
An \class{AddressList} instance has the following methods:
|
|
|
|
\begin{methoddesc}{__len__}{}
|
|
Return the number of addresses in the address list.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{__str__}{}
|
|
Return a canonicalized string representation of the address list.
|
|
Addresses are rendered in "name" <host@domain> form, comma-separated.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{__add__}{alist}
|
|
Return a new \class{AddressList} instance that contains all addresses
|
|
in both \class{AddressList} operands, with duplicates removed (set
|
|
union).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{__iadd__}{alist}
|
|
In-place version of \method{__add__()}; turns this \class{AddressList}
|
|
instance into the union of itself and the right-hand instance,
|
|
\var{alist}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{__sub__}{alist}
|
|
Return a new \class{AddressList} instance that contains every address
|
|
in the left-hand \class{AddressList} operand that is not present in
|
|
the right-hand address operand (set difference).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{__isub__}{alist}
|
|
In-place version of \method{__sub__()}, removing addresses in this
|
|
list which are also in \var{alist}.
|
|
\end{methoddesc}
|
|
|
|
|
|
Finally, \class{AddressList} instances have one public instance variable:
|
|
|
|
\begin{memberdesc}{addresslist}
|
|
A list of tuple string pairs, one per address. In each member, the
|
|
first is the canonicalized name part, the second is the
|
|
actual route-address (\character{@}-separated username-host.domain
|
|
pair).
|
|
\end{memberdesc}
|