Add project/build filters

agjohnson · agjohnson · commit 57d6fbb56b46 · 2021-05-26T17:34:11.000-06:00
Most of these filters are currently only used in views when the new
templates are enabled. The project dashboard view context data was
replaced with a filter, which does enable sorting on the dashboard view
using request arguments (like `?sort=built_last`), but this isn't
exposed in the UI.
diff --git a/readthedocs/builds/filters.py b/readthedocs/builds/filters.py
@@ -0,0 +1,43 @@
+import logging
+
+from django.forms.widgets import HiddenInput
+from django.utils.translation import ugettext_lazy as _
+from django_filters import CharFilter, ChoiceFilter, FilterSet
+
+from readthedocs.builds.constants import BUILD_STATE_FINISHED
+
+log = logging.getLogger(__name__)
+
+
+class BuildListFilter(FilterSet):
+
+    STATE_ACTIVE = 'active'
+    STATE_SUCCESS = 'succeeded'
+    STATE_FAILED = 'failed'
+
+    STATE_CHOICES = (
+        (STATE_ACTIVE, _('Active')),
+        (STATE_SUCCESS, _('Build finished')),
+        (STATE_FAILED, _('Build failed')),
+    )
+
+    # Attribute filter fields
+    version = CharFilter(field_name='version__slug', widget=HiddenInput)
+    state = ChoiceFilter(
+        label=_('State'),
+        choices=STATE_CHOICES,
+        empty_label=_('Any'),
+        method='get_state',
+    )
+
+    def get_state(self, queryset, name, value):
+        if value == self.STATE_ACTIVE:
+            queryset = queryset.exclude(state=BUILD_STATE_FINISHED)
+        elif value == self.STATE_SUCCESS:
+            queryset = queryset.filter(state=BUILD_STATE_FINISHED, success=True)
+        elif value == self.STATE_FAILED:
+            queryset = queryset.filter(
+                state=BUILD_STATE_FINISHED,
+                success=False,
+            )
+        return queryset
diff --git a/readthedocs/builds/views.py b/readthedocs/builds/views.py
@@ -4,25 +4,23 @@
 import textwrap
 from urllib.parse import urlparse
 
+from django.conf import settings
 from django.contrib import messages
 from django.contrib.auth.decorators import login_required
-from django.http import (
-    HttpResponseForbidden,
-    HttpResponseRedirect,
-)
+from django.http import HttpResponseForbidden, HttpResponseRedirect
 from django.shortcuts import get_object_or_404
 from django.urls import reverse
 from django.utils.decorators import method_decorator
 from django.views.generic import DetailView, ListView
 from requests.utils import quote
 
+from readthedocs.builds.filters import BuildListFilter
 from readthedocs.builds.models import Build, Version
 from readthedocs.core.permissions import AdminPermission
 from readthedocs.core.utils import trigger_build
 from readthedocs.doc_builder.exceptions import BuildEnvironmentError
 from readthedocs.projects.models import Project
 
-
 log = logging.getLogger(__name__)
 
 
@@ -97,7 +95,13 @@ def get_context_data(self, **kwargs):  # pylint: disable=arguments-differ
         context['project'] = self.project
         context['active_builds'] = active_builds
         context['versions'] = self._get_versions(self.project)
-        context['build_qs'] = self.get_queryset()
+
+        builds = self.get_queryset()
+        if settings.RTD_EXT_THEME_ENABLED:
+            filter = BuildListFilter(self.request.GET, queryset=builds)
+            context['filter'] = filter
+            builds = filter.qs
+        context['build_qs'] = builds
 
         return context
 
diff --git a/readthedocs/projects/filters.py b/readthedocs/projects/filters.py
@@ -0,0 +1,158 @@
+import logging
+
+from django.db.models import Count, F, Max
+from django.forms.widgets import HiddenInput
+from django.utils.translation import ugettext_lazy as _
+from django_filters import CharFilter, ChoiceFilter, FilterSet, OrderingFilter
+
+log = logging.getLogger(__name__)
+
+
+class SortOrderingFilter(OrderingFilter):
+
+    """
+    Version list sort ordering django_filters filter.
+
+    Django-filter is highly opionated, and the default model filters do not work
+    well with empty/null values in the filter choices. In our case, empty/null
+    values are used for a default query. So, to make this work, we will use a
+    custom filter, instead of an automated model filter.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.extra['choices'] = [
+            ('name', _('Name')),
+            ('-name', _('Name (descending)')),
+            ('-recent', _('Most recently built')),
+            ('recent', _('Least recently built')),
+        ]
+
+    def filter(self, qs, value):
+        # This is where we use the None value for this custom filter. This
+        # doesn't work with a standard model filter.
+        if value is None:
+            value = ['relevance']
+        return qs.annotate(
+            # Default ordering is number of builds, but could be another proxy
+            # for version populatrity
+            relevance=Count('builds'),
+            # Most recent build date, this appears inverted in the option value
+            recent=Max('builds__date'),
+            # Alias field name here, as ``OrderingFilter`` was having trouble
+            # doing this with it's native field mapping
+            name=F('verbose_name'),
+        ).order_by(*value)
+
+
+class ProjectSortOrderingFilter(OrderingFilter):
+
+    """
+    Project list sort ordering django_filters filter.
+
+    Django-filter is highly opionated, and the default model filters do not work
+    well with empty/null values in the filter choices. In our case, empty/null
+    values are used for a default query. So, to make this work, we will use a
+    custom filter, instead of an automated model filter.
+    """
+
+    SORT_NAME = 'name'
+    SORT_MODIFIED_DATE = 'modified_date'
+    SORT_BUILD_DATE = 'built_last'
+    SORT_BUILD_COUNT = 'build_count'
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.extra['choices'] = [
+            (f'-{self.SORT_NAME}', _('Name (descending)')),
+            (f'-{self.SORT_MODIFIED_DATE}', _('Most recently modified')),
+            (self.SORT_MODIFIED_DATE, _('Least recently modified')),
+            (self.SORT_BUILD_DATE, _('Most recently built')),
+            (f'-{self.SORT_BUILD_DATE}', _('Least recently built')),
+            (f'-{self.SORT_BUILD_COUNT}', _('Most frequently built')),
+            (self.SORT_BUILD_COUNT, _('Least frequently built')),
+        ]
+
+    def filter(self, qs, value):
+        # This is where we use the None value from the custom filter
+        if value is None:
+            value = [self.SORT_NAME]
+        return qs.annotate(
+            **{
+                self.SORT_BUILD_DATE: Max('versions__builds__date'),
+                self.SORT_BUILD_COUNT: Count('versions__builds'),
+            }
+        ).order_by(*value)
+
+
+class ProjectListFilterSet(FilterSet):
+
+    """
+    Project list filter set for project list view.
+
+    This filter set enables list view sorting using a custom filter, and
+    provides search-as-you-type lookup filter as well.
+    """
+
+    project = CharFilter(field_name='slug', widget=HiddenInput)
+    sort = ProjectSortOrderingFilter(
+        field_name='sort',
+        label=_('Sort by'),
+        empty_label=_('Name'),
+    )
+
+
+class ProjectVersionListFilterSet(FilterSet):
+
+    """
+    Filter and sorting for project version listing page.
+
+    This is used from the project versions list view page to provide filtering
+    and sorting to the version list and search UI. It is normally instantiated
+    with an included queryset, which provides user project authorization.
+    """
+
+    VISIBILITY_HIDDEN = 'hidden'
+    VISIBILITY_VISIBLE = 'visible'
+
+    VISIBILITY_CHOICES = (
+        ('hidden', _('Hidden versions')),
+        ('visible', _('Visible versions')),
+    )
+
+    PRIVACY_CHOICES = (
+        ('public', _('Public versions')),
+        ('private', _('Private versions')),
+    )
+
+    # Attribute filter fields
+    version = CharFilter(field_name='slug', widget=HiddenInput)
+    privacy = ChoiceFilter(
+        field_name='privacy_level',
+        label=_('Privacy'),
+        choices=PRIVACY_CHOICES,
+        empty_label=_('Any'),
+    )
+    # This field looks better as ``visibility=hidden`` than it does
+    # ``hidden=true``, otherwise we could use a BooleanFilter instance here
+    # instead
+    visibility = ChoiceFilter(
+        field_name='hidden',
+        label=_('Visibility'),
+        choices=VISIBILITY_CHOICES,
+        method='get_visibility',
+        empty_label=_('Any'),
+    )
+
+    sort = ProjectSortOrderingFilter(
+        field_name='sort',
+        label=_('Sort by'),
+        empty_label=_('Relevance'),
+    )
+
+    def get_visibility(self, queryset, name, value):
+        if value == self.VISIBILITY_HIDDEN:
+            return queryset.filter(hidden=True)
+        if value == self.VISIBILITY_VISIBLE:
+            return queryset.filter(hidden=False)
+        return queryset
diff --git a/readthedocs/projects/views/private.py b/readthedocs/projects/views/private.py
@@ -51,6 +51,7 @@
 from readthedocs.oauth.tasks import attach_webhook
 from readthedocs.oauth.utils import update_webhook
 from readthedocs.projects import tasks
+from readthedocs.projects.filters import ProjectListFilterSet
 from readthedocs.projects.forms import (
     DomainForm,
     EmailHookForm,
@@ -100,6 +101,13 @@ def get_context_data(self, **kwargs):
         context = super().get_context_data(**kwargs)
         # Set the default search to search files instead of projects
         context['type'] = 'file'
+
+        filter = ProjectListFilterSet(self.request.GET, queryset=self.get_queryset())
+        context['filter'] = filter
+        context['project_list'] = filter.qs
+        # Alternatively, dynamically override super()-derived `project_list` context_data
+        # context[self.get_context_object_name(filter.qs)] = filter.qs
+
         return context
 
     def validate_primary_email(self, user):
diff --git a/readthedocs/projects/views/public.py b/readthedocs/projects/views/public.py
@@ -31,6 +31,7 @@
 from readthedocs.builds.views import BuildTriggerMixin
 from readthedocs.core.permissions import AdminPermission
 from readthedocs.core.utils.extend import SettingsOverrideObject
+from readthedocs.projects.filters import ProjectVersionListFilterSet
 from readthedocs.projects.models import Project
 from readthedocs.projects.templatetags.projects_tags import sort_version_aware
 from readthedocs.projects.views.mixins import ProjectRelationListMixin
@@ -86,12 +87,8 @@ def project_redirect(request, invalid_project_slug):
     ))
 
 
-class ProjectDetailViewBase(
-        ProjectRelationListMixin,
-        BuildTriggerMixin,
-        ProjectOnboardMixin,
-        DetailView
-):
+class ProjectDetailViewBase(ProjectRelationListMixin, BuildTriggerMixin,
+                            ProjectOnboardMixin, DetailView):
 
     """Display project onboard steps."""
 
@@ -108,7 +105,17 @@ def get_context_data(self, **kwargs):
         context = super().get_context_data(**kwargs)
 
         project = self.get_project()
-        context['versions'] = self._get_versions(project)
+
+        # Get filtered and sorted versions
+        versions = self._get_versions(project)
+        if settings.RTD_EXT_THEME_ENABLED:
+            filter = ProjectVersionListFilterSet(
+                self.request.GET,
+                queryset=versions,
+            )
+            context['filter'] = filter
+            versions = filter.qs
+        context['versions'] = versions
 
         protocol = 'http'
         if self.request.is_secure():
