add docstrings for views and view tests

rubberstamp/tests/views.py

@@ -14,6 +14,7 @@ def setUp(self):
         self.user = User.objects.get(username='user')
 
     def test_app_list(self):
+        """The root view shows a list of apps and the permissions they define."""
         xr = self.client.get('/')
         self.assertEqual(xr.status_code, 302)
 
@@ -39,6 +40,7 @@ def test_app_list(self):
         self.assertTrue(all(c in tp[1] for c in ['use', 'have']))
 
     def test_type_list_for_perm(self):
+        """Given a permission codename, show a list of types to which it applies."""
         xr = self.client.get('/testapp.not/')
         self.assertEqual(xr.status_code, 302)
         xr = self.client.get('/testapp.use/')
@@ -64,6 +66,7 @@ def test_type_list_for_perm(self):
         self.assertTrue(otm_ct in type_list)
 
     def test_type_to_user(self):
+        """Assign a permission for a type to a user."""
         xr = self.client.get('/testapp.use.testapp.nomodel/')
         self.assertEqual(xr.status_code, 302)
         xr = self.client.get('/testapp.use.testapp.testmodel/')
@@ -101,6 +104,7 @@ def test_type_to_user(self):
         self.assertTrue(user4.has_perm('testapp.use.testapp.testmodel'))
 
     def test_type_to_group(self):
+        """Assign a permission for a type to a group."""
         AppPermission.objects.assign('rubberstamp.manage.rubberstamp.apppermission', self.user)
         self.client.login(username='user', password='')
         post_dict = {
@@ -118,6 +122,7 @@ def test_type_to_group(self):
         self.assertTrue(user4.has_perm('testapp.use.testapp.testmodel'))
 
     def test_type_remove(self):
+        """Remove (un-assign) permissions from a user or group."""
         AppPermission.objects.assign('rubberstamp.manage.rubberstamp.apppermission', self.user)
         self.client.login(username='user', password='')
         user4 = User.objects.get(pk=4)
@@ -140,6 +145,7 @@ def test_type_remove(self):
         self.assertFalse(user5.has_perm('testapp.use.testapp.testmodel'))
 
     def test_object_list(self):
+        """Given a permission and type, return a list of objects of that type."""
         xr = self.client.get('/testapp.use.testapp.nomodel/objects/')
         self.assertEqual(xr.status_code, 302)
         xr = self.client.get('/testapp.use.testapp.testmodel/objects/')
@@ -166,6 +172,7 @@ def test_object_list(self):
         self.assertEqual(len(objects), 2)
 
     def test_object_to_user(self):
+        """Assign a permission for an object to a user."""
         xr = self.client.get('/testapp.use.testapp.testmodel/objects/100/')
         self.assertEqual(xr.status_code, 302)
         xr = self.client.get('/testapp.use.testapp.testmodel/objects/1/')

rubberstamp/views.py

@@ -8,6 +8,15 @@
 
 
 def app_list(request):
+    """
+    Returns a list of apps and their permission codenames.
+    
+    Renders the template ``'rubberstamp/app_list.html'``, with context
+    containing ``app_perms``, a list of tuples like::
+    
+        [('app_label', ['codename', 'codename', ...]), ...]
+    """
+
     app_codes = AppPermission.objects.order_by('app_label', 'codename') \
         .values_list('app_label', 'codename')
     on_app = None
@@ -18,13 +27,23 @@ def app_list(request):
             app_perms.append((app, [])) # add app and empty perm list
         app_perms[-1][1].append(code) # add this code to the current app's list
 
+    # app perms should be a list of tuples like
+    # [('app_label', ['codename', 'codename', ...]), ...]
     return render_to_response(
         'rubberstamp/app_list.html',
         {'app_perms': app_perms}
     )
 
 
 def type_list(request, app_label, codename):
+    """
+    Given an app label and permission codename, returns a list of types to
+    which that permission can apply.
+    
+    Renders the template ``'rubberstamp/type_list.html'``, with context
+    containing ``types``, a list of `ContentType` objects.
+    """
+
     perm = get_object_or_404(
         AppPermission, app_label=app_label, codename=codename)
     return render_to_response(
@@ -34,6 +53,15 @@ def type_list(request, app_label, codename):
 
 
 def object_list(request, app, code, target_app, target_model):
+    """
+    Given an app label and permission codename, as well as a "target" app label
+    and model name, returns a list of objects of the target type to which the
+    permission can apply.
+    
+    Renders the template ``'rubberstamp/object_list.html'``, with context
+    containing ``objects``, a list of instances of the appropriate type.
+    """
+
     target_ct = get_object_or_404(
         ContentType, app_label=target_app, model=target_model)
     perm = get_object_or_404(AppPermission,
@@ -46,6 +74,18 @@ def object_list(request, app, code, target_app, target_model):
 
 
 def type_perms(request, app, code, target_app, target_model, obj_pk=None):
+    """
+    Takes the same arguments as ``object_list``, but returns a form to specify
+    users and groups to assign/unassign the given permission to.
+    
+    Also accepts an option argument, the primary key of an object of the given
+    type; if given, then the permissions will be assigned for that specific
+    object instead of the type.
+    
+    Renders the template ``'rubberstamp/type_perms.html'``, with context
+    containing ``assign_form``, a Django form to select users and groups.
+    """
+
     target_ct = get_object_or_404(
         ContentType, app_label=target_app, model=target_model)
     perm = get_object_or_404(AppPermission,