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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
\declaremodule{standard}{email.utils}
\modulesynopsis{Miscellaneous email package utilities.}
There are several useful utilities provided in the \module{email.utils}
module:
\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{('', '')} is returned.
\end{funcdesc}
\begin{funcdesc}{formataddr}{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.get_all()}. 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}{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 indexes 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 indexes 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}\optional{, usegmt}}}
Returns a date string as per \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 \code{True}, interprets
\var{timeval}, and returns a date relative to the local timezone
instead of UTC, properly taking daylight savings time into account.
The default is \code{False} meaning UTC is used.
Optional \var{usegmt} is a flag that when \code{True}, outputs a
date string with the timezone as an ascii string \code{GMT}, rather
than a numeric \code{-0000}. This is needed for some protocols (such
as HTTP). This only applies when \var{localtime} is \code{False}.
\versionadded{2.4}
\end{funcdesc}
\begin{funcdesc}{make_msgid}{\optional{idstring}}
Returns a string suitable for an \rfc{2822}-compliant
\mailheader{Message-ID} header. Optional \var{idstring} if given, is
a string used to strengthen the uniqueness of the message id.
\end{funcdesc}
\begin{funcdesc}{decode_rfc2231}{s}
Decode the string \var{s} according to \rfc{2231}.
\end{funcdesc}
\begin{funcdesc}{encode_rfc2231}{s\optional{, charset\optional{, language}}}
Encode the string \var{s} according to \rfc{2231}. Optional
\var{charset} and \var{language}, if given is the character set name
and language name to use. If neither is given, \var{s} is returned
as-is. If \var{charset} is given but \var{language} is not, the
string is encoded using the empty string for \var{language}.
\end{funcdesc}
\begin{funcdesc}{collapse_rfc2231_value}{value\optional{, errors\optional{,
fallback_charset}}}
When a header parameter is encoded in \rfc{2231} format,
\method{Message.get_param()} may return a 3-tuple containing the character
set, language, and value. \function{collapse_rfc2231_value()} turns this into
a unicode string. Optional \var{errors} is passed to the \var{errors}
argument of the built-in \function{unicode()} function; it defaults to
\code{replace}. Optional \var{fallback_charset} specifies the character set
to use if the one in the \rfc{2231} header is not known by Python; it defaults
to \code{us-ascii}.
For convenience, if the \var{value} passed to
\function{collapse_rfc2231_value()} is not a tuple, it should be a string and
it is returned unquoted.
\end{funcdesc}
\begin{funcdesc}{decode_params}{params}
Decode parameters list according to \rfc{2231}. \var{params} is a
sequence of 2-tuples containing elements of the form
\code{(content-type, string-value)}.
\end{funcdesc}
\versionchanged[The \function{dump_address_pair()} function has been removed;
use \function{formataddr()} instead]{2.4}
\versionchanged[The \function{decode()} function has been removed; use the
\method{Header.decode_header()} method instead]{2.4}
\versionchanged[The \function{encode()} function has been removed; use the
\method{Header.encode()} method instead]{2.4}
|
