pep257ifys core and api (#2245)

Author: fboxwala

prospector.yml

@@ -34,6 +34,10 @@ mccabe:
 
 pep257:
   run: false
+  disable:
+      - D105
+      - D211
+      - D104
 
 pyflakes:
   disable:

readthedocs/api/utils.py

@@ -19,13 +19,16 @@
 
 
 class SearchMixin(object):
-    '''
+
+    """
     Adds a search api to any ModelResource provided the model is indexed.
+
     The search can be configured using the Meta class in each ModelResource.
     The search is limited to the model defined by the meta queryset. If the
     search is invalid, a 400 Bad Request will be raised.
 
     e.g.
+
         class Meta:
             # Return facet counts for each facetname
             search_facets = ['facetname1', 'facetname1']
@@ -35,7 +38,8 @@ class Meta:
 
             # Highlight search terms in the text
             search_highlight = True
-    '''
+    """
+
     def get_search(self, request, **kwargs):
         self.method_check(request, allowed=['get'])
         self.is_authenticated(request)
@@ -49,11 +53,12 @@ def get_search(self, request, **kwargs):
         return self.create_response(request, object_list)
 
     def _url_template(self, query, selected_facets):
-        '''
+        """
         Construct a url template to assist with navigating the resources.
+
         This looks a bit nasty but urllib.urlencode resulted in even
         nastier output...
-        '''
+        """
         query_params = []
         for facet in selected_facets:
             query_params.append(('selected_facets', facet))
@@ -67,12 +72,13 @@ def _url_template(self, query, selected_facets):
 
     def _search(self, request, model, facets=None, page_size=20,
                 highlight=True):
-        '''
+        """
         `facets`
+
             A list of facets to include with the results
         `models`
             Limit the search to one or more models
-        '''
+        """
         form = FacetedSearchForm(request.GET, facets=facets or [],
                                  models=(model,), load_all=True)
         if not form.is_valid():

readthedocs/core/forms.py

@@ -42,32 +42,34 @@ def save(self, *args, **kwargs):
 
 class FacetField(forms.MultipleChoiceField):
 
-    '''
-    For filtering searches on a facet, with validation for the format
-    of facet values.
-    '''
+    """
+    For filtering searches on a facet.
+
+    Has validation for the format of facet values.
+    """
 
     def valid_value(self, value):
-        '''
+        """
         Although this is a choice field, no choices need to be supplied.
+
         Instead, we just validate that the value is in the correct format
         for facet filtering (facet_name:value)
-        '''
+        """
         if ":" not in value:
             return False
         return True
 
 
 class FacetedSearchForm(SearchForm):
 
-    '''
+    """
     Supports fetching faceted results with a corresponding query.
 
     `facets`
         A list of facet names for which to get facet counts
     `models`
         Limit the search to one or more models
-    '''
+    """
 
     selected_facets = FacetField(required=False)
 

readthedocs/core/management/commands/archive.py

@@ -10,8 +10,11 @@
 
 
 class Command(BaseCommand):
-    """Custom management command to rebuild documentation for all projects on
-    the site. Invoked via ``./manage.py update_repos``.
+
+    """
+    Custom management command to rebuild documentation for all projects.
+
+    Invoked via ``./manage.py update_repos``.
     """
 
     def handle(self, *args, **options):

readthedocs/core/management/commands/clean_builds.py

@@ -27,9 +27,7 @@ class Command(BaseCommand):
     )
 
     def handle(self, *args, **options):
-        '''
-        Find stale builds and remove build paths
-        '''
+        """Find stale builds and remove build paths"""
         max_date = datetime.now() - timedelta(days=options['days'])
         queryset = (Build.objects
                     .values('project', 'version')

readthedocs/core/management/commands/reindex_elasticsearch.py

@@ -22,9 +22,7 @@ class Command(BaseCommand):
     )
 
     def handle(self, *args, **options):
-        '''
-        Build/index all versions or a single project's version
-        '''
+        """Build/index all versions or a single project's version"""
         project = options['project']
 
         queryset = Version.objects.public()

readthedocs/core/management/commands/sync_builds.py

@@ -9,8 +9,11 @@
 
 
 class Command(BaseCommand):
-    """Custom management command to rebuild documentation for all projects on
-    the site. Invoked via ``./manage.py update_repos``.
+
+    """
+    Custom management command to rebuild documentation for all projects.
+
+    Invoked via ``./manage.py update_repos``.
     """
 
     option_list = BaseCommand.option_list + (

readthedocs/core/management/commands/update_api.py

@@ -9,6 +9,7 @@
 
 
 class Command(BaseCommand):
+
     """
     Build documentation using the API and not hitting a database.
 

readthedocs/core/management/commands/update_repos.py

@@ -12,8 +12,10 @@
 
 class Command(BaseCommand):
 
-    """Custom management command to rebuild documentation for all projects on
-    the site. Invoked via ``./manage.py update_repos``.
+    """
+    Custom management command to rebuild documentation for all projects.
+
+    Invoked via ``./manage.py update_repos``.
     """
 
     option_list = BaseCommand.option_list + (

readthedocs/core/management/commands/update_versions.py

@@ -5,8 +5,11 @@
 
 
 class Command(BaseCommand):
-    """Custom management command to rebuild documentation for all projects on
-    the site. Invoked via ``./manage.py update_repos``.
+
+    """
+    Custom management command to rebuild documentation for all projects.
+
+    Invoked via ``./manage.py update_repos``.
     """
 
     def handle(self, *args, **options):

readthedocs/core/middleware.py

@@ -178,6 +178,7 @@ class ProxyMiddleware(object):
 
     """
     Middleware that sets REMOTE_ADDR based on HTTP_X_FORWARDED_FOR, if the
+
     latter is set. This is useful if you're sitting behind a reverse proxy that
     causes each request's REMOTE_ADDR to be set to 127.0.0.1.
     Note that this does NOT validate HTTP_X_FORWARDED_FOR. If you're not behind
@@ -207,6 +208,7 @@ class FooterNoSessionMiddleware(SessionMiddleware):
 
     This will reduce the size of our session table drastically.
     """
+
     IGNORE_URLS = ['/api/v2/footer_html', '/sustainability/view', '/sustainability/click']
 
     def process_request(self, request):

readthedocs/core/mixins.py

@@ -1,6 +1,4 @@
-"""
-Common mixin classes for views
-"""
+"""Common mixin classes for views"""
 
 from vanilla import ListView
 from django.contrib.auth.decorators import login_required

readthedocs/core/models.py

@@ -14,8 +14,8 @@
 
 class UserProfile (models.Model):
 
-    """Additional information about a User.
-    """
+    """Additional information about a User."""
+
     user = AutoOneToOneField('auth.User', verbose_name=_('User'),
                              related_name='profile')
     whitelisted = models.BooleanField(_('Whitelisted'), default=False)

readthedocs/core/symlink.py

@@ -69,6 +69,7 @@
 
 
 class Symlink(object):
+
     """Base class for symlinking of projects."""
 
     def __init__(self, project):

readthedocs/core/templatetags/core_tags.py

@@ -14,10 +14,11 @@
 
 @register.filter
 def gravatar(email, size=48):
-    """hacked from djangosnippets.org, but basically given an email address
+    """
+    hacked from djangosnippets.org, but basically given an email address
+
     render an img tag with the hashed up bits needed for leetness
     omgwtfstillreading
-
     """
     url = "http://www.gravatar.com/avatar.php?%s" % urllib.urlencode({
         'gravatar_id': hashlib.md5(email).hexdigest(),

readthedocs/core/utils/__init__.py

@@ -16,9 +16,7 @@
 
 
 def run_on_app_servers(command):
-    """
-    A helper to copy a single file across app servers
-    """
+    """A helper to copy a single file across app servers"""
     log.info("Running %s on app servers" % command)
     ret_val = 0
     if getattr(settings, "MULTIPLE_APP_SERVERS", None):

readthedocs/core/utils/tasks/public.py

@@ -14,25 +14,22 @@
 
 
 class PublicTask(Task):
+
     """
     See oauth.tasks for usage example.
 
     Subclasses need to define a ``run_public`` method.
     """
+
     public_name = 'unknown'
 
     @classmethod
     def check_permission(cls, request, state, context):
-        """
-        Override this method to define who can monitor this task.
-        """
+        """Override this method to define who can monitor this task."""
         return False
 
     def get_task_data(self):
-        """
-        Return a tuple with the state that should be set next and the results
-        task.
-        """
+        """Return tuple with state to be set next and results task."""
         state = 'STARTED'
         info = {
             'task_name': self.name,
@@ -49,6 +46,7 @@ def update_progress_data(self):
     def set_permission_context(self, context):
         """
         Set data that can be used by ``check_permission`` to authorize a
+
         request for the this task. By default it will be the ``kwargs`` passed
         into the task.
         """
@@ -58,6 +56,7 @@ def set_permission_context(self, context):
     def set_public_data(self, data):
         """
         Set data that can be displayed in the frontend to authorized users.
+
         This might include progress data about the task.
         """
         self.request.update(public_data=data)
@@ -83,14 +82,14 @@ def after_return(self, status, retval, task_id, args, kwargs, einfo):
 def permission_check(check):
     """
     Class decorator for subclasses of PublicTask to sprinkle in re-usable
+
     permission checks::
 
         @permission_check(user_id_matches)
         class MyTask(PublicTask):
             def run_public(self, user_id):
                 pass
     """
-
     def decorator(cls):
         cls.check_permission = staticmethod(check)
         return cls

readthedocs/core/utils/tasks/retrieve.py

@@ -14,9 +14,9 @@ def __init__(self, task_id, *args, **kwargs):
 def get_task_data(task_id):
     """
     Will raise `TaskNotFound` if the task is in state ``PENDING`` or the task
+
     meta data has no ``'task_name'`` key set.
     """
-
     result = AsyncResult(task_id)
     state, info = result.state, result.info
     if state == 'PENDING':