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