<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"module-email.Iterators.html" />
<link rel=
"prev" href=
"module-email.Errors.html" />
<link rel=
"parent" href=
"module-email.html" />
<link rel=
"next" href=
"module-email.Iterators.html" />
<meta name='aesop' content='information'
/>
<title>12.2.9 Miscellaneous utilities
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"12.2.8 Exception and Defect"
href=
"module-email.Errors.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"12.2 email "
href=
"module-email.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"12.2.10 Iterators"
href=
"module-email.Iterators.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-email.Errors.html">12.2.8 Exception and Defect
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-email.html">12.2 email
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"module-email.Iterators.html">12.2.10 Iterators
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION0014290000000000000000">
12.2.9 Miscellaneous utilities
</A>
<A NAME=
"module-email.Utils"></A>
There are several useful utilities provided in the
<tt class=
"module">email.Utils
</tt><dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3942' xml:id='l2h-
3942'
class=
"function">quote
</tt></b>(
</nobr></td>
<td><var>str
</var>)
</td></tr></table></dt>
Return a new string with backslashes in
<var>str
</var> replaced by two
backslashes, and double quotes replaced by backslash-double quote.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3943' xml:id='l2h-
3943'
class=
"function">unquote
</tt></b>(
</nobr></td>
<td><var>str
</var>)
</td></tr></table></dt>
Return a new string which is an
<em>unquoted
</em> version of
<var>str
</var>.
If
<var>str
</var> ends and begins with double quotes, they are stripped
off. Likewise if
<var>str
</var> ends and begins with angle brackets, they
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3944' xml:id='l2h-
3944'
class=
"function">parseaddr
</tt></b>(
</nobr></td>
<td><var>address
</var>)
</td></tr></table></dt>
Parse address - which should be the value of some address-containing
field such as
<span class=
"mailheader">To:
</span> or
<span class=
"mailheader">Cc:
</span> - into its constituent
<em>realname
</em> and
<em>email address
</em> parts. Returns a tuple of that
information, unless the parse fails, in which case a
2-tuple of
<code>('', '')
</code> is returned.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3945' xml:id='l2h-
3945'
class=
"function">formataddr
</tt></b>(
</nobr></td>
<td><var>pair
</var>)
</td></tr></table></dt>
The inverse of
<tt class=
"method">parseaddr()
</tt>, this takes a
2-tuple of the form
<code>(realname, email_address)
</code> and returns the string value suitable
for a
<span class=
"mailheader">To:
</span> or
<span class=
"mailheader">Cc:
</span> header. If the first element of
<var>pair
</var> is false, then the second element is returned unmodified.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3946' xml:id='l2h-
3946'
class=
"function">getaddresses
</tt></b>(
</nobr></td>
<td><var>fieldvalues
</var>)
</td></tr></table></dt>
This method returns a list of
2-tuples of the form returned by
<code>parseaddr()
</code>.
<var>fieldvalues
</var> is a sequence of header field
values as might be returned by
<tt class=
"method">Message.get_all()
</tt>. Here's a
simple example that gets all the recipients of a message:
<div class=
"verbatim"><pre>
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)
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3947' xml:id='l2h-
3947'
class=
"function">parsedate
</tt></b>(
</nobr></td>
<td><var>date
</var>)
</td></tr></table></dt>
Attempts to parse a date according to the rules in
<a class=
"rfc" id='rfcref-
90972' xml:id='rfcref-
90972'
href=
"http://www.faqs.org/rfcs/rfc2822.html">RFC
2822</a>.
however, some mailers don't follow that format as specified, so
<tt class=
"function">parsedate()
</tt> tries to guess correctly in such cases.
<var>date
</var> is a string containing an
<a class=
"rfc" id='rfcref-
90974' xml:id='rfcref-
90974'
href=
"http://www.faqs.org/rfcs/rfc2822.html">RFC
2822</a> date, such as
<code>"Mon, 20 Nov 1995 19:12:08 -0500"</code>. If it succeeds in parsing
the date,
<tt class=
"function">parsedate()
</tt> returns a
9-tuple that can be passed
directly to
<tt class=
"function">time.mktime()
</tt>; otherwise
<code>None
</code> will be
returned. Note that fields
6,
7, and
8 of the result tuple are not
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3948' xml:id='l2h-
3948'
class=
"function">parsedate_tz
</tt></b>(
</nobr></td>
<td><var>date
</var>)
</td></tr></table></dt>
Performs the same function as
<tt class=
"function">parsedate()
</tt>, but returns
either
<code>None
</code> or a
10-tuple; the first
9 elements make up a tuple
that can be passed directly to
<tt class=
"function">time.mktime()
</tt>, and the tenth
is the offset of the date's timezone from UTC (which is the official
term for Greenwich Mean Time)
<A NAME=
"tex2html124" HREF=
"#foot58346"><SUP>12.3</SUP></A>. If the input
string has no timezone, the last element of the tuple returned is
<code>None
</code>. Note that fields
6,
7, and
8 of the result tuple are not
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3949' xml:id='l2h-
3949'
class=
"function">mktime_tz
</tt></b>(
</nobr></td>
<td><var>tuple
</var>)
</td></tr></table></dt>
Turn a
10-tuple as returned by
<tt class=
"function">parsedate_tz()
</tt> into a UTC
timestamp. It the timezone item in the tuple is
<code>None
</code>, assume
local time. Minor deficiency:
<tt class=
"function">mktime_tz()
</tt> interprets the
first
8 elements of
<var>tuple
</var> 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
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3950' xml:id='l2h-
3950'
class=
"function">formatdate
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>timeval
</var><big>[
</big><var>, localtime
</var><big>]
</big><var></var><big>[
</big><var>, usegmt
</var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Returns a date string as per
<a class=
"rfc" id='rfcref-
90976' xml:id='rfcref-
90976'
href=
"http://www.faqs.org/rfcs/rfc2822.html">RFC
2822</a>, e.g.:
<div class=
"verbatim"><pre>
Fri,
09 Nov
2001 01:
08:
47 -
0000Optional
<var>timeval
</var> if given is a floating point time value as
accepted by
<tt class=
"function">time.gmtime()
</tt> and
<tt class=
"function">time.localtime()
</tt>,
otherwise the current time is used.
Optional
<var>localtime
</var> is a flag that when
<code>True
</code>, interprets
<var>timeval
</var>, and returns a date relative to the local timezone
instead of UTC, properly taking daylight savings time into account.
The default is
<code>False
</code> meaning UTC is used.
Optional
<var>usegmt
</var> is a flag that when
<code>True
</code>, outputs a
date string with the timezone as an ascii string
<code>GMT
</code>, rather
than a numeric
<code>-
0000</code>. This is needed for some protocols (such
as HTTP). This only applies when
<var>localtime
</var> is
<code>False
</code>.
<span class=
"versionnote">New in version
2.4.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3951' xml:id='l2h-
3951'
class=
"function">make_msgid
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>idstring
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Returns a string suitable for an
<a class=
"rfc" id='rfcref-
90978' xml:id='rfcref-
90978'
href=
"http://www.faqs.org/rfcs/rfc2822.html">RFC
2822</a>-compliant
<span class=
"mailheader">Message-ID:
</span> header. Optional
<var>idstring
</var> if given, is
a string used to strengthen the uniqueness of the message id.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3952' xml:id='l2h-
3952'
class=
"function">decode_rfc2231
</tt></b>(
</nobr></td>
<td><var>s
</var>)
</td></tr></table></dt>
Decode the string
<var>s
</var> according to
<a class=
"rfc" id='rfcref-
90980' xml:id='rfcref-
90980'
href=
"http://www.faqs.org/rfcs/rfc2231.html">RFC
2231</a>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3953' xml:id='l2h-
3953'
class=
"function">encode_rfc2231
</tt></b>(
</nobr></td>
<td><var>s
</var><big>[
</big><var>, charset
</var><big>[
</big><var>, language
</var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Encode the string
<var>s
</var> according to
<a class=
"rfc" id='rfcref-
90982' xml:id='rfcref-
90982'
href=
"http://www.faqs.org/rfcs/rfc2231.html">RFC
2231</a>. Optional
<var>charset
</var> and
<var>language
</var>, if given is the character set name
and language name to use. If neither is given,
<var>s
</var> is returned
as-is. If
<var>charset
</var> is given but
<var>language
</var> is not, the
string is encoded using the empty string for
<var>language
</var>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3954' xml:id='l2h-
3954'
class=
"function">collapse_rfc2231_value
</tt></b>(
</nobr></td>
<td><var>value
</var><big>[
</big><var>, errors
</var><big>[
</big><var>,
fallback_charset
</var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>When a header parameter is encoded in
<a class=
"rfc" id='rfcref-
90984' xml:id='rfcref-
90984'
href=
"http://www.faqs.org/rfcs/rfc2231.html">RFC
2231</a> format,
<tt class=
"method">Message.get_param()
</tt> may return a
3-tuple containing the character
set, language, and value.
<tt class=
"function">collapse_rfc2231_value()
</tt> turns this into
a unicode string. Optional
<var>errors
</var> is passed to the
<var>errors
</var>argument of the built-in
<tt class=
"function">unicode()
</tt> function; it defaults to
<code>replace
</code>. Optional
<var>fallback_charset
</var> specifies the character set
to use if the one in the
<a class=
"rfc" id='rfcref-
90986' xml:id='rfcref-
90986'
href=
"http://www.faqs.org/rfcs/rfc2231.html">RFC
2231</a> header is not known by Python; it defaults
to
<code>us-ascii
</code>.
For convenience, if the
<var>value
</var> passed to
<tt class=
"function">collapse_rfc2231_value()
</tt> is not a tuple, it should be a string and
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3955' xml:id='l2h-
3955'
class=
"function">decode_params
</tt></b>(
</nobr></td>
<td><var>params
</var>)
</td></tr></table></dt>
Decode parameters list according to
<a class=
"rfc" id='rfcref-
90988' xml:id='rfcref-
90988'
href=
"http://www.faqs.org/rfcs/rfc2231.html">RFC
2231</a>.
<var>params
</var> is a
sequence of
2-tuples containing elements of the form
<code>(content-type, string-value)
</code>.
<span class=
"versionnote">Changed in version
2.4:
The
<tt class=
"function">dump_address_pair()
</tt> function has been removed;
use
<tt class=
"function">formataddr()
</tt> instead..
</span><span class=
"versionnote">Changed in version
2.4:
The
<tt class=
"function">decode()
</tt> function has been removed; use the
<tt class=
"method">Header.decode_header()
</tt> method instead..
</span>
<span class=
"versionnote">Changed in version
2.4:
The
<tt class=
"function">encode()
</tt> function has been removed; use the
<tt class=
"method">Header.encode()
</tt> method instead..
</span>
<BR><HR><H4>Footnotes
</H4>
<DT><A NAME=
"foot58346">... Time)
</A><A
href=
"module-email.Utils.html#tex2html124"><SUP>12.3</SUP></A></DT>
<DD>Note that the sign of the timezone
offset is the opposite of the sign of the
<code>time.timezone
</code>variable for the same timezone; the latter variable follows the
POSIX standard while this module follows
<a class=
"rfc" id='rfcref-
90963' xml:id='rfcref-
90963'
href=
"http://www.faqs.org/rfcs/rfc2822.html">RFC
2822</a>.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"12.2.8 Exception and Defect"
href=
"module-email.Errors.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"12.2 email "
href=
"module-email.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"12.2.10 Iterators"
href=
"module-email.Iterators.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-email.Errors.html">12.2.8 Exception and Defect
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-email.html">12.2 email
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"module-email.Iterators.html">12.2.10 Iterators
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-DV / blob