mirror of https://github.com/python/cpython
236 lines
9.2 KiB
TeX
236 lines
9.2 KiB
TeX
\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. The \var{bind_and_activate} parameter controls whether
|
|
\method{server_bind()} and \method{server_activate()} are called immediately
|
|
by the constructor; it defaults to true. Setting it to false allows code to
|
|
manipulate the \var{allow_reuse_address} class variable before the address
|
|
is bound.
|
|
\versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5}
|
|
\versionchanged[The \var{bind_and_activate} parameter was added]{2.6}
|
|
\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}
|