\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 twobackslashes, 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 strippedoff. Likewise if \var{str} ends and begins with angle brackets, theyare stripped off.\end{funcdesc} \begin{funcdesc}{parseaddr}{address}Parse address -- which should be the value of some address-containingfield such as \mailheader{To} or \mailheader{Cc} -- into its constituent\emph{realname} and \emph{email address} parts. Returns a tuple of thatinformation, 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 suitablefor 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 fieldvalues as might be returned by \method{Message.get_all()}. Here's asimple 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 parsingthe date, \function{parsedate()} returns a 9-tuple that can be passeddirectly to \function{time.mktime()}; otherwise \code{None} will bereturned. Note that fields 6, 7, and 8 of the result tuple are notusable.\end{funcdesc} \begin{funcdesc}{parsedate_tz}{date}Performs the same function as \function{parsedate()}, but returnseither \code{None} or a 10-tuple; the first 9 elements make up a tuplethat can be passed directly to \function{time.mktime()}, and the tenthis the offset of the date's timezone from UTC (which is the officialterm for Greenwich Mean Time)\footnote{Note that the sign of the timezoneoffset 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 inputstring 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 notusable.\end{funcdesc} \begin{funcdesc}{mktime_tz}{tuple}Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTCtimestamp. It the timezone item in the tuple is \code{None}, assumelocal time. Minor deficiency: \function{mktime_tz()} interprets thefirst 8 elements of \var{tuple} as a local time and then compensatesfor the timezone difference. This may yield a slight error aroundchanges in daylight savings time, though not worth worrying about forcommon 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 asaccepted 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 timezoneinstead 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}, ratherthan a numeric \code{-0000}. This is needed for some protocols (suchas 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, isa 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 nameand language name to use. If neither is given, \var{s} is returnedas-is. If \var{charset} is given but \var{language} is not, thestring 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 characterset, language, and value. \function{collapse_rfc2231_value()} turns this intoa 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 setto use if the one in the \rfc{2231} header is not known by Python; it defaultsto \code{us-ascii}. For convenience, if the \var{value} passed to\function{collapse_rfc2231_value()} is not a tuple, it should be a string andit is returned unquoted.\end{funcdesc} \begin{funcdesc}{decode_params}{params}Decode parameters list according to \rfc{2231}. \var{params} is asequence 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}
\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 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}\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}