Source

python-clinic / Doc / library / xmlrpc.server.rst

Full commit

:mod:`xmlrpc.server` --- Basic XML-RPC servers

Source code: :source:`Lib/xmlrpc/server.py`


The :mod:`xmlrpc.server` 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`.

Warning

The :mod:`xmlrpc.client` module is not secure against maliciously constructed data. If you need to parse untrusted or unauthenticated data see :ref:`xml-vulnerabilities`.

Create a new server instance. This class provides methods for registration of functions that can be called by the XML-RPC protocol. The requestHandler parameter should be a factory for request handler instances; it defaults to :class:`SimpleXMLRPCRequestHandler`. The addr and requestHandler parameters are passed to the :class:`socketserver.TCPServer` constructor. If logRequests is true (the default), requests will be logged; setting this parameter to false will turn off logging. The allow_none and encoding parameters are passed on to :mod:`xmlrpc.client` and control the XML-RPC responses that will be returned from the server. The bind_and_activate parameter controls whether :meth:`server_bind` and :meth:`server_activate` are called immediately by the constructor; it defaults to true. Setting it to false allows code to manipulate the allow_reuse_address class variable before the address is bound. The use_builtin_types parameter is passed to the :func:`~xmlrpc.client.loads` function and controls which types are processed when date/times values or binary data are received; it defaults to false.

Create a new instance to handle XML-RPC requests in a CGI environment. The allow_none and encoding parameters are passed on to :mod:`xmlrpc.client` and control the XML-RPC responses that will be returned from the server. The use_builtin_types parameter is passed to the :func:`~xmlrpc.client.loads` function and controls which types are processed when date/times values or binary data are received; it defaults to false.

Create a new request handler instance. This request handler supports POST requests and modifies logging so that the logRequests parameter to the :class:`SimpleXMLRPCServer` constructor parameter is honored.

SimpleXMLRPCServer Objects

The :class:`SimpleXMLRPCServer` class is based on :class:`socketserver.TCPServer` and provides a means of creating simple, stand alone XML-RPC servers.

SimpleXMLRPCServer Example

Server code:

from xmlrpc.server import SimpleXMLRPCServer
from xmlrpc.server import SimpleXMLRPCRequestHandler

# Restrict to a particular path.
class RequestHandler(SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

# Create server
server = SimpleXMLRPCServer(("localhost", 8000),
                            requestHandler=RequestHandler)
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 'mul').
class MyFuncs:
    def mul(self, x, y):
        return x * y

server.register_instance(MyFuncs())

# Run the server's main loop
server.serve_forever()

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

import xmlrpc.client

s = xmlrpc.client.ServerProxy('http://localhost:8000')
print(s.pow(2,3))  # Returns 2**3 = 8
print(s.add(2,3))  # Returns 5
print(s.mul(5,2))  # Returns 5*2 = 10

# Print list of available methods
print(s.system.listMethods())

CGIXMLRPCRequestHandler

The :class:`CGIXMLRPCRequestHandler` class can be used to handle XML-RPC requests sent to Python CGI scripts.

Example:

class MyFuncs:
    def mul(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()

Documenting XMLRPC server

These classes extend the above classes to serve HTML documentation in response to HTTP GET requests. Servers can either be free standing, using :class:`DocXMLRPCServer`, or embedded in a CGI environment, using :class:`DocCGIXMLRPCRequestHandler`.

Create a new server instance. All parameters have the same meaning as for :class:`SimpleXMLRPCServer`; requestHandler defaults to :class:`DocXMLRPCRequestHandler`.

Create a new instance to handle XML-RPC requests in a CGI environment.

Create a new request handler instance. This request handler supports XML-RPC POST requests, documentation GET requests, and modifies logging so that the logRequests parameter to the :class:`DocXMLRPCServer` constructor parameter is honored.

DocXMLRPCServer Objects

The :class:`DocXMLRPCServer` class is derived from :class:`SimpleXMLRPCServer` and provides a means of creating self-documenting, stand alone XML-RPC servers. HTTP POST requests are handled as XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style HTML documentation. This allows a server to provide its own web-based documentation.

DocCGIXMLRPCRequestHandler

The :class:`DocCGIXMLRPCRequestHandler` class is derived from :class:`CGIXMLRPCRequestHandler` and provides a means of creating self-documenting, XML-RPC CGI scripts. HTTP POST requests are handled as XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style HTML documentation. This allows a server to provide its own web-based documentation.