Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{rfc822} --- |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 2 | Parse RFC 2822 mail headers} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 3 | |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{rfc822} |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 5 | \modulesynopsis{Parse \rfc{2822} style mail messages.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 6 | |
Fred Drake | 4613876 | 2002-09-25 22:13:27 +0000 | [diff] [blame] | 7 | \deprecated{2.3}{The \refmodule{email} package should be used in |
| 8 | preference to the \module{rfc822} module. This |
| 9 | module is present only to maintain backward |
| 10 | compatibility.} |
| 11 | |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 12 | This module defines a class, \class{Message}, which represents an |
| 13 | ``email message'' as defined by the Internet standard |
Fred Drake | e78661b | 2001-07-17 05:17:58 +0000 | [diff] [blame] | 14 | \rfc{2822}.\footnote{This module originally conformed to \rfc{822}, |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 15 | hence the name. Since then, \rfc{2822} has been released as an |
| 16 | update to \rfc{822}. This module should be considered |
| 17 | \rfc{2822}-conformant, especially in cases where the |
Fred Drake | e78661b | 2001-07-17 05:17:58 +0000 | [diff] [blame] | 18 | syntax or semantics have changed since \rfc{822}.} Such messages |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 19 | consist of a collection of message headers, and a message body. This |
| 20 | module also defines a helper class |
| 21 | \class{AddressList} for parsing \rfc{2822} addresses. Please refer to |
| 22 | the RFC for information on the specific syntax of \rfc{2822} messages. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 23 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 24 | The \refmodule{mailbox}\refstmodindex{mailbox} module provides classes |
| 25 | to read mailboxes produced by various end-user mail programs. |
Guido van Rossum | 067a2ac | 1997-06-02 17:30:03 +0000 | [diff] [blame] | 26 | |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 27 | \begin{classdesc}{Message}{file\optional{, seekable}} |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame] | 28 | A \class{Message} instance is instantiated with an input object as |
| 29 | parameter. Message relies only on the input object having a |
Fred Drake | 23329d4 | 1998-08-10 17:46:22 +0000 | [diff] [blame] | 30 | \method{readline()} method; in particular, ordinary file objects |
| 31 | qualify. Instantiation reads headers from the input object up to a |
| 32 | delimiter line (normally a blank line) and stores them in the |
Eric S. Raymond | e7213c7 | 2001-01-27 10:56:14 +0000 | [diff] [blame] | 33 | instance. The message body, following the headers, is not consumed. |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame] | 34 | |
Fred Drake | 23329d4 | 1998-08-10 17:46:22 +0000 | [diff] [blame] | 35 | This class can work with any input object that supports a |
| 36 | \method{readline()} method. If the input object has seek and tell |
| 37 | capability, the \method{rewindbody()} method will work; also, illegal |
| 38 | lines will be pushed back onto the input stream. If the input object |
| 39 | lacks seek but has an \method{unread()} method that can push back a |
| 40 | line of input, \class{Message} will use that to push back illegal |
| 41 | lines. Thus this class can be used to parse messages coming from a |
| 42 | buffered stream. |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame] | 43 | |
Fred Drake | 23329d4 | 1998-08-10 17:46:22 +0000 | [diff] [blame] | 44 | The optional \var{seekable} argument is provided as a workaround for |
| 45 | certain stdio libraries in which \cfunction{tell()} discards buffered |
| 46 | data before discovering that the \cfunction{lseek()} system call |
| 47 | doesn't work. For maximum portability, you should set the seekable |
| 48 | argument to zero to prevent that initial \method{tell()} when passing |
Raymond Hettinger | 999b57c | 2003-08-25 04:28:05 +0000 | [diff] [blame] | 49 | in an unseekable object such as a file object created from a socket |
Fred Drake | 23329d4 | 1998-08-10 17:46:22 +0000 | [diff] [blame] | 50 | object. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 51 | |
| 52 | Input lines as read from the file may either be terminated by CR-LF or |
| 53 | by a single linefeed; a terminating CR-LF is replaced by a single |
| 54 | linefeed before the line is stored. |
| 55 | |
| 56 | All header matching is done independent of upper or lower case; |
Fred Drake | 23329d4 | 1998-08-10 17:46:22 +0000 | [diff] [blame] | 57 | e.g.\ \code{\var{m}['From']}, \code{\var{m}['from']} and |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 58 | \code{\var{m}['FROM']} all yield the same result. |
| 59 | \end{classdesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 60 | |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 61 | \begin{classdesc}{AddressList}{field} |
Fred Drake | ae0f292 | 1999-06-10 15:03:07 +0000 | [diff] [blame] | 62 | You may instantiate the \class{AddressList} helper class using a single |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 63 | string parameter, a comma-separated list of \rfc{2822} addresses to be |
Fred Drake | 23329d4 | 1998-08-10 17:46:22 +0000 | [diff] [blame] | 64 | parsed. (The parameter \code{None} yields an empty list.) |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 65 | \end{classdesc} |
| 66 | |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 67 | \begin{funcdesc}{quote}{str} |
| 68 | Return a new string with backslashes in \var{str} replaced by two |
| 69 | backslashes and double quotes replaced by backslash-double quote. |
| 70 | \end{funcdesc} |
| 71 | |
| 72 | \begin{funcdesc}{unquote}{str} |
| 73 | Return a new string which is an \emph{unquoted} version of \var{str}. |
| 74 | If \var{str} ends and begins with double quotes, they are stripped |
| 75 | off. Likewise if \var{str} ends and begins with angle brackets, they |
| 76 | are stripped off. |
| 77 | \end{funcdesc} |
| 78 | |
| 79 | \begin{funcdesc}{parseaddr}{address} |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 80 | Parse \var{address}, which should be the value of some |
| 81 | address-containing field such as \mailheader{To} or \mailheader{Cc}, |
| 82 | into its constituent ``realname'' and ``email address'' parts. |
| 83 | Returns a tuple of that information, unless the parse fails, in which |
| 84 | case a 2-tuple \code{(None, None)} is returned. |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 85 | \end{funcdesc} |
| 86 | |
| 87 | \begin{funcdesc}{dump_address_pair}{pair} |
| 88 | The inverse of \method{parseaddr()}, this takes a 2-tuple of the form |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 89 | \code{(\var{realname}, \var{email_address})} and returns the string |
| 90 | value suitable for a \mailheader{To} or \mailheader{Cc} header. If |
| 91 | the first element of \var{pair} is false, then the second element is |
| 92 | returned unmodified. |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 93 | \end{funcdesc} |
| 94 | |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 95 | \begin{funcdesc}{parsedate}{date} |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 96 | Attempts to parse a date according to the rules in \rfc{2822}. |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 97 | however, some mailers don't follow that format as specified, so |
| 98 | \function{parsedate()} tries to guess correctly in such cases. |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 99 | \var{date} is a string containing an \rfc{2822} date, such as |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 100 | \code{'Mon, 20 Nov 1995 19:12:08 -0500'}. If it succeeds in parsing |
| 101 | the date, \function{parsedate()} returns a 9-tuple that can be passed |
| 102 | directly to \function{time.mktime()}; otherwise \code{None} will be |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 103 | returned. Note that fields 6, 7, and 8 of the result tuple are not |
| 104 | usable. |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 105 | \end{funcdesc} |
| 106 | |
| 107 | \begin{funcdesc}{parsedate_tz}{date} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 108 | Performs the same function as \function{parsedate()}, but returns |
| 109 | either \code{None} or a 10-tuple; the first 9 elements make up a tuple |
| 110 | that can be passed directly to \function{time.mktime()}, and the tenth |
| 111 | is the offset of the date's timezone from UTC (which is the official |
| 112 | term for Greenwich Mean Time). (Note that the sign of the timezone |
| 113 | offset is the opposite of the sign of the \code{time.timezone} |
| 114 | variable for the same timezone; the latter variable follows the |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 115 | \POSIX{} standard while this module follows \rfc{2822}.) If the input |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 116 | string has no timezone, the last element of the tuple returned is |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 117 | \code{None}. Note that fields 6, 7, and 8 of the result tuple are not |
| 118 | usable. |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 119 | \end{funcdesc} |
| 120 | |
Guido van Rossum | 8cf94e6 | 1998-02-18 05:09:14 +0000 | [diff] [blame] | 121 | \begin{funcdesc}{mktime_tz}{tuple} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 122 | Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC |
Fred Drake | d93d68b | 2002-01-05 01:52:41 +0000 | [diff] [blame] | 123 | timestamp. If the timezone item in the tuple is \code{None}, assume |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 124 | local time. Minor deficiency: this first interprets the first 8 |
| 125 | elements as a local time and then compensates for the timezone |
| 126 | difference; this may yield a slight error around daylight savings time |
Guido van Rossum | 8cf94e6 | 1998-02-18 05:09:14 +0000 | [diff] [blame] | 127 | switch dates. Not enough to worry about for common use. |
| 128 | \end{funcdesc} |
| 129 | |
Fred Drake | ea00205 | 1999-04-28 18:11:09 +0000 | [diff] [blame] | 130 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 131 | \begin{seealso} |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 132 | \seemodule{email}{Comprehensive email handling package; supersedes |
Fred Drake | 2d3c03d | 2002-08-06 21:26:01 +0000 | [diff] [blame] | 133 | the \module{rfc822} module.} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 134 | \seemodule{mailbox}{Classes to read various mailbox formats produced |
| 135 | by end-user mail programs.} |
Fred Drake | 2d3c03d | 2002-08-06 21:26:01 +0000 | [diff] [blame] | 136 | \seemodule{mimetools}{Subclass of \class{rfc822.Message} that |
| 137 | handles MIME encoded messages.} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 138 | \end{seealso} |
| 139 | |
| 140 | |
Fred Drake | ea00205 | 1999-04-28 18:11:09 +0000 | [diff] [blame] | 141 | \subsection{Message Objects \label{message-objects}} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 142 | |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 143 | A \class{Message} instance has the following methods: |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 144 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 145 | \begin{methoddesc}{rewindbody}{} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 146 | Seek to the start of the message body. This only works if the file |
| 147 | object is seekable. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 148 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 149 | |
Guido van Rossum | 444d0f8 | 1998-06-11 13:50:02 +0000 | [diff] [blame] | 150 | \begin{methoddesc}{isheader}{line} |
| 151 | Returns a line's canonicalized fieldname (the dictionary key that will |
Barry Warsaw | 95400a2 | 2001-07-16 20:47:58 +0000 | [diff] [blame] | 152 | be used to index it) if the line is a legal \rfc{2822} header; otherwise |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 153 | returns \code{None} (implying that parsing should stop here and the |
| 154 | line be pushed back on the input stream). It is sometimes useful to |
| 155 | override this method in a subclass. |
Guido van Rossum | 444d0f8 | 1998-06-11 13:50:02 +0000 | [diff] [blame] | 156 | \end{methoddesc} |
| 157 | |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame] | 158 | \begin{methoddesc}{islast}{line} |
| 159 | Return true if the given line is a delimiter on which Message should |
Guido van Rossum | 444d0f8 | 1998-06-11 13:50:02 +0000 | [diff] [blame] | 160 | stop. The delimiter line is consumed, and the file object's read |
| 161 | location positioned immediately after it. By default this method just |
| 162 | checks that the line is blank, but you can override it in a subclass. |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame] | 163 | \end{methoddesc} |
| 164 | |
| 165 | \begin{methoddesc}{iscomment}{line} |
Neal Norwitz | 6b35370 | 2002-04-09 18:15:00 +0000 | [diff] [blame] | 166 | Return \code{True} if the given line should be ignored entirely, just skipped. |
| 167 | By default this is a stub that always returns \code{False}, but you can |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame] | 168 | override it in a subclass. |
| 169 | \end{methoddesc} |
| 170 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 171 | \begin{methoddesc}{getallmatchingheaders}{name} |
Guido van Rossum | 6c4f003 | 1995-03-07 10:14:09 +0000 | [diff] [blame] | 172 | Return a list of lines consisting of all headers matching |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 173 | \var{name}, if any. Each physical line, whether it is a continuation |
| 174 | line or not, is a separate list item. Return the empty list if no |
| 175 | header matches \var{name}. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 176 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 177 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 178 | \begin{methoddesc}{getfirstmatchingheader}{name} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 179 | Return a list of lines comprising the first header matching |
Fred Drake | ea00205 | 1999-04-28 18:11:09 +0000 | [diff] [blame] | 180 | \var{name}, and its continuation line(s), if any. Return |
| 181 | \code{None} if there is no header matching \var{name}. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 182 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 183 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 184 | \begin{methoddesc}{getrawheader}{name} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 185 | Return a single string consisting of the text after the colon in the |
| 186 | first header matching \var{name}. This includes leading whitespace, |
| 187 | the trailing linefeed, and internal linefeeds and whitespace if there |
| 188 | any continuation line(s) were present. Return \code{None} if there is |
| 189 | no header matching \var{name}. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 190 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 191 | |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame] | 192 | \begin{methoddesc}{getheader}{name\optional{, default}} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 193 | Like \code{getrawheader(\var{name})}, but strip leading and trailing |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame] | 194 | whitespace. Internal whitespace is not stripped. The optional |
| 195 | \var{default} argument can be used to specify a different default to |
| 196 | be returned when there is no header matching \var{name}. |
| 197 | \end{methoddesc} |
| 198 | |
| 199 | \begin{methoddesc}{get}{name\optional{, default}} |
Fred Drake | 23329d4 | 1998-08-10 17:46:22 +0000 | [diff] [blame] | 200 | An alias for \method{getheader()}, to make the interface more compatible |
Guido van Rossum | 1299100 | 1998-06-10 21:34:27 +0000 | [diff] [blame] | 201 | with regular dictionaries. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 202 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 203 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 204 | \begin{methoddesc}{getaddr}{name} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 205 | Return a pair \code{(\var{full name}, \var{email address})} parsed |
| 206 | from the string returned by \code{getheader(\var{name})}. If no |
| 207 | header matching \var{name} exists, return \code{(None, None)}; |
| 208 | otherwise both the full name and the address are (possibly empty) |
| 209 | strings. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 210 | |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 211 | Example: If \var{m}'s first \mailheader{From} header contains the |
| 212 | string \code{'jack@cwi.nl (Jack Jansen)'}, then |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 213 | \code{m.getaddr('From')} will yield the pair |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 214 | \code{('Jack Jansen', 'jack@cwi.nl')}. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 215 | If the header contained |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 216 | \code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 217 | exact same result. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 218 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 219 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 220 | \begin{methoddesc}{getaddrlist}{name} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 221 | This is similar to \code{getaddr(\var{list})}, but parses a header |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 222 | containing a list of email addresses (e.g.\ a \mailheader{To} header) and |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 223 | returns a list of \code{(\var{full name}, \var{email address})} pairs |
| 224 | (even if there was only one address in the header). If there is no |
| 225 | header matching \var{name}, return an empty list. |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 226 | |
Barry Warsaw | 53610ca | 1999-01-14 21:26:54 +0000 | [diff] [blame] | 227 | If multiple headers exist that match the named header (e.g. if there |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 228 | are several \mailheader{Cc} headers), all are parsed for addresses. |
| 229 | Any continuation lines the named headers contain are also parsed. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 230 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 231 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 232 | \begin{methoddesc}{getdate}{name} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 233 | Retrieve a header using \method{getheader()} and parse it into a 9-tuple |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 234 | compatible with \function{time.mktime()}; note that fields 6, 7, and 8 |
| 235 | are not usable. If there is no header matching |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 236 | \var{name}, or it is unparsable, return \code{None}. |
| 237 | |
| 238 | Date parsing appears to be a black art, and not all mailers adhere to |
| 239 | the standard. While it has been tested and found correct on a large |
| 240 | collection of email from many sources, it is still possible that this |
| 241 | function may occasionally yield an incorrect result. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 242 | \end{methoddesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 243 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 244 | \begin{methoddesc}{getdate_tz}{name} |
Fred Drake | cdea8a3 | 1998-03-14 06:17:43 +0000 | [diff] [blame] | 245 | Retrieve a header using \method{getheader()} and parse it into a |
| 246 | 10-tuple; the first 9 elements will make a tuple compatible with |
| 247 | \function{time.mktime()}, and the 10th is a number giving the offset |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 248 | of the date's timezone from UTC. Note that fields 6, 7, and 8 |
| 249 | are not usable. Similarly to \method{getdate()}, if |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 250 | there is no header matching \var{name}, or it is unparsable, return |
| 251 | \code{None}. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 252 | \end{methoddesc} |
Guido van Rossum | 843e712 | 1996-12-06 21:23:53 +0000 | [diff] [blame] | 253 | |
Fred Drake | 7063149 | 2001-05-22 14:36:30 +0000 | [diff] [blame] | 254 | \class{Message} instances also support a limited mapping interface. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 255 | In particular: \code{\var{m}[name]} is like |
| 256 | \code{\var{m}.getheader(name)} but raises \exception{KeyError} if |
| 257 | there is no matching header; and \code{len(\var{m})}, |
Fred Drake | 853276e | 2003-07-16 17:58:38 +0000 | [diff] [blame] | 258 | \code{\var{m}.get(\var{name}\optional{, \var{default}})}, |
Fred Drake | aa02c84 | 2002-10-09 22:33:23 +0000 | [diff] [blame] | 259 | \code{\var{m}.has_key(\var{name})}, \code{\var{m}.keys()}, |
Fred Drake | 6b4593e | 2001-05-22 15:12:46 +0000 | [diff] [blame] | 260 | \code{\var{m}.values()} \code{\var{m}.items()}, and |
Fred Drake | 853276e | 2003-07-16 17:58:38 +0000 | [diff] [blame] | 261 | \code{\var{m}.setdefault(\var{name}\optional{, \var{default}})} act as |
Fred Drake | aa02c84 | 2002-10-09 22:33:23 +0000 | [diff] [blame] | 262 | expected, with the one difference that \method{setdefault()} uses |
| 263 | an empty string as the default value. \class{Message} instances |
Fred Drake | 98cfab6 | 2001-05-22 22:00:40 +0000 | [diff] [blame] | 264 | also support the mapping writable interface \code{\var{m}[name] = |
| 265 | value} and \code{del \var{m}[name]}. \class{Message} objects do not |
| 266 | support the \method{clear()}, \method{copy()}, \method{popitem()}, or |
Fred Drake | 6b4593e | 2001-05-22 15:12:46 +0000 | [diff] [blame] | 267 | \method{update()} methods of the mapping interface. (Support for |
Fred Drake | e78661b | 2001-07-17 05:17:58 +0000 | [diff] [blame] | 268 | \method{get()} and \method{setdefault()} was only added in Python |
Fred Drake | 6b4593e | 2001-05-22 15:12:46 +0000 | [diff] [blame] | 269 | 2.2.) |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 270 | |
Fred Drake | f5072b9 | 2001-09-06 15:07:55 +0000 | [diff] [blame] | 271 | Finally, \class{Message} instances have some public instance variables: |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 272 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 273 | \begin{memberdesc}{headers} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 274 | A list containing the entire set of header lines, in the order in |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 275 | which they were read (except that setitem calls may disturb this |
| 276 | order). Each line contains a trailing newline. The |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 277 | blank line terminating the headers is not contained in the list. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 278 | \end{memberdesc} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 279 | |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 280 | \begin{memberdesc}{fp} |
Fred Drake | ea00205 | 1999-04-28 18:11:09 +0000 | [diff] [blame] | 281 | The file or file-like object passed at instantiation time. This can |
| 282 | be used to read the message content. |
Fred Drake | e14dde2 | 1998-04-04 06:19:30 +0000 | [diff] [blame] | 283 | \end{memberdesc} |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 284 | |
Fred Drake | f5072b9 | 2001-09-06 15:07:55 +0000 | [diff] [blame] | 285 | \begin{memberdesc}{unixfrom} |
| 286 | The \UNIX{} \samp{From~} line, if the message had one, or an empty |
| 287 | string. This is needed to regenerate the message in some contexts, |
| 288 | such as an \code{mbox}-style mailbox file. |
| 289 | \end{memberdesc} |
| 290 | |
Fred Drake | ea00205 | 1999-04-28 18:11:09 +0000 | [diff] [blame] | 291 | |
| 292 | \subsection{AddressList Objects \label{addresslist-objects}} |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 293 | |
| 294 | An \class{AddressList} instance has the following methods: |
| 295 | |
Fred Drake | 9c84636 | 2001-04-09 15:42:56 +0000 | [diff] [blame] | 296 | \begin{methoddesc}{__len__}{} |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 297 | Return the number of addresses in the address list. |
| 298 | \end{methoddesc} |
| 299 | |
Fred Drake | 9c84636 | 2001-04-09 15:42:56 +0000 | [diff] [blame] | 300 | \begin{methoddesc}{__str__}{} |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 301 | Return a canonicalized string representation of the address list. |
| 302 | Addresses are rendered in "name" <host@domain> form, comma-separated. |
| 303 | \end{methoddesc} |
| 304 | |
Fred Drake | 9c84636 | 2001-04-09 15:42:56 +0000 | [diff] [blame] | 305 | \begin{methoddesc}{__add__}{alist} |
| 306 | Return a new \class{AddressList} instance that contains all addresses |
| 307 | in both \class{AddressList} operands, with duplicates removed (set |
| 308 | union). |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 309 | \end{methoddesc} |
| 310 | |
Fred Drake | 9c84636 | 2001-04-09 15:42:56 +0000 | [diff] [blame] | 311 | \begin{methoddesc}{__iadd__}{alist} |
| 312 | In-place version of \method{__add__()}; turns this \class{AddressList} |
| 313 | instance into the union of itself and the right-hand instance, |
| 314 | \var{alist}. |
| 315 | \end{methoddesc} |
| 316 | |
| 317 | \begin{methoddesc}{__sub__}{alist} |
| 318 | Return a new \class{AddressList} instance that contains every address |
| 319 | in the left-hand \class{AddressList} operand that is not present in |
| 320 | the right-hand address operand (set difference). |
| 321 | \end{methoddesc} |
| 322 | |
| 323 | \begin{methoddesc}{__isub__}{alist} |
| 324 | In-place version of \method{__sub__()}, removing addresses in this |
| 325 | list which are also in \var{alist}. |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 326 | \end{methoddesc} |
| 327 | |
| 328 | |
| 329 | Finally, \class{AddressList} instances have one public instance variable: |
| 330 | |
| 331 | \begin{memberdesc}{addresslist} |
| 332 | A list of tuple string pairs, one per address. In each member, the |
Eric S. Raymond | e7213c7 | 2001-01-27 10:56:14 +0000 | [diff] [blame] | 333 | first is the canonicalized name part, the second is the |
Fred Drake | 9c84636 | 2001-04-09 15:42:56 +0000 | [diff] [blame] | 334 | actual route-address (\character{@}-separated username-host.domain |
| 335 | pair). |
Guido van Rossum | 8729483 | 1998-06-16 22:27:40 +0000 | [diff] [blame] | 336 | \end{memberdesc} |