Doc/lib/libsimplexmlrpc.tex

   1 \section{\module{SimpleXMLRPCServer} ---
   2          Basic XML-RPC server}
   3
   4 \declaremodule{standard}{SimpleXMLRPCServer}
   5 \modulesynopsis{Basic XML-RPC server implementation.}
   6 \moduleauthor{Brian Quinlan}{brianq@activestate.com}
   7 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   8
   9 \versionadded{2.2}
  10
  11 The \module{SimpleXMLRPCServer} module provides a basic server
  12 framework for XML-RPC servers written in Python.  Servers can either
  13 be free standing, using \class{SimpleXMLRPCServer}, or embedded in a
  14 CGI environment, using \class{CGIXMLRPCRequestHandler}.
  15
  16 \begin{classdesc}{SimpleXMLRPCServer}{addr\optional{,
  17                                       requestHandler\optional{,
  18                                         logRequests\optional{, allow_none\optional{, encoding}}}}}
  19
  20   Create a new server instance.  This class
  21   provides methods for registration of functions that can be called by
  22   the XML-RPC protocol.  The \var{requestHandler} parameter
  23   should be a factory for request handler instances; it defaults to
  24   \class{SimpleXMLRPCRequestHandler}.  The \var{addr} and
  25   \var{requestHandler} parameters are passed to the
  26   \class{\refmodule{SocketServer}.TCPServer} constructor.  If
  27   \var{logRequests} is true (the default), requests will be logged;
  28   setting this parameter to false will turn off logging.
  29   The \var{allow_none} and \var{encoding} parameters are passed on to
  30   \module{xmlrpclib} and control the XML-RPC responses that will be returned
  31   from the server.
  32   \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5}
  33 \end{classdesc}
  34
  35 \begin{classdesc}{CGIXMLRPCRequestHandler}{\optional{allow_none\optional{, encoding}}}
  36   Create a new instance to handle XML-RPC requests in a CGI
  37   environment.
  38   The \var{allow_none} and \var{encoding} parameters are passed on to
  39   \module{xmlrpclib} and control the XML-RPC responses that will be returned
  40   from the server.
  41   \versionadded{2.3}
  42   \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5}
  43 \end{classdesc}
  44
  45 \begin{classdesc}{SimpleXMLRPCRequestHandler}{}
  46   Create a new request handler instance.  This request handler
  47   supports \code{POST} requests and modifies logging so that the
  48   \var{logRequests} parameter to the \class{SimpleXMLRPCServer}
  49   constructor parameter is honored.
  50 \end{classdesc}
  51
  52
  53 \subsection{SimpleXMLRPCServer Objects \label{simple-xmlrpc-servers}}
  54
  55 The \class{SimpleXMLRPCServer} class is based on
  56 \class{SocketServer.TCPServer} and provides a means of creating
  57 simple, stand alone XML-RPC servers.
  58
  59 \begin{methoddesc}[SimpleXMLRPCServer]{register_function}{function\optional{,
  60                                                           name}}
  61   Register a function that can respond to XML-RPC requests.  If
  62   \var{name} is given, it will be the method name associated with
  63   \var{function}, otherwise \code{\var{function}.__name__} will be
  64   used.  \var{name} can be either a normal or Unicode string, and may
  65   contain characters not legal in Python identifiers, including the
  66   period character.
  67 \end{methoddesc}
  68
  69 \begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance\optional{,
  70                                        allow_dotted_names}}
  71   Register an object which is used to expose method names which have
  72   not been registered using \method{register_function()}.  If
  73   \var{instance} contains a \method{_dispatch()} method, it is called
  74   with the requested method name and the parameters from the request.  Its
  75   API is \code{def \method{_dispatch}(self, method, params)} (note that
  76   \var{params} does not represent a variable argument list).  If it calls an
  77   underlying function to perform its task, that function is called as
  78   \code{func(*params)}, expanding the parameter list.
  79   The return value from \method{_dispatch()} is returned to the client as
  80   the result.  If
  81   \var{instance} does not have a \method{_dispatch()} method, it is
  82   searched for an attribute matching the name of the requested method.
  83
  84   If the optional \var{allow_dotted_names} argument is true and the
  85   instance does not have a \method{_dispatch()} method, then
  86   if the requested method name contains periods, each component of the
  87   method name is searched for individually, with the effect that a
  88   simple hierarchical search is performed.  The value found from this
  89   search is then called with the parameters from the request, and the
  90   return value is passed back to the client.
  91
  92   \begin{notice}[warning]
  93   Enabling the \var{allow_dotted_names} option allows intruders to access
  94   your module's global variables and may allow intruders to execute
  95   arbitrary code on your machine.  Only use this option on a secure,
  96   closed network.
  97   \end{notice}
  98
  99   \versionchanged[\var{allow_dotted_names} was added to plug a security hole;
 100   prior versions are insecure]{2.3.5, 2.4.1}
 101
 102 \end{methoddesc}
 103
 104 \begin{methoddesc}{register_introspection_functions}{}
 105   Registers the XML-RPC introspection functions \code{system.listMethods},
 106   \code{system.methodHelp} and \code{system.methodSignature}.
 107   \versionadded{2.3}
 108 \end{methoddesc}
 109
 110 \begin{methoddesc}{register_multicall_functions}{}
 111   Registers the XML-RPC multicall function system.multicall.
 112 \end{methoddesc}
 113
 114 \begin{memberdesc}[SimpleXMLRPCServer]{rpc_paths}
 115 An attribute value that must be a tuple listing valid path portions of
 116 the URL for receiving XML-RPC requests.  Requests posted to other
 117 paths will result in a 404 ``no such page'' HTTP error.  If this
 118 tuple is empty, all paths will be considered valid.
 119 The default value is \code{('/', '/RPC2')}.
 120   \versionadded{2.5}
 121 \end{memberdesc}
 122
 123 Example:
 124
 125 \begin{verbatim}
 126 from SimpleXMLRPCServer import SimpleXMLRPCServer
 127
 128 # Create server
 129 server = SimpleXMLRPCServer(("localhost", 8000))
 130 server.register_introspection_functions()
 131
 132 # Register pow() function; this will use the value of
 133 # pow.__name__ as the name, which is just 'pow'.
 134 server.register_function(pow)
 135
 136 # Register a function under a different name
 137 def adder_function(x,y):
 138     return x + y
 139 server.register_function(adder_function, 'add')
 140
 141 # Register an instance; all the methods of the instance are
 142 # published as XML-RPC methods (in this case, just 'div').
 143 class MyFuncs:
 144     def div(self, x, y):
 145         return x // y
 146
 147 server.register_instance(MyFuncs())
 148
 149 # Run the server's main loop
 150 server.serve_forever()
 151 \end{verbatim}
 152
 153 The following client code will call the methods made available by
 154 the preceding server:
 155
 156 \begin{verbatim}
 157 import xmlrpclib
 158
 159 s = xmlrpclib.Server('http://localhost:8000')
 160 print s.pow(2,3)  # Returns 2**3 = 8
 161 print s.add(2,3)  # Returns 5
 162 print s.div(5,2)  # Returns 5//2 = 2
 163
 164 # Print list of available methods
 165 print s.system.listMethods()
 166 \end{verbatim}
 167
 168
 169 \subsection{CGIXMLRPCRequestHandler}
 170
 171 The \class{CGIXMLRPCRequestHandler} class can be used to
 172 handle XML-RPC requests sent to Python CGI scripts.
 173
 174 \begin{methoddesc}{register_function}{function\optional{, name}}
 175 Register a function that can respond to XML-RPC requests. If
 176 \var{name} is given, it will be the method name associated with
 177 function, otherwise \var{function.__name__} will be used. \var{name}
 178 can be either a normal or Unicode string, and may contain
 179 characters not legal in Python identifiers, including the period
 180 character.
 181 \end{methoddesc}
 182
 183 \begin{methoddesc}{register_instance}{instance}
 184 Register an object which is used to expose method names
 185 which have not been registered using \method{register_function()}. If
 186 instance contains a \method{_dispatch()} method, it is called with the
 187 requested method name and the parameters from the
 188 request; the return value is returned to the client as the result.
 189 If instance does not have a \method{_dispatch()} method, it is searched
 190 for an attribute matching the name of the requested method; if
 191 the requested method name contains periods, each
 192 component of the method name is searched for individually,
 193 with the effect that a simple hierarchical search is performed.
 194 The value found from this search is then called with the
 195 parameters from the request, and the return value is passed
 196 back to the client.
 197 \end{methoddesc}
 198
 199 \begin{methoddesc}{register_introspection_functions}{}
 200 Register the XML-RPC introspection functions
 201 \code{system.listMethods}, \code{system.methodHelp} and
 202 \code{system.methodSignature}.
 203 \end{methoddesc}
 204
 205 \begin{methoddesc}{register_multicall_functions}{}
 206 Register the XML-RPC multicall function \code{system.multicall}.
 207 \end{methoddesc}
 208
 209 \begin{methoddesc}{handle_request}{\optional{request_text = None}}
 210 Handle a XML-RPC request. If \var{request_text} is given, it
 211 should be the POST data provided by the HTTP server,
 212 otherwise the contents of stdin will be used.
 213 \end{methoddesc}
 214
 215 Example:
 216
 217 \begin{verbatim}
 218 class MyFuncs:
 219     def div(self, x, y) : return x // y
 220
 221
 222 handler = CGIXMLRPCRequestHandler()
 223 handler.register_function(pow)
 224 handler.register_function(lambda x,y: x+y, 'add')
 225 handler.register_introspection_functions()
 226 handler.register_instance(MyFuncs())
 227 handler.handle_request()
 228 \end{verbatim}