Doc/library/simplexmlrpcserver.rst

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