add hg and python

1 files changed, 228 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libsimplexmlrpc.tex b/sys/src/cmd/python/Doc/lib/libsimplexmlrpc.tex
new file mode 100644
index 000000000..6b458558c
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libsimplexmlrpc.tex
@@ -0,0 +1,228 @@
+\section{\module{SimpleXMLRPCServer} ---
+         Basic XML-RPC server}
+
+\declaremodule{standard}{SimpleXMLRPCServer}
+\modulesynopsis{Basic XML-RPC server implementation.}
+\moduleauthor{Brian Quinlan}{brianq@activestate.com}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+\versionadded{2.2}
+
+The \module{SimpleXMLRPCServer} module provides a basic server
+framework for XML-RPC servers written in Python.  Servers can either
+be free standing, using \class{SimpleXMLRPCServer}, or embedded in a
+CGI environment, using \class{CGIXMLRPCRequestHandler}.
+
+\begin{classdesc}{SimpleXMLRPCServer}{addr\optional{,
+                                      requestHandler\optional{,
+					logRequests\optional{, allow_none\optional{, encoding}}}}}
+
+  Create a new server instance.  This class
+  provides methods for registration of functions that can be called by
+  the XML-RPC protocol.  The \var{requestHandler} parameter
+  should be a factory for request handler instances; it defaults to
+  \class{SimpleXMLRPCRequestHandler}.  The \var{addr} and
+  \var{requestHandler} parameters are passed to the
+  \class{\refmodule{SocketServer}.TCPServer} constructor.  If
+  \var{logRequests} is true (the default), requests will be logged;
+  setting this parameter to false will turn off logging.  
+  The \var{allow_none} and \var{encoding} parameters are passed on to 
+  \module{xmlrpclib} and control the XML-RPC responses that will be returned 
+  from the server.
+  \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5}
+\end{classdesc}
+
+\begin{classdesc}{CGIXMLRPCRequestHandler}{\optional{allow_none\optional{, encoding}}}
+  Create a new instance to handle XML-RPC requests in a CGI
+  environment. 
+  The \var{allow_none} and \var{encoding} parameters are passed on to 
+  \module{xmlrpclib} and control the XML-RPC responses that will be returned 
+  from the server.
+  \versionadded{2.3}
+  \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5}
+\end{classdesc}
+
+\begin{classdesc}{SimpleXMLRPCRequestHandler}{}
+  Create a new request handler instance.  This request handler
+  supports \code{POST} requests and modifies logging so that the
+  \var{logRequests} parameter to the \class{SimpleXMLRPCServer}
+  constructor parameter is honored.
+\end{classdesc}
+
+
+\subsection{SimpleXMLRPCServer Objects \label{simple-xmlrpc-servers}}
+
+The \class{SimpleXMLRPCServer} class is based on
+\class{SocketServer.TCPServer} and provides a means of creating
+simple, stand alone XML-RPC servers.
+
+\begin{methoddesc}[SimpleXMLRPCServer]{register_function}{function\optional{,
+                                                          name}}
+  Register a function that can respond to XML-RPC requests.  If
+  \var{name} is given, it will be the method name associated with
+  \var{function}, otherwise \code{\var{function}.__name__} will be
+  used.  \var{name} can be either a normal or Unicode string, and may
+  contain characters not legal in Python identifiers, including the
+  period character.
+\end{methoddesc}
+
+\begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance\optional{,
+                                       allow_dotted_names}}
+  Register an object which is used to expose method names which have
+  not been registered using \method{register_function()}.  If
+  \var{instance} contains a \method{_dispatch()} method, it is called
+  with the requested method name and the parameters from the request.  Its
+  API is \code{def \method{_dispatch}(self, method, params)} (note that
+  \var{params} does not represent a variable argument list).  If it calls an
+  underlying function to perform its task, that function is called as
+  \code{func(*params)}, expanding the parameter list.
+  The return value from \method{_dispatch()} is returned to the client as
+  the result.  If
+  \var{instance} does not have a \method{_dispatch()} method, it is
+  searched for an attribute matching the name of the requested method.
+
+  If the optional \var{allow_dotted_names} argument is true and the
+  instance does not have a \method{_dispatch()} method, then
+  if the requested method name contains periods, each component of the
+  method name is searched for individually, with the effect that a
+  simple hierarchical search is performed.  The value found from this
+  search is then called with the parameters from the request, and the
+  return value is passed back to the client.
+
+  \begin{notice}[warning]
+  Enabling the \var{allow_dotted_names} option allows intruders to access
+  your module's global variables and may allow intruders to execute
+  arbitrary code on your machine.  Only use this option on a secure,
+  closed network.
+  \end{notice}
+
+  \versionchanged[\var{allow_dotted_names} was added to plug a security hole;
+  prior versions are insecure]{2.3.5, 2.4.1}
+
+\end{methoddesc}
+
+\begin{methoddesc}{register_introspection_functions}{}
+  Registers the XML-RPC introspection functions \code{system.listMethods},
+  \code{system.methodHelp} and \code{system.methodSignature}. 
+  \versionadded{2.3}
+\end{methoddesc}
+
+\begin{methoddesc}{register_multicall_functions}{}
+  Registers the XML-RPC multicall function system.multicall.
+\end{methoddesc}
+
+\begin{memberdesc}[SimpleXMLRPCServer]{rpc_paths}
+An attribute value that must be a tuple listing valid path portions of
+the URL for receiving XML-RPC requests.  Requests posted to other
+paths will result in a 404 ``no such page'' HTTP error.  If this
+tuple is empty, all paths will be considered valid.
+The default value is \code{('/', '/RPC2')}.
+  \versionadded{2.5}
+\end{memberdesc}
+
+Example:
+
+\begin{verbatim}
+from SimpleXMLRPCServer import SimpleXMLRPCServer
+
+# Create server
+server = SimpleXMLRPCServer(("localhost", 8000))
+server.register_introspection_functions()
+
+# Register pow() function; this will use the value of 
+# pow.__name__ as the name, which is just 'pow'.
+server.register_function(pow)
+
+# Register a function under a different name
+def adder_function(x,y):
+    return x + y
+server.register_function(adder_function, 'add')
+
+# Register an instance; all the methods of the instance are 
+# published as XML-RPC methods (in this case, just 'div').
+class MyFuncs:
+    def div(self, x, y): 
+        return x // y
+    
+server.register_instance(MyFuncs())
+
+# Run the server's main loop
+server.serve_forever()
+\end{verbatim}
+
+The following client code will call the methods made available by 
+the preceding server:
+
+\begin{verbatim}
+import xmlrpclib
+
+s = xmlrpclib.Server('http://localhost:8000')
+print s.pow(2,3)  # Returns 2**3 = 8
+print s.add(2,3)  # Returns 5
+print s.div(5,2)  # Returns 5//2 = 2
+
+# Print list of available methods
+print s.system.listMethods()
+\end{verbatim}
+
+
+\subsection{CGIXMLRPCRequestHandler}
+
+The \class{CGIXMLRPCRequestHandler} class can be used to 
+handle XML-RPC requests sent to Python CGI scripts.
+
+\begin{methoddesc}{register_function}{function\optional{, name}}
+Register a function that can respond to XML-RPC requests. If 
+\var{name} is given, it will be the method name associated with 
+function, otherwise \var{function.__name__} will be used. \var{name}
+can be either a normal or Unicode string, and may contain 
+characters not legal in Python identifiers, including the period
+character. 
+\end{methoddesc}
+
+\begin{methoddesc}{register_instance}{instance}
+Register an object which is used to expose method names 
+which have not been registered using \method{register_function()}. If 
+instance contains a \method{_dispatch()} method, it is called with the 
+requested method name and the parameters from the 
+request; the return value is returned to the client as the result.
+If instance does not have a \method{_dispatch()} method, it is searched 
+for an attribute matching the name of the requested method; if 
+the requested method name contains periods, each 
+component of the method name is searched for individually, 
+with the effect that a simple hierarchical search is performed. 
+The value found from this search is then called with the 
+parameters from the request, and the return value is passed 
+back to the client. 
+\end{methoddesc}
+
+\begin{methoddesc}{register_introspection_functions}{}
+Register the XML-RPC introspection functions 
+\code{system.listMethods}, \code{system.methodHelp} and 
+\code{system.methodSignature}.
+\end{methoddesc}
+
+\begin{methoddesc}{register_multicall_functions}{}
+Register the XML-RPC multicall function \code{system.multicall}.
+\end{methoddesc}
+
+\begin{methoddesc}{handle_request}{\optional{request_text = None}}
+Handle a XML-RPC request. If \var{request_text} is given, it 
+should be the POST data provided by the HTTP server, 
+otherwise the contents of stdin will be used.
+\end{methoddesc}
+
+Example:
+
+\begin{verbatim}
+class MyFuncs:
+    def div(self, x, y) : return x // y
+
+
+handler = CGIXMLRPCRequestHandler()
+handler.register_function(pow)
+handler.register_function(lambda x,y: x+y, 'add')
+handler.register_introspection_functions()
+handler.register_instance(MyFuncs())
+handler.handle_request()
+\end{verbatim}