Fred Drake | 3a0351c | 1998-04-04 07:23:21 +0000 | [diff] [blame] | 1 | \section{Standard Module \module{rfc822}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-rfc822} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 3 | \stmodindex{rfc822} |
| 4 | |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 5 | |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 6 | This module defines a class, \class{Message}, which represents a |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 7 | collection of ``email headers'' as defined by the Internet standard |
Fred Drake | c589124 | 1998-02-09 19:16:20 +0000 | [diff] [blame] | 8 | \rfc{822}. It is used in various contexts, usually to read such |
| 9 | headers from a file. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 10 | |
Fred Drake | 5ca9033 | 1997-12-16 15:19:47 +0000 | [diff] [blame] | 11 | Note that there's a separate module to read \UNIX{}, MH, and MMDF |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 12 | style mailbox files: \module{mailbox}\refstmodindex{mailbox}. |
Guido van Rossum | 067a2ac | 1997-06-02 17:30:03 +0000 | [diff] [blame] | 13 | |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 14 | \begin{classdesc}{Message}{file\optional{, seekable}} |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame^] | 15 | A \class{Message} instance is instantiated with an input object as |
| 16 | parameter. Message relies only on the input object having a |
| 17 | \code{readline} method; in particular, ordinary file objects qualify. |
| 18 | Instantiation reads headers from the input object up to a delimiter |
| 19 | line (normally a blank line) and stores them in the instance. |
| 20 | |
| 21 | If the input object has \code{seek} and \code{tell} methods, the |
| 22 | last action of the class initialization is to try to seek the object |
| 23 | to just before the blank line that terminates the headers. |
| 24 | Otherwise, if the input object has an \code{unread} method, that |
| 25 | method is used to push back the delimiter line. |
| 26 | |
| 27 | The optional \code{seekable} argument is provided as a workaround for |
| 28 | certain stdio libraries in which tell() discards buffered data before |
| 29 | discovering that the \code{lseek()} system call doesn't work. For |
| 30 | maximum portability, you should set the seekable argument to zero to |
| 31 | prevent that initial \code{tell} when passing in an unseekable object |
| 32 | such as a a file object created from a socket object. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 33 | |
| 34 | Input lines as read from the file may either be terminated by CR-LF or |
| 35 | by a single linefeed; a terminating CR-LF is replaced by a single |
| 36 | linefeed before the line is stored. |
| 37 | |
| 38 | All header matching is done independent of upper or lower case; |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 39 | e.g. \code{\var{m}['From']}, \code{\var{m}['from']} and |
| 40 | \code{\var{m}['FROM']} all yield the same result. |
| 41 | \end{classdesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 42 | |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 43 | \begin{funcdesc}{parsedate}{date} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 44 | Attempts to parse a date according to the rules in \rfc{822}. |
| 45 | however, some mailers don't follow that format as specified, so |
| 46 | \function{parsedate()} tries to guess correctly in such cases. |
Fred Drake | c589124 | 1998-02-09 19:16:20 +0000 | [diff] [blame] | 47 | \var{date} is a string containing an \rfc{822} date, such as |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 48 | \code{'Mon, 20 Nov 1995 19:12:08 -0500'}. If it succeeds in parsing |
| 49 | the date, \function{parsedate()} returns a 9-tuple that can be passed |
| 50 | directly to \function{time.mktime()}; otherwise \code{None} will be |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 51 | returned. |
| 52 | \end{funcdesc} |
| 53 | |
| 54 | \begin{funcdesc}{parsedate_tz}{date} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 55 | Performs the same function as \function{parsedate()}, but returns |
| 56 | either \code{None} or a 10-tuple; the first 9 elements make up a tuple |
| 57 | that can be passed directly to \function{time.mktime()}, and the tenth |
| 58 | is the offset of the date's timezone from UTC (which is the official |
| 59 | term for Greenwich Mean Time). (Note that the sign of the timezone |
| 60 | offset is the opposite of the sign of the \code{time.timezone} |
| 61 | variable for the same timezone; the latter variable follows the |
| 62 | \POSIX{} standard while this module follows \rfc{822}.) If the input |
| 63 | string has no timezone, the last element of the tuple returned is |
| 64 | \code{None}. |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 65 | \end{funcdesc} |
| 66 | |
Guido van Rossum | 8cf94e6 | 1998-02-18 05:09:14 +0000 | [diff] [blame] | 67 | \begin{funcdesc}{mktime_tz}{tuple} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 68 | Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC |
| 69 | timestamp. It the timezone item in the tuple is \code{None}, assume |
| 70 | local time. Minor deficiency: this first interprets the first 8 |
| 71 | elements as a local time and then compensates for the timezone |
| 72 | difference; this may yield a slight error around daylight savings time |
Guido van Rossum | 8cf94e6 | 1998-02-18 05:09:14 +0000 | [diff] [blame] | 73 | switch dates. Not enough to worry about for common use. |
| 74 | \end{funcdesc} |
| 75 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 76 | \subsection{Message Objects} |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 77 | \label{message-objects} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 78 | |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 79 | A \class{Message} instance has the following methods: |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 80 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 81 | \begin{methoddesc}{rewindbody}{} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 82 | Seek to the start of the message body. This only works if the file |
| 83 | object is seekable. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 84 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 85 | |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame^] | 86 | \begin{methoddesc}{islast}{line} |
| 87 | Return true if the given line is a delimiter on which Message should |
| 88 | stop. By default this method just checks that the line is blank, but |
| 89 | you can override it in a subclass. |
| 90 | \end{methoddesc} |
| 91 | |
| 92 | \begin{methoddesc}{iscomment}{line} |
| 93 | Return true if the given line should be ignored entirely, just skipped. |
| 94 | By default this is a stub that always returns false, but you can |
| 95 | override it in a subclass. |
| 96 | \end{methoddesc} |
| 97 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 98 | \begin{methoddesc}{getallmatchingheaders}{name} |
Guido van Rossum | 6c4f003 | 1995-03-07 10:14:09 +0000 | [diff] [blame] | 99 | Return a list of lines consisting of all headers matching |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 100 | \var{name}, if any. Each physical line, whether it is a continuation |
| 101 | line or not, is a separate list item. Return the empty list if no |
| 102 | header matches \var{name}. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 103 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 104 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 105 | \begin{methoddesc}{getfirstmatchingheader}{name} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 106 | Return a list of lines comprising the first header matching |
| 107 | \var{name}, and its continuation line(s), if any. Return \code{None} |
| 108 | if there is no header matching \var{name}. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 109 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 110 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 111 | \begin{methoddesc}{getrawheader}{name} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 112 | Return a single string consisting of the text after the colon in the |
| 113 | first header matching \var{name}. This includes leading whitespace, |
| 114 | the trailing linefeed, and internal linefeeds and whitespace if there |
| 115 | any continuation line(s) were present. Return \code{None} if there is |
| 116 | no header matching \var{name}. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 117 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 118 | |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame^] | 119 | \begin{methoddesc}{getheader}{name\optional{, default}} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 120 | Like \code{getrawheader(\var{name})}, but strip leading and trailing |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame^] | 121 | whitespace. Internal whitespace is not stripped. The optional |
| 122 | \var{default} argument can be used to specify a different default to |
| 123 | be returned when there is no header matching \var{name}. |
| 124 | \end{methoddesc} |
| 125 | |
| 126 | \begin{methoddesc}{get}{name\optional{, default}} |
| 127 | An alias for \code{getheader()}, to make the interface more compatible |
| 128 | with regular dictionaries. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 129 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 130 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 131 | \begin{methoddesc}{getaddr}{name} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 132 | Return a pair \code{(\var{full name}, \var{email address})} parsed |
| 133 | from the string returned by \code{getheader(\var{name})}. If no |
| 134 | header matching \var{name} exists, return \code{(None, None)}; |
| 135 | otherwise both the full name and the address are (possibly empty) |
| 136 | strings. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 137 | |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 138 | Example: If \var{m}'s first \code{From} header contains the string |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 139 | \code{'jack@cwi.nl (Jack Jansen)'}, then |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 140 | \code{m.getaddr('From')} will yield the pair |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 141 | \code{('Jack Jansen', 'jack@cwi.nl')}. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 142 | If the header contained |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 143 | \code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 144 | exact same result. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 145 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 146 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 147 | \begin{methoddesc}{getaddrlist}{name} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 148 | This is similar to \code{getaddr(\var{list})}, but parses a header |
| 149 | containing a list of email addresses (e.g. a \code{To} header) and |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 150 | returns a list of \code{(\var{full name}, \var{email address})} pairs |
| 151 | (even if there was only one address in the header). If there is no |
| 152 | header matching \var{name}, return an empty list. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 153 | |
| 154 | XXX The current version of this function is not really correct. It |
| 155 | yields bogus results if a full name contains a comma. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 156 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 157 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 158 | \begin{methoddesc}{getdate}{name} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 159 | Retrieve a header using \method{getheader()} and parse it into a 9-tuple |
| 160 | compatible with \function{time.mktime()}. If there is no header matching |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 161 | \var{name}, or it is unparsable, return \code{None}. |
| 162 | |
| 163 | Date parsing appears to be a black art, and not all mailers adhere to |
| 164 | the standard. While it has been tested and found correct on a large |
| 165 | collection of email from many sources, it is still possible that this |
| 166 | function may occasionally yield an incorrect result. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 167 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 168 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 169 | \begin{methoddesc}{getdate_tz}{name} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 170 | Retrieve a header using \method{getheader()} and parse it into a |
| 171 | 10-tuple; the first 9 elements will make a tuple compatible with |
| 172 | \function{time.mktime()}, and the 10th is a number giving the offset |
| 173 | of the date's timezone from UTC. Similarly to \method{getdate()}, if |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 174 | there is no header matching \var{name}, or it is unparsable, return |
| 175 | \code{None}. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 176 | \end{methoddesc} |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 177 | |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 178 | \class{Message} instances also support a read-only mapping interface. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 179 | In particular: \code{\var{m}[name]} is like |
| 180 | \code{\var{m}.getheader(name)} but raises \exception{KeyError} if |
| 181 | there is no matching header; and \code{len(\var{m})}, |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 182 | \code{\var{m}.has_key(name)}, \code{\var{m}.keys()}, |
| 183 | \code{\var{m}.values()} and \code{\var{m}.items()} act as expected |
| 184 | (and consistently). |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 185 | |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 186 | Finally, \class{Message} instances have two public instance variables: |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 187 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 188 | \begin{memberdesc}{headers} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 189 | A list containing the entire set of header lines, in the order in |
| 190 | which they were read. Each line contains a trailing newline. The |
| 191 | blank line terminating the headers is not contained in the list. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 192 | \end{memberdesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 193 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 194 | \begin{memberdesc}{fp} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 195 | The file object passed at instantiation time. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 196 | \end{memberdesc} |