Merge pull request #2938 from rtfd/restapi-linting-less

Fix linting problems with restapi application

Author: ericholscher

prospector-more.yml

@@ -2,9 +2,6 @@ inherits: prospector
 
 strictness: medium
 
-ignore-paths:
-  - restapi/
-
 pylint:
   options:
     docstring-min-length: 20

readthedocs/restapi/client.py

@@ -1,3 +1,4 @@
+"""Simple client to access our API with Slumber credentials."""
 import logging
 
 from slumber import API, serialize

readthedocs/restapi/permissions.py

@@ -1,3 +1,4 @@
+"""Defines access permissions for the API."""
 from rest_framework import permissions
 from readthedocs.privacy.backend import AdminPermission
 

readthedocs/restapi/serializers.py

@@ -1,3 +1,4 @@
+"""Defines serializers for each of our models."""
 from rest_framework import serializers
 
 from readthedocs.builds.models import Build, BuildCommandResult, Version

readthedocs/restapi/signals.py

@@ -1,3 +1,4 @@
+"""We define custom Django signals to trigger when a footer is rendered."""
 import django.dispatch
 
 footer_response = django.dispatch.Signal(

readthedocs/restapi/urls.py

@@ -1,3 +1,4 @@
+"""Define routes between URL paths and views/endpoints."""
 from django.conf.urls import url, include
 
 from rest_framework import routers

readthedocs/restapi/utils.py

@@ -1,16 +1,15 @@
+"""Utility functions that are used by both views and celery tasks."""
 import hashlib
 import logging
 
-import requests
-
 from readthedocs.builds.constants import NON_REPOSITORY_VERSIONS
 from readthedocs.builds.models import Version
 from readthedocs.search.indexes import PageIndex, ProjectIndex, SectionIndex
 
 log = logging.getLogger(__name__)
 
 
-def sync_versions(project, versions, type):
+def sync_versions(project, versions, type):  # pylint: disable=redefined-builtin
     """Update the database with the current versions from the repository."""
     # Bookkeeping for keeping tag/branch identifies correct
     verbose_names = [v['verbose_name'] for v in versions]
@@ -39,8 +38,8 @@ def sync_versions(project, versions, type):
                     type=type,
                     machine=False,
                 )
-                log.info("(Sync Versions) Updated Version: [%s=%s] " % (
-                    version['verbose_name'], version['identifier']))
+                log.info("(Sync Versions) Updated Version: [%s=%s] ",
+                         version['verbose_name'], version['identifier'])
         else:
             # New Version
             created_version = Version.objects.create(
@@ -51,7 +50,7 @@ def sync_versions(project, versions, type):
             )
             added.add(created_version.slug)
     if added:
-        log.info("(Sync Versions) Added Versions: [%s] " % ' '.join(added))
+        log.info("(Sync Versions) Added Versions: [%s] ", ' '.join(added))
     return added
 
 
@@ -72,7 +71,7 @@ def delete_versions(project, version_data):
 
     if to_delete_qs.count():
         ret_val = {obj.slug for obj in to_delete_qs}
-        log.info("(Sync Versions) Deleted Versions: [%s]" % ' '.join(ret_val))
+        log.info("(Sync Versions) Deleted Versions: [%s]", ' '.join(ret_val))
         to_delete_qs.delete()
         return ret_val
     else:
@@ -86,6 +85,8 @@ def index_search_request(version, page_list, commit, project_scale, page_scale,
     In order to keep sub-projects all indexed on the same shard, indexes will be
     updated using the parent project's slug as the routing value.
     """
+    # TODO refactor this function
+    # pylint: disable=too-many-locals
     project = version.project
 
     log_msg = ' '.join([page['path'] for page in page_list])
@@ -112,7 +113,7 @@ def index_search_request(version, page_list, commit, project_scale, page_scale,
     routes = [project.slug]
     routes.extend([p.parent.slug for p in project.superprojects.all()])
     for page in page_list:
-        log.debug("Indexing page: %s:%s" % (project.slug, page['path']))
+        log.debug("Indexing page: %s:%s", project.slug, page['path'])
         page_id = (hashlib
                    .md5('-'.join([project.slug, version.slug, page['path']]))
                    .hexdigest())
@@ -129,18 +130,18 @@ def index_search_request(version, page_list, commit, project_scale, page_scale,
             'weight': page_scale + project_scale,
         })
         if section:
-            for section in page['sections']:
+            for sect in page['sections']:
                 section_index_list.append({
                     'id': (hashlib
                            .md5('-'.join([project.slug, version.slug,
-                                         page['path'], section['id']]))
+                                         page['path'], sect['id']]))
                            .hexdigest()),
                     'project': project.slug,
                     'version': version.slug,
                     'path': page['path'],
-                    'page_id': section['id'],
-                    'title': section['title'],
-                    'content': section['content'],
+                    'page_id': sect['id'],
+                    'title': sect['title'],
+                    'content': sect['content'],
                     'weight': page_scale,
                 })
             for route in routes:

readthedocs/restapi/views/core_views.py

@@ -1,3 +1,4 @@
+"""Utility endpoints relating to canonical urls, embedded content, etc."""
 from rest_framework import decorators, permissions, status
 from rest_framework.renderers import JSONRenderer
 from rest_framework.response import Response

readthedocs/restapi/views/footer_views.py

@@ -1,3 +1,4 @@
+"""Endpoint to generate footer HTML."""
 from django.shortcuts import get_object_or_404
 from django.template import RequestContext, loader as template_loader
 from django.conf import settings
@@ -18,6 +19,11 @@
 
 
 def get_version_compare_data(project, base_version=None):
+    """Retrieve metadata about the highest version available for this project.
+
+    :param base_version: We assert whether or not the base_version is also the
+                         highest version in the resulting "is_highest" value.
+    """
     highest_version_obj, highest_version_comparable = highest_version(
         project.versions.public().filter(active=True))
     ret_val = {
@@ -48,6 +54,9 @@ def get_version_compare_data(project, base_version=None):
 @decorators.permission_classes((permissions.AllowAny,))
 @decorators.renderer_classes((JSONRenderer, JSONPRenderer))
 def footer_html(request):
+    """Render and return footer markup."""
+    # TODO refactor this function
+    # pylint: disable=too-many-locals
     project_slug = request.GET.get('project', None)
     version_slug = request.GET.get('version', None)
     page_slug = request.GET.get('page', None)

readthedocs/restapi/views/integrations.py

@@ -1,14 +1,14 @@
+"""Endpoints integrating with Github, Bitbucket, and other webhooks."""
 import json
 import logging
 
 from rest_framework import permissions
 from rest_framework.views import APIView
 from rest_framework.renderers import JSONRenderer
 from rest_framework.response import Response
-from rest_framework.exceptions import APIException, ParseError, NotFound
+from rest_framework.exceptions import ParseError, NotFound
 
 from django.shortcuts import get_object_or_404
-from django.http import Http404
 
 from readthedocs.core.views.hooks import build_branches
 from readthedocs.core.signals import (webhook_github, webhook_bitbucket,
@@ -27,12 +27,14 @@
 
 class WebhookMixin(object):
 
+    """Base class for Webhook mixins."""
+
     permission_classes = (permissions.AllowAny,)
     renderer_classes = (JSONRenderer,)
     integration = None
     integration_type = None
 
-    def post(self, request, project_slug, format=None):
+    def post(self, request, project_slug):
         """Set up webhook post view with request and project objects"""
         self.request = request
         self.project = None

readthedocs/restapi/views/model_views.py

@@ -1,3 +1,4 @@
+"""Endpoints for listing Projects, Versions, Builds, etc."""
 import logging
 
 from django.shortcuts import get_object_or_404
@@ -12,7 +13,6 @@
 from readthedocs.core.utils import trigger_build
 from readthedocs.oauth.services import GitHubService, registry
 from readthedocs.oauth.models import RemoteOrganization, RemoteRepository
-from readthedocs.builds.constants import STABLE
 from readthedocs.projects.models import Project, EmailHook, Domain
 from readthedocs.projects.version_handling import determine_stable_version
 
@@ -29,6 +29,9 @@
 
 
 class ProjectViewSet(viewsets.ModelViewSet):
+
+    """List, filter, etc. Projects."""
+
     permission_classes = [APIPermission]
     renderer_classes = (JSONRenderer,)
     serializer_class = ProjectSerializer
@@ -44,7 +47,7 @@ def get_queryset(self):
     def valid_versions(self, request, **kwargs):
         """Maintain state of versions that are wanted."""
         project = get_object_or_404(
-            Project.objects.api(self.request.user), pk=kwargs['pk'])
+            Project.objects.api(request.user), pk=kwargs['pk'])
         if not project.num_major or not project.num_minor or not project.num_point:
             return Response(
                 {'error': 'Project does not support point version control'},
@@ -59,7 +62,7 @@ def valid_versions(self, request, **kwargs):
         })
 
     @detail_route()
-    def translations(self, request, pk, **kwargs):
+    def translations(self, *_, **__):
         translations = self.get_object().translations.all()
         return Response({
             'translations': ProjectSerializer(translations, many=True).data
@@ -68,7 +71,7 @@ def translations(self, request, pk, **kwargs):
     @detail_route()
     def subprojects(self, request, **kwargs):
         project = get_object_or_404(
-            Project.objects.api(self.request.user), pk=kwargs['pk'])
+            Project.objects.api(request.user), pk=kwargs['pk'])
         rels = project.subprojects.all()
         children = [rel.child for rel in rels]
         return Response({
@@ -78,7 +81,7 @@ def subprojects(self, request, **kwargs):
     @decorators.detail_route(permission_classes=[permissions.IsAdminUser])
     def token(self, request, **kwargs):
         project = get_object_or_404(
-            Project.objects.api(self.request.user), pk=kwargs['pk'])
+            Project.objects.api(request.user), pk=kwargs['pk'])
         token = GitHubService.get_token_for_project(project, force_local=True)
         return Response({
             'token': token
@@ -87,7 +90,7 @@ def token(self, request, **kwargs):
     @decorators.detail_route()
     def canonical_url(self, request, **kwargs):
         project = get_object_or_404(
-            Project.objects.api(self.request.user), pk=kwargs['pk'])
+            Project.objects.api(request.user), pk=kwargs['pk'])
         return Response({
             'url': project.get_docs_url()
         })
@@ -100,7 +103,7 @@ def sync_versions(self, request, **kwargs):
         Returns the identifiers for the versions that have been deleted.
         """
         project = get_object_or_404(
-            Project.objects.api(self.request.user), pk=kwargs['pk'])
+            Project.objects.api(request.user), pk=kwargs['pk'])
 
         # If the currently highest non-prerelease version is active, then make
         # the new latest version active as well.
@@ -124,7 +127,7 @@ def sync_versions(self, request, **kwargs):
                 added_versions.update(ret_set)
             deleted_versions = api_utils.delete_versions(project, data)
         except Exception, e:
-            log.exception("Sync Versions Error: %s" % e.message)
+            log.exception("Sync Versions Error: %s", e.message)
             return Response({'error': e.message}, status=status.HTTP_400_BAD_REQUEST)
 
         promoted_version = project.update_stable_version()

readthedocs/restapi/views/search_views.py

@@ -1,3 +1,4 @@
+"""Endpoints related to searching through projects, sections, etc."""
 import logging
 
 from rest_framework import decorators, permissions, status

readthedocs/restapi/views/task_views.py

@@ -1,3 +1,4 @@
+"""Endpoints relating to task/job status, etc."""
 import logging
 
 from django.core.urlresolvers import reverse