added comments. lots of comments.

braces/forms.py

@@ -8,5 +8,6 @@ class UserKwargModelFormMixin(object):
     anything else is done.
     """
     def __init__(self, *args, **kwargs):
-        self.user = kwargs.pop("user", None)
+        self.user = kwargs.pop("user", None)  # Pop the user off the
+                                              # passed in kwargs.
         super(UserKwargModelFormMixin, self).__init__(*args, **kwargs)

braces/views.py

@@ -18,6 +18,9 @@ class CreateAndRedirectToEditView(CreateView):
     success_url_name = None
 
     def get_success_url(self):
+        # First we check for a name to be provided on the view object.
+        # If one is, we reverse it and finish running the method,
+        # otherwise we raise a configuration error.
         if self.success_url_name:
             self.success_url = reverse(self.success_url_name,
                 kwargs={'pk': self.object.pk})
@@ -64,24 +67,30 @@ class SomeView(PermissionRequiredMixin, ListView):
             raise_exception = True
             ...
     """
-    login_url = settings.LOGIN_URL
-    permission_required = None
-    raise_exception = False
-    redirect_field_name = REDIRECT_FIELD_NAME
+    login_url = settings.LOGIN_URL  # LOGIN_URL from project settings
+    permission_required = None  # Default required perms to none
+    raise_exception = False  # Default whether to raise an exception to none
+    redirect_field_name = REDIRECT_FIELD_NAME  # Set by django.contrib.auth
 
     def dispatch(self, request, *args, **kwargs):
-        # Verify class settings
+        # Make sure that a permission_required is set on the view,
+        # and if it is, that it only has two parts (app.action_model)
+        # or raise a configuration error.
         if self.permission_required == None or len(
             self.permission_required.split(".")) != 2:
             raise ImproperlyConfigured("'PermissionRequiredMixin' requires "
                 "'permission_required' attribute to be set.")
 
+        # Check to see if the request's user has the required permission.
         has_permission = request.user.has_perm(self.permission_required)
 
-        if not has_permission:
-            if self.raise_exception:
-                return HttpResponseForbidden()
+        if not has_permission:  # If the user lacks the permission
+            if self.raise_exception:  # *and* if an exception was desired
+                return HttpResponseForbidden()  # return a forbidden response.
             else:
+                # otherwise, redirect the user to the login page.
+                # Also, handily, sets the `next` GET argument
+                # for future redirects.
                 path = urlquote(request.get_full_path())
                 tup = self.login_url, self.redirect_field_name, path
                 return HttpResponseRedirect("%s?%s=%s" % tup)
@@ -98,6 +107,7 @@ class UserFormKwargsMixin(object):
     """
     def get_form_kwargs(self, **kwargs):
         kwargs = super(UserFormKwargsMixin, self).get_form_kwargs(**kwargs)
+        # Update the existing form kwargs dict with the request's user.
         kwargs.update({"user": self.request.user})
         return kwargs
 
@@ -111,22 +121,29 @@ class SuccessURLRedirectListMixin(object):
     This is only to be used for redirecting to a list page. If you need
     to reverse the url with kwargs, this is not the mixin to use.
     """
-    success_list_url = None
+    success_list_url = None  # Default the success url to none
 
     def get_success_url(self):
+        # Return the reversed success url.
         return reverse(self.success_list_url)
 
 
 class SuperuserRequiredMixin(object):
-    login_url = settings.LOGIN_URL
-    raise_exception = False
-    redirect_field_name = REDIRECT_FIELD_NAME
+    """
+    Mixin allows you to require a user with `is_superuser` set to True.
+    """
+    login_url = settings.LOGIN_URL  # LOGIN_URL from project settings
+    raise_exception = False  # Default whether to raise an exception to none
+    redirect_field_name = REDIRECT_FIELD_NAME  # Set by django.contrib.auth
 
     def dispatch(self, request, *args, **kwargs):
-        if not request.user.is_superuser:
-            if self.raise_exception:
-                return HttpResponseForbidden()
+        if not request.user.is_superuser:  # If the user is a standard user,
+            if self.raise_exception:  # *and* if an exception was desired
+                return HttpResponseForbidden()  # return a forbidden response.
             else:
+                # otherwise, redirect the user to the login page.
+                # Also, handily, sets the `next` GET argument for
+                # future redirects.
                 path = urlquote(request.get_full_path())
                 tup = self.login_url, self.redirect_field_name, path
                 return HttpResponseRedirect("%s?%s=%s" % tup)
@@ -140,15 +157,18 @@ class SetHeadlineMixin(object):
     Mixin allows you to set a static headline through a static property on the
     class or programmatically by overloading the get_headline method.
     """
-    headline = None
+    headline = None  # Default the headline to none
 
     def get_context_data(self, **kwargs):
         kwargs = super(SetHeadlineMixin, self).get_context_data(**kwargs)
+        # Update the existing context dict with the provided headline.
         kwargs.update({"headline": self.get_headline()})
         return kwargs
 
     def get_headline(self):
-        if self.headline is None:
+        if self.headline is None:  # If no headline was provided as a view
+                                   # attribute and this method wasn't overriden
+                                   # raise a configuration error.
             raise ImproperlyConfigured(u"%(cls)s is missing a headline. Define "
                 u"%(cls)s.headline, or override "
                 u"%(cls)s.get_headline()." % {"cls": self.__class__.__name__
@@ -161,33 +181,46 @@ class SelectRelatedMixin(object):
     Mixin allows you to provide a tuple or list of related models to
     perform a select_related on.
     """
-    select_related = None
+    select_related = None  # Default related fields to none
 
     def get_queryset(self):
-        if self.select_related is None:
+        if self.select_related is None:  # If no fields were provided,
+                                         # raise a configuration error
             raise ImproperlyConfigured(u"%(cls)s is missing the select_related "
                 "property. This must be a tuple or list." % {
                     "cls": self.__class__.__name__})
 
         if not isinstance(self.select_related, (tuple, list)):
+            # If the select_related argument is *not* a tuple or list,
+            # raise a configuration error.
             raise ImproperlyConfigured(u"%(cls)s's select_related property "
                 "must be a tuple or list." % {"cls": self.__class__.__name__})
 
+        # Get the current queryset of the view
         queryset = super(SelectRelatedMixin, self).get_queryset()
+
+        # Return the queryset with a comma-joined argument to `select_related`.
         return queryset.select_related(
             ", ".join(self.select_related)
         )
 
+
 class StaffuserRequiredMixin(object):
-    login_url = settings.LOGIN_URL
-    raise_exception = False
-    redirect_field_name = REDIRECT_FIELD_NAME
+    """
+    Mixin allows you to require a user with `is_staff` set to True.
+    """
+    login_url = settings.LOGIN_URL  # LOGIN_URL from project settings
+    raise_exception = False  # Default whether to raise an exception to none
+    redirect_field_name = REDIRECT_FIELD_NAME  # Set by django.contrib.auth
 
     def dispatch(self, request, *args, **kwargs):
-        if not request.user.is_staff:
-            if self.raise_exception:
-                return HttpResponseForbidden()
+        if not request.user.is_staff:  # If the request's user is not staff,
+            if self.raise_exception:  # *and* if an exception was desired
+                return HttpResponseForbidden()  # return a forbidden response
             else:
+                # otherwise, redirect the user to the login page.
+                # Also, handily, sets the GET `next` argument for
+                # future redirects.
                 path = urlquote(request.get_full_path())
                 tup = self.login_url, self.redirect_field_name, path
                 return HttpResponseRedirect("%s?%s=%s" % tup)