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