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('"', '"') |
---|
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 | class DocXMLRPCServer( SimpleXMLRPCServer, |
---|
244 | XMLRPCDocGenerator): |
---|
245 | """XML-RPC and HTML documentation server. |
---|
246 | |
---|
247 | Adds the ability to serve server documentation to the capabilities |
---|
248 | of SimpleXMLRPCServer. |
---|
249 | """ |
---|
250 | |
---|
251 | def __init__(self, addr, requestHandler=DocXMLRPCRequestHandler, |
---|
252 | logRequests=1, allow_none=False, encoding=None, |
---|
253 | bind_and_activate=True): |
---|
254 | SimpleXMLRPCServer.__init__(self, addr, requestHandler, logRequests, |
---|
255 | allow_none, encoding, bind_and_activate) |
---|
256 | XMLRPCDocGenerator.__init__(self) |
---|
257 | |
---|
258 | class DocCGIXMLRPCRequestHandler( CGIXMLRPCRequestHandler, |
---|
259 | XMLRPCDocGenerator): |
---|
260 | """Handler for XML-RPC data and documentation requests passed through |
---|
261 | CGI""" |
---|
262 | |
---|
263 | def handle_get(self): |
---|
264 | """Handles the HTTP GET request. |
---|
265 | |
---|
266 | Interpret all HTTP GET requests as requests for server |
---|
267 | documentation. |
---|
268 | """ |
---|
269 | |
---|
270 | response = self.generate_html_documentation() |
---|
271 | |
---|
272 | print 'Content-Type: text/html' |
---|
273 | print 'Content-Length: %d' % len(response) |
---|
274 | print |
---|
275 | sys.stdout.write(response) |
---|
276 | |
---|
277 | def __init__(self): |
---|
278 | CGIXMLRPCRequestHandler.__init__(self) |
---|
279 | XMLRPCDocGenerator.__init__(self) |
---|