1
:mod:`xmlrpc.server` --- Basic XML-RPC servers
2
==============================================
4
.. module:: xmlrpc.server
5
:synopsis: Basic XML-RPC server implementations.
6
.. moduleauthor:: Brian Quinlan <brianq@activestate.com>
7
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
9
**Source code:** :source:`Lib/xmlrpc/server.py`
13
The :mod:`xmlrpc.server` module provides a basic server framework for XML-RPC
14
servers written in Python. Servers can either be free standing, using
15
:class:`SimpleXMLRPCServer`, or embedded in a CGI environment, using
16
:class:`CGIXMLRPCRequestHandler`.
21
The :mod:`xmlrpc.client` module is not secure against maliciously
22
constructed data. If you need to parse untrusted or unauthenticated data see
23
:ref:`xml-vulnerabilities`.
26
.. class:: SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler,\
27
logRequests=True, allow_none=False, encoding=None,\
28
bind_and_activate=True, use_builtin_types=False)
30
Create a new server instance. This class provides methods for registration of
31
functions that can be called by the XML-RPC protocol. The *requestHandler*
32
parameter should be a factory for request handler instances; it defaults to
33
:class:`SimpleXMLRPCRequestHandler`. The *addr* and *requestHandler* parameters
34
are passed to the :class:`socketserver.TCPServer` constructor. If *logRequests*
35
is true (the default), requests will be logged; setting this parameter to false
36
will turn off logging. The *allow_none* and *encoding* parameters are passed
37
on to :mod:`xmlrpc.client` and control the XML-RPC responses that will be returned
38
from the server. The *bind_and_activate* parameter controls whether
39
:meth:`server_bind` and :meth:`server_activate` are called immediately by the
40
constructor; it defaults to true. Setting it to false allows code to manipulate
41
the *allow_reuse_address* class variable before the address is bound.
42
The *use_builtin_types* parameter is passed to the
43
:func:`~xmlrpc.client.loads` function and controls which types are processed
44
when date/times values or binary data are received; it defaults to false.
46
.. versionchanged:: 3.3
47
The *use_builtin_types* flag was added.
50
.. class:: CGIXMLRPCRequestHandler(allow_none=False, encoding=None,\
51
use_builtin_types=False)
53
Create a new instance to handle XML-RPC requests in a CGI environment. The
54
*allow_none* and *encoding* parameters are passed on to :mod:`xmlrpc.client`
55
and control the XML-RPC responses that will be returned from the server.
56
The *use_builtin_types* parameter is passed to the
57
:func:`~xmlrpc.client.loads` function and controls which types are processed
58
when date/times values or binary data are received; it defaults to false.
60
.. versionchanged:: 3.3
61
The *use_builtin_types* flag was added.
64
.. class:: SimpleXMLRPCRequestHandler()
66
Create a new request handler instance. This request handler supports ``POST``
67
requests and modifies logging so that the *logRequests* parameter to the
68
:class:`SimpleXMLRPCServer` constructor parameter is honored.
71
.. _simple-xmlrpc-servers:
73
SimpleXMLRPCServer Objects
74
--------------------------
76
The :class:`SimpleXMLRPCServer` class is based on
77
:class:`socketserver.TCPServer` and provides a means of creating simple, stand
78
alone XML-RPC servers.
81
.. method:: SimpleXMLRPCServer.register_function(function, name=None)
83
Register a function that can respond to XML-RPC requests. If *name* is given,
84
it will be the method name associated with *function*, otherwise
85
``function.__name__`` will be used. *name* can be either a normal or Unicode
86
string, and may contain characters not legal in Python identifiers, including
90
.. method:: SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)
92
Register an object which is used to expose method names which have not been
93
registered using :meth:`register_function`. If *instance* contains a
94
:meth:`_dispatch` method, it is called with the requested method name and the
95
parameters from the request. Its API is ``def _dispatch(self, method, params)``
96
(note that *params* does not represent a variable argument list). If it calls
97
an underlying function to perform its task, that function is called as
98
``func(*params)``, expanding the parameter list. The return value from
99
:meth:`_dispatch` is returned to the client as the result. If *instance* does
100
not have a :meth:`_dispatch` method, it is searched for an attribute matching
101
the name of the requested method.
103
If the optional *allow_dotted_names* argument is true and the instance does not
104
have a :meth:`_dispatch` method, then if the requested method name contains
105
periods, each component of the method name is searched for individually, with
106
the effect that a simple hierarchical search is performed. The value found from
107
this search is then called with the parameters from the request, and the return
108
value is passed back to the client.
112
Enabling the *allow_dotted_names* option allows intruders to access your
113
module's global variables and may allow intruders to execute arbitrary code on
114
your machine. Only use this option on a secure, closed network.
117
.. method:: SimpleXMLRPCServer.register_introspection_functions()
119
Registers the XML-RPC introspection functions ``system.listMethods``,
120
``system.methodHelp`` and ``system.methodSignature``.
123
.. method:: SimpleXMLRPCServer.register_multicall_functions()
125
Registers the XML-RPC multicall function system.multicall.
128
.. attribute:: SimpleXMLRPCRequestHandler.rpc_paths
130
An attribute value that must be a tuple listing valid path portions of the URL
131
for receiving XML-RPC requests. Requests posted to other paths will result in a
132
404 "no such page" HTTP error. If this tuple is empty, all paths will be
133
considered valid. The default value is ``('/', '/RPC2')``.
136
.. _simplexmlrpcserver-example:
138
SimpleXMLRPCServer Example
139
^^^^^^^^^^^^^^^^^^^^^^^^^^
142
from xmlrpc.server import SimpleXMLRPCServer
143
from xmlrpc.server import SimpleXMLRPCRequestHandler
145
# Restrict to a particular path.
146
class RequestHandler(SimpleXMLRPCRequestHandler):
147
rpc_paths = ('/RPC2',)
150
server = SimpleXMLRPCServer(("localhost", 8000),
151
requestHandler=RequestHandler)
152
server.register_introspection_functions()
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)
158
# Register a function under a different name
159
def adder_function(x,y):
161
server.register_function(adder_function, 'add')
163
# Register an instance; all the methods of the instance are
164
# published as XML-RPC methods (in this case, just 'mul').
169
server.register_instance(MyFuncs())
171
# Run the server's main loop
172
server.serve_forever()
174
The following client code will call the methods made available by the preceding
179
s = xmlrpc.client.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.mul(5,2)) # Returns 5*2 = 10
184
# Print list of available methods
185
print(s.system.listMethods())
188
CGIXMLRPCRequestHandler
189
-----------------------
191
The :class:`CGIXMLRPCRequestHandler` class can be used to handle XML-RPC
192
requests sent to Python CGI scripts.
195
.. method:: CGIXMLRPCRequestHandler.register_function(function, name=None)
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.
204
.. method:: CGIXMLRPCRequestHandler.register_instance(instance)
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.
218
.. method:: CGIXMLRPCRequestHandler.register_introspection_functions()
220
Register the XML-RPC introspection functions ``system.listMethods``,
221
``system.methodHelp`` and ``system.methodSignature``.
224
.. method:: CGIXMLRPCRequestHandler.register_multicall_functions()
226
Register the XML-RPC multicall function ``system.multicall``.
229
.. method:: CGIXMLRPCRequestHandler.handle_request(request_text=None)
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.
241
handler = CGIXMLRPCRequestHandler()
242
handler.register_function(pow)
243
handler.register_function(lambda x,y: x+y, 'add')
244
handler.register_introspection_functions()
245
handler.register_instance(MyFuncs())
246
handler.handle_request()
249
Documenting XMLRPC server
250
-------------------------
252
These classes extend the above classes to serve HTML documentation in response
253
to HTTP GET requests. Servers can either be free standing, using
254
:class:`DocXMLRPCServer`, or embedded in a CGI environment, using
255
:class:`DocCGIXMLRPCRequestHandler`.
258
.. class:: DocXMLRPCServer(addr, requestHandler=DocXMLRPCRequestHandler,\
259
logRequests=True, allow_none=False, encoding=None,\
260
bind_and_activate=True, use_builtin_types=True)
262
Create a new server instance. All parameters have the same meaning as for
263
:class:`SimpleXMLRPCServer`; *requestHandler* defaults to
264
:class:`DocXMLRPCRequestHandler`.
266
.. versionchanged:: 3.3
267
The *use_builtin_types* flag was added.
270
.. class:: DocCGIXMLRPCRequestHandler()
272
Create a new instance to handle XML-RPC requests in a CGI environment.
275
.. class:: DocXMLRPCRequestHandler()
277
Create a new request handler instance. This request handler supports XML-RPC
278
POST requests, documentation GET requests, and modifies logging so that the
279
*logRequests* parameter to the :class:`DocXMLRPCServer` constructor parameter is
283
.. _doc-xmlrpc-servers:
285
DocXMLRPCServer Objects
286
-----------------------
288
The :class:`DocXMLRPCServer` class is derived from :class:`SimpleXMLRPCServer`
289
and provides a means of creating self-documenting, stand alone XML-RPC
290
servers. HTTP POST requests are handled as XML-RPC method calls. HTTP GET
291
requests are handled by generating pydoc-style HTML documentation. This allows a
292
server to provide its own web-based documentation.
295
.. method:: DocXMLRPCServer.set_server_title(server_title)
297
Set the title used in the generated HTML documentation. This title will be used
298
inside the HTML "title" element.
301
.. method:: DocXMLRPCServer.set_server_name(server_name)
303
Set the name used in the generated HTML documentation. This name will appear at
304
the top of the generated documentation inside a "h1" element.
307
.. method:: DocXMLRPCServer.set_server_documentation(server_documentation)
309
Set the description used in the generated HTML documentation. This description
310
will appear as a paragraph, below the server name, in the documentation.
313
DocCGIXMLRPCRequestHandler
314
--------------------------
316
The :class:`DocCGIXMLRPCRequestHandler` class is derived from
317
:class:`CGIXMLRPCRequestHandler` and provides a means of creating
318
self-documenting, XML-RPC CGI scripts. HTTP POST requests are handled as XML-RPC
319
method calls. HTTP GET requests are handled by generating pydoc-style HTML
320
documentation. This allows a server to provide its own web-based documentation.
323
.. method:: DocCGIXMLRPCRequestHandler.set_server_title(server_title)
325
Set the title used in the generated HTML documentation. This title will be used
326
inside the HTML "title" element.
329
.. method:: DocCGIXMLRPCRequestHandler.set_server_name(server_name)
331
Set the name used in the generated HTML documentation. This name will appear at
332
the top of the generated documentation inside a "h1" element.
335
.. method:: DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)
337
Set the description used in the generated HTML documentation. This description
338
will appear as a paragraph, below the server name, in the documentation.
added
removed
Doc/library/xmlrpc.server.rst
