Doc/library/simplexmlrpcserver.rst

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