Doc/lib/librfc822.tex

   1 \section{Built-in module \sectcode{rfc822}}
   2 \stmodindex{rfc822}
   3
   4 \renewcommand{\indexsubitem}{(in module rfc822)}
   5
   6 This module defines a class, \code{Message}, which represents a
   7 collection of ``email headers'' as defined by the Internet standard
   8 RFC 822.  It is used in various contexts, usually to read such headers
   9 from a file.
  10
  11 A \code{Message} instance is instantiated with an open file object as
  12 parameter.  Instantiation reads headers from the file up to a blank
  13 line and stores them in the instance; after instantiation, the file is
  14 positioned directly after the blank line that terminates the headers.
  15
  16 Input lines as read from the file may either be terminated by CR-LF or
  17 by a single linefeed; a terminating CR-LF is replaced by a single
  18 linefeed before the line is stored.
  19
  20 All header matching is done independent of upper or lower case;
  21 e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield
  22 the same result.
  23
  24 A \code{Message} instance has the following methods:
  25
  26 \begin{funcdesc}{rewindbody}{}
  27 Seek to the start of the message body.  This only works if the file
  28 object is seekable.
  29 \end{funcdesc}
  30
  31 \begin{funcdesc}{getallmatchingheaders}{name}
  32 Return a list of lines consisting of all headers matching
  33 \var{name}, if any.  Each physical line, whether it is a continuation
  34 line or not, is a separate list item.  Return the empty list if no
  35 header matches \var{name}.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{getfirstmatchingheader}{name}
  39 Return a list of lines comprising the first header matching
  40 \var{name}, and its continuation line(s), if any.  Return \code{None}
  41 if there is no header matching \var{name}.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{getrawheader}{name}
  45 Return a single string consisting of the text after the colon in the
  46 first header matching \var{name}.  This includes leading whitespace,
  47 the trailing linefeed, and internal linefeeds and whitespace if there
  48 any continuation line(s) were present.  Return \code{None} if there is
  49 no header matching \var{name}.
  50 \end{funcdesc}
  51
  52 \begin{funcdesc}{getheader}{name}
  53 Like \code{getrawheader(\var{name})}, but strip leading and trailing
  54 whitespace (but not internal whitespace).
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{getaddr}{name}
  58 Return a pair (full name, email address) parsed from the string
  59 returned by \code{getheader(\var{name})}.  If no header matching
  60 \var{name} exists, return \code{None, None}; otherwise both the full
  61 name and the address are (possibly empty )strings.
  62
  63 Example: If \code{m}'s first \code{From} header contains the string
  64 \code{'guido@cwi.nl (Guido van Rossum)'}, then
  65 \code{m.getaddr('From')} will yield the pair
  66 \code{('Guido van Rossum', 'guido@cwi.nl')}.
  67 If the header contained
  68 \code{'Guido van Rossum <guido@cwi.nl>'} instead, it would yield the
  69 exact same result.
  70 \end{funcdesc}
  71
  72 \begin{funcdesc}{getaddrlist}{name}
  73 This is similar to \code{getaddr(\var{list})}, but parses a header
  74 containing a list of email addresses (e.g. a \code{To} header) and
  75 returns a list of (full name, email address) pairs (even if there was
  76 only one address in the header).  If there is no header matching
  77 \var{name}, return an empty list.
  78
  79 XXX The current version of this function is not really correct.  It
  80 yields bogus results if a full name contains a comma.
  81 \end{funcdesc}
  82
  83 \begin{funcdesc}{getdate}{name}
  84 Retrieve a header using \code{getheader} and parse it into a 9-tuple
  85 compatible with \code{time.mktime()}.  If there is no header matching
  86 \var{name}, or it is unparsable, return \code{None}.
  87
  88 Date parsing appears to be a black art, and not all mailers adhere to
  89 the standard.  While it has been tested and found correct on a large
  90 collection of email from many sources, it is still possible that this
  91 function may occasionally yield an incorrect result.
  92 \end{funcdesc}
  93
  94 \code{Message} instances also support a read-only mapping interface.
  95 In particular: \code{m[name]} is the same as \code{m.getheader(name)};
  96 and \code{len(m)}, \code{m.has_key(name)}, \code{m.keys()},
  97 \code{m.values()} and \code{m.items()} act as expected (and
  98 consistently).
  99
 100 Finally, \code{Message} instances have two public instance variables:
 101
 102 \begin{datadesc}{headers}
 103 A list containing the entire set of header lines, in the order in
 104 which they were read.  Each line contains a trailing newline.  The
 105 blank line terminating the headers is not contained in the list.
 106 \end{datadesc}
 107
 108 \begin{datadesc}{fp}
 109 The file object passed at instantiation time.
 110 \end{datadesc}