/usr/share/pyshared/sphinxcontrib/autohttp/flask.py is in python-sphinxcontrib-httpdomain 1.1.8-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | """
sphinxcontrib.autohttp.flask
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The sphinx.ext.autodoc-style HTTP API reference builder (from Flask)
for sphinxcontrib.httpdomain.
:copyright: Copyright 2011 by Hong Minhee
:license: BSD, see LICENSE for details.
"""
import re
try:
import cStringIO as StringIO
except ImportError:
import StringIO
from docutils import nodes
from docutils.statemachine import ViewList
from sphinx.util import force_decode
from sphinx.util.compat import Directive
from sphinx.util.nodes import nested_parse_with_titles
from sphinx.util.docstrings import prepare_docstring
from sphinx.pycode import ModuleAnalyzer
from sphinxcontrib import httpdomain
def import_object(import_name):
module_name, expr = import_name.split(':', 1)
mod = __import__(module_name)
mod = reduce(getattr, module_name.split('.')[1:], mod)
globals = __builtins__
if not isinstance(globals, dict):
globals = globals.__dict__
return eval(expr, globals, mod.__dict__)
def http_directive(method, path, content):
method = method.lower().strip()
if isinstance(content, basestring):
content = content.splitlines()
yield ''
yield '.. http:{method}:: {path}'.format(**locals())
yield ''
for line in content:
yield ' ' + line
yield ''
def translate_werkzeug_rule(rule):
from werkzeug.routing import parse_rule
buf = StringIO.StringIO()
for conv, arg, var in parse_rule(rule):
if conv:
buf.write('(')
if conv != 'default':
buf.write(conv)
buf.write(':')
buf.write(var)
buf.write(')')
else:
buf.write(var)
return buf.getvalue()
def get_routes(app):
for rule in app.url_map.iter_rules():
methods = rule.methods.difference(['OPTIONS', 'HEAD'])
for method in methods:
path = translate_werkzeug_rule(rule.rule)
yield method, path, rule.endpoint
class AutoflaskDirective(Directive):
has_content = True
required_arguments = 1
option_spec = {'endpoints': str,
'undoc-endpoints': str,
'undoc-blueprints': str,
'undoc-static': str,
'include-empty-docstring': str}
@property
def endpoints(self):
try:
endpoints = re.split(r'\s*,\s*', self.options['endpoints'])
except KeyError:
# means 'endpoints' option was missing
return None
return frozenset(endpoints)
@property
def undoc_endpoints(self):
try:
endpoints = re.split(r'\s*,\s*', self.options['undoc-endpoints'])
except KeyError:
return frozenset()
return frozenset(endpoints)
@property
def undoc_blueprints(self):
try:
blueprints = re.split(r'\s*,\s*', self.options['undoc-blueprints'])
except KeyError:
return frozenset()
return frozenset(blueprints)
def make_rst(self):
app = import_object(self.arguments[0])
for method, path, endpoint in get_routes(app):
try:
blueprint, endpoint_internal = endpoint.split('.')
if blueprint in self.undoc_blueprints:
continue
except ValueError:
pass # endpoint is not within a blueprint
if self.endpoints and endpoint not in self.endpoints:
continue
if endpoint in self.undoc_endpoints:
continue
try:
static_url_path = app.static_url_path # Flask 0.7 or higher
except AttributeError:
static_url_path = app.static_path # Flask 0.6 or under
if ('undoc-static' in self.options and endpoint == 'static' and
path == static_url_path + '/(path:filename)'):
continue
view = app.view_functions[endpoint]
docstring = view.__doc__ or ''
if hasattr(view, 'view_class'):
meth_func = getattr(view.view_class, method.lower(), None)
if meth_func and meth_func.__doc__:
docstring = meth_func.__doc__
if not isinstance(docstring, unicode):
analyzer = ModuleAnalyzer.for_module(view.__module__)
docstring = force_decode(docstring, analyzer.encoding)
if not docstring and 'include-empty-docstring' not in self.options:
continue
docstring = prepare_docstring(docstring)
for line in http_directive(method, path, docstring):
yield line
def run(self):
node = nodes.section()
node.document = self.state.document
result = ViewList()
for line in self.make_rst():
result.append(line, '<autoflask>')
nested_parse_with_titles(self.state, result, node)
return node.children
def setup(app):
if 'http' not in app.domains:
httpdomain.setup(app)
app.add_directive('autoflask', AutoflaskDirective)
|