There are several useful utilities provided in the email.utils
module:
-
Return a new string with backslashes in str replaced by two
backslashes, and double quotes replaced by backslash-double quote.
-
Return a new string which is an unquoted version of str.
If str ends and begins with double quotes, they are stripped
off. Likewise if str ends and begins with angle brackets, they
are stripped off.
-
Parse address - which should be the value of some address-containing
field such as or - into its constituent
realname and email address parts. Returns a tuple of that
information, unless the parse fails, in which case a 2-tuple of
('', '') is returned.
-
The inverse of parseaddr(), this takes a 2-tuple of the form
(realname, email_address) and returns the string value suitable
for a or header. If the first element of
pair is false, then the second element is returned unmodified.
getaddresses( |
fieldvalues) |
-
This method returns a list of 2-tuples of the form returned by
parseaddr() . fieldvalues is a sequence of header field
values as might be returned by Message.get_all(). Here's a
simple example that gets all the recipients of a message:
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)
-
Attempts to parse a date according to the rules in RFC 2822.
however, some mailers don't follow that format as specified, so
parsedate() tries to guess correctly in such cases.
date is a string containing an RFC 2822 date, such as
"Mon, 20 Nov 1995 19:12:08 -0500" . If it succeeds in parsing
the date, parsedate() returns a 9-tuple that can be passed
directly to time.mktime(); otherwise None will be
returned. Note that fields 6, 7, and 8 of the result tuple are not
usable.
-
Performs the same function as parsedate(), but returns
either
None or a 10-tuple; the first 9 elements make up a tuple
that can be passed directly to time.mktime(), and the tenth
is the offset of the date's timezone from UTC (which is the official
term for Greenwich Mean Time)7.3. If the input
string has no timezone, the last element of the tuple returned is
None . Note that fields 6, 7, and 8 of the result tuple are not
usable.
-
Turn a 10-tuple as returned by parsedate_tz() into a UTC
timestamp. It the timezone item in the tuple is
None , assume
local time. Minor deficiency: mktime_tz() interprets the
first 8 elements of 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.
formatdate( |
[timeval[, localtime][, usegmt]]) |
-
Returns a date string as per RFC 2822, e.g.:
Fri, 09 Nov 2001 01:08:47 -0000
Optional timeval if given is a floating point time value as
accepted by time.gmtime() and time.localtime(),
otherwise the current time is used.
Optional localtime is a flag that when True , interprets
timeval, and returns a date relative to the local timezone
instead of UTC, properly taking daylight savings time into account.
The default is False meaning UTC is used.
Optional usegmt is a flag that when True , outputs a
date string with the timezone as an ascii string GMT , rather
than a numeric -0000 . This is needed for some protocols (such
as HTTP). This only applies when localtime is False .
New in version 2.4.
-
Returns a string suitable for an RFC 2822-compliant
header. Optional idstring if given, is
a string used to strengthen the uniqueness of the message id.
-
Decode the string s according to RFC 2231.
encode_rfc2231( |
s[, charset[, language]]) |
-
Encode the string s according to RFC 2231. Optional
charset and language, if given is the character set name
and language name to use. If neither is given, s is returned
as-is. If charset is given but language is not, the
string is encoded using the empty string for language.
collapse_rfc2231_value( |
value[, errors[,
fallback_charset]]) |
-
When a header parameter is encoded in RFC 2231 format,
Message.get_param() may return a 3-tuple containing the character
set, language, and value. collapse_rfc2231_value() turns this into
a unicode string. Optional errors is passed to the errors
argument of the built-in unicode() function; it defaults to
replace . Optional fallback_charset specifies the character set
to use if the one in the RFC 2231 header is not known by Python; it defaults
to us-ascii .
For convenience, if the value passed to
collapse_rfc2231_value() is not a tuple, it should be a string and
it is returned unquoted.
-
Decode parameters list according to RFC 2231. params is a
sequence of 2-tuples containing elements of the form
(content-type, string-value) .
Changed in version 2.4:
The dump_address_pair() function has been removed;
use formataddr() instead.
Changed in version 2.4:
The decode() function has been removed; use the
Header.decode_header() method instead.
Changed in version 2.4:
The encode() function has been removed; use the
Header.encode() method instead.
Footnotes
- ... Time)7.3
- Note that the sign of the timezone
offset is the opposite of the sign of the
time.timezone
variable for the same timezone; the latter variable follows the
POSIX standard while this module follows RFC 2822.
Release 2.5.2, documentation updated on 21st February, 2008.
See About this document... for information on suggesting changes.
|