Patch #473586: Implement CGIXMLRPCRequestHandler.

Doc/lib/libsimplexmlrpc.tex

@@ -8,14 +8,13 @@
 
 
 The \module{SimpleXMLRPCServer} module provides a basic server
-framework for XML-RPC servers written in Python.  The server object is
-based on the \class{\refmodule{SocketServer}.TCPServer} class,
-and the request handler is based on the
-\class{\refmodule{BaseHTTPServer}.BaseHTTPRequestHandler} class.
-
+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}}}
+
   Create a new server instance.  The \var{requestHandler} parameter
   should be a factory for request handler instances; it defaults to
   \class{SimpleXMLRPCRequestHandler}.  The \var{addr} and
@@ -27,6 +26,10 @@ and the request handler is based on the
   the XML-RPC protocol.
 \end{classdesc}
 
+\begin{classdesc}{CGIXMLRPCRequestHandler}{}
+  Create a new instance to handle XML-RPC requests in a CGI
+  environment. \versionadded{2.3}
+\end{classdesc}
 
 \begin{classdesc}{SimpleXMLRPCRequestHandler}{}
   Create a new request handler instance.  This request handler
@@ -38,20 +41,18 @@ and the request handler is based on the
 
 \subsection{SimpleXMLRPCServer Objects \label{simple-xmlrpc-servers}}
 
-The \class{SimpleXMLRPCServer} class provides two methods that an
-application can use to register functions that can be called via the
-XML-RPC protocol via the request handler.
+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.  The
-  function must be callable with a single parameter which will be the
-  return value of \function{\refmodule{xmlrpclib}.loads()} when called
-  with the payload of the request.  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.
+  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}
@@ -68,3 +69,89 @@ XML-RPC protocol via the request handler.
   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}{}
+  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}
+
+Example:
+
+\begin{verbatim}
+class MyFuncs:
+    def div(self, x, y) : return div(x,y)
+
+
+server = SimpleXMLRPCServer(("localhost", 8000))
+server.register_function(pow)
+server.register_function(lambda x,y: x+y, 'add')
+server.register_introspection_functions()
+server.register_instance(MyFuncs())
+server.serve_forever()
+\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 \methode{_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 div(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}