You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
280 lines
10 KiB
280 lines
10 KiB
4 months ago
|
"""Self documenting XML-RPC Server.
|
||
|
|
|
||
|
|
This module can be used to create XML-RPC servers that
|
||
|
|
serve pydoc-style documentation in response to HTTP
|
||
|
|
GET requests. This documentation is dynamically generated
|
||
|
|
based on the functions and methods registered with the
|
||
|
|
server.
|
||
|
|
|
||
|
|
This module is built upon the pydoc and SimpleXMLRPCServer
|
||
|
|
modules.
|
||
|
|
"""
|
||
|
|
|
||
|
|
import pydoc
|
||
|
|
import inspect
|
||
|
|
import re
|
||
|
|
import sys
|
||
|
|
|
||
|
|
from SimpleXMLRPCServer import (SimpleXMLRPCServer,
|
||
|
|
SimpleXMLRPCRequestHandler,
|
||
|
|
CGIXMLRPCRequestHandler,
|
||
|
|
resolve_dotted_attribute)
|
||
|
|
|
||
|
|
class ServerHTMLDoc(pydoc.HTMLDoc):
|
||
|
|
"""Class used to generate pydoc HTML document for a server"""
|
||
|
|
|
||
|
|
def markup(self, text, escape=None, funcs={}, classes={}, methods={}):
|
||
|
|
"""Mark up some plain text, given a context of symbols to look for.
|
||
|
|
Each context dictionary maps object names to anchor names."""
|
||
|
|
escape = escape or self.escape
|
||
|
|
results = []
|
||
|
|
here = 0
|
||
|
|
|
||
|
|
# XXX Note that this regular expression does not allow for the
|
||
|
|
# hyperlinking of arbitrary strings being used as method
|
||
|
|
# names. Only methods with names consisting of word characters
|
||
|
|
# and '.'s are hyperlinked.
|
||
|
|
pattern = re.compile(r'\b((http|ftp)://\S+[\w/]|'
|
||
|
|
r'RFC[- ]?(\d+)|'
|
||
|
|
r'PEP[- ]?(\d+)|'
|
||
|
|
r'(self\.)?((?:\w|\.)+))\b')
|
||
|
|
while 1:
|
||
|
|
match = pattern.search(text, here)
|
||
|
|
if not match: break
|
||
|
|
start, end = match.span()
|
||
|
|
results.append(escape(text[here:start]))
|
||
|
|
|
||
|
|
all, scheme, rfc, pep, selfdot, name = match.groups()
|
||
|
|
if scheme:
|
||
|
|
url = escape(all).replace('"', '"')
|
||
|
|
results.append('<a href="%s">%s</a>' % (url, url))
|
||
|
|
elif rfc:
|
||
|
|
url = 'http://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc)
|
||
|
|
results.append('<a href="%s">%s</a>' % (url, escape(all)))
|
||
|
|
elif pep:
|
||
|
|
url = 'http://www.python.org/dev/peps/pep-%04d/' % int(pep)
|
||
|
|
results.append('<a href="%s">%s</a>' % (url, escape(all)))
|
||
|
|
elif text[end:end+1] == '(':
|
||
|
|
results.append(self.namelink(name, methods, funcs, classes))
|
||
|
|
elif selfdot:
|
||
|
|
results.append('self.<strong>%s</strong>' % name)
|
||
|
|
else:
|
||
|
|
results.append(self.namelink(name, classes))
|
||
|
|
here = end
|
||
|
|
results.append(escape(text[here:]))
|
||
|
|
return ''.join(results)
|
||
|
|
|
||
|
|
def docroutine(self, object, name, mod=None,
|
||
|
|
funcs={}, classes={}, methods={}, cl=None):
|
||
|
|
"""Produce HTML documentation for a function or method object."""
|
||
|
|
|
||
|
|
anchor = (cl and cl.__name__ or '') + '-' + name
|
||
|
|
note = ''
|
||
|
|
|
||
|
|
title = '<a name="%s"><strong>%s</strong></a>' % (
|
||
|
|
self.escape(anchor), self.escape(name))
|
||
|
|
|
||
|
|
if inspect.ismethod(object):
|
||
|
|
args, varargs, varkw, defaults = inspect.getargspec(object.im_func)
|
||
|
|
# exclude the argument bound to the instance, it will be
|
||
|
|
# confusing to the non-Python user
|
||
|
|
argspec = inspect.formatargspec (
|
||
|
|
args[1:],
|
||
|
|
varargs,
|
||
|
|
varkw,
|
||
|
|
defaults,
|
||
|
|
formatvalue=self.formatvalue
|
||
|
|
)
|
||
|
|
elif inspect.isfunction(object):
|
||
|
|
args, varargs, varkw, defaults = inspect.getargspec(object)
|
||
|
|
argspec = inspect.formatargspec(
|
||
|
|
args, varargs, varkw, defaults, formatvalue=self.formatvalue)
|
||
|
|
else:
|
||
|
|
argspec = '(...)'
|
||
|
|
|
||
|
|
if isinstance(object, tuple):
|
||
|
|
argspec = object[0] or argspec
|
||
|
|
docstring = object[1] or ""
|
||
|
|
else:
|
||
|
|
docstring = pydoc.getdoc(object)
|
||
|
|
|
||
|
|
decl = title + argspec + (note and self.grey(
|
||
|
|
'<font face="helvetica, arial">%s</font>' % note))
|
||
|
|
|
||
|
|
doc = self.markup(
|
||
|
|
docstring, self.preformat, funcs, classes, methods)
|
||
|
|
doc = doc and '<dd><tt>%s</tt></dd>' % doc
|
||
|
|
return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)
|
||
|
|
|
||
|
|
def docserver(self, server_name, package_documentation, methods):
|
||
|
|
"""Produce HTML documentation for an XML-RPC server."""
|
||
|
|
|
||
|
|
fdict = {}
|
||
|
|
for key, value in methods.items():
|
||
|
|
fdict[key] = '#-' + key
|
||
|
|
fdict[value] = fdict[key]
|
||
|
|
|
||
|
|
server_name = self.escape(server_name)
|
||
|
|
head = '<big><big><strong>%s</strong></big></big>' % server_name
|
||
|
|
result = self.heading(head, '#ffffff', '#7799ee')
|
||
|
|
|
||
|
|
doc = self.markup(package_documentation, self.preformat, fdict)
|
||
|
|
doc = doc and '<tt>%s</tt>' % doc
|
||
|
|
result = result + '<p>%s</p>\n' % doc
|
||
|
|
|
||
|
|
contents = []
|
||
|
|
method_items = sorted(methods.items())
|
||
|
|
for key, value in method_items:
|
||
|
|
contents.append(self.docroutine(value, key, funcs=fdict))
|
||
|
|
result = result + self.bigsection(
|
||
|
|
'Methods', '#ffffff', '#eeaa77', pydoc.join(contents))
|
||
|
|
|
||
|
|
return result
|
||
|
|
|
||
|
|
class XMLRPCDocGenerator:
|
||
|
|
"""Generates documentation for an XML-RPC server.
|
||
|
|
|
||
|
|
This class is designed as mix-in and should not
|
||
|
|
be constructed directly.
|
||
|
|
"""
|
||
|
|
|
||
|
|
def __init__(self):
|
||
|
|
# setup variables used for HTML documentation
|
||
|
|
self.server_name = 'XML-RPC Server Documentation'
|
||
|
|
self.server_documentation = \
|
||
|
|
"This server exports the following methods through the XML-RPC "\
|
||
|
|
"protocol."
|
||
|
|
self.server_title = 'XML-RPC Server Documentation'
|
||
|
|
|
||
|
|
def set_server_title(self, server_title):
|
||
|
|
"""Set the HTML title of the generated server documentation"""
|
||
|
|
|
||
|
|
self.server_title = server_title
|
||
|
|
|
||
|
|
def set_server_name(self, server_name):
|
||
|
|
"""Set the name of the generated HTML server documentation"""
|
||
|
|
|
||
|
|
self.server_name = server_name
|
||
|
|
|
||
|
|
def set_server_documentation(self, server_documentation):
|
||
|
|
"""Set the documentation string for the entire server."""
|
||
|
|
|
||
|
|
self.server_documentation = server_documentation
|
||
|
|
|
||
|
|
def generate_html_documentation(self):
|
||
|
|
"""generate_html_documentation() => html documentation for the server
|
||
|
|
|
||
|
|
Generates HTML documentation for the server using introspection for
|
||
|
|
installed functions and instances that do not implement the
|
||
|
|
_dispatch method. Alternatively, instances can choose to implement
|
||
|
|
the _get_method_argstring(method_name) method to provide the
|
||
|
|
argument string used in the documentation and the
|
||
|
|
_methodHelp(method_name) method to provide the help text used
|
||
|
|
in the documentation."""
|
||
|
|
|
||
|
|
methods = {}
|
||
|
|
|
||
|
|
for method_name in self.system_listMethods():
|
||
|
|
if method_name in self.funcs:
|
||
|
|
method = self.funcs[method_name]
|
||
|
|
elif self.instance is not None:
|
||
|
|
method_info = [None, None] # argspec, documentation
|
||
|
|
if hasattr(self.instance, '_get_method_argstring'):
|
||
|
|
method_info[0] = self.instance._get_method_argstring(method_name)
|
||
|
|
if hasattr(self.instance, '_methodHelp'):
|
||
|
|
method_info[1] = self.instance._methodHelp(method_name)
|
||
|
|
|
||
|
|
method_info = tuple(method_info)
|
||
|
|
if method_info != (None, None):
|
||
|
|
method = method_info
|
||
|
|
elif not hasattr(self.instance, '_dispatch'):
|
||
|
|
try:
|
||
|
|
method = resolve_dotted_attribute(
|
||
|
|
self.instance,
|
||
|
|
method_name
|
||
|
|
)
|
||
|
|
except AttributeError:
|
||
|
|
method = method_info
|
||
|
|
else:
|
||
|
|
method = method_info
|
||
|
|
else:
|
||
|
|
assert 0, "Could not find method in self.functions and no "\
|
||
|
|
"instance installed"
|
||
|
|
|
||
|
|
methods[method_name] = method
|
||
|
|
|
||
|
|
documenter = ServerHTMLDoc()
|
||
|
|
documentation = documenter.docserver(
|
||
|
|
self.server_name,
|
||
|
|
self.server_documentation,
|
||
|
|
methods
|
||
|
|
)
|
||
|
|
|
||
|
|
return documenter.page(self.server_title, documentation)
|
||
|
|
|
||
|
|
class DocXMLRPCRequestHandler(SimpleXMLRPCRequestHandler):
|
||
|
|
"""XML-RPC and documentation request handler class.
|
||
|
|
|
||
|
|
Handles all HTTP POST requests and attempts to decode them as
|
||
|
|
XML-RPC requests.
|
||
|
|
|
||
|
|
Handles all HTTP GET requests and interprets them as requests
|
||
|
|
for documentation.
|
||
|
|
"""
|
||
|
|
|
||
|
|
def do_GET(self):
|
||
|
|
"""Handles the HTTP GET request.
|
||
|
|
|
||
|
|
Interpret all HTTP GET requests as requests for server
|
||
|
|
documentation.
|
||
|
|
"""
|
||
|
|
# Check that the path is legal
|
||
|
|
if not self.is_rpc_path_valid():
|
||
|
|
self.report_404()
|
||
|
|
return
|
||
|
|
|
||
|
|
response = self.server.generate_html_documentation()
|
||
|
|
self.send_response(200)
|
||
|
|
self.send_header("Content-type", "text/html")
|
||
|
|
self.send_header("Content-length", str(len(response)))
|
||
|
|
self.end_headers()
|
||
|
|
self.wfile.write(response)
|
||
|
|
|
||
|
|
class DocXMLRPCServer( SimpleXMLRPCServer,
|
||
|
|
XMLRPCDocGenerator):
|
||
|
|
"""XML-RPC and HTML documentation server.
|
||
|
|
|
||
|
|
Adds the ability to serve server documentation to the capabilities
|
||
|
|
of SimpleXMLRPCServer.
|
||
|
|
"""
|
||
|
|
|
||
|
|
def __init__(self, addr, requestHandler=DocXMLRPCRequestHandler,
|
||
|
|
logRequests=1, allow_none=False, encoding=None,
|
||
|
|
bind_and_activate=True):
|
||
|
|
SimpleXMLRPCServer.__init__(self, addr, requestHandler, logRequests,
|
||
|
|
allow_none, encoding, bind_and_activate)
|
||
|
|
XMLRPCDocGenerator.__init__(self)
|
||
|
|
|
||
|
|
class DocCGIXMLRPCRequestHandler( CGIXMLRPCRequestHandler,
|
||
|
|
XMLRPCDocGenerator):
|
||
|
|
"""Handler for XML-RPC data and documentation requests passed through
|
||
|
|
CGI"""
|
||
|
|
|
||
|
|
def handle_get(self):
|
||
|
|
"""Handles the HTTP GET request.
|
||
|
|
|
||
|
|
Interpret all HTTP GET requests as requests for server
|
||
|
|
documentation.
|
||
|
|
"""
|
||
|
|
|
||
|
|
response = self.generate_html_documentation()
|
||
|
|
|
||
|
|
print 'Content-Type: text/html'
|
||
|
|
print 'Content-Length: %d' % len(response)
|
||
|
|
print
|
||
|
|
sys.stdout.write(response)
|
||
|
|
|
||
|
|
def __init__(self):
|
||
|
|
CGIXMLRPCRequestHandler.__init__(self)
|
||
|
|
XMLRPCDocGenerator.__init__(self)
|