add hg and python

1 files changed, 507 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libimaplib.tex b/sys/src/cmd/python/Doc/lib/libimaplib.tex
new file mode 100644
index 000000000..7658bc965
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libimaplib.tex
@@ -0,0 +1,507 @@
+\section{\module{imaplib} ---
+         IMAP4 protocol client}
+
+\declaremodule{standard}{imaplib}
+\modulesynopsis{IMAP4 protocol client (requires sockets).}
+\moduleauthor{Piers Lauder}{piers@communitysolutions.com.au}
+\sectionauthor{Piers Lauder}{piers@communitysolutions.com.au}
+
+% Based on HTML documentation by Piers Lauder
+% <piers@communitysolutions.com.au>;
+% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
+% Revised by ESR, January 2000.
+% Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002 
+% Changes for IMAP4_stream by Piers Lauder
+% <piers@communitysolutions.com.au>, November 2002
+
+\indexii{IMAP4}{protocol}
+\indexii{IMAP4_SSL}{protocol}
+\indexii{IMAP4_stream}{protocol}
+
+This module defines three classes, \class{IMAP4}, \class{IMAP4_SSL}
+and \class{IMAP4_stream}, which encapsulate a
+connection to an IMAP4 server and implement a large subset of the
+IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward
+compatible with IMAP4 (\rfc{1730}) servers, but note that the
+\samp{STATUS} command is not supported in IMAP4.
+
+Three classes are provided by the \module{imaplib} module,
+\class{IMAP4} is the base class:
+
+\begin{classdesc}{IMAP4}{\optional{host\optional{, port}}}
+This class implements the actual IMAP4 protocol.  The connection is
+created and protocol version (IMAP4 or IMAP4rev1) is determined when
+the instance is initialized.
+If \var{host} is not specified, \code{''} (the local host) is used.
+If \var{port} is omitted, the standard IMAP4 port (143) is used.
+\end{classdesc}
+
+Three exceptions are defined as attributes of the \class{IMAP4} class:
+
+\begin{excdesc}{IMAP4.error}
+Exception raised on any errors.  The reason for the exception is
+passed to the constructor as a string.
+\end{excdesc}
+
+\begin{excdesc}{IMAP4.abort}
+IMAP4 server errors cause this exception to be raised.  This is a
+sub-class of \exception{IMAP4.error}.  Note that closing the instance
+and instantiating a new one will usually allow recovery from this
+exception.
+\end{excdesc}
+
+\begin{excdesc}{IMAP4.readonly}
+This exception is raised when a writable mailbox has its status
+changed by the server.  This is a sub-class of
+\exception{IMAP4.error}.  Some other client now has write permission,
+and the mailbox will need to be re-opened to re-obtain write
+permission.
+\end{excdesc}
+
+There's also a subclass for secure connections:
+
+\begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{,
+                             keyfile\optional{, certfile}}}}}
+This is a subclass derived from \class{IMAP4} that connects over an
+SSL encrypted socket (to use this class you need a socket module that
+was compiled with SSL support).  If \var{host} is not specified,
+\code{''} (the local host) is used.  If \var{port} is omitted, the
+standard IMAP4-over-SSL port (993) is used.  \var{keyfile} and
+\var{certfile} are also optional - they can contain a PEM formatted
+private key and certificate chain file for the SSL connection.
+\end{classdesc}
+
+The second subclass allows for connections created by a child process:
+
+\begin{classdesc}{IMAP4_stream}{command}
+This is a subclass derived from \class{IMAP4} that connects
+to the \code{stdin/stdout} file descriptors created by passing
+\var{command} to \code{os.popen2()}.
+\versionadded{2.3}
+\end{classdesc}
+
+The following utility functions are defined:
+
+\begin{funcdesc}{Internaldate2tuple}{datestr}
+  Converts an IMAP4 INTERNALDATE string to Coordinated Universal
+  Time. Returns a \refmodule{time} module tuple.
+\end{funcdesc}
+
+\begin{funcdesc}{Int2AP}{num}
+  Converts an integer into a string representation using characters
+  from the set [\code{A} .. \code{P}].
+\end{funcdesc}
+
+\begin{funcdesc}{ParseFlags}{flagstr}
+  Converts an IMAP4 \samp{FLAGS} response to a tuple of individual
+  flags.
+\end{funcdesc}
+
+\begin{funcdesc}{Time2Internaldate}{date_time}
+  Converts a \refmodule{time} module tuple to an IMAP4
+  \samp{INTERNALDATE} representation.  Returns a string in the form:
+  \code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes).
+\end{funcdesc}
+
+
+Note that IMAP4 message numbers change as the mailbox changes; in
+particular, after an \samp{EXPUNGE} command performs deletions the
+remaining messages are renumbered. So it is highly advisable to use
+UIDs instead, with the UID command.
+
+At the end of the module, there is a test section that contains a more
+extensive example of usage.
+
+\begin{seealso}
+  \seetext{Documents describing the protocol, and sources and binaries 
+           for servers implementing it, can all be found at the
+           University of Washington's \emph{IMAP Information Center}
+           (\url{http://www.cac.washington.edu/imap/}).}
+\end{seealso}
+
+
+\subsection{IMAP4 Objects \label{imap4-objects}}
+
+All IMAP4rev1 commands are represented by methods of the same name,
+either upper-case or lower-case.
+
+All arguments to commands are converted to strings, except for
+\samp{AUTHENTICATE}, and the last argument to \samp{APPEND} which is
+passed as an IMAP4 literal.  If necessary (the string contains IMAP4
+protocol-sensitive characters and isn't enclosed with either
+parentheses or double quotes) each string is quoted. However, the
+\var{password} argument to the \samp{LOGIN} command is always quoted.
+If you want to avoid having an argument string quoted
+(eg: the \var{flags} argument to \samp{STORE}) then enclose the string in
+parentheses (eg: \code{r'(\e Deleted)'}).
+
+Each command returns a tuple: \code{(\var{type}, [\var{data},
+...])} where \var{type} is usually \code{'OK'} or \code{'NO'},
+and \var{data} is either the text from the command response, or
+mandated results from the command. Each \var{data}
+is either a string, or a tuple. If a tuple, then the first part
+is the header of the response, and the second part contains
+the data (ie: 'literal' value).
+
+The \var{message_set} options to commands below is a string specifying one
+or more messages to be acted upon.  It may be a simple message number
+(\code{'1'}), a range of message numbers (\code{'2:4'}), or a group of
+non-contiguous ranges separated by commas (\code{'1:3,6:9'}).  A range
+can contain an asterisk to indicate an infinite upper bound
+(\code{'3:*'}).
+
+An \class{IMAP4} instance has the following methods:
+
+
+\begin{methoddesc}{append}{mailbox, flags, date_time, message}
+  Append \var{message} to named mailbox. 
+\end{methoddesc}
+
+\begin{methoddesc}{authenticate}{mechanism, authobject}
+  Authenticate command --- requires response processing.
+
+  \var{mechanism} specifies which authentication mechanism is to be
+  used - it should appear in the instance variable \code{capabilities}
+  in the form \code{AUTH=mechanism}.
+
+  \var{authobject} must be a callable object:
+
+\begin{verbatim}
+data = authobject(response)
+\end{verbatim}
+
+  It will be called to process server continuation responses.
+  It should return \code{data} that will be encoded and sent to server.
+  It should return \code{None} if the client abort response \samp{*} should
+  be sent instead.
+\end{methoddesc}
+
+\begin{methoddesc}{check}{}
+  Checkpoint mailbox on server. 
+\end{methoddesc}
+
+\begin{methoddesc}{close}{}
+  Close currently selected mailbox. Deleted messages are removed from
+  writable mailbox. This is the recommended command before
+  \samp{LOGOUT}.
+\end{methoddesc}
+
+\begin{methoddesc}{copy}{message_set, new_mailbox}
+  Copy \var{message_set} messages onto end of \var{new_mailbox}. 
+\end{methoddesc}
+
+\begin{methoddesc}{create}{mailbox}
+  Create new mailbox named \var{mailbox}.
+\end{methoddesc}
+
+\begin{methoddesc}{delete}{mailbox}
+  Delete old mailbox named \var{mailbox}.
+\end{methoddesc}
+
+\begin{methoddesc}{deleteacl}{mailbox, who}
+  Delete the ACLs (remove any rights) set for who on mailbox.
+\versionadded{2.4}
+\end{methoddesc}
+
+\begin{methoddesc}{expunge}{}
+  Permanently remove deleted items from selected mailbox. Generates an
+  \samp{EXPUNGE} response for each deleted message. Returned data
+  contains a list of \samp{EXPUNGE} message numbers in order
+  received.
+\end{methoddesc}
+
+\begin{methoddesc}{fetch}{message_set, message_parts}
+  Fetch (parts of) messages.  \var{message_parts} should be
+  a string of message part names enclosed within parentheses,
+  eg: \samp{"(UID BODY[TEXT])"}.  Returned data are tuples
+  of message part envelope and data.
+\end{methoddesc}
+
+\begin{methoddesc}{getacl}{mailbox}
+  Get the \samp{ACL}s for \var{mailbox}.
+  The method is non-standard, but is supported by the \samp{Cyrus} server.
+\end{methoddesc}
+
+\begin{methoddesc}{getannotation}{mailbox, entry, attribute}
+  Retrieve the specified \samp{ANNOTATION}s for \var{mailbox}.
+  The method is non-standard, but is supported by the \samp{Cyrus} server.
+\versionadded{2.5}
+\end{methoddesc}
+
+\begin{methoddesc}{getquota}{root}
+  Get the \samp{quota} \var{root}'s resource usage and limits.
+  This method is part of the IMAP4 QUOTA extension defined in rfc2087.
+\versionadded{2.3}
+\end{methoddesc}
+
+\begin{methoddesc}{getquotaroot}{mailbox}
+  Get the list of \samp{quota} \samp{roots} for the named \var{mailbox}.
+  This method is part of the IMAP4 QUOTA extension defined in rfc2087.
+\versionadded{2.3}
+\end{methoddesc}
+
+\begin{methoddesc}{list}{\optional{directory\optional{, pattern}}}
+  List mailbox names in \var{directory} matching
+  \var{pattern}.  \var{directory} defaults to the top-level mail
+  folder, and \var{pattern} defaults to match anything.  Returned data
+  contains a list of \samp{LIST} responses.
+\end{methoddesc}
+
+\begin{methoddesc}{login}{user, password}
+  Identify the client using a plaintext password.
+  The \var{password} will be quoted.
+\end{methoddesc}
+
+\begin{methoddesc}{login_cram_md5}{user, password}
+  Force use of \samp{CRAM-MD5} authentication when identifying the
+  client to protect the password.  Will only work if the server
+  \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}.
+\versionadded{2.3}
+\end{methoddesc}
+
+\begin{methoddesc}{logout}{}
+  Shutdown connection to server. Returns server \samp{BYE} response.
+\end{methoddesc}
+
+\begin{methoddesc}{lsub}{\optional{directory\optional{, pattern}}}
+  List subscribed mailbox names in directory matching pattern.
+  \var{directory} defaults to the top level directory and
+  \var{pattern} defaults to match any mailbox.
+  Returned data are tuples of message part envelope and data.
+\end{methoddesc}
+
+\begin{methoddesc}{myrights}{mailbox}
+  Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
+\versionadded{2.4}
+\end{methoddesc}
+
+\begin{methoddesc}{namespace}{}
+  Returns IMAP namespaces as defined in RFC2342.
+\versionadded{2.3}
+\end{methoddesc}
+
+\begin{methoddesc}{noop}{}
+  Send \samp{NOOP} to server.
+\end{methoddesc}
+
+\begin{methoddesc}{open}{host, port}
+  Opens socket to \var{port} at \var{host}.
+  The connection objects established by this method
+  will be used in the \code{read}, \code{readline}, \code{send}, and
+  \code{shutdown} methods.
+  You may override this method.
+\end{methoddesc}
+
+\begin{methoddesc}{partial}{message_num, message_part, start, length}
+  Fetch truncated part of a message.
+  Returned data is a tuple of message part envelope and data.
+\end{methoddesc}
+
+\begin{methoddesc}{proxyauth}{user}
+  Assume authentication as \var{user}.
+  Allows an authorised administrator to proxy into any user's mailbox.
+\versionadded{2.3}
+\end{methoddesc}
+
+\begin{methoddesc}{read}{size}
+  Reads \var{size} bytes from the remote server.
+  You may override this method.
+\end{methoddesc}
+
+\begin{methoddesc}{readline}{}
+  Reads one line from the remote server.
+  You may override this method.
+\end{methoddesc}
+
+\begin{methoddesc}{recent}{}
+  Prompt server for an update. Returned data is \code{None} if no new
+  messages, else value of \samp{RECENT} response.
+\end{methoddesc}
+
+\begin{methoddesc}{rename}{oldmailbox, newmailbox}
+  Rename mailbox named \var{oldmailbox} to \var{newmailbox}.
+\end{methoddesc}
+
+\begin{methoddesc}{response}{code}
+  Return data for response \var{code} if received, or
+  \code{None}. Returns the given code, instead of the usual type.
+\end{methoddesc}
+
+\begin{methoddesc}{search}{charset, criterion\optional{, ...}}
+  Search mailbox for matching messages.  \var{charset} may be
+  \code{None}, in which case no \samp{CHARSET} will be specified in the
+  request to the server.  The IMAP protocol requires that at least one
+  criterion be specified; an exception will be raised when the server
+  returns an error.
+
+  Example:
+
+\begin{verbatim}
+# M is a connected IMAP4 instance...
+typ, msgnums = M.search(None, 'FROM', '"LDJ"')
+
+# or:
+typ, msgnums = M.search(None, '(FROM "LDJ")')
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}{select}{\optional{mailbox\optional{, readonly}}}
+  Select a mailbox. Returned data is the count of messages in
+  \var{mailbox} (\samp{EXISTS} response).  The default \var{mailbox}
+  is \code{'INBOX'}.  If the \var{readonly} flag is set, modifications
+  to the mailbox are not allowed.
+\end{methoddesc}
+
+\begin{methoddesc}{send}{data}
+  Sends \code{data} to the remote server.
+  You may override this method.
+\end{methoddesc}
+
+\begin{methoddesc}{setacl}{mailbox, who, what}
+  Set an \samp{ACL} for \var{mailbox}.
+  The method is non-standard, but is supported by the \samp{Cyrus} server.
+\end{methoddesc}
+
+\begin{methoddesc}{setannotation}{mailbox, entry, attribute\optional{, ...}}
+  Set \samp{ANNOTATION}s for \var{mailbox}.
+  The method is non-standard, but is supported by the \samp{Cyrus} server.
+\versionadded{2.5}
+\end{methoddesc}
+
+\begin{methoddesc}{setquota}{root, limits}
+  Set the \samp{quota} \var{root}'s resource \var{limits}.
+  This method is part of the IMAP4 QUOTA extension defined in rfc2087.
+\versionadded{2.3}
+\end{methoddesc}
+
+\begin{methoddesc}{shutdown}{}
+  Close connection established in \code{open}.
+  You may override this method.
+\end{methoddesc}
+
+\begin{methoddesc}{socket}{}
+  Returns socket instance used to connect to server.
+\end{methoddesc}
+
+\begin{methoddesc}{sort}{sort_criteria, charset, search_criterion\optional{, ...}}
+  The \code{sort} command is a variant of \code{search} with sorting
+  semantics for the results.  Returned data contains a space separated
+  list of matching message numbers.
+
+  Sort has two arguments before the \var{search_criterion}
+  argument(s); a parenthesized list of \var{sort_criteria}, and the
+  searching \var{charset}.  Note that unlike \code{search}, the
+  searching \var{charset} argument is mandatory.  There is also a
+  \code{uid sort} command which corresponds to \code{sort} the way
+  that \code{uid search} corresponds to \code{search}.  The
+  \code{sort} command first searches the mailbox for messages that
+  match the given searching criteria using the charset argument for
+  the interpretation of strings in the searching criteria.  It then
+  returns the numbers of matching messages.
+
+  This is an \samp{IMAP4rev1} extension command.
+\end{methoddesc}
+
+\begin{methoddesc}{status}{mailbox, names}
+  Request named status conditions for \var{mailbox}. 
+\end{methoddesc}
+
+\begin{methoddesc}{store}{message_set, command, flag_list}
+  Alters flag dispositions for messages in mailbox.  \var{command} is
+  specified by section 6.4.6 of \rfc{2060} as being one of "FLAGS", "+FLAGS",
+  or "-FLAGS", optionally with a suffix of ".SILENT".
+
+  For example, to set the delete flag on all messages:
+
+\begin{verbatim}
+typ, data = M.search(None, 'ALL')
+for num in data[0].split():
+   M.store(num, '+FLAGS', '\\Deleted')
+M.expunge()
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}{subscribe}{mailbox}
+  Subscribe to new mailbox.
+\end{methoddesc}
+
+\begin{methoddesc}{thread}{threading_algorithm, charset,
+                           search_criterion\optional{, ...}}
+  The \code{thread} command is a variant of \code{search} with
+  threading semantics for the results.  Returned data contains a space
+  separated list of thread members.
+
+  Thread members consist of zero or more messages numbers, delimited
+  by spaces, indicating successive parent and child.
+
+  Thread has two arguments before the \var{search_criterion}
+  argument(s); a \var{threading_algorithm}, and the searching
+  \var{charset}.  Note that unlike \code{search}, the searching
+  \var{charset} argument is mandatory.  There is also a \code{uid
+  thread} command which corresponds to \code{thread} the way that
+  \code{uid search} corresponds to \code{search}.  The \code{thread}
+  command first searches the mailbox for messages that match the given
+  searching criteria using the charset argument for the interpretation
+  of strings in the searching criteria. It then returns the matching
+  messages threaded according to the specified threading algorithm.
+
+  This is an \samp{IMAP4rev1} extension command. \versionadded{2.4}
+\end{methoddesc}
+
+\begin{methoddesc}{uid}{command, arg\optional{, ...}}
+  Execute command args with messages identified by UID, rather than
+  message number.  Returns response appropriate to command.  At least
+  one argument must be supplied; if none are provided, the server will
+  return an error and an exception will be raised.
+\end{methoddesc}
+
+\begin{methoddesc}{unsubscribe}{mailbox}
+  Unsubscribe from old mailbox.
+\end{methoddesc}
+
+\begin{methoddesc}{xatom}{name\optional{, arg\optional{, ...}}}
+  Allow simple extension commands notified by server in
+  \samp{CAPABILITY} response.
+\end{methoddesc}
+
+
+Instances of \class{IMAP4_SSL} have just one additional method:
+
+\begin{methoddesc}{ssl}{}
+  Returns SSLObject instance used for the secure connection with the server.
+\end{methoddesc}
+
+
+The following attributes are defined on instances of \class{IMAP4}:
+
+
+\begin{memberdesc}{PROTOCOL_VERSION}
+The most recent supported protocol in the
+\samp{CAPABILITY} response from the server.
+\end{memberdesc}
+
+\begin{memberdesc}{debug}
+Integer value to control debugging output.  The initialize value is
+taken from the module variable \code{Debug}.  Values greater than
+three trace each command.
+\end{memberdesc}
+
+
+\subsection{IMAP4 Example \label{imap4-example}}
+
+Here is a minimal example (without error checking) that opens a
+mailbox and retrieves and prints all messages:
+
+\begin{verbatim}
+import getpass, imaplib
+
+M = imaplib.IMAP4()
+M.login(getpass.getuser(), getpass.getpass())
+M.select()
+typ, data = M.search(None, 'ALL')
+for num in data[0].split():
+    typ, data = M.fetch(num, '(RFC822)')
+    print 'Message %s\n%s\n' % (num, data[0][1])
+M.close()
+M.logout()
+\end{verbatim}