refactor collection filters with django_filters

This MR aims to re-implement existing collection filters in api viewsets that are implemented in get_queryset methods with django-filter filtersets.

This has multiple advantages:

• DRF will auto-generate a filter form for the filterset fields when browsing the API with the browser, making it easier to browse & filter collections.
• Filter values can easily be validated and most are validated out-of-the-box.
• Filter documentation can be added per filter.
• django_filter is supported by drf-spectecular, which will generate a nice and tidy OpenAPI documentation for us.

program/filters.py

+import datetime
+
 from django_filters import rest_framework as filters
 
+from django import forms
 from django.contrib.auth.models import User
 from django.db.models import Q, QuerySet
 from django.utils import timezone
@@ -90,3 +93,88 @@ class ShowFilterSet(StaticFilterHelpTextMixin, filters.FilterSet):
             "topic",
             "type",
         ]
+
+
+class TimeSlotFilterSet(filters.FilterSet):
+    order = filters.OrderingFilter(
+        fields=[field.name for field in models.TimeSlot._meta.get_fields()]
+    )
+    surrounding = filters.BooleanFilter(
+        method="filter_surrounding",
+        label="Return surrounding timeslots",
+        help_text=(
+            "Returns the 10 nearest timeslots for the current date if set to true. "
+            "No filtering is performed if set to false. "
+            "If specified without a value true is assumed."
+        ),
+    )
+    # The start/end filters will always be applied even if no query parameter has been set.
+    # This is because we enforce a value in the clean_start and clean_end methods
+    # of the filterset form.
+    start = filters.DateFilter(
+        method="filter_start",
+        help_text=(
+            "Only returns timeslots after that start on or after the specified date. "
+            "By default, this is set to the current date."
+        ),
+    )
+    end = filters.DateFilter(
+        method="filter_end",
+        help_text=(
+            "Only returns timeslots that end on or before the specified date. "
+            "By default, this is set to value of the start filter + 60 days."
+        ),
+    )
+
+    def filter_surrounding(self, queryset: QuerySet, name: str, value: bool):
+        if value is not True:
+            return queryset
+        start = self.form.cleaned_data.get("start", None) or timezone.now()
+        nearest_timeslots_in_future = (
+            models.TimeSlot.objects.filter(start__gte=start)
+            .order_by("start")
+            .values_list("id", flat=True)[:5]
+        )
+        nearest_timeslots_in_past = (
+            models.TimeSlot.objects.filter(start__lt=start)
+            .order_by("-start")
+            .values_list("id", flat=True)[:5]
+        )
+        relevant_timeslot_ids = list(nearest_timeslots_in_future) + list(
+            nearest_timeslots_in_past
+        )
+        return queryset.filter(id__in=relevant_timeslot_ids)
+
+    def filter_start(self, queryset: QuerySet, name: str, value: datetime.date):
+        start = timezone.make_aware(datetime.datetime.combine(value, datetime.time.min))
+        return queryset.filter(start__gte=start)
+
+    def filter_end(self, queryset: QuerySet, name: str, value: datetime.date):
+        end = timezone.make_aware(datetime.datetime.combine(value, datetime.time.max))
+        return queryset.filter(end__lte=end)
+
+    def filter_queryset(self, queryset):
+        queryset = super().filter_queryset(queryset)
+        # This is for backwards compatibility as the surrounding-filter was formerly implemented
+        # by just checking for the existence of the query parameter.
+        if self.request.GET.get("surrounding", None) == "":
+            queryset = self.filter_surrounding(queryset, "surrounding", True)
+        return queryset
+
+    class Meta:
+        model = models.TimeSlot
+        fields = [
+            "order",
+            "start",
+            "end",
+            "surrounding",
+        ]
+
+        class form(forms.Form):
+            def clean_start(self):
+                start = self.cleaned_data.get("start", None)
+                return start or timezone.now().date()
+
+            def clean_end(self):
+                end = self.cleaned_data.get("end", None)
+                return end or self.cleaned_data["start"] + datetime.timedelta(days=60)