| \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}[SimpleXMLRPCServer]{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}[SimpleXMLRPCServer]{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}[CGIXMLRPCRequestHandler]{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}[CGIXMLRPCRequestHandler]{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}[CGIXMLRPCRequestHandler]{register_introspection_functions}{} |
| Register the XML-RPC introspection functions |
| \code{system.listMethods}, \code{system.methodHelp} and |
| \code{system.methodSignature}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[CGIXMLRPCRequestHandler]{register_multicall_functions}{} |
| Register the XML-RPC multicall function \code{system.multicall}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[CGIXMLRPCRequestHandler]{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} |