add hg and python

1 files changed, 157 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/emailutil.tex b/sys/src/cmd/python/Doc/lib/emailutil.tex
new file mode 100644
index 000000000..fe9647363
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/emailutil.tex
@@ -0,0 +1,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 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}