source: trunk/essentials/dev-lang/python/Lib/SimpleXMLRPCServer.py@ 3314

Last change on this file since 3314 was 3225, checked in by bird, 19 years ago

Python 2.5
File size: 20.4 KB
Line 
1"""Simple XML-RPC Server.
2
3This module can be used to create simple XML-RPC servers
4by creating a server and either installing functions, a
5class instance, or by extending the SimpleXMLRPCServer
6class.
7
8It can also be used to handle XML-RPC requests in a CGI
9environment using CGIXMLRPCRequestHandler.
10
11A list of possible usage patterns follows:
12
131. Install functions:
14
15server = SimpleXMLRPCServer(("localhost", 8000))
16server.register_function(pow)
17server.register_function(lambda x,y: x+y, 'add')
18server.serve_forever()
19
202. Install an instance:
21
22class 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
36server = SimpleXMLRPCServer(("localhost", 8000))
37server.register_introspection_functions()
38server.register_instance(MyFuncs())
39server.serve_forever()
40
413. Install an instance with custom dispatch method:
42
43class 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
67server = SimpleXMLRPCServer(("localhost", 8000))
68server.register_introspection_functions()
69server.register_instance(Math())
70server.serve_forever()
71
724. Subclass SimpleXMLRPCServer:
73
74class 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
89server = MathServer(("localhost", 8000))
90server.serve_forever()
91
925. CGI script:
93
94server = CGIXMLRPCRequestHandler()
95server.register_function(pow)
96server.handle_request()
97"""
98
99# Written by Brian Quinlan ([email protected]).
100# Based on code written by Fredrik Lundh.
101
102import xmlrpclib
103from xmlrpclib import Fault
104import SocketServer
105import BaseHTTPServer
106import sys
107import os
108try:
109 import fcntl
110except ImportError:
111 fcntl = None
112
113def 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
137def 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
145def 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
158class 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
419class 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
505class 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
533class 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
590if __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()
Note: See TracBrowser for help on using the repository browser.