1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
\declaremodule{standard}{email.Utils}
\modulesynopsis{Miscellaneous email package utilities.}
There are several useful utilities provided with the \module{email}
package.
\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 address -- which should be the value of some address-containing
field such as \mailheader{To} or \mailheader{Cc} -- into its constituent
\emph{realname} and \emph{email address} parts. Returns a tuple of that
information, unless the parse fails, in which case a 2-tuple of
\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{(realname, 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}{getaddresses}{fieldvalues}
This method returns a list of 2-tuples of the form returned by
\code{parseaddr()}. \var{fieldvalues} is a sequence of header field
values as might be returned by \method{Message.getall()}. Here's a
simple example that gets all the recipients of a message:
\begin{verbatim}
from email.Utils import getaddresses
tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
\end{verbatim}
\end{funcdesc}
\begin{funcdesc}{decode}{s}
This method decodes a string according to the rules in \rfc{2047}. It
returns the decoded string as a Python unicode string.
\end{funcdesc}
\begin{funcdesc}{encode}{s\optional{, charset\optional{, encoding}}}
This method encodes a string according to the rules in \rfc{2047}. It
is not actually the inverse of \function{decode()} since it doesn't
handle multiple character sets or multiple string parts needing
encoding. In fact, the input string \var{s} must already be encoded
in the \var{charset} character set (Python can't reliably guess what
character set a string might be encoded in). The default
\var{charset} is \samp{iso-8859-1}.
\var{encoding} must be either the letter \character{q} for
Quoted-Printable or \character{b} for Base64 encoding. If
neither, a \exception{ValueError} is raised. Both the \var{charset} and
the \var{encoding} strings are case-insensitive, and coerced to lower
case in the returned string.
\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)\footnote{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. It the timezone item in the tuple is \code{None}, assume
local time. Minor deficiency: \function{mktime_tz()} interprets the
first 8 elements of \var{tuple} as a local time and then compensates
for the timezone difference. This may yield a slight error around
changes in daylight savings time, though not worth worrying about for
common use.
\end{funcdesc}
\begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}}}
Returns a date string as per Internet standard \rfc{2822}, e.g.:
\begin{verbatim}
Fri, 09 Nov 2001 01:08:47 -0000
\end{verbatim}
Optional \var{timeval} if given is a floating point time value as
accepted by \function{time.gmtime()} and \function{time.localtime()},
otherwise the current time is used.
Optional \var{localtime} is a flag that when true, interprets
\var{timeval}, and returns a date relative to the local timezone
instead of UTC, properly taking daylight savings time into account.
\end{funcdesc}
|
