Lib/DocXMLRPCServer.py

   1 """Self documenting XML-RPC Server.
   2
   3 This module can be used to create XML-RPC servers that
   4 serve pydoc-style documentation in response to HTTP
   5 GET requests. This documentation is dynamically generated
   6 based on the functions and methods registered with the
   7 server.
   8
   9 This module is built upon the pydoc and SimpleXMLRPCServer
  10 modules.
  11 """
  12
  13 import pydoc
  14 import inspect
  15 import re
  16 import sys
  17
  18 from SimpleXMLRPCServer import (SimpleXMLRPCServer,
  19             SimpleXMLRPCRequestHandler,
  20             CGIXMLRPCRequestHandler,
  21             resolve_dotted_attribute)
  22
  23 class ServerHTMLDoc(pydoc.HTMLDoc):
  24     """Class used to generate pydoc HTML document for a server"""
  25
  26     def markup(self, text, escape=None, funcs={}, classes={}, methods={}):
  27         """Mark up some plain text, given a context of symbols to look for.
  28         Each context dictionary maps object names to anchor names."""
  29         escape = escape or self.escape
  30         results = []
  31         here = 0
  32
  33         # XXX Note that this regular expression does not allow for the
  34         # hyperlinking of arbitrary strings being used as method
  35         # names. Only methods with names consisting of word characters
  36         # and '.'s are hyperlinked.
  37         pattern = re.compile(r'\b((http|ftp)://\S+[\w/]|'
  38                                 r'RFC[- ]?(\d+)|'
  39                                 r'PEP[- ]?(\d+)|'
  40                                 r'(self\.)?((?:\w|\.)+))\b')
  41         while 1:
  42             match = pattern.search(text, here)
  43             if not match: break
  44             start, end = match.span()
  45             results.append(escape(text[here:start]))
  46
  47             all, scheme, rfc, pep, selfdot, name = match.groups()
  48             if scheme:
  49                 url = escape(all).replace('"', '&quot;')
  50                 results.append('<a href="%s">%s</a>' % (url, url))
  51             elif rfc:
  52                 url = 'http://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc)
  53                 results.append('<a href="%s">%s</a>' % (url, escape(all)))
  54             elif pep:
  55                 url = 'http://www.python.org/dev/peps/pep-%04d/' % int(pep)
  56                 results.append('<a href="%s">%s</a>' % (url, escape(all)))
  57             elif text[end:end+1] == '(':
  58                 results.append(self.namelink(name, methods, funcs, classes))
  59             elif selfdot:
  60                 results.append('self.<strong>%s</strong>' % name)
  61             else:
  62                 results.append(self.namelink(name, classes))
  63             here = end
  64         results.append(escape(text[here:]))
  65         return ''.join(results)
  66
  67     def docroutine(self, object, name, mod=None,
  68                    funcs={}, classes={}, methods={}, cl=None):
  69         """Produce HTML documentation for a function or method object."""
  70
  71         anchor = (cl and cl.__name__ or '') + '-' + name
  72         note = ''
  73
  74         title = '<a name="%s"><strong>%s</strong></a>' % (
  75             self.escape(anchor), self.escape(name))
  76
  77         if inspect.ismethod(object):
  78             args, varargs, varkw, defaults = inspect.getargspec(object.im_func)
  79             # exclude the argument bound to the instance, it will be
  80             # confusing to the non-Python user
  81             argspec = inspect.formatargspec (
  82                     args[1:],
  83                     varargs,
  84                     varkw,
  85                     defaults,
  86                     formatvalue=self.formatvalue
  87                 )
  88         elif inspect.isfunction(object):
  89             args, varargs, varkw, defaults = inspect.getargspec(object)
  90             argspec = inspect.formatargspec(
  91                 args, varargs, varkw, defaults, formatvalue=self.formatvalue)
  92         else:
  93             argspec = '(...)'
  94
  95         if isinstance(object, tuple):
  96             argspec = object[0] or argspec
  97             docstring = object[1] or ""
  98         else:
  99             docstring = pydoc.getdoc(object)
 100
 101         decl = title + argspec + (note and self.grey(
 102                '<font face="helvetica, arial">%s</font>' % note))
 103
 104         doc = self.markup(
 105             docstring, self.preformat, funcs, classes, methods)
 106         doc = doc and '<dd><tt>%s</tt></dd>' % doc
 107         return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)
 108
 109     def docserver(self, server_name, package_documentation, methods):
 110         """Produce HTML documentation for an XML-RPC server."""
 111
 112         fdict = {}
 113         for key, value in methods.items():
 114             fdict[key] = '#-' + key
 115             fdict[value] = fdict[key]
 116
 117         server_name = self.escape(server_name)
 118         head = '<big><big><strong>%s</strong></big></big>' % server_name
 119         result = self.heading(head, '#ffffff', '#7799ee')
 120
 121         doc = self.markup(package_documentation, self.preformat, fdict)
 122         doc = doc and '<tt>%s</tt>' % doc
 123         result = result + '<p>%s</p>\n' % doc
 124
 125         contents = []
 126         method_items = sorted(methods.items())
 127         for key, value in method_items:
 128             contents.append(self.docroutine(value, key, funcs=fdict))
 129         result = result + self.bigsection(
 130             'Methods', '#ffffff', '#eeaa77', pydoc.join(contents))
 131
 132         return result
 133
 134 class XMLRPCDocGenerator:
 135     """Generates documentation for an XML-RPC server.
 136
 137     This class is designed as mix-in and should not
 138     be constructed directly.
 139     """
 140
 141     def __init__(self):
 142         # setup variables used for HTML documentation
 143         self.server_name = 'XML-RPC Server Documentation'
 144         self.server_documentation = \
 145             "This server exports the following methods through the XML-RPC "\
 146             "protocol."
 147         self.server_title = 'XML-RPC Server Documentation'
 148
 149     def set_server_title(self, server_title):
 150         """Set the HTML title of the generated server documentation"""
 151
 152         self.server_title = server_title
 153
 154     def set_server_name(self, server_name):
 155         """Set the name of the generated HTML server documentation"""
 156
 157         self.server_name = server_name
 158
 159     def set_server_documentation(self, server_documentation):
 160         """Set the documentation string for the entire server."""
 161
 162         self.server_documentation = server_documentation
 163
 164     def generate_html_documentation(self):
 165         """generate_html_documentation() => html documentation for the server
 166
 167         Generates HTML documentation for the server using introspection for
 168         installed functions and instances that do not implement the
 169         _dispatch method. Alternatively, instances can choose to implement
 170         the _get_method_argstring(method_name) method to provide the
 171         argument string used in the documentation and the
 172         _methodHelp(method_name) method to provide the help text used
 173         in the documentation."""
 174
 175         methods = {}
 176
 177         for method_name in self.system_listMethods():
 178             if method_name in self.funcs:
 179                 method = self.funcs[method_name]
 180             elif self.instance is not None:
 181                 method_info = [None, None] # argspec, documentation
 182                 if hasattr(self.instance, '_get_method_argstring'):
 183                     method_info[0] = self.instance._get_method_argstring(method_name)
 184                 if hasattr(self.instance, '_methodHelp'):
 185                     method_info[1] = self.instance._methodHelp(method_name)
 186
 187                 method_info = tuple(method_info)
 188                 if method_info != (None, None):
 189                     method = method_info
 190                 elif not hasattr(self.instance, '_dispatch'):
 191                     try:
 192                         method = resolve_dotted_attribute(
 193                                     self.instance,
 194                                     method_name
 195                                     )
 196                     except AttributeError:
 197                         method = method_info
 198                 else:
 199                     method = method_info
 200             else:
 201                 assert 0, "Could not find method in self.functions and no "\
 202                           "instance installed"
 203
 204             methods[method_name] = method
 205
 206         documenter = ServerHTMLDoc()
 207         documentation = documenter.docserver(
 208                                 self.server_name,
 209                                 self.server_documentation,
 210                                 methods
 211                             )
 212
 213         return documenter.page(self.server_title, documentation)
 214
 215 class DocXMLRPCRequestHandler(SimpleXMLRPCRequestHandler):
 216     """XML-RPC and documentation request handler class.
 217
 218     Handles all HTTP POST requests and attempts to decode them as
 219     XML-RPC requests.
 220
 221     Handles all HTTP GET requests and interprets them as requests
 222     for documentation.
 223     """
 224
 225     def do_GET(self):
 226         """Handles the HTTP GET request.
 227
 228         Interpret all HTTP GET requests as requests for server
 229         documentation.
 230         """
 231         # Check that the path is legal
 232         if not self.is_rpc_path_valid():
 233             self.report_404()
 234             return
 235
 236         response = self.server.generate_html_documentation()
 237         self.send_response(200)
 238         self.send_header("Content-type", "text/html")
 239         self.send_header("Content-length", str(len(response)))
 240         self.end_headers()
 241         self.wfile.write(response)
 242
 243         # shut down the connection
 244         self.wfile.flush()
 245         self.connection.shutdown(1)
 246
 247 class DocXMLRPCServer(  SimpleXMLRPCServer,
 248                         XMLRPCDocGenerator):
 249     """XML-RPC and HTML documentation server.
 250
 251     Adds the ability to serve server documentation to the capabilities
 252     of SimpleXMLRPCServer.
 253     """
 254
 255     def __init__(self, addr, requestHandler=DocXMLRPCRequestHandler,
 256                  logRequests=1, allow_none=False, encoding=None,
 257                  bind_and_activate=True):
 258         SimpleXMLRPCServer.__init__(self, addr, requestHandler, logRequests,
 259                                     allow_none, encoding, bind_and_activate)
 260         XMLRPCDocGenerator.__init__(self)
 261
 262 class DocCGIXMLRPCRequestHandler(   CGIXMLRPCRequestHandler,
 263                                     XMLRPCDocGenerator):
 264     """Handler for XML-RPC data and documentation requests passed through
 265     CGI"""
 266
 267     def handle_get(self):
 268         """Handles the HTTP GET request.
 269
 270         Interpret all HTTP GET requests as requests for server
 271         documentation.
 272         """
 273
 274         response = self.generate_html_documentation()
 275
 276         print 'Content-Type: text/html'
 277         print 'Content-Length: %d' % len(response)
 278         print
 279         sys.stdout.write(response)
 280
 281     def __init__(self):
 282         CGIXMLRPCRequestHandler.__init__(self)
 283         XMLRPCDocGenerator.__init__(self)