The email package documentation, currently organized the way I think

Fred prefers.  I'm not sure I like this organization, so it may change.

1 files changed, 119 insertions, 0 deletions

diff --git a/Doc/lib/emailutil.tex b/Doc/lib/emailutil.tex
new file mode 100644
index 0000000..e028fcd
--- /dev/null
+++ b/Doc/lib/emailutil.tex
@@ -0,0 +1,119 @@
+\section{\module{email.Utils} ---
+         Miscellaneous email package utilities}
+
+\declaremodule{standard}{email.Utils}
+\modulesynopsis{Miscellaneous email package utilities.}
+\sectionauthor{Barry A. Warsaw}{barry@zope.com}
+
+\versionadded{2.2}
+
+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 \code{To:} or \code{Cc:} -- 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
+\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 \code{To:} or \code{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 \samp{q} for
+Quoted-Printable or \samp{b} for Base64 encoding.  If
+neither, a \code{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 worring about for
+common use.
+\end{funcdesc}
+
+\begin{funcdesc}{formatdate}{\optional{timeval}}
+Returns the time formatted as per Internet standards \rfc{2822}
+and updated by \rfc{1123}.  If \var{timeval} is provided, then it
+should be a floating point time value as expected by
+\method{time.gmtime()}, otherwise the current time is used.
+\end{funcdesc}