Patch #473586: Implement CGIXMLRPCRequestHandler.
diff --git a/Doc/lib/libsimplexmlrpc.tex b/Doc/lib/libsimplexmlrpc.tex
index be56c45..6531b52 100644
--- a/Doc/lib/libsimplexmlrpc.tex
+++ b/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 @@
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 @@
\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 @@
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}
\ No newline at end of file