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 .. _simplexmlrpcserver-example:

   137 

   138 SimpleXMLRPCServer Example

   139 ^^^^^^^^^^^^^^^^^^^^^^^^^^

   140 Server code::

   141 

   142    from SimpleXMLRPCServer import SimpleXMLRPCServer

   143    from SimpleXMLRPCServer import SimpleXMLRPCRequestHandler

   144 

   145    # Restrict to a particular path.

   146    class RequestHandler(SimpleXMLRPCRequestHandler):

   147        rpc_paths = ('/RPC2',)

   148 

   149    # Create server

   150    server = SimpleXMLRPCServer(("localhost", 8000),

   151                                requestHandler=RequestHandler)

   152    server.register_introspection_functions()

   153 

   154    # Register pow() function; this will use the value of 

   155    # pow.__name__ as the name, which is just 'pow'.

   156    server.register_function(pow)

   157 

   158    # Register a function under a different name

   159    def adder_function(x,y):

   160        return x + y

   161    server.register_function(adder_function, 'add')

   162 

   163    # Register an instance; all the methods of the instance are 

   164    # published as XML-RPC methods (in this case, just 'div').

   165    class MyFuncs:

   166        def div(self, x, y): 

   167            return x // y

   168 

   169    server.register_instance(MyFuncs())

   170 

   171    # Run the server's main loop

   172    server.serve_forever()

   173 

   174 The following client code will call the methods made available by the preceding

   175 server::

   176 

   177    import xmlrpclib

   178 

   179    s = xmlrpclib.ServerProxy('http://localhost:8000')

   180    print s.pow(2,3)  # Returns 2**3 = 8

   181    print s.add(2,3)  # Returns 5

   182    print s.div(5,2)  # Returns 5//2 = 2

   183 

   184    # Print list of available methods

   185    print s.system.listMethods()

   186 

   187 

   188 CGIXMLRPCRequestHandler

   189 -----------------------

   190 

   191 The :class:`CGIXMLRPCRequestHandler` class can be used to  handle XML-RPC

   192 requests sent to Python CGI scripts.

   193 

   194 

   195 .. method:: CGIXMLRPCRequestHandler.register_function(function[, name])

   196 

   197    Register a function that can respond to XML-RPC requests. If  *name* is given,

   198    it will be the method name associated with  function, otherwise

   199    *function.__name__* will be used. *name* can be either a normal or Unicode

   200    string, and may contain  characters not legal in Python identifiers, including

   201    the period character.

   202 

   203 

   204 .. method:: CGIXMLRPCRequestHandler.register_instance(instance)

   205 

   206    Register an object which is used to expose method names  which have not been

   207    registered using :meth:`register_function`. If  instance contains a

   208    :meth:`_dispatch` method, it is called with the  requested method name and the

   209    parameters from the  request; the return value is returned to the client as the

   210    result. If instance does not have a :meth:`_dispatch` method, it is searched

   211    for an attribute matching the name of the requested method; if  the requested

   212    method name contains periods, each  component of the method name is searched for

   213    individually,  with the effect that a simple hierarchical search is performed.

   214    The value found from this search is then called with the  parameters from the

   215    request, and the return value is passed  back to the client.

   216 

   217 

   218 .. method:: CGIXMLRPCRequestHandler.register_introspection_functions()

   219 

   220    Register the XML-RPC introspection functions  ``system.listMethods``,

   221    ``system.methodHelp`` and  ``system.methodSignature``.

   222 

   223 

   224 .. method:: CGIXMLRPCRequestHandler.register_multicall_functions()

   225 

   226    Register the XML-RPC multicall function ``system.multicall``.

   227 

   228 

   229 .. method:: CGIXMLRPCRequestHandler.handle_request([request_text = None])

   230 

   231    Handle a XML-RPC request. If *request_text* is given, it  should be the POST

   232    data provided by the HTTP server,  otherwise the contents of stdin will be used.

   233 

   234 Example::

   235 

   236    class MyFuncs:

   237        def div(self, x, y) : return x // y

   238 

   239 

   240    handler = CGIXMLRPCRequestHandler()

   241    handler.register_function(pow)

   242    handler.register_function(lambda x,y: x+y, 'add')

   243    handler.register_introspection_functions()

   244    handler.register_instance(MyFuncs())

   245    handler.handle_request()

   246