1:mod:`xmlrpc.server` --- Basic XML-RPC servers
2==============================================
3
4.. module:: xmlrpc.server
5   :synopsis: Basic XML-RPC server implementations.
6
7.. moduleauthor:: Brian Quinlan <brianq@activestate.com>
8.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
9
10**Source code:** :source:`Lib/xmlrpc/server.py`
11
12--------------
13
14The :mod:`xmlrpc.server` module provides a basic server framework for XML-RPC
15servers written in Python.  Servers can either be free standing, using
16:class:`SimpleXMLRPCServer`, or embedded in a CGI environment, using
17:class:`CGIXMLRPCRequestHandler`.
18
19
20.. warning::
21
22   The :mod:`xmlrpc.server` module is not secure against maliciously
23   constructed data.  If you need to parse untrusted or unauthenticated data see
24   :ref:`xml-vulnerabilities`.
25
26
27.. class:: SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler,\
28               logRequests=True, allow_none=False, encoding=None,\
29               bind_and_activate=True, use_builtin_types=False)
30
31   Create a new server instance.  This class provides methods for registration of
32   functions that can be called by the XML-RPC protocol.  The *requestHandler*
33   parameter should be a factory for request handler instances; it defaults to
34   :class:`SimpleXMLRPCRequestHandler`.  The *addr* and *requestHandler* parameters
35   are passed to the :class:`socketserver.TCPServer` constructor.  If *logRequests*
36   is true (the default), requests will be logged; setting this parameter to false
37   will turn off logging.   The *allow_none* and *encoding* parameters are passed
38   on to :mod:`xmlrpc.client` and control the XML-RPC responses that will be returned
39   from the server. The *bind_and_activate* parameter controls whether
40   :meth:`server_bind` and :meth:`server_activate` are called immediately by the
41   constructor; it defaults to true. Setting it to false allows code to manipulate
42   the *allow_reuse_address* class variable before the address is bound.
43   The *use_builtin_types* parameter is passed to the
44   :func:`~xmlrpc.client.loads` function and controls which types are processed
45   when date/times values or binary data are received; it defaults to false.
46
47   .. versionchanged:: 3.3
48      The *use_builtin_types* flag was added.
49
50
51.. class:: CGIXMLRPCRequestHandler(allow_none=False, encoding=None,\
52               use_builtin_types=False)
53
54   Create a new instance to handle XML-RPC requests in a CGI environment.  The
55   *allow_none* and *encoding* parameters are passed on to :mod:`xmlrpc.client`
56   and control the XML-RPC responses that will be returned from the server.
57   The *use_builtin_types* parameter is passed to the
58   :func:`~xmlrpc.client.loads` function and controls which types are processed
59   when date/times values or binary data are received; it defaults to false.
60
61   .. versionchanged:: 3.3
62      The *use_builtin_types* flag was added.
63
64
65.. class:: SimpleXMLRPCRequestHandler()
66
67   Create a new request handler instance.  This request handler supports ``POST``
68   requests and modifies logging so that the *logRequests* parameter to the
69   :class:`SimpleXMLRPCServer` constructor parameter is honored.
70
71
72.. _simple-xmlrpc-servers:
73
74SimpleXMLRPCServer Objects
75--------------------------
76
77The :class:`SimpleXMLRPCServer` class is based on
78:class:`socketserver.TCPServer` and provides a means of creating simple, stand
79alone XML-RPC servers.
80
81
82.. method:: SimpleXMLRPCServer.register_function(function, name=None)
83
84   Register a function that can respond to XML-RPC requests.  If *name* is given,
85   it will be the method name associated with *function*, otherwise
86   ``function.__name__`` will be used.  *name* can be either a normal or Unicode
87   string, and may contain characters not legal in Python identifiers, including
88   the period character.
89
90
91.. method:: SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)
92
93   Register an object which is used to expose method names which have not been
94   registered using :meth:`register_function`.  If *instance* contains a
95   :meth:`_dispatch` method, it is called with the requested method name and the
96   parameters from the request.  Its API is ``def _dispatch(self, method, params)``
97   (note that *params* does not represent a variable argument list).  If it calls
98   an underlying function to perform its task, that function is called as
99   ``func(*params)``, expanding the parameter list. The return value from
100   :meth:`_dispatch` is returned to the client as the result.  If *instance* does
101   not have a :meth:`_dispatch` method, it is searched for an attribute matching
102   the name of the requested method.
103
104   If the optional *allow_dotted_names* argument is true and the instance does not
105   have a :meth:`_dispatch` method, then if the requested method name contains
106   periods, each component of the method name is searched for individually, with
107   the effect that a simple hierarchical search is performed.  The value found from
108   this search is then called with the parameters from the request, and the return
109   value is passed back to the client.
110
111   .. warning::
112
113      Enabling the *allow_dotted_names* option allows intruders to access your
114      module's global variables and may allow intruders to execute arbitrary code on
115      your machine.  Only use this option on a secure, closed network.
116
117
118.. method:: SimpleXMLRPCServer.register_introspection_functions()
119
120   Registers the XML-RPC introspection functions ``system.listMethods``,
121   ``system.methodHelp`` and ``system.methodSignature``.
122
123
124.. method:: SimpleXMLRPCServer.register_multicall_functions()
125
126   Registers the XML-RPC multicall function system.multicall.
127
128
129.. attribute:: SimpleXMLRPCRequestHandler.rpc_paths
130
131   An attribute value that must be a tuple listing valid path portions of the URL
132   for receiving XML-RPC requests.  Requests posted to other paths will result in a
133   404 "no such page" HTTP error.  If this tuple is empty, all paths will be
134   considered valid. The default value is ``('/', '/RPC2')``.
135
136
137.. _simplexmlrpcserver-example:
138
139SimpleXMLRPCServer Example
140^^^^^^^^^^^^^^^^^^^^^^^^^^
141Server code::
142
143   from xmlrpc.server import SimpleXMLRPCServer
144   from xmlrpc.server import SimpleXMLRPCRequestHandler
145
146   # Restrict to a particular path.
147   class RequestHandler(SimpleXMLRPCRequestHandler):
148       rpc_paths = ('/RPC2',)
149
150   # Create server
151   with SimpleXMLRPCServer(("localhost", 8000),
152                           requestHandler=RequestHandler) as server:
153       server.register_introspection_functions()
154
155       # Register pow() function; this will use the value of
156       # pow.__name__ as the name, which is just 'pow'.
157       server.register_function(pow)
158
159       # Register a function under a different name
160       def adder_function(x,y):
161           return x + y
162       server.register_function(adder_function, 'add')
163
164       # Register an instance; all the methods of the instance are
165       # published as XML-RPC methods (in this case, just 'mul').
166       class MyFuncs:
167           def mul(self, x, y):
168               return x * y
169
170       server.register_instance(MyFuncs())
171
172       # Run the server's main loop
173       server.serve_forever()
174
175The following client code will call the methods made available by the preceding
176server::
177
178   import xmlrpc.client
179
180   s = xmlrpc.client.ServerProxy('http://localhost:8000')
181   print(s.pow(2,3))  # Returns 2**3 = 8
182   print(s.add(2,3))  # Returns 5
183   print(s.mul(5,2))  # Returns 5*2 = 10
184
185   # Print list of available methods
186   print(s.system.listMethods())
187
188The following example included in the :file:`Lib/xmlrpc/server.py` module shows
189a server allowing dotted names and registering a multicall function.
190
191.. warning::
192
193  Enabling the *allow_dotted_names* option allows intruders to access your
194  module's global variables and may allow intruders to execute arbitrary code on
195  your machine.  Only use this example only within a secure, closed network.
196
197::
198
199    import datetime
200
201    class ExampleService:
202        def getData(self):
203            return '42'
204
205        class currentTime:
206            @staticmethod
207            def getCurrentTime():
208                return datetime.datetime.now()
209
210    with SimpleXMLRPCServer(("localhost", 8000)) as server:
211        server.register_function(pow)
212        server.register_function(lambda x,y: x+y, 'add')
213        server.register_instance(ExampleService(), allow_dotted_names=True)
214        server.register_multicall_functions()
215        print('Serving XML-RPC on localhost port 8000')
216        try:
217            server.serve_forever()
218        except KeyboardInterrupt:
219            print("\nKeyboard interrupt received, exiting.")
220            sys.exit(0)
221
222This ExampleService demo can be invoked from the command line::
223
224    python -m xmlrpc.server
225
226
227The client that interacts with the above server is included in
228`Lib/xmlrpc/client.py`::
229
230    server = ServerProxy("http://localhost:8000")
231
232    try:
233        print(server.currentTime.getCurrentTime())
234    except Error as v:
235        print("ERROR", v)
236
237    multi = MultiCall(server)
238    multi.getData()
239    multi.pow(2,9)
240    multi.add(1,2)
241    try:
242        for response in multi():
243            print(response)
244    except Error as v:
245        print("ERROR", v)
246
247This client which interacts with the demo XMLRPC server can be invoked as::
248
249    python -m xmlrpc.client
250
251
252CGIXMLRPCRequestHandler
253-----------------------
254
255The :class:`CGIXMLRPCRequestHandler` class can be used to  handle XML-RPC
256requests sent to Python CGI scripts.
257
258
259.. method:: CGIXMLRPCRequestHandler.register_function(function, name=None)
260
261   Register a function that can respond to XML-RPC requests. If  *name* is given,
262   it will be the method name associated with  function, otherwise
263   *function.__name__* will be used. *name* can be either a normal or Unicode
264   string, and may contain  characters not legal in Python identifiers, including
265   the period character.
266
267
268.. method:: CGIXMLRPCRequestHandler.register_instance(instance)
269
270   Register an object which is used to expose method names  which have not been
271   registered using :meth:`register_function`. If  instance contains a
272   :meth:`_dispatch` method, it is called with the  requested method name and the
273   parameters from the  request; the return value is returned to the client as the
274   result. If instance does not have a :meth:`_dispatch` method, it is searched
275   for an attribute matching the name of the requested method; if  the requested
276   method name contains periods, each  component of the method name is searched for
277   individually,  with the effect that a simple hierarchical search is performed.
278   The value found from this search is then called with the  parameters from the
279   request, and the return value is passed  back to the client.
280
281
282.. method:: CGIXMLRPCRequestHandler.register_introspection_functions()
283
284   Register the XML-RPC introspection functions  ``system.listMethods``,
285   ``system.methodHelp`` and  ``system.methodSignature``.
286
287
288.. method:: CGIXMLRPCRequestHandler.register_multicall_functions()
289
290   Register the XML-RPC multicall function ``system.multicall``.
291
292
293.. method:: CGIXMLRPCRequestHandler.handle_request(request_text=None)
294
295   Handle an XML-RPC request. If *request_text* is given, it should be the POST
296   data provided by the HTTP server,  otherwise the contents of stdin will be used.
297
298Example::
299
300   class MyFuncs:
301       def mul(self, x, y):
302           return x * y
303
304
305   handler = CGIXMLRPCRequestHandler()
306   handler.register_function(pow)
307   handler.register_function(lambda x,y: x+y, 'add')
308   handler.register_introspection_functions()
309   handler.register_instance(MyFuncs())
310   handler.handle_request()
311
312
313Documenting XMLRPC server
314-------------------------
315
316These classes extend the above classes to serve HTML documentation in response
317to HTTP GET requests.  Servers can either be free standing, using
318:class:`DocXMLRPCServer`, or embedded in a CGI environment, using
319:class:`DocCGIXMLRPCRequestHandler`.
320
321
322.. class:: DocXMLRPCServer(addr, requestHandler=DocXMLRPCRequestHandler,\
323               logRequests=True, allow_none=False, encoding=None,\
324               bind_and_activate=True, use_builtin_types=True)
325
326   Create a new server instance. All parameters have the same meaning as for
327   :class:`SimpleXMLRPCServer`; *requestHandler* defaults to
328   :class:`DocXMLRPCRequestHandler`.
329
330   .. versionchanged:: 3.3
331      The *use_builtin_types* flag was added.
332
333
334.. class:: DocCGIXMLRPCRequestHandler()
335
336   Create a new instance to handle XML-RPC requests in a CGI environment.
337
338
339.. class:: DocXMLRPCRequestHandler()
340
341   Create a new request handler instance. This request handler supports XML-RPC
342   POST requests, documentation GET requests, and modifies logging so that the
343   *logRequests* parameter to the :class:`DocXMLRPCServer` constructor parameter is
344   honored.
345
346
347.. _doc-xmlrpc-servers:
348
349DocXMLRPCServer Objects
350-----------------------
351
352The :class:`DocXMLRPCServer` class is derived from :class:`SimpleXMLRPCServer`
353and provides a means of creating self-documenting, stand alone XML-RPC
354servers. HTTP POST requests are handled as XML-RPC method calls. HTTP GET
355requests are handled by generating pydoc-style HTML documentation. This allows a
356server to provide its own web-based documentation.
357
358
359.. method:: DocXMLRPCServer.set_server_title(server_title)
360
361   Set the title used in the generated HTML documentation. This title will be used
362   inside the HTML "title" element.
363
364
365.. method:: DocXMLRPCServer.set_server_name(server_name)
366
367   Set the name used in the generated HTML documentation. This name will appear at
368   the top of the generated documentation inside a "h1" element.
369
370
371.. method:: DocXMLRPCServer.set_server_documentation(server_documentation)
372
373   Set the description used in the generated HTML documentation. This description
374   will appear as a paragraph, below the server name, in the documentation.
375
376
377DocCGIXMLRPCRequestHandler
378--------------------------
379
380The :class:`DocCGIXMLRPCRequestHandler` class is derived from
381:class:`CGIXMLRPCRequestHandler` and provides a means of creating
382self-documenting, XML-RPC CGI scripts. HTTP POST requests are handled as XML-RPC
383method calls. HTTP GET requests are handled by generating pydoc-style HTML
384documentation. This allows a server to provide its own web-based documentation.
385
386
387.. method:: DocCGIXMLRPCRequestHandler.set_server_title(server_title)
388
389   Set the title used in the generated HTML documentation. This title will be used
390   inside the HTML "title" element.
391
392
393.. method:: DocCGIXMLRPCRequestHandler.set_server_name(server_name)
394
395   Set the name used in the generated HTML documentation. This name will appear at
396   the top of the generated documentation inside a "h1" element.
397
398
399.. method:: DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)
400
401   Set the description used in the generated HTML documentation. This description
402   will appear as a paragraph, below the server name, in the documentation.
403