Lib/SimpleXMLRPCServer.py

   1 """Simple XML-RPC Server.
   2
   3 This module can be used to create simple XML-RPC servers
   4 by creating a server and either installing functions, a
   5 class instance, or by extending the SimpleXMLRPCServer
   6 class.
   7
   8 It can also be used to handle XML-RPC requests in a CGI
   9 environment using CGIXMLRPCRequestHandler.
  10
  11 A list of possible usage patterns follows:
  12
  13 1. Install functions:
  14
  15 server = SimpleXMLRPCServer(("localhost", 8000))
  16 server.register_function(pow)
  17 server.register_function(lambda x,y: x+y, 'add')
  18 server.serve_forever()
  19
  20 2. Install an instance:
  21
  22 class MyFuncs:
  23     def __init__(self):
  24         # make all of the string functions available through
  25         # string.func_name
  26         import string
  27         self.string = string
  28     def _listMethods(self):
  29         # implement this method so that system.listMethods
  30         # knows to advertise the strings methods
  31         return list_public_methods(self) + \
  32                 ['string.' + method for method in list_public_methods(self.string)]
  33     def pow(self, x, y): return pow(x, y)
  34     def add(self, x, y) : return x + y
  35
  36 server = SimpleXMLRPCServer(("localhost", 8000))
  37 server.register_introspection_functions()
  38 server.register_instance(MyFuncs())
  39 server.serve_forever()
  40
  41 3. Install an instance with custom dispatch method:
  42
  43 class Math:
  44     def _listMethods(self):
  45         # this method must be present for system.listMethods
  46         # to work
  47         return ['add', 'pow']
  48     def _methodHelp(self, method):
  49         # this method must be present for system.methodHelp
  50         # to work
  51         if method == 'add':
  52             return "add(2,3) => 5"
  53         elif method == 'pow':
  54             return "pow(x, y[, z]) => number"
  55         else:
  56             # By convention, return empty
  57             # string if no help is available
  58             return ""
  59     def _dispatch(self, method, params):
  60         if method == 'pow':
  61             return pow(*params)
  62         elif method == 'add':
  63             return params[0] + params[1]
  64         else:
  65             raise 'bad method'
  66
  67 server = SimpleXMLRPCServer(("localhost", 8000))
  68 server.register_introspection_functions()
  69 server.register_instance(Math())
  70 server.serve_forever()
  71
  72 4. Subclass SimpleXMLRPCServer:
  73
  74 class MathServer(SimpleXMLRPCServer):
  75     def _dispatch(self, method, params):
  76         try:
  77             # We are forcing the 'export_' prefix on methods that are
  78             # callable through XML-RPC to prevent potential security
  79             # problems
  80             func = getattr(self, 'export_' + method)
  81         except AttributeError:
  82             raise Exception('method "%s" is not supported' % method)
  83         else:
  84             return func(*params)
  85
  86     def export_add(self, x, y):
  87         return x + y
  88
  89 server = MathServer(("localhost", 8000))
  90 server.serve_forever()
  91
  92 5. CGI script:
  93
  94 server = CGIXMLRPCRequestHandler()
  95 server.register_function(pow)
  96 server.handle_request()
  97 """
  98
  99 # Written by Brian Quinlan (brian@sweetapp.com).
 100 # Based on code written by Fredrik Lundh.
 101
 102 import xmlrpclib
 103 from xmlrpclib import Fault
 104 import SocketServer
 105 import BaseHTTPServer
 106 import sys
 107 import os
 108 try:
 109     import fcntl
 110 except ImportError:
 111     fcntl = None
 112
 113 def resolve_dotted_attribute(obj, attr, allow_dotted_names=True):
 114     """resolve_dotted_attribute(a, 'b.c.d') => a.b.c.d
 115
 116     Resolves a dotted attribute name to an object.  Raises
 117     an AttributeError if any attribute in the chain starts with a '_'.
 118
 119     If the optional allow_dotted_names argument is false, dots are not
 120     supported and this function operates similar to getattr(obj, attr).
 121     """
 122
 123     if allow_dotted_names:
 124         attrs = attr.split('.')
 125     else:
 126         attrs = [attr]
 127
 128     for i in attrs:
 129         if i.startswith('_'):
 130             raise AttributeError(
 131                 'attempt to access private attribute "%s"' % i
 132                 )
 133         else:
 134             obj = getattr(obj,i)
 135     return obj
 136
 137 def list_public_methods(obj):
 138     """Returns a list of attribute strings, found in the specified
 139     object, which represent callable attributes"""
 140
 141     return [member for member in dir(obj)
 142                 if not member.startswith('_') and
 143                     callable(getattr(obj, member))]
 144
 145 def remove_duplicates(lst):
 146     """remove_duplicates([2,2,2,1,3,3]) => [3,1,2]
 147
 148     Returns a copy of a list without duplicates. Every list
 149     item must be hashable and the order of the items in the
 150     resulting list is not defined.
 151     """
 152     u = {}
 153     for x in lst:
 154         u[x] = 1
 155
 156     return u.keys()
 157
 158 class SimpleXMLRPCDispatcher:
 159     """Mix-in class that dispatches XML-RPC requests.
 160
 161     This class is used to register XML-RPC method handlers
 162     and then to dispatch them. There should never be any
 163     reason to instantiate this class directly.
 164     """
 165
 166     def __init__(self, allow_none, encoding):
 167         self.funcs = {}
 168         self.instance = None
 169         self.allow_none = allow_none
 170         self.encoding = encoding
 171
 172     def register_instance(self, instance, allow_dotted_names=False):
 173         """Registers an instance to respond to XML-RPC requests.
 174
 175         Only one instance can be installed at a time.
 176
 177         If the registered instance has a _dispatch method then that
 178         method will be called with the name of the XML-RPC method and
 179         its parameters as a tuple
 180         e.g. instance._dispatch('add',(2,3))
 181
 182         If the registered instance does not have a _dispatch method
 183         then the instance will be searched to find a matching method
 184         and, if found, will be called. Methods beginning with an '_'
 185         are considered private and will not be called by
 186         SimpleXMLRPCServer.
 187
 188         If a registered function matches a XML-RPC request, then it
 189         will be called instead of the registered instance.
 190
 191         If the optional allow_dotted_names argument is true and the
 192         instance does not have a _dispatch method, method names
 193         containing dots are supported and resolved, as long as none of
 194         the name segments start with an '_'.
 195
 196             *** SECURITY WARNING: ***
 197
 198             Enabling the allow_dotted_names options allows intruders
 199             to access your module's global variables and may allow
 200             intruders to execute arbitrary code on your machine.  Only
 201             use this option on a secure, closed network.
 202
 203         """
 204
 205         self.instance = instance
 206         self.allow_dotted_names = allow_dotted_names
 207
 208     def register_function(self, function, name = None):
 209         """Registers a function to respond to XML-RPC requests.
 210
 211         The optional name argument can be used to set a Unicode name
 212         for the function.
 213         """
 214
 215         if name is None:
 216             name = function.__name__
 217         self.funcs[name] = function
 218
 219     def register_introspection_functions(self):
 220         """Registers the XML-RPC introspection methods in the system
 221         namespace.
 222
 223         see http://xmlrpc.usefulinc.com/doc/reserved.html
 224         """
 225
 226         self.funcs.update({'system.listMethods' : self.system_listMethods,
 227                       'system.methodSignature' : self.system_methodSignature,
 228                       'system.methodHelp' : self.system_methodHelp})
 229
 230     def register_multicall_functions(self):
 231         """Registers the XML-RPC multicall method in the system
 232         namespace.
 233
 234         see http://www.xmlrpc.com/discuss/msgReader$1208"""
 235
 236         self.funcs.update({'system.multicall' : self.system_multicall})
 237
 238     def _marshaled_dispatch(self, data, dispatch_method = None):
 239         """Dispatches an XML-RPC method from marshalled (XML) data.
 240
 241         XML-RPC methods are dispatched from the marshalled (XML) data
 242         using the _dispatch method and the result is returned as
 243         marshalled data. For backwards compatibility, a dispatch
 244         function can be provided as an argument (see comment in
 245         SimpleXMLRPCRequestHandler.do_POST) but overriding the
 246         existing method through subclassing is the prefered means
 247         of changing method dispatch behavior.
 248         """
 249
 250         try:
 251             params, method = xmlrpclib.loads(data)
 252
 253             # generate response
 254             if dispatch_method is not None:
 255                 response = dispatch_method(method, params)
 256             else:
 257                 response = self._dispatch(method, params)
 258             # wrap response in a singleton tuple
 259             response = (response,)
 260             response = xmlrpclib.dumps(response, methodresponse=1,
 261                                        allow_none=self.allow_none, encoding=self.encoding)
 262         except Fault, fault:
 263             response = xmlrpclib.dumps(fault, allow_none=self.allow_none,
 264                                        encoding=self.encoding)
 265         except:
 266             # report exception back to server
 267             response = xmlrpclib.dumps(
 268                 xmlrpclib.Fault(1, "%s:%s" % (sys.exc_type, sys.exc_value)),
 269                 encoding=self.encoding, allow_none=self.allow_none,
 270                 )
 271
 272         return response
 273
 274     def system_listMethods(self):
 275         """system.listMethods() => ['add', 'subtract', 'multiple']
 276
 277         Returns a list of the methods supported by the server."""
 278
 279         methods = self.funcs.keys()
 280         if self.instance is not None:
 281             # Instance can implement _listMethod to return a list of
 282             # methods
 283             if hasattr(self.instance, '_listMethods'):
 284                 methods = remove_duplicates(
 285                         methods + self.instance._listMethods()
 286                     )
 287             # if the instance has a _dispatch method then we
 288             # don't have enough information to provide a list
 289             # of methods
 290             elif not hasattr(self.instance, '_dispatch'):
 291                 methods = remove_duplicates(
 292                         methods + list_public_methods(self.instance)
 293                     )
 294         methods.sort()
 295         return methods
 296
 297     def system_methodSignature(self, method_name):
 298         """system.methodSignature('add') => [double, int, int]
 299
 300         Returns a list describing the signature of the method. In the
 301         above example, the add method takes two integers as arguments
 302         and returns a double result.
 303
 304         This server does NOT support system.methodSignature."""
 305
 306         # See http://xmlrpc.usefulinc.com/doc/sysmethodsig.html
 307
 308         return 'signatures not supported'
 309
 310     def system_methodHelp(self, method_name):
 311         """system.methodHelp('add') => "Adds two integers together"
 312
 313         Returns a string containing documentation for the specified method."""
 314
 315         method = None
 316         if self.funcs.has_key(method_name):
 317             method = self.funcs[method_name]
 318         elif self.instance is not None:
 319             # Instance can implement _methodHelp to return help for a method
 320             if hasattr(self.instance, '_methodHelp'):
 321                 return self.instance._methodHelp(method_name)
 322             # if the instance has a _dispatch method then we
 323             # don't have enough information to provide help
 324             elif not hasattr(self.instance, '_dispatch'):
 325                 try:
 326                     method = resolve_dotted_attribute(
 327                                 self.instance,
 328                                 method_name,
 329                                 self.allow_dotted_names
 330                                 )
 331                 except AttributeError:
 332                     pass
 333
 334         # Note that we aren't checking that the method actually
 335         # be a callable object of some kind
 336         if method is None:
 337             return ""
 338         else:
 339             import pydoc
 340             return pydoc.getdoc(method)
 341
 342     def system_multicall(self, call_list):
 343         """system.multicall([{'methodName': 'add', 'params': [2, 2]}, ...]) => \
 344 [[4], ...]
 345
 346         Allows the caller to package multiple XML-RPC calls into a single
 347         request.
 348
 349         See http://www.xmlrpc.com/discuss/msgReader$1208
 350         """
 351
 352         results = []
 353         for call in call_list:
 354             method_name = call['methodName']
 355             params = call['params']
 356
 357             try:
 358                 # XXX A marshalling error in any response will fail the entire
 359                 # multicall. If someone cares they should fix this.
 360                 results.append([self._dispatch(method_name, params)])
 361             except Fault, fault:
 362                 results.append(
 363                     {'faultCode' : fault.faultCode,
 364                      'faultString' : fault.faultString}
 365                     )
 366             except:
 367                 results.append(
 368                     {'faultCode' : 1,
 369                      'faultString' : "%s:%s" % (sys.exc_type, sys.exc_value)}
 370                     )
 371         return results
 372
 373     def _dispatch(self, method, params):
 374         """Dispatches the XML-RPC method.
 375
 376         XML-RPC calls are forwarded to a registered function that
 377         matches the called XML-RPC method name. If no such function
 378         exists then the call is forwarded to the registered instance,
 379         if available.
 380
 381         If the registered instance has a _dispatch method then that
 382         method will be called with the name of the XML-RPC method and
 383         its parameters as a tuple
 384         e.g. instance._dispatch('add',(2,3))
 385
 386         If the registered instance does not have a _dispatch method
 387         then the instance will be searched to find a matching method
 388         and, if found, will be called.
 389
 390         Methods beginning with an '_' are considered private and will
 391         not be called.
 392         """
 393
 394         func = None
 395         try:
 396             # check to see if a matching function has been registered
 397             func = self.funcs[method]
 398         except KeyError:
 399             if self.instance is not None:
 400                 # check for a _dispatch method
 401                 if hasattr(self.instance, '_dispatch'):
 402                     return self.instance._dispatch(method, params)
 403                 else:
 404                     # call instance method directly
 405                     try:
 406                         func = resolve_dotted_attribute(
 407                             self.instance,
 408                             method,
 409                             self.allow_dotted_names
 410                             )
 411                     except AttributeError:
 412                         pass
 413
 414         if func is not None:
 415             return func(*params)
 416         else:
 417             raise Exception('method "%s" is not supported' % method)
 418
 419 class SimpleXMLRPCRequestHandler(BaseHTTPServer.BaseHTTPRequestHandler):
 420     """Simple XML-RPC request handler class.
 421
 422     Handles all HTTP POST requests and attempts to decode them as
 423     XML-RPC requests.
 424     """
 425
 426     # Class attribute listing the accessible path components;
 427     # paths not on this list will result in a 404 error.
 428     rpc_paths = ('/', '/RPC2')
 429
 430     def is_rpc_path_valid(self):
 431         if self.rpc_paths:
 432             return self.path in self.rpc_paths
 433         else:
 434             # If .rpc_paths is empty, just assume all paths are legal
 435             return True
 436
 437     def do_POST(self):
 438         """Handles the HTTP POST request.
 439
 440         Attempts to interpret all HTTP POST requests as XML-RPC calls,
 441         which are forwarded to the server's _dispatch method for handling.
 442         """
 443
 444         # Check that the path is legal
 445         if not self.is_rpc_path_valid():
 446             self.report_404()
 447             return
 448
 449         try:
 450             # Get arguments by reading body of request.
 451             # We read this in chunks to avoid straining
 452             # socket.read(); around the 10 or 15Mb mark, some platforms
 453             # begin to have problems (bug #792570).
 454             max_chunk_size = 10*1024*1024
 455             size_remaining = int(self.headers["content-length"])
 456             L = []
 457             while size_remaining:
 458                 chunk_size = min(size_remaining, max_chunk_size)
 459                 L.append(self.rfile.read(chunk_size))
 460                 size_remaining -= len(L[-1])
 461             data = ''.join(L)
 462
 463             # In previous versions of SimpleXMLRPCServer, _dispatch
 464             # could be overridden in this class, instead of in
 465             # SimpleXMLRPCDispatcher. To maintain backwards compatibility,
 466             # check to see if a subclass implements _dispatch and dispatch
 467             # using that method if present.
 468             response = self.server._marshaled_dispatch(
 469                     data, getattr(self, '_dispatch', None)
 470                 )
 471         except: # This should only happen if the module is buggy
 472             # internal error, report as HTTP server error
 473             self.send_response(500)
 474             self.end_headers()
 475         else:
 476             # got a valid XML RPC response
 477             self.send_response(200)
 478             self.send_header("Content-type", "text/xml")
 479             self.send_header("Content-length", str(len(response)))
 480             self.end_headers()
 481             self.wfile.write(response)
 482
 483             # shut down the connection
 484             self.wfile.flush()
 485             self.connection.shutdown(1)
 486
 487     def report_404 (self):
 488             # Report a 404 error
 489         self.send_response(404)
 490         response = 'No such page'
 491         self.send_header("Content-type", "text/plain")
 492         self.send_header("Content-length", str(len(response)))
 493         self.end_headers()
 494         self.wfile.write(response)
 495         # shut down the connection
 496         self.wfile.flush()
 497         self.connection.shutdown(1)
 498
 499     def log_request(self, code='-', size='-'):
 500         """Selectively log an accepted request."""
 501
 502         if self.server.logRequests:
 503             BaseHTTPServer.BaseHTTPRequestHandler.log_request(self, code, size)
 504
 505 class SimpleXMLRPCServer(SocketServer.TCPServer,
 506                          SimpleXMLRPCDispatcher):
 507     """Simple XML-RPC server.
 508
 509     Simple XML-RPC server that allows functions and a single instance
 510     to be installed to handle requests. The default implementation
 511     attempts to dispatch XML-RPC calls to the functions or instance
 512     installed in the server. Override the _dispatch method inhereted
 513     from SimpleXMLRPCDispatcher to change this behavior.
 514     """
 515
 516     allow_reuse_address = True
 517
 518     def __init__(self, addr, requestHandler=SimpleXMLRPCRequestHandler,
 519                  logRequests=True, allow_none=False, encoding=None):
 520         self.logRequests = logRequests
 521
 522         SimpleXMLRPCDispatcher.__init__(self, allow_none, encoding)
 523         SocketServer.TCPServer.__init__(self, addr, requestHandler)
 524
 525         # [Bug #1222790] If possible, set close-on-exec flag; if a
 526         # method spawns a subprocess, the subprocess shouldn't have
 527         # the listening socket open.
 528         if fcntl is not None and hasattr(fcntl, 'FD_CLOEXEC'):
 529             flags = fcntl.fcntl(self.fileno(), fcntl.F_GETFD)
 530             flags |= fcntl.FD_CLOEXEC
 531             fcntl.fcntl(self.fileno(), fcntl.F_SETFD, flags)
 532
 533 class CGIXMLRPCRequestHandler(SimpleXMLRPCDispatcher):
 534     """Simple handler for XML-RPC data passed through CGI."""
 535
 536     def __init__(self, allow_none=False, encoding=None):
 537         SimpleXMLRPCDispatcher.__init__(self, allow_none, encoding)
 538
 539     def handle_xmlrpc(self, request_text):
 540         """Handle a single XML-RPC request"""
 541
 542         response = self._marshaled_dispatch(request_text)
 543
 544         print 'Content-Type: text/xml'
 545         print 'Content-Length: %d' % len(response)
 546         print
 547         sys.stdout.write(response)
 548
 549     def handle_get(self):
 550         """Handle a single HTTP GET request.
 551
 552         Default implementation indicates an error because
 553         XML-RPC uses the POST method.
 554         """
 555
 556         code = 400
 557         message, explain = \
 558                  BaseHTTPServer.BaseHTTPRequestHandler.responses[code]
 559
 560         response = BaseHTTPServer.DEFAULT_ERROR_MESSAGE % \
 561             {
 562              'code' : code,
 563              'message' : message,
 564              'explain' : explain
 565             }
 566         print 'Status: %d %s' % (code, message)
 567         print 'Content-Type: text/html'
 568         print 'Content-Length: %d' % len(response)
 569         print
 570         sys.stdout.write(response)
 571
 572     def handle_request(self, request_text = None):
 573         """Handle a single XML-RPC request passed through a CGI post method.
 574
 575         If no XML data is given then it is read from stdin. The resulting
 576         XML-RPC response is printed to stdout along with the correct HTTP
 577         headers.
 578         """
 579
 580         if request_text is None and \
 581             os.environ.get('REQUEST_METHOD', None) == 'GET':
 582             self.handle_get()
 583         else:
 584             # POST data is normally available through stdin
 585             if request_text is None:
 586                 request_text = sys.stdin.read()
 587
 588             self.handle_xmlrpc(request_text)
 589
 590 if __name__ == '__main__':
 591     print 'Running XML-RPC server on port 8000'
 592     server = SimpleXMLRPCServer(("localhost", 8000))
 593     server.register_function(pow)
 594     server.register_function(lambda x,y: x+y, 'add')
 595     server.serve_forever()