Merge pull request #14 from BallisticBuddha/customProperties

Custom Function Properties

Author: lukeyeager

examples/custom/blog.py

@@ -57,11 +57,10 @@ def get_post(id):
 
 
 @app.route('/post', methods=["POST"])
-@auto.doc(groups=['posts', 'private'])
+@auto.doc(groups=['posts', 'private'],
+    form_data=['title', 'content', 'authorid'])
 def post_post():
-    """Create a new post.
-    Form Data: title, content, authorid.
-    """
+    """Create a new post."""
     authorid = request.form.get('authorid', None)
     Post(request.form['title'],
          request.form['content'],
@@ -84,11 +83,10 @@ def get_user(id):
 
 
 @app.route('/users', methods=['POST'])
-@auto.doc(groups=['users', 'private'])
+@auto.doc(groups=['users', 'private'],
+    form_data=['username'])
 def post_user(id):
-    """Creates a new user.
-    Form Data: username.
-    """
+    """Creates a new user."""
     User(request.form['username'])
     redirect('/users')
 

examples/custom/templates/autodoc_custom.html

@@ -22,7 +22,7 @@
                 margin: 20px 20px;
             }
 
-            .location { font-style: italic;}
+            .location { font-style: italic; }
 
             ul.methods:before { content: "Methods: "; }
             ul.methods li {
@@ -43,6 +43,11 @@
             ul.arguments li:after { content: ","; }
             ul.arguments li:last-child:after { content: ""; }
 
+            ul.property li {
+                display: inline;
+                list-style: none;
+            }
+
             .docstring:before { content: "Description: "; }
         </style>
     </head>
@@ -60,9 +65,9 @@ <h1>
             <a id="rule-{{doc.rule|urlencode}}" class="rule"><h2>{{doc.rule|escape}}</h2></a>
             <p class="location">{{doc.location.filename}}:{{doc.location.line}}</p>
             <ul class="methods">
-                    {% for method in doc.methods -%}
-                    <li class="method">{{method}}</li>
-                    {% endfor %}
+                {% for method in doc.methods -%}
+                <li class="method">{{method}}</li>
+                {% endfor %}
             </ul>
             <ul class="arguments">
                 {% for arg in doc.args %}
@@ -72,6 +77,11 @@ <h1>
                 </li>
                 {% endfor %}
             </ul>
+            <ul class="property">
+                {% for prop in doc if prop not in defaults %}
+                <li class="property">{{prop}}:{{doc[prop]}}</br></li>
+                {% endfor %}
+            </ul>
             <p class="docstring">{% autoescape false %}{{doc.docstring|urlize|nl2br}}{% endautoescape %}</p>
         </div>
         {% endfor %}

flask_autodoc/autodoc.py

@@ -26,6 +26,10 @@ class Autodoc(object):
     def __init__(self, app=None):
         self.app = app
         self.func_groups = defaultdict(set)
+        self.func_props = defaultdict()
+        self.immutable_props = ['rule', 'endpoint']
+        self.default_props = ['methods', 'docstring', 
+            'args', 'defaults', 'location'] + self.immutable_props
         self.func_locations = defaultdict(dict)
         if app is not None:
             self.init_app(app)
@@ -57,7 +61,7 @@ def nl2br(eval_ctx, value):
                                  for p in _paragraph_re.split(value))
             return result
 
-    def doc(self, groups=None):
+    def doc(self, groups=None, **properties):
         """Add flask route to autodoc for automatic documentation
 
         Any route decorated with this method will be added to the list of
@@ -66,6 +70,14 @@ def doc(self, groups=None):
         By default, the route is added to the 'all' group.
         By specifying group or groups argument, the route can be added to one
         or multiple other groups as well, besides the 'all' group.
+
+        Custom parameters may also be passed in beyond groups, if they are
+        named something not already in the dict descibed in the docstring for 
+        the generare() function, they will be added to the route's properties,
+        which can be accessed from the template.
+
+        If a parameter is passed in with a name that is already in the dict, but
+        not of a reserved name, the passed parameter overrides that dict value.
         """
         def decorator(f):
             # Set group[s]
@@ -77,6 +89,7 @@ def decorator(f):
                     groupset.add(groups)
             groupset.add('all')
             self.func_groups[f] = groupset
+            self.func_props[f] = properties
 
             # Set location
             caller_frame = inspect.stack()[1]
@@ -120,20 +133,24 @@ def generate(self, groups='all', sort=None):
             func = current_app.view_functions[rule.endpoint]
             arguments = rule.arguments if rule.arguments else ['None']
             func_groups = self.func_groups[func]
+            func_props = self.func_props[func] if func in self.func_props \
+                else {}
             location = self.func_locations.get(func, None)
 
             if func_groups.intersection(groups_to_generate):
-                links.append(
-                    dict(
-                        methods=rule.methods,
-                        rule="%s" % rule,
-                        endpoint=rule.endpoint,
-                        docstring=func.__doc__,
-                        args=arguments,
-                        defaults=rule.defaults,
-                        location=location,
-                    )
+                props = dict(
+                    methods=rule.methods,
+                    rule="%s" % rule,
+                    endpoint=rule.endpoint,
+                    docstring=func.__doc__,
+                    args=arguments,
+                    defaults=rule.defaults,
+                    location=location,
                 )
+                for p in func_props:
+                    if p not in self.immutable_props:
+                        props[p] = func_props[p]
+                links.append(props)
         if sort:
             return sort(links)
         else:
@@ -150,10 +167,12 @@ def html(self, groups='all', template=None, **context):
         By specifying the group or groups arguments, only routes belonging to
         those groups will be returned.
         """
+        context['autodoc'] = context['autodoc'] if 'autodoc' in context \
+            else self.generate(groups=groups)
+        context['defaults'] = context['defaults'] if 'defaults' in context \
+            else self.default_props
         if template:
-            return render_template(template,
-                                   autodoc=self.generate(groups=groups),
-                                   **context)
+            return render_template(template, **context)
         else:
             filename = os.path.join(
                 os.path.dirname(__file__),
@@ -163,7 +182,4 @@ def html(self, groups='all', template=None, **context):
             with open(filename) as file:
                 content = file.read()
                 with current_app.app_context():
-                    return render_template_string(
-                        content,
-                        autodoc=self.generate(groups=groups),
-                        **context)
+                    return render_template_string(content, **context)

tests/test_autodoc.py

@@ -1,5 +1,6 @@
 import unittest
 import sys
+import os
 
 from flask import Flask
 from flask.ext.autodoc import Autodoc
@@ -104,7 +105,6 @@ def pub():
             self.assertIn('/pub', doc[0]['rule'])
 
     def testGroups(self):
-
         @self.app.route('/a')
         @self.autodoc.doc()
         def a():
@@ -143,6 +143,71 @@ def c():
             self.assertIn('/b', rules)
             self.assertIn('/c', rules)
 
+    def testCustomParams(self):
+        @self.app.route('/needsargs', methods=['GET'])
+        @self.autodoc.doc('needs_getargs', getargs={
+            'a': 'A Value',
+            'b': 'B Value'  
+            })
+        def getit():
+            return 'I need specific GET parameters.'
+
+        @self.app.route('/noargs')
+        @self.autodoc.doc(groups=['needs_json', 'noargs'],
+            expected_type='application/json')
+        def needjson():
+            return 'I do not need any parameters, but am picky about types.'
+
+        with self.app.app_context():
+            doc = self.autodoc.generate('needs_getargs')
+            self.assertTrue(len(doc) == 1)
+            self.assertIn('getargs', doc[0])
+            self.assertEqual('B Value', doc[0]['getargs']['b'])
+
+            doc = self.autodoc.generate('noargs')
+            self.assertTrue(len(doc) == 1)
+            self.assertNotIn('getargs', doc[0])
+
+            doc = self.autodoc.generate('needs_json')
+            self.assertTrue(len(doc) == 1)
+            self.assertIn('expected_type', doc[0])
+            self.assertEqual('application/json', doc[0]['expected_type'])
+
+    def testOverrideParams(self):
+        @self.app.route('/added')
+        @self.autodoc.doc('add', args=['option'])
+        def original():
+            return 'I make my own options.'
+
+        @self.app.route('/modified', defaults={'option1': 1})
+        @self.app.route('/modified/<int:option1>')
+        @self.autodoc.doc('modify', args=['option2'], defaults=[2])
+        def override_allowed(option1):
+            return 'I modify my own options.'
+
+        @self.app.route('/prohibited')
+        @self.autodoc.doc('fail', rule='/not/supposed/to/be/here')
+        def override_prohibited():
+            return 'I make my own rules.'
+
+        with self.app.app_context():
+            doc = self.autodoc.generate('add')
+            self.assertTrue(len(doc) == 1)
+            self.assertIn('option', doc[0]['args'])
+
+            doc = self.autodoc.generate('modify')
+            args = [doc[i]['args'] for i in range(len(doc))]
+            defaults = [doc[i]['defaults'] for i in range(len(doc))]
+            self.assertNotIn(['option1'], args)
+            self.assertNotIn([1], defaults)
+            self.assertIn(['option2'], args)
+            self.assertIn([2], defaults)
+
+            doc = self.autodoc.generate('fail')
+            self.assertTrue(len(doc) == 1)
+            self.assertNotEqual('/not/supposed/to/be/here', doc[0]['rule'])
+            self.assertEqual('/prohibited', doc[0]['rule'])
+
     def testHTML(self):
         @self.app.route('/')
         @self.autodoc.doc()
@@ -182,3 +247,4 @@ def ab(param1, param2):
                     '\/p1\/.*string:param1.*\/p2\/.*int:param2.*'
                 )
             self.assertIn('Returns arguments', doc)
+