Debian Codegraph @

Lib/xmlrpc/server.py

raw
1 r"""XML-RPC Servers.
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 The Doc* classes can be used to create XML-RPC servers that
12 serve pydoc-style documentation in response to HTTP
13 GET requests. This documentation is dynamically generated
14 based on the functions and methods registered with the
15 server.
16
17 A list of possible usage patterns follows:
18
19 1. Install functions:
20
21 server = SimpleXMLRPCServer(("localhost", 8000))
22 server.register_function(pow)
23 server.register_function(lambda x,y: x+y, 'add')
24 server.serve_forever()
25
26 2. Install an instance:
27
28 class MyFuncs:
29 def __init__(self):
30 # make all of the sys functions available through sys.func_name
31 import sys
32 self.sys = sys
33 def _listMethods(self):
34 # implement this method so that system.listMethods
35 # knows to advertise the sys methods
36 return list_public_methods(self) + \
37 ['sys.' + method for method in list_public_methods(self.sys)]
38 def pow(self, x, y): return pow(x, y)
39 def add(self, x, y) : return x + y
40
41 server = SimpleXMLRPCServer(("localhost", 8000))
42 server.register_introspection_functions()
43 server.register_instance(MyFuncs())
44 server.serve_forever()
45
46 3. Install an instance with custom dispatch method:
47
48 class Math:
49 def _listMethods(self):
50 # this method must be present for system.listMethods
51 # to work
52 return ['add', 'pow']
53 def _methodHelp(self, method):
54 # this method must be present for system.methodHelp
55 # to work
56 if method == 'add':
57 return "add(2,3) => 5"
58 elif method == 'pow':
59 return "pow(x, y[, z]) => number"
60 else:
61 # By convention, return empty
62 # string if no help is available
63 return ""
64 def _dispatch(self, method, params):
65 if method == 'pow':
66 return pow(*params)
67 elif method == 'add':
68 return params[0] + params[1]
69 else:
70 raise ValueError('bad method')
71
72 server = SimpleXMLRPCServer(("localhost", 8000))
73 server.register_introspection_functions()
74 server.register_instance(Math())
75 server.serve_forever()
76
77 4. Subclass SimpleXMLRPCServer:
78
79 class MathServer(SimpleXMLRPCServer):
80 def _dispatch(self, method, params):
81 try:
82 # We are forcing the 'export_' prefix on methods that are
83 # callable through XML-RPC to prevent potential security
84 # problems
85 func = getattr(self, 'export_' + method)
86 except AttributeError:
87 raise Exception('method "%s" is not supported' % method)
88 else:
89 return func(*params)
90
91 def export_add(self, x, y):
92 return x + y
93
94 server = MathServer(("localhost", 8000))
95 server.serve_forever()
96
97 5. CGI script:
98
99 server = CGIXMLRPCRequestHandler()
100 server.register_function(pow)
101 server.handle_request()
102 """
103
104 # Written by Brian Quinlan ([email protected]).
105 # Based on code written by Fredrik Lundh.
106
107 from xmlrpc.client import Fault, dumps, loads, gzip_encode, gzip_decode
108 from http.server import BaseHTTPRequestHandler
109 from functools import partial
110 from inspect import signature
111 import html
112 import http.server
113 import socketserver
114 import sys
115 import os
116 import re
117 import pydoc
118 import traceback
119 try:
120 import fcntl
121 except ImportError:
122 fcntl = None
123
124 def resolve_dotted_attribute(obj, attr, allow_dotted_names=True):
125 """resolve_dotted_attribute(a, 'b.c.d') => a.b.c.d
126
127 Resolves a dotted attribute name to an object. Raises
128 an AttributeError if any attribute in the chain starts with a '_'.
129
130 If the optional allow_dotted_names argument is false, dots are not
131 supported and this function operates similar to getattr(obj, attr).
132 """
133
134 if allow_dotted_names:
135 attrs = attr.split('.')
136 else:
137 attrs = [attr]
138
139 for i in attrs:
140 if i.startswith('_'):
141 raise AttributeError(
142 'attempt to access private attribute "%s"' % i
143 )
144 else:
145 obj = getattr(obj,i)
146 return obj
147
148 def list_public_methods(obj):
149 """Returns a list of attribute strings, found in the specified
150 object, which represent callable attributes"""
151
152 return [member for member in dir(obj)
153 if not member.startswith('_') and
154 callable(getattr(obj, member))]
155
156 class SimpleXMLRPCDispatcher:
157 """Mix-in class that dispatches XML-RPC requests.
158
159 This class is used to register XML-RPC method handlers
160 and then to dispatch them. This class doesn't need to be
161 instanced directly when used by SimpleXMLRPCServer but it
162 can be instanced when used by the MultiPathXMLRPCServer
163 """
164
165 def __init__(self, allow_none=False, encoding=None,
166 use_builtin_types=False):
167 self.funcs = {}
168 self.instance = None
169 self.allow_none = allow_none
170 self.encoding = encoding or 'utf-8'
171 self.use_builtin_types = use_builtin_types
172
173 def register_instance(self, instance, allow_dotted_names=False):
174 """Registers an instance to respond to XML-RPC requests.
175
176 Only one instance can be installed at a time.
177
178 If the registered instance has a _dispatch method then that
179 method will be called with the name of the XML-RPC method and
180 its parameters as a tuple
181 e.g. instance._dispatch('add',(2,3))
182
183 If the registered instance does not have a _dispatch method
184 then the instance will be searched to find a matching method
185 and, if found, will be called. Methods beginning with an '_'
186 are considered private and will not be called by
187 SimpleXMLRPCServer.
188
189 If a registered function matches an XML-RPC request, then it
190 will be called instead of the registered instance.
191
192 If the optional allow_dotted_names argument is true and the
193 instance does not have a _dispatch method, method names
194 containing dots are supported and resolved, as long as none of
195 the name segments start with an '_'.
196
197 *** SECURITY WARNING: ***
198
199 Enabling the allow_dotted_names options allows intruders
200 to access your module's global variables and may allow
201 intruders to execute arbitrary code on your machine. Only
202 use this option on a secure, closed network.
203
204 """
205
206 self.instance = instance
207 self.allow_dotted_names = allow_dotted_names
208
209 def register_function(self, function=None, name=None):
210 """Registers a function to respond to XML-RPC requests.
211
212 The optional name argument can be used to set a Unicode name
213 for the function.
214 """
215 # decorator factory
216 if function is None:
217 return partial(self.register_function, name=name)
218
219 if name is None:
220 name = function.__name__
221 self.funcs[name] = function
222
223 return function
224
225 def register_introspection_functions(self):
226 """Registers the XML-RPC introspection methods in the system
227 namespace.
228
229 see http://xmlrpc.usefulinc.com/doc/reserved.html
230 """
231
232 self.funcs.update({'system.listMethods' : self.system_listMethods,
233 'system.methodSignature' : self.system_methodSignature,
234 'system.methodHelp' : self.system_methodHelp})
235
236 def register_multicall_functions(self):
237 """Registers the XML-RPC multicall method in the system
238 namespace.
239
240 see http://www.xmlrpc.com/discuss/msgReader$1208"""
241
242 self.funcs['system.multicall'] = self.system_multicall
243
244 def _marshaled_dispatch(self, data, dispatch_method = None, path = None):
245 """Dispatches an XML-RPC method from marshalled (XML) data.
246
247 XML-RPC methods are dispatched from the marshalled (XML) data
248 using the _dispatch method and the result is returned as
249 marshalled data. For backwards compatibility, a dispatch
250 function can be provided as an argument (see comment in
251 SimpleXMLRPCRequestHandler.do_POST) but overriding the
252 existing method through subclassing is the preferred means
253 of changing method dispatch behavior.
254 """
255
256 try:
257 params, method = loads(data, use_builtin_types=self.use_builtin_types)
258
259 # generate response
260 if dispatch_method is not None:
261 response = dispatch_method(method, params)
262 else:
263 response = self._dispatch(method, params)
264 # wrap response in a singleton tuple
265 response = (response,)
266 response = dumps(response, methodresponse=1,
267 allow_none=self.allow_none, encoding=self.encoding)
268 except Fault as fault:
269 response = dumps(fault, allow_none=self.allow_none,
270 encoding=self.encoding)
271 except BaseException as exc:
272 response = dumps(
273 Fault(1, "%s:%s" % (type(exc), exc)),
274 encoding=self.encoding, allow_none=self.allow_none,
275 )
276
277 return response.encode(self.encoding, 'xmlcharrefreplace')
278
279 def system_listMethods(self):
280 """system.listMethods() => ['add', 'subtract', 'multiple']
281
282 Returns a list of the methods supported by the server."""
283
284 methods = set(self.funcs.keys())
285 if self.instance is not None:
286 # Instance can implement _listMethod to return a list of
287 # methods
288 if hasattr(self.instance, '_listMethods'):
289 methods |= set(self.instance._listMethods())
290 # if the instance has a _dispatch method then we
291 # don't have enough information to provide a list
292 # of methods
293 elif not hasattr(self.instance, '_dispatch'):
294 methods |= set(list_public_methods(self.instance))
295 return sorted(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 method_name in self.funcs:
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 return pydoc.getdoc(method)
340
341 def system_multicall(self, call_list):
342 """system.multicall([{'methodName': 'add', 'params': [2, 2]}, ...]) => \
343 [[4], ...]
344
345 Allows the caller to package multiple XML-RPC calls into a single
346 request.
347
348 See http://www.xmlrpc.com/discuss/msgReader$1208
349 """
350
351 results = []
352 for call in call_list:
353 method_name = call['methodName']
354 params = call['params']
355
356 try:
357 # XXX A marshalling error in any response will fail the entire
358 # multicall. If someone cares they should fix this.
359 results.append([self._dispatch(method_name, params)])
360 except Fault as fault:
361 results.append(
362 {'faultCode' : fault.faultCode,
363 'faultString' : fault.faultString}
364 )
365 except BaseException as exc:
366 results.append(
367 {'faultCode' : 1,
368 'faultString' : "%s:%s" % (type(exc), exc)}
369 )
370 return results
371
372 def _dispatch(self, method, params):
373 """Dispatches the XML-RPC method.
374
375 XML-RPC calls are forwarded to a registered function that
376 matches the called XML-RPC method name. If no such function
377 exists then the call is forwarded to the registered instance,
378 if available.
379
380 If the registered instance has a _dispatch method then that
381 method will be called with the name of the XML-RPC method and
382 its parameters as a tuple
383 e.g. instance._dispatch('add',(2,3))
384
385 If the registered instance does not have a _dispatch method
386 then the instance will be searched to find a matching method
387 and, if found, will be called.
388
389 Methods beginning with an '_' are considered private and will
390 not be called.
391 """
392
393 try:
394 # call the matching registered function
395 func = self.funcs[method]
396 except KeyError:
397 pass
398 else:
399 if func is not None:
400 return func(*params)
401 raise Exception('method "%s" is not supported' % method)
402
403 if self.instance is not None:
404 if hasattr(self.instance, '_dispatch'):
405 # call the `_dispatch` method on the instance
406 return self.instance._dispatch(method, params)
407
408 # call the instance's method directly
409 try:
410 func = resolve_dotted_attribute(
411 self.instance,
412 method,
413 self.allow_dotted_names
414 )
415 except AttributeError:
416 pass
417 else:
418 if func is not None:
419 return func(*params)
420
421 raise Exception('method "%s" is not supported' % method)
422
423 class SimpleXMLRPCRequestHandler(BaseHTTPRequestHandler):
424 """Simple XML-RPC request handler class.
425
426 Handles all HTTP POST requests and attempts to decode them as
427 XML-RPC requests.
428 """
429
430 # Class attribute listing the accessible path components;
431 # paths not on this list will result in a 404 error.
432 rpc_paths = ('/', '/RPC2', '/pydoc.css')
433
434 #if not None, encode responses larger than this, if possible
435 encode_threshold = 1400 #a common MTU
436
437 #Override form StreamRequestHandler: full buffering of output
438 #and no Nagle.
439 wbufsize = -1
440 disable_nagle_algorithm = True
441
442 # a re to match a gzip Accept-Encoding
443 aepattern = re.compile(r"""
444 \s* ([^\s;]+) \s* #content-coding
445 (;\s* q \s*=\s* ([0-9\.]+))? #q
446 """, re.VERBOSE | re.IGNORECASE)
447
448 def accept_encodings(self):
449 r = {}
450 ae = self.headers.get("Accept-Encoding", "")
451 for e in ae.split(","):
452 match = self.aepattern.match(e)
453 if match:
454 v = match.group(3)
455 v = float(v) if v else 1.0
456 r[match.group(1)] = v
457 return r
458
459 def is_rpc_path_valid(self):
460 if self.rpc_paths:
461 return self.path in self.rpc_paths
462 else:
463 # If .rpc_paths is empty, just assume all paths are legal
464 return True
465
466 def do_POST(self):
467 """Handles the HTTP POST request.
468
469 Attempts to interpret all HTTP POST requests as XML-RPC calls,
470 which are forwarded to the server's _dispatch method for handling.
471 """
472
473 # Check that the path is legal
474 if not self.is_rpc_path_valid():
475 self.report_404()
476 return
477
478 try:
479 # Get arguments by reading body of request.
480 # We read this in chunks to avoid straining
481 # socket.read(); around the 10 or 15Mb mark, some platforms
482 # begin to have problems (bug #792570).
483 max_chunk_size = 10*1024*1024
484 size_remaining = int(self.headers["content-length"])
485 L = []
486 while size_remaining:
487 chunk_size = min(size_remaining, max_chunk_size)
488 chunk = self.rfile.read(chunk_size)
489 if not chunk:
490 break
491 L.append(chunk)
492 size_remaining -= len(L[-1])
493 data = b''.join(L)
494
495 data = self.decode_request_content(data)
496 if data is None:
497 return #response has been sent
498
499 # In previous versions of SimpleXMLRPCServer, _dispatch
500 # could be overridden in this class, instead of in
501 # SimpleXMLRPCDispatcher. To maintain backwards compatibility,
502 # check to see if a subclass implements _dispatch and dispatch
503 # using that method if present.
504 response = self.server._marshaled_dispatch(
505 data, getattr(self, '_dispatch', None), self.path
506 )
507 except Exception as e: # This should only happen if the module is buggy
508 # internal error, report as HTTP server error
509 self.send_response(500)
510
511 # Send information about the exception if requested
512 if hasattr(self.server, '_send_traceback_header') and \
513 self.server._send_traceback_header:
514 self.send_header("X-exception", str(e))
515 trace = traceback.format_exc()
516 trace = str(trace.encode('ASCII', 'backslashreplace'), 'ASCII')
517 self.send_header("X-traceback", trace)
518
519 self.send_header("Content-length", "0")
520 self.end_headers()
521 else:
522 self.send_response(200)
523 self.send_header("Content-type", "text/xml")
524 if self.encode_threshold is not None:
525 if len(response) > self.encode_threshold:
526 q = self.accept_encodings().get("gzip", 0)
527 if q:
528 try:
529 response = gzip_encode(response)
530 self.send_header("Content-Encoding", "gzip")
531 except NotImplementedError:
532 pass
533 self.send_header("Content-length", str(len(response)))
534 self.end_headers()
535 self.wfile.write(response)
536
537 def decode_request_content(self, data):
538 #support gzip encoding of request
539 encoding = self.headers.get("content-encoding", "identity").lower()
540 if encoding == "identity":
541 return data
542 if encoding == "gzip":
543 try:
544 return gzip_decode(data)
545 except NotImplementedError:
546 self.send_response(501, "encoding %r not supported" % encoding)
547 except ValueError:
548 self.send_response(400, "error decoding gzip content")
549 else:
550 self.send_response(501, "encoding %r not supported" % encoding)
551 self.send_header("Content-length", "0")
552 self.end_headers()
553
554 def report_404 (self):
555 # Report a 404 error
556 self.send_response(404)
557 response = b'No such page'
558 self.send_header("Content-type", "text/plain")
559 self.send_header("Content-length", str(len(response)))
560 self.end_headers()
561 self.wfile.write(response)
562
563 def log_request(self, code='-', size='-'):
564 """Selectively log an accepted request."""
565
566 if self.server.logRequests:
567 BaseHTTPRequestHandler.log_request(self, code, size)
568
569 class SimpleXMLRPCServer(socketserver.TCPServer,
570 SimpleXMLRPCDispatcher):
571 """Simple XML-RPC server.
572
573 Simple XML-RPC server that allows functions and a single instance
574 to be installed to handle requests. The default implementation
575 attempts to dispatch XML-RPC calls to the functions or instance
576 installed in the server. Override the _dispatch method inherited
577 from SimpleXMLRPCDispatcher to change this behavior.
578 """
579
580 allow_reuse_address = True
581 allow_reuse_port = False
582
583 # Warning: this is for debugging purposes only! Never set this to True in
584 # production code, as will be sending out sensitive information (exception
585 # and stack trace details) when exceptions are raised inside
586 # SimpleXMLRPCRequestHandler.do_POST
587 _send_traceback_header = False
588
589 def __init__(self, addr, requestHandler=SimpleXMLRPCRequestHandler,
590 logRequests=True, allow_none=False, encoding=None,
591 bind_and_activate=True, use_builtin_types=False):
592 self.logRequests = logRequests
593
594 SimpleXMLRPCDispatcher.__init__(self, allow_none, encoding, use_builtin_types)
595 socketserver.TCPServer.__init__(self, addr, requestHandler, bind_and_activate)
596
597
598 class MultiPathXMLRPCServer(SimpleXMLRPCServer):
599 """Multipath XML-RPC Server
600 This specialization of SimpleXMLRPCServer allows the user to create
601 multiple Dispatcher instances and assign them to different
602 HTTP request paths. This makes it possible to run two or more
603 'virtual XML-RPC servers' at the same port.
604 Make sure that the requestHandler accepts the paths in question.
605 """
606 def __init__(self, addr, requestHandler=SimpleXMLRPCRequestHandler,
607 logRequests=True, allow_none=False, encoding=None,
608 bind_and_activate=True, use_builtin_types=False):
609
610 SimpleXMLRPCServer.__init__(self, addr, requestHandler, logRequests, allow_none,
611 encoding, bind_and_activate, use_builtin_types)
612 self.dispatchers = {}
613 self.allow_none = allow_none
614 self.encoding = encoding or 'utf-8'
615
616 def add_dispatcher(self, path, dispatcher):
617 self.dispatchers[path] = dispatcher
618 return dispatcher
619
620 def get_dispatcher(self, path):
621 return self.dispatchers[path]
622
623 def _marshaled_dispatch(self, data, dispatch_method = None, path = None):
624 try:
625 response = self.dispatchers[path]._marshaled_dispatch(
626 data, dispatch_method, path)
627 except BaseException as exc:
628 # report low level exception back to server
629 # (each dispatcher should have handled their own
630 # exceptions)
631 response = dumps(
632 Fault(1, "%s:%s" % (type(exc), exc)),
633 encoding=self.encoding, allow_none=self.allow_none)
634 response = response.encode(self.encoding, 'xmlcharrefreplace')
635 return response
636
637 class CGIXMLRPCRequestHandler(SimpleXMLRPCDispatcher):
638 """Simple handler for XML-RPC data passed through CGI."""
639
640 def __init__(self, allow_none=False, encoding=None, use_builtin_types=False):
641 SimpleXMLRPCDispatcher.__init__(self, allow_none, encoding, use_builtin_types)
642
643 def handle_xmlrpc(self, request_text):
644 """Handle a single XML-RPC request"""
645
646 response = self._marshaled_dispatch(request_text)
647
648 print('Content-Type: text/xml')
649 print('Content-Length: %d' % len(response))
650 print()
651 sys.stdout.flush()
652 sys.stdout.buffer.write(response)
653 sys.stdout.buffer.flush()
654
655 def handle_get(self):
656 """Handle a single HTTP GET request.
657
658 Default implementation indicates an error because
659 XML-RPC uses the POST method.
660 """
661
662 code = 400
663 message, explain = BaseHTTPRequestHandler.responses[code]
664
665 response = http.server.DEFAULT_ERROR_MESSAGE % \
666 {
667 'code' : code,
668 'message' : message,
669 'explain' : explain
670 }
671 response = response.encode('utf-8')
672 print('Status: %d %s' % (code, message))
673 print('Content-Type: %s' % http.server.DEFAULT_ERROR_CONTENT_TYPE)
674 print('Content-Length: %d' % len(response))
675 print()
676 sys.stdout.flush()
677 sys.stdout.buffer.write(response)
678 sys.stdout.buffer.flush()
679
680 def handle_request(self, request_text=None):
681 """Handle a single XML-RPC request passed through a CGI post method.
682
683 If no XML data is given then it is read from stdin. The resulting
684 XML-RPC response is printed to stdout along with the correct HTTP
685 headers.
686 """
687
688 if request_text is None and \
689 os.environ.get('REQUEST_METHOD', None) == 'GET':
690 self.handle_get()
691 else:
692 # POST data is normally available through stdin
693 try:
694 length = int(os.environ.get('CONTENT_LENGTH', None))
695 except (ValueError, TypeError):
696 length = -1
697 if request_text is None:
698 request_text = sys.stdin.read(length)
699
700 self.handle_xmlrpc(request_text)
701
702
703 # -----------------------------------------------------------------------------
704 # Self documenting XML-RPC Server.
705
706 class ServerHTMLDoc(pydoc.HTMLDoc):
707 """Class used to generate pydoc HTML document for a server"""
708
709 def markup(self, text, escape=None, funcs={}, classes={}, methods={}):
710 """Mark up some plain text, given a context of symbols to look for.
711 Each context dictionary maps object names to anchor names."""
712 escape = escape or self.escape
713 results = []
714 here = 0
715
716 # XXX Note that this regular expression does not allow for the
717 # hyperlinking of arbitrary strings being used as method
718 # names. Only methods with names consisting of word characters
719 # and '.'s are hyperlinked.
720 pattern = re.compile(r'\b((http|https|ftp)://\S+[\w/]|'
721 r'RFC[- ]?(\d+)|'
722 r'PEP[- ]?(\d+)|'
723 r'(self\.)?((?:\w|\.)+))\b')
724 while match := pattern.search(text, here):
725 start, end = match.span()
726 results.append(escape(text[here:start]))
727
728 all, scheme, rfc, pep, selfdot, name = match.groups()
729 if scheme:
730 url = escape(all).replace('"', '"')
731 results.append('<a href="%s">%s</a>' % (url, url))
732 elif rfc:
733 url = 'https://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc)
734 results.append('<a href="%s">%s</a>' % (url, escape(all)))
735 elif pep:
736 url = 'https://peps.python.org/pep-%04d/' % int(pep)
737 results.append('<a href="%s">%s</a>' % (url, escape(all)))
738 elif text[end:end+1] == '(':
739 results.append(self.namelink(name, methods, funcs, classes))
740 elif selfdot:
741 results.append('self.<strong>%s</strong>' % name)
742 else:
743 results.append(self.namelink(name, classes))
744 here = end
745 results.append(escape(text[here:]))
746 return ''.join(results)
747
748 def docroutine(self, object, name, mod=None,
749 funcs={}, classes={}, methods={}, cl=None):
750 """Produce HTML documentation for a function or method object."""
751
752 anchor = (cl and cl.__name__ or '') + '-' + name
753 note = ''
754
755 title = '<a name="%s"><strong>%s</strong></a>' % (
756 self.escape(anchor), self.escape(name))
757
758 if callable(object):
759 argspec = str(signature(object))
760 else:
761 argspec = '(...)'
762
763 if isinstance(object, tuple):
764 argspec = object[0] or argspec
765 docstring = object[1] or ""
766 else:
767 docstring = pydoc.getdoc(object)
768
769 decl = title + argspec + (note and self.grey(
770 '<font face="helvetica, arial">%s</font>' % note))
771
772 doc = self.markup(
773 docstring, self.preformat, funcs, classes, methods)
774 doc = doc and '<dd><tt>%s</tt></dd>' % doc
775 return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)
776
777 def docserver(self, server_name, package_documentation, methods):
778 """Produce HTML documentation for an XML-RPC server."""
779
780 fdict = {}
781 for key, value in methods.items():
782 fdict[key] = '#-' + key
783 fdict[value] = fdict[key]
784
785 server_name = self.escape(server_name)
786 head = '<big><big><strong>%s</strong></big></big>' % server_name
787 result = self.heading(head)
788
789 doc = self.markup(package_documentation, self.preformat, fdict)
790 doc = doc and '<tt>%s</tt>' % doc
791 result = result + '<p>%s</p>\n' % doc
792
793 contents = []
794 method_items = sorted(methods.items())
795 for key, value in method_items:
796 contents.append(self.docroutine(value, key, funcs=fdict))
797 result = result + self.bigsection(
798 'Methods', 'functions', ''.join(contents))
799
800 return result
801
802
803 def page(self, title, contents):
804 """Format an HTML page."""
805 css_path = "/pydoc.css"
806 css_link = (
807 '<link rel="stylesheet" type="text/css" href="%s">' %
808 css_path)
809 return '''\
810 <!DOCTYPE>
811 <html lang="en">
812 <head>
813 <meta charset="utf-8">
814 <title>Python: %s</title>
815 %s</head><body>%s</body></html>''' % (title, css_link, contents)
816
817 class XMLRPCDocGenerator:
818 """Generates documentation for an XML-RPC server.
819
820 This class is designed as mix-in and should not
821 be constructed directly.
822 """
823
824 def __init__(self):
825 # setup variables used for HTML documentation
826 self.server_name = 'XML-RPC Server Documentation'
827 self.server_documentation = \
828 "This server exports the following methods through the XML-RPC "\
829 "protocol."
830 self.server_title = 'XML-RPC Server Documentation'
831
832 def set_server_title(self, server_title):
833 """Set the HTML title of the generated server documentation"""
834
835 self.server_title = server_title
836
837 def set_server_name(self, server_name):
838 """Set the name of the generated HTML server documentation"""
839
840 self.server_name = server_name
841
842 def set_server_documentation(self, server_documentation):
843 """Set the documentation string for the entire server."""
844
845 self.server_documentation = server_documentation
846
847 def generate_html_documentation(self):
848 """generate_html_documentation() => html documentation for the server
849
850 Generates HTML documentation for the server using introspection for
851 installed functions and instances that do not implement the
852 _dispatch method. Alternatively, instances can choose to implement
853 the _get_method_argstring(method_name) method to provide the
854 argument string used in the documentation and the
855 _methodHelp(method_name) method to provide the help text used
856 in the documentation."""
857
858 methods = {}
859
860 for method_name in self.system_listMethods():
861 if method_name in self.funcs:
862 method = self.funcs[method_name]
863 elif self.instance is not None:
864 method_info = [None, None] # argspec, documentation
865 if hasattr(self.instance, '_get_method_argstring'):
866 method_info[0] = self.instance._get_method_argstring(method_name)
867 if hasattr(self.instance, '_methodHelp'):
868 method_info[1] = self.instance._methodHelp(method_name)
869
870 method_info = tuple(method_info)
871 if method_info != (None, None):
872 method = method_info
873 elif not hasattr(self.instance, '_dispatch'):
874 try:
875 method = resolve_dotted_attribute(
876 self.instance,
877 method_name
878 )
879 except AttributeError:
880 method = method_info
881 else:
882 method = method_info
883 else:
884 assert 0, "Could not find method in self.functions and no "\
885 "instance installed"
886
887 methods[method_name] = method
888
889 documenter = ServerHTMLDoc()
890 documentation = documenter.docserver(
891 self.server_name,
892 self.server_documentation,
893 methods
894 )
895
896 return documenter.page(html.escape(self.server_title), documentation)
897
898 class DocXMLRPCRequestHandler(SimpleXMLRPCRequestHandler):
899 """XML-RPC and documentation request handler class.
900
901 Handles all HTTP POST requests and attempts to decode them as
902 XML-RPC requests.
903
904 Handles all HTTP GET requests and interprets them as requests
905 for documentation.
906 """
907
908 def _get_css(self, url):
909 path_here = os.path.dirname(os.path.realpath(__file__))
910 css_path = os.path.join(path_here, "..", "pydoc_data", "_pydoc.css")
911 with open(css_path, mode="rb") as fp:
912 return fp.read()
913
914 def do_GET(self):
915 """Handles the HTTP GET request.
916
917 Interpret all HTTP GET requests as requests for server
918 documentation.
919 """
920 # Check that the path is legal
921 if not self.is_rpc_path_valid():
922 self.report_404()
923 return
924
925 if self.path.endswith('.css'):
926 content_type = 'text/css'
927 response = self._get_css(self.path)
928 else:
929 content_type = 'text/html'
930 response = self.server.generate_html_documentation().encode('utf-8')
931
932 self.send_response(200)
933 self.send_header('Content-Type', '%s; charset=UTF-8' % content_type)
934 self.send_header("Content-length", str(len(response)))
935 self.end_headers()
936 self.wfile.write(response)
937
938 class DocXMLRPCServer( SimpleXMLRPCServer,
939 XMLRPCDocGenerator):
940 """XML-RPC and HTML documentation server.
941
942 Adds the ability to serve server documentation to the capabilities
943 of SimpleXMLRPCServer.
944 """
945
946 def __init__(self, addr, requestHandler=DocXMLRPCRequestHandler,
947 logRequests=True, allow_none=False, encoding=None,
948 bind_and_activate=True, use_builtin_types=False):
949 SimpleXMLRPCServer.__init__(self, addr, requestHandler, logRequests,
950 allow_none, encoding, bind_and_activate,
951 use_builtin_types)
952 XMLRPCDocGenerator.__init__(self)
953
954 class DocCGIXMLRPCRequestHandler( CGIXMLRPCRequestHandler,
955 XMLRPCDocGenerator):
956 """Handler for XML-RPC data and documentation requests passed through
957 CGI"""
958
959 def handle_get(self):
960 """Handles the HTTP GET request.
961
962 Interpret all HTTP GET requests as requests for server
963 documentation.
964 """
965
966 response = self.generate_html_documentation().encode('utf-8')
967
968 print('Content-Type: text/html')
969 print('Content-Length: %d' % len(response))
970 print()
971 sys.stdout.flush()
972 sys.stdout.buffer.write(response)
973 sys.stdout.buffer.flush()
974
975 def __init__(self):
976 CGIXMLRPCRequestHandler.__init__(self)
977 XMLRPCDocGenerator.__init__(self)
978
979
980 if __name__ == '__main__':
981 import datetime
982
983 class ExampleService:
984 def getData(self):
985 return '42'
986
987 class currentTime:
988 @staticmethod
989 def getCurrentTime():
990 return datetime.datetime.now()
991
992 with SimpleXMLRPCServer(("localhost", 8000)) as server:
993 server.register_function(pow)
994 server.register_function(lambda x,y: x+y, 'add')
995 server.register_instance(ExampleService(), allow_dotted_names=True)
996 server.register_multicall_functions()
997 print('Serving XML-RPC on localhost port 8000')
998 print('It is advisable to run this example server within a secure, closed network.')
999 try:
1000 server.serve_forever()
1001 except KeyboardInterrupt:
1002 print("\nKeyboard interrupt received, exiting.")
1003 sys.exit(0)