add hg and python

1 files changed, 383 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libxmlrpclib.tex b/sys/src/cmd/python/Doc/lib/libxmlrpclib.tex
new file mode 100644
index 000000000..3645b824d
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libxmlrpclib.tex
@@ -0,0 +1,383 @@
+\section{\module{xmlrpclib} --- XML-RPC client access}
+
+\declaremodule{standard}{xmlrpclib}
+\modulesynopsis{XML-RPC client access.}
+\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
+\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
+
+% Not everything is documented yet.  It might be good to describe 
+% Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
+
+\versionadded{2.2}
+
+XML-RPC is a Remote Procedure Call method that uses XML passed via
+HTTP as a transport.  With it, a client can call methods with
+parameters on a remote server (the server is named by a URI) and get back
+structured data.  This module supports writing XML-RPC client code; it
+handles all the details of translating between conformable Python
+objects and XML on the wire.
+
+\begin{classdesc}{ServerProxy}{uri\optional{, transport\optional{,
+                               encoding\optional{, verbose\optional{, 
+                               allow_none\optional{, use_datetime}}}}}}
+A \class{ServerProxy} instance is an object that manages communication
+with a remote XML-RPC server.  The required first argument is a URI
+(Uniform Resource Indicator), and will normally be the URL of the
+server.  The optional second argument is a transport factory instance;
+by default it is an internal \class{SafeTransport} instance for https:
+URLs and an internal HTTP \class{Transport} instance otherwise.  The
+optional third argument is an encoding, by default UTF-8. The optional
+fourth argument is a debugging flag.  If \var{allow_none} is true, 
+the Python constant \code{None} will be translated into XML; the
+default behaviour is for \code{None} to raise a \exception{TypeError}.
+This is a commonly-used extension to the XML-RPC specification, but isn't
+supported by all clients and servers; see
+\url{http://ontosys.com/xml-rpc/extensions.php} for a description. 
+The \var{use_datetime} flag can be used to cause date/time values to be
+presented as \class{\refmodule{datetime}.datetime} objects; this is false
+by default.  \class{\refmodule{datetime}.datetime},
+\class{\refmodule{datetime}.date} and \class{\refmodule{datetime}.time}
+objects may be passed to calls.  \class{\refmodule{datetime}.date} objects
+are converted with a time of ``00:00:00''.
+\class{\refmodule{datetime}.time} objects are converted using today's date.
+
+Both the HTTP and HTTPS transports support the URL syntax extension for
+HTTP Basic Authentication: \code{http://user:pass@host:port/path}.  The 
+\code{user:pass} portion will be base64-encoded as an HTTP `Authorization'
+header, and sent to the remote server as part of the connection process
+when invoking an XML-RPC method.  You only need to use this if the
+remote server requires a Basic Authentication user and password.
+
+The returned instance is a proxy object with methods that can be used
+to invoke corresponding RPC calls on the remote server.  If the remote
+server supports the introspection API, the proxy can also be used to query
+the remote server for the methods it supports (service discovery) and
+fetch other server-associated metadata.
+
+\class{ServerProxy} instance methods take Python basic types and objects as 
+arguments and return Python basic types and classes.  Types that are
+conformable (e.g. that can be marshalled through XML), include the
+following (and except where noted, they are unmarshalled as the same
+Python type):
+
+\begin{tableii}{l|l}{constant}{Name}{Meaning}
+  \lineii{boolean}{The \constant{True} and \constant{False} constants}
+  \lineii{integers}{Pass in directly}
+  \lineii{floating-point numbers}{Pass in directly}
+  \lineii{strings}{Pass in directly}
+  \lineii{arrays}{Any Python sequence type containing conformable
+                  elements. Arrays are returned as lists}
+  \lineii{structures}{A Python dictionary. Keys must be strings,
+                      values may be any conformable type.}
+  \lineii{dates}{in seconds since the epoch (pass in an instance of the
+                 \class{DateTime} class) or a
+                 \class{\refmodule{datetime}.datetime},
+                 \class{\refmodule{datetime}.date} or
+                 \class{\refmodule{datetime}.time} instance} 
+  \lineii{binary data}{pass in an instance of the \class{Binary}
+                       wrapper class}
+\end{tableii}
+
+This is the full set of data types supported by XML-RPC.  Method calls
+may also raise a special \exception{Fault} instance, used to signal
+XML-RPC server errors, or \exception{ProtocolError} used to signal an
+error in the HTTP/HTTPS transport layer.  Both \exception{Fault} and
+\exception{ProtocolError} derive from a base class called
+\exception{Error}.  Note that even though starting with Python 2.2 you
+can subclass builtin types, the xmlrpclib module currently does not
+marshal instances of such subclasses.
+
+When passing strings, characters special to XML such as \samp{<},
+\samp{>}, and \samp{\&} will be automatically escaped.  However, it's
+the caller's responsibility to ensure that the string is free of
+characters that aren't allowed in XML, such as the control characters
+with ASCII values between 0 and 31; failing to do this will result in
+an XML-RPC request that isn't well-formed XML.  If you have to pass
+arbitrary strings via XML-RPC, use the \class{Binary} wrapper class
+described below.
+
+\class{Server} is retained as an alias for \class{ServerProxy} for backwards
+compatibility.  New code should use \class{ServerProxy}.
+
+\versionchanged[The \var{use_datetime} flag was added]{2.5}
+\end{classdesc}
+
+
+\begin{seealso}
+  \seetitle[http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html]
+           {XML-RPC HOWTO}{A good description of XML operation and
+            client software in several languages.  Contains pretty much
+            everything an XML-RPC client developer needs to know.}
+  \seetitle[http://xmlrpc-c.sourceforge.net/hacks.php]
+           {XML-RPC Hacks page}{Extensions for various open-source
+            libraries to support introspection and multicall.}
+\end{seealso}
+
+
+\subsection{ServerProxy Objects \label{serverproxy-objects}}
+
+A \class{ServerProxy} instance has a method corresponding to
+each remote procedure call accepted by the XML-RPC server.  Calling
+the method performs an RPC, dispatched by both name and argument
+signature (e.g. the same method name can be overloaded with multiple
+argument signatures).  The RPC finishes by returning a value, which
+may be either returned data in a conformant type or a \class{Fault} or
+\class{ProtocolError} object indicating an error.
+
+Servers that support the XML introspection API support some common
+methods grouped under the reserved \member{system} member:
+
+\begin{methoddesc}{system.listMethods}{}
+This method returns a list of strings, one for each (non-system)
+method supported by the XML-RPC server.
+\end{methoddesc}
+
+\begin{methoddesc}{system.methodSignature}{name}
+This method takes one parameter, the name of a method implemented by
+the XML-RPC server.It returns an array of possible signatures for this
+method. A signature is an array of types. The first of these types is
+the return type of the method, the rest are parameters.
+
+Because multiple signatures (ie. overloading) is permitted, this method
+returns a list of signatures rather than a singleton.
+
+Signatures themselves are restricted to the top level parameters
+expected by a method. For instance if a method expects one array of
+structs as a parameter, and it returns a string, its signature is
+simply "string, array". If it expects three integers and returns a
+string, its signature is "string, int, int, int".
+
+If no signature is defined for the method, a non-array value is
+returned. In Python this means that the type of the returned 
+value will be something other that list.
+\end{methoddesc}
+
+\begin{methoddesc}{system.methodHelp}{name}
+This method takes one parameter, the name of a method implemented by
+the XML-RPC server.  It returns a documentation string describing the
+use of that method. If no such string is available, an empty string is
+returned. The documentation string may contain HTML markup.  
+\end{methoddesc}
+
+Introspection methods are currently supported by servers written in
+PHP, C and Microsoft .NET. Partial introspection support is included
+in recent updates to UserLand Frontier. Introspection support for
+Perl, Python and Java is available at the \ulink{XML-RPC
+Hacks}{http://xmlrpc-c.sourceforge.net/hacks.php} page.
+
+
+\subsection{Boolean Objects \label{boolean-objects}}
+
+This class may be initialized from any Python value; the instance
+returned depends only on its truth value.  It supports various Python
+operators through \method{__cmp__()}, \method{__repr__()},
+\method{__int__()}, and \method{__nonzero__()} methods, all
+implemented in the obvious ways.
+
+It also has the following method, supported mainly for internal use by
+the unmarshalling code:
+
+\begin{methoddesc}{encode}{out}
+Write the XML-RPC encoding of this Boolean item to the out stream object.
+\end{methoddesc}
+
+
+\subsection{DateTime Objects \label{datetime-objects}}
+
+This class may be initialized with seconds since the epoch, a time tuple, an
+ISO 8601 time/date string, or a {}\class{\refmodule{datetime}.datetime},
+{}\class{\refmodule{datetime}.date} or {}\class{\refmodule{datetime}.time}
+instance.  It has the following methods, supported mainly for internal use
+by the marshalling/unmarshalling code:
+
+\begin{methoddesc}{decode}{string}
+Accept a string as the instance's new time value.
+\end{methoddesc}
+
+\begin{methoddesc}{encode}{out}
+Write the XML-RPC encoding of this \class{DateTime} item to the
+\var{out} stream object.
+\end{methoddesc}
+
+It also supports certain of Python's built-in operators through 
+\method{__cmp__()} and \method{__repr__()} methods.
+
+
+\subsection{Binary Objects \label{binary-objects}}
+
+This class may be initialized from string data (which may include NULs).
+The primary access to the content of a \class{Binary} object is
+provided by an attribute:
+
+\begin{memberdesc}[Binary]{data}
+The binary data encapsulated by the \class{Binary} instance.  The data
+is provided as an 8-bit string.
+\end{memberdesc}
+
+\class{Binary} objects have the following methods, supported mainly
+for internal use by the marshalling/unmarshalling code:
+
+\begin{methoddesc}[Binary]{decode}{string}
+Accept a base64 string and decode it as the instance's new data.
+\end{methoddesc}
+
+\begin{methoddesc}[Binary]{encode}{out}
+Write the XML-RPC base 64 encoding of this binary item to the out
+stream object.
+\end{methoddesc}
+
+It also supports certain of Python's built-in operators through a
+\method{__cmp__()} method.
+
+
+\subsection{Fault Objects \label{fault-objects}}
+
+A \class{Fault} object encapsulates the content of an XML-RPC fault tag.
+Fault objects have the following members:
+
+\begin{memberdesc}{faultCode}
+A string indicating the fault type.
+\end{memberdesc}
+
+\begin{memberdesc}{faultString}
+A string containing a diagnostic message associated with the fault.
+\end{memberdesc}
+
+
+\subsection{ProtocolError Objects \label{protocol-error-objects}}
+
+A \class{ProtocolError} object describes a protocol error in the
+underlying transport layer (such as a 404 `not found' error if the
+server named by the URI does not exist).  It has the following
+members:
+
+\begin{memberdesc}{url}
+The URI or URL that triggered the error.
+\end{memberdesc}
+
+\begin{memberdesc}{errcode}
+The error code.
+\end{memberdesc}
+
+\begin{memberdesc}{errmsg}
+The error message or diagnostic string.
+\end{memberdesc}
+
+\begin{memberdesc}{headers}
+A string containing the headers of the HTTP/HTTPS request that
+triggered the error.
+\end{memberdesc}
+
+\subsection{MultiCall Objects}
+
+\versionadded{2.4}
+
+In \url{http://www.xmlrpc.com/discuss/msgReader\%241208}, an approach
+is presented to encapsulate multiple calls to a remote server into a
+single request.
+
+\begin{classdesc}{MultiCall}{server}
+
+Create an object used to boxcar method calls. \var{server} is the
+eventual target of the call. Calls can be made to the result object,
+but they will immediately return \var{None}, and only store the
+call name and parameters in the \class{MultiCall} object. Calling
+the object itself causes all stored calls to be transmitted as
+a single \code{system.multicall} request. The result of this call
+is a generator; iterating over this generator yields the individual
+results.
+
+\end{classdesc}
+
+A usage example of this class is
+
+\begin{verbatim}
+multicall = MultiCall(server_proxy)
+multicall.add(2,3)
+multicall.get_address("Guido")
+add_result, address = multicall()
+\end{verbatim}
+
+\subsection{Convenience Functions}
+
+\begin{funcdesc}{boolean}{value}
+Convert any Python value to one of the XML-RPC Boolean constants,
+\code{True} or \code{False}.
+\end{funcdesc}
+
+\begin{funcdesc}{dumps}{params\optional{, methodname\optional{, 
+	                methodresponse\optional{, encoding\optional{,
+	                allow_none}}}}}
+Convert \var{params} into an XML-RPC request.
+or into a response if \var{methodresponse} is true.
+\var{params} can be either a tuple of arguments or an instance of the 
+\exception{Fault} exception class.  If \var{methodresponse} is true,
+only a single value can be returned, meaning that \var{params} must be of length 1.
+\var{encoding}, if supplied, is the encoding to use in the generated
+XML; the default is UTF-8.  Python's \constant{None} value cannot be
+used in standard XML-RPC; to allow using it via an extension, 
+provide a true value for \var{allow_none}.
+\end{funcdesc}
+
+\begin{funcdesc}{loads}{data\optional{, use_datetime}}
+Convert an XML-RPC request or response into Python objects, a
+\code{(\var{params}, \var{methodname})}.  \var{params} is a tuple of argument; \var{methodname}
+is a string, or \code{None} if no method name is present in the packet.
+If the XML-RPC packet represents a fault condition, this
+function will raise a \exception{Fault} exception.
+The \var{use_datetime} flag can be used to cause date/time values to be
+presented as \class{\refmodule{datetime}.datetime} objects; this is false
+by default.
+Note that even if you call an XML-RPC method with
+\class{\refmodule{datetime}.date} or \class{\refmodule{datetime}.time}
+objects, they are converted to \class{DateTime} objects internally, so only
+{}\class{\refmodule{datetime}.datetime} objects will be returned.
+
+\versionchanged[The \var{use_datetime} flag was added]{2.5}
+\end{funcdesc}
+
+
+
+\subsection{Example of Client Usage \label{xmlrpc-client-example}}
+
+\begin{verbatim}
+# simple test program (from the XML-RPC specification)
+from xmlrpclib import ServerProxy, Error
+
+# server = ServerProxy("http://localhost:8000") # local server
+server = ServerProxy("http://betty.userland.com")
+
+print server
+
+try:
+    print server.examples.getStateName(41)
+except Error, v:
+    print "ERROR", v
+\end{verbatim}
+
+To access an XML-RPC server through a proxy, you need to define 
+a custom transport.  The following example, 
+written by NoboNobo, % fill in original author's name if we ever learn it
+shows how:
+
+% Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html
+\begin{verbatim}
+import xmlrpclib, httplib
+
+class ProxiedTransport(xmlrpclib.Transport):
+    def set_proxy(self, proxy):
+        self.proxy = proxy
+    def make_connection(self, host):
+        self.realhost = host
+	h = httplib.HTTP(self.proxy)
+	return h
+    def send_request(self, connection, handler, request_body):
+        connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler))
+    def send_host(self, connection, host):
+        connection.putheader('Host', self.realhost)
+
+p = ProxiedTransport()
+p.set_proxy('proxy-server:8080')
+server = xmlrpclib.Server('http://time.xmlrpc.com/RPC2', transport=p)
+print server.currentTime.getCurrentTime()
+\end{verbatim}