Python code coverage for Lib/DocXMLRPCServer.py

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