I did some more code-keeping in this commit. I added a lot of documentation, so

that most of my functions do indeed have effective docstrings. I also changed
the decorators so that they imply eachother in a logical way. I also modified
the one decorator get_media_comment_by_id to be more usable with the variable
urls of mediagoblin.user_pages.views:file_a_report. I also noticed a few tests
had broken, so I went through them and fixed them up, finding that mostly there
were problems in my actual writing of the tests. I also did a few other small
tasks such as creating a new User method to check whether or not a User is ban-
-ned.

===============================================================================
    Added in documentation
===============================================================================
--\  mediagoblin/db/models.py
--\  mediagoblin/decorators.py
--\  mediagoblin/moderation/forms.py
--\  mediagoblin/moderation/tools.py
--\  mediagoblin/moderation/views.py
--\  mediagoblin/user_pages/lib.py

===============================================================================
    Rearranged decorators to be more efficient
===============================================================================
--\  mediagoblin/decorators.py
--| Made it so that user_not_banned is encapsulated in require_active_login
--| Made it so that require_active_login is encapsulated in user_has_privilege
--| Changed get_media_comment_by_id into get_optional_media_comment_by_id. It
  | now returns valid code if the MediaComment id is absent. This makes it pos-
  | -sible to use this decorator for the function:
  |         mediagoblin.user_pages.views:file_a_report

--\  mediagoblin/user_pages/views.py
--| Replaced the mediagoblin.user_pages.views:file_a_comment_report with the
  | decorator mentioned above

--\  mediagoblin/user_pages/routing.py

        -----------------------------------------------------------
        |     took out unnecessary @user_not_banned decorators    |
        -----------------------------------------------------------
--\  mediagoblin/submit/views.py
--\  mediagoblin/user_pages/views.py

===============================================================================
    Fixed broken tests
===============================================================================
--\  mediagoblin/tests/test_auth.py
--\  mediagoblin/tests/test_privileges.py
--\  mediagoblin/tests/test_submission.py

===============================================================================
    Fixed broken code
===============================================================================
--\  mediagoblin/tools/response.py

===============================================================================
    Other Tasks
===============================================================================
--\  mediagoblin/db/models.py
--| Added in User.is_banned() method
--\  mediagoblin/decorators.py
--| Utitilized User.is_banned() method in the user_not_banned decorator

--\  mediagoblin/moderation/views.py
--| Made it impossible for an admin to ban themself.
--| Got rid of a vestigial print statement

--\  mediagoblin/templates/mediagoblin/base.html
--| Made it so the top panel does not show up for users that are banned.

--\  mediagoblin/templates/mediagoblin/moderation/user.html
--| Rearranged the javascript slightly

===============================================================================

1 files changed, 59 insertions, 12 deletions

diff --git a/mediagoblin/db/models.py b/mediagoblin/db/models.py
index 1e8d0a0c..f25dc32c 100644
--- a/mediagoblin/db/models.py
+++ b/mediagoblin/db/models.py
@@ -105,6 +105,17 @@ class User(Base, UserMixin):
         _log.info('Deleted user "{0}" account'.format(self.username))
 
     def has_privilege(self,*priv_names):
+        """
+        This method checks to make sure a user has all the correct privileges
+        to access a piece of content.
+
+        :param  priv_names      A variable number of unicode objects which rep-
+                                -resent the different privileges which may give
+                                the user access to this content. If you pass
+                                multiple arguments, the user will be granted
+                                access if they have ANY of the privileges
+                                passed.
+        """
         if len(priv_names) == 1:
             priv = Privilege.query.filter(
                 Privilege.privilege_name==priv_names[0]).one()
@@ -114,6 +125,16 @@ class User(Base, UserMixin):
                 self.has_privilege(*priv_names[1:])
         return False
 
+    def is_banned(self):
+        """
+        Checks if this user is banned.
+
+            :returns                True if self is banned
+            :returns                False if self is not
+        """
+        return UserBan.query.get(self.id) is not None
+
+
 class Client(Base):
     """
         Model representing a client - Used for API Auth
@@ -655,15 +676,21 @@ with_polymorphic(
 
 class ReportBase(Base):
     """
-    This is the basic report table which the other reports are based off of.
-        :keyword reporter_id
-        :keyword report_content
-        :keyword reported_user_id
-        :keyword created
-        :keyword resolved
-        :keyword result
-        :keyword discriminator
-
+    This is the basic report object which the other reports are based off of.
+
+        :keyword    reporter_id         Holds the id of the user who created
+                                            the report, as an Integer column.
+        :keyword    report_content      Hold the explanation left by the repor-
+                                            -ter to indicate why they filed the
+                                            report in the first place, as a
+                                            Unicode column.
+        :keyword    reported_user_id    Holds the id of the user who created
+                                            the content which was reported, as
+                                            an Integer column.
+        :keyword    created             Holds a datetime column of when the re-
+                                            -port was filed.
+        :keyword    discriminator       This column distinguishes between the
+                                            different types of reports.
     """
     __tablename__ = 'core__reports'
     id = Column(Integer, primary_key=True)
@@ -698,7 +725,9 @@ class ReportBase(Base):
 
 class CommentReport(ReportBase):
     """
-    A class to keep track of reports that have been filed on comments
+    Reports that have been filed on comments.
+        :keyword    comment_id          Holds the integer value of the reported
+                                            comment's ID
     """
     __tablename__ = 'core__reports_on_comments'
     __mapper_args__ = {'polymorphic_identity': 'comment_report'}
@@ -713,7 +742,9 @@ class CommentReport(ReportBase):
 
 class MediaReport(ReportBase):
     """
-    A class to keep track of reports that have been filed on media entries
+    Reports that have been filed on media entries
+        :keyword    media_entry_id      Holds the integer value of the reported
+                                            media entry's ID
     """
     __tablename__ = 'core__reports_on_media'
     __mapper_args__ = {'polymorphic_identity': 'media_report'}
@@ -729,7 +760,23 @@ class MediaReport(ReportBase):
 
 class ArchivedReport(ReportBase):
     """
-    A table to keep track of reports that have been resolved
+    Reports that have been resolved. The media_entry and comment columns must
+    be optional so that if the media entry/comment is deleted, the archive can
+    still exist.
+        :keyword    comment_id          Holds the Integer value of the reported
+                                            comment's ID. This column is optio-
+                                            -nal.
+        :keyword    media_entry_id      Holds the Integer value of the reported
+                                            media entry's ID. This column is
+                                            optional.
+        :keyword    resolver_id         Holds the id of the moderator/admin who
+                                            resolved the report.
+        :keyword    resolved            Holds the DateTime object which descri-
+                                            -bes when this report was resolved
+        :keyword    result              Holds the UnicodeText column of the
+                                            resolver's reasons for resolving
+                                            the report this way. Some of this
+                                            is auto-generated
     """
     __tablename__ = 'core__reports_archived'
     __mapper_args__ = {'polymorphic_identity': 'archived_report'}