AKPlan/models.py

-# Create your models here.

AKPlan/templatetags/color_gradients.py

 # gradients based on http://bsou.io/posts/color-gradients-with-python
 
 
-def hex_to_rgb(hex):
+def hex_to_rgb(hex): #pylint: disable=redefined-builtin
     """
     Convert hex color to RGB color code
     :param hex: hex encoded color
@@ -23,8 +23,7 @@ def rgb_to_hex(rgb):
     """
     # Components need to be integers for hex to make sense
     rgb = [int(x) for x in rgb]
-    return "#"+"".join(["0{0:x}".format(v) if v < 16 else
-                        "{0:x}".format(v) for v in rgb])
+    return "#"+"".join([f"0{v:x}" if v < 16 else f"{v:x}" for v in rgb])
 
 
 def linear_blend(start_hex, end_hex, position):

AKPlan/templatetags/tags_AKPlan.py

@@ -11,6 +11,14 @@ register = template.Library()
 
 @register.filter
 def highlight_change_colors(akslot):
+    """
+    Adjust color to highlight recent changes if needed
+
+    :param akslot: akslot to determine color for
+    :type akslot: AKSlot
+    :return: color that should be used (either default color of the category or some kind of red)
+    :rtype: str
+    """
     # Do not highlight in preview mode or when changes occurred before the plan was published
     if akslot.event.plan_hidden or (akslot.event.plan_published_at is not None
                                     and akslot.event.plan_published_at > akslot.updated):
@@ -25,9 +33,14 @@ def highlight_change_colors(akslot):
     # Recent change? Calculate gradient blend between red and
     recentness = seconds_since_update / settings.PLAN_MAX_HIGHLIGHT_UPDATE_SECONDS
     return darken("#b71540", recentness)
-    # return linear_blend("#b71540", "#000000", recentness)
 
 
 @register.simple_tag
 def timestamp_now(tz):
+    """
+    Get the current timestamp for the given timezone
+
+    :param tz: timezone to be used for the timestamp
+    :return: current timestamp in given timezone
+    """
     return date_format(datetime.now().astimezone(tz), "c")

AKPlan/tests.py

@@ -4,6 +4,9 @@ from AKModel.tests import BasicViewTests
 
 
 class PlanViewTests(BasicViewTests, TestCase):
+    """
+    Tests for AKPlan
+    """
     fixtures = ['model.json']
     APP_NAME = 'plan'
 
@@ -15,7 +18,10 @@ class PlanViewTests(BasicViewTests, TestCase):
     ]
 
     def test_plan_hidden(self):
-        view_name_with_prefix, url = self._name_and_url(('plan_overview', {'event_slug': 'kif23'}))
+        """
+        Test correct handling of plan visibility
+        """
+        _, url = self._name_and_url(('plan_overview', {'event_slug': 'kif23'}))
 
         self.client.logout()
         response = self.client.get(url)
@@ -28,8 +34,11 @@ class PlanViewTests(BasicViewTests, TestCase):
                                msg_prefix="Plan is not visible for staff user")
 
     def test_wall_redirect(self):
-        view_name_with_prefix, url_wall = self._name_and_url(('plan_wall', {'event_slug': 'kif23'}))
-        view_name_with_prefix, url_plan = self._name_and_url(('plan_overview', {'event_slug': 'kif23'}))
+        """
+        Test: Make sure that user is redirected from wall to overview when plan is hidden
+        """
+        _, url_wall = self._name_and_url(('plan_wall', {'event_slug': 'kif23'}))
+        _, url_plan = self._name_and_url(('plan_overview', {'event_slug': 'kif23'}))
 
         response = self.client.get(url_wall)
         self.assertRedirects(response, url_plan,

AKPlan/views.py

-from datetime import timedelta
-
 from django.conf import settings
 from django.shortcuts import redirect
 from django.urls import reverse_lazy
@@ -11,6 +9,11 @@ from AKModel.metaviews.admin import FilterByEventSlugMixin
 
 
 class PlanIndexView(FilterByEventSlugMixin, ListView):
+    """
+    Default plan view
+
+    Shows two lists of current and upcoming AKs and a graphical full plan below
+    """
     model = AKSlot
     template_name = "AKPlan/plan_index.html"
     context_object_name = "akslots"
@@ -60,6 +63,15 @@ class PlanIndexView(FilterByEventSlugMixin, ListView):
 
 
 class PlanScreenView(PlanIndexView):
+    """
+    Plan view optimized for screens and projectors
+
+    This again shows current and upcoming AKs as well as a graphical plan,
+    but no navigation elements and trys to use the available space as best as possible
+    such that no scrolling is needed.
+
+    The view contains a frontend functionality for auto-reload.
+    """
     template_name = "AKPlan/plan_wall.html"
 
     def get(self, request, *args, **kwargs):
@@ -92,22 +104,34 @@ class PlanScreenView(PlanIndexView):
 
 
 class PlanRoomView(FilterByEventSlugMixin, DetailView):
+    """
+    Plan view for a single room
+    """
     template_name = "AKPlan/plan_room.html"
     model = Room
     context_object_name = "room"
 
     def get_context_data(self, *, object_list=None, **kwargs):
         context = super().get_context_data(object_list=object_list, **kwargs)
+        # Restrict AKSlot list to the given room
+        # while joining AK, room and category information to reduce the amount of necessary SQL queries
         context["slots"] = AKSlot.objects.filter(room=context['room']).select_related('ak', 'ak__category', 'ak__track')
         return context
 
 
 class PlanTrackView(FilterByEventSlugMixin, DetailView):
+    """
+    Plan view for a single track
+    """
     template_name = "AKPlan/plan_track.html"
     model = AKTrack
     context_object_name = "track"
 
     def get_context_data(self, *, object_list=None, **kwargs):
         context = super().get_context_data(object_list=object_list, **kwargs)
-        context["slots"] = AKSlot.objects.filter(event=self.event, ak__track=context['track']).select_related('ak', 'room', 'ak__category')
+        # Restrict AKSlot list to given track
+        # while joining AK, room and category information to reduce the amount of necessary SQL queries
+        context["slots"] = AKSlot.objects.\
+            filter(event=self.event, ak__track=context['track']).\
+            select_related('ak', 'room', 'ak__category')
         return context

AKPlanning/locale/de_DE/LC_MESSAGES/django.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-05-15 20:03+0200\n"
+"POT-Creation-Date: 2023-08-16 16:30+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -17,10 +17,10 @@ msgstr ""
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 
-#: AKPlanning/settings.py:147
+#: AKPlanning/settings.py:148
 msgid "German"
 msgstr "Deutsch"
 
-#: AKPlanning/settings.py:148
+#: AKPlanning/settings.py:149
 msgid "English"
 msgstr "Englisch"

AKPlanning/settings.py

@@ -55,6 +55,7 @@ INSTALLED_APPS = [
     'bootstrap_datepicker_plus',
     'django_tex',
     'compressor',
+    'docs',
 ]
 
 MIDDLEWARE = [
@@ -234,4 +235,9 @@ CSP_FONT_SRC = ("'self'", "data:", "fonts.gstatic.com")
 SEND_MAILS = True
 EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
 
+# Documentation
+
+DOCS_ROOT = os.path.join(BASE_DIR, 'docs/_build/html')
+DOCS_ACCESS = 'public'
+
 include(optional("settings/*.py"))

AKPlanning/urls.py

-"""AKPlanning URL Configuration
+"""
+AKPlanning URL Configuration
 
 The `urlpatterns` list routes URLs to views. For more information please see:
     https://docs.djangoproject.com/en/2.2/topics/http/urls/
@@ -13,13 +14,15 @@ Including another URLconf
     1. Import the include() function: from django.urls import include, path
     2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
 """
+
 import debug_toolbar
 from django.apps import apps
 from django.contrib import admin
-from django.urls import path, include
+from django.urls import path, include, re_path
 
 urlpatterns = [
     path('admin/', admin.site.urls),
+    re_path(r'^docs/', include('docs.urls')),
     path('accounts/', include('django.contrib.auth.urls')),
     path('accounts/', include('registration.backends.simple.urls')),
     path('', include('AKModel.urls', namespace='model')),

AKScheduling/admin.py

-# Register your models here.

AKScheduling/api.py

@@ -12,20 +12,32 @@ from AKModel.metaviews.admin import EventSlugMixin
 
 
 class ResourceSerializer(serializers.ModelSerializer):
+    """
+    REST Framework Serializer for Rooms to produce format required for fullcalendar resources
+    """
     class Meta:
         model = Room
         fields = ['id', 'title']
 
     title = serializers.SerializerMethodField('transform_title')
 
-    def transform_title(self, obj):
+    @staticmethod
+    def transform_title(obj):
+        """
+        Adapt title, add capacity information if room has a restriction (capacity is not -1)
+        """
         if obj.capacity > 0:
             return f"{obj.title} [{obj.capacity}]"
         return obj.title
 
 
-class ResourcesViewSet(EventSlugMixin, mixins.RetrieveModelMixin, mixins.ListModelMixin, viewsets.GenericViewSet):
-    permission_classes = (permissions.DjangoModelPermissionsOrAnonReadOnly,)
+class ResourcesViewSet(EventSlugMixin, mixins.ListModelMixin, viewsets.GenericViewSet):
+    """
+    API View: Rooms (resources to schedule for in fullcalendar)
+
+    Read-only, adaption to fullcalendar format through :class:`ResourceSerializer`
+    """
+    permission_classes = (permissions.DjangoModelPermissions,)
     serializer_class = ResourceSerializer
 
     def get_queryset(self):
@@ -33,6 +45,13 @@ class ResourcesViewSet(EventSlugMixin, mixins.RetrieveModelMixin, mixins.ListMod
 
 
 class EventsView(LoginRequiredMixin, EventSlugMixin, ListView):
+    """
+    API View: Slots (events to schedule in fullcalendar)
+
+    Read-only, JSON formatted response is created manually since it requires a bunch of "custom" fields that have
+    different names compared to the normal model or are not present at all and need to be computed to create the
+    required format for fullcalendar.
+    """
     model = AKSlot
 
     def get_queryset(self):
@@ -48,7 +67,10 @@ class EventsView(LoginRequiredMixin, EventSlugMixin, ListView):
                 "start": timezone.localtime(slot.start, self.event.timezone).strftime("%Y-%m-%d %H:%M:%S"),
                 "end": timezone.localtime(slot.end, self.event.timezone).strftime("%Y-%m-%d %H:%M:%S"),
                 "backgroundColor": slot.ak.category.color,
-                "borderColor": "#2c3e50" if slot.fixed else '#e74c3c' if slot.constraintviolation_set.count() > 0 else slot.ak.category.color,
+                "borderColor":
+                    "#2c3e50" if slot.fixed
+                    else '#e74c3c' if slot.constraintviolation_set.count() > 0
+                    else slot.ak.category.color,
                 "constraint": 'roomAvailable',
                 "editable": not slot.fixed,
                 'url': str(reverse('admin:AKModel_akslot_change', args=[slot.pk])),
@@ -59,6 +81,13 @@ class EventsView(LoginRequiredMixin, EventSlugMixin, ListView):
 
 
 class RoomAvailabilitiesView(LoginRequiredMixin, EventSlugMixin, ListView):
+    """
+    API view: Availabilities of rooms
+
+    Read-only, JSON formatted response is created manually since it requires a bunch of "custom" fields that have
+    different names compared to the normal model or are not present at all and need to be computed to create the
+    required format for fullcalendar.
+    """
     model = Availability
     context_object_name = "availabilities"
 
@@ -81,6 +110,13 @@ class RoomAvailabilitiesView(LoginRequiredMixin, EventSlugMixin, ListView):
 
 
 class DefaultSlotsView(LoginRequiredMixin, EventSlugMixin, ListView):
+    """
+    API view: default slots
+
+    Read-only, JSON formatted response is created manually since it requires a bunch of "custom" fields that have
+    different names compared to the normal model or are not present at all and need to be computed to create the
+    required format for fullcalendar.
+    """
     model = DefaultSlot
     context_object_name = "default_slots"
 
@@ -105,6 +141,9 @@ class DefaultSlotsView(LoginRequiredMixin, EventSlugMixin, ListView):
 
 
 class EventSerializer(serializers.ModelSerializer):
+    """
+    REST framework serializer to adapt between AKSlot model and the event format of fullcalendar
+    """
     class Meta:
         model = AKSlot
         fields = ['id', 'start', 'end', 'roomId']
@@ -114,17 +153,31 @@ class EventSerializer(serializers.ModelSerializer):
     roomId = serializers.IntegerField(source='room.pk')
 
     def update(self, instance, validated_data):
+        # Ignore timezone of input (treat it as timezone-less) and set the event timezone
+        # By working like this, the client does not need to know about timezones, since every timestamp it deals with
+        # has the timezone offsets already applied
         start = timezone.make_aware(timezone.make_naive(validated_data.get('start')), instance.event.timezone)
         end = timezone.make_aware(timezone.make_naive(validated_data.get('end')), instance.event.timezone)
         instance.start = start
-        instance.room = get_object_or_404(Room, pk=validated_data.get('room')["pk"])
+        # Also, adapt from start & end format of fullcalendar to our start & duration model
         diff = end - start
         instance.duration = round(diff.days * 24 + (diff.seconds / 3600), 2)
+
+        # Updated room if needed (pk changed -- otherwise, no need for an additional database lookup)
+        new_room_id = validated_data.get('room')["pk"]
+        if instance.room.pk != new_room_id:
+            instance.room = get_object_or_404(Room, pk=new_room_id)
+
         instance.save()
         return instance
 
 
-class EventsViewSet(EventSlugMixin, viewsets.ModelViewSet):
+class EventsViewSet(EventSlugMixin, mixins.UpdateModelMixin, viewsets.GenericViewSet):
+    """
+    API view: Update scheduling of a slot (event in fullcalendar format)
+
+    Write-only (will however reply with written values to PUT request)
+    """
     permission_classes = (permissions.DjangoModelPermissions,)
     serializer_class = EventSerializer
 
@@ -136,17 +189,26 @@ class EventsViewSet(EventSlugMixin, viewsets.ModelViewSet):
 
 
 class ConstraintViolationSerializer(serializers.ModelSerializer):
+    """
+    REST Framework Serializer for constraint violations
+    """
     class Meta:
         model = ConstraintViolation
-        fields = ['pk', 'type_display', 'aks', 'ak_slots', 'ak_owner', 'room', 'requirement', 'category', 'comment', 'timestamp_display', 'manually_resolved', 'level_display', 'details', 'edit_url']
+        fields = ['pk', 'type_display', 'aks', 'ak_slots', 'ak_owner', 'room', 'requirement', 'category', 'comment',
+                  'timestamp_display', 'manually_resolved', 'level_display', 'details', 'edit_url']
+
 
+class ConstraintViolationsViewSet(EventSlugMixin, mixins.ListModelMixin, viewsets.GenericViewSet):
+    """
+    API View: Constraint Violations of an event
 
-class ConstraintViolationsViewSet(EventSlugMixin, viewsets.ModelViewSet):
+    Read-only, fields and model selected in :class:`ConstraintViolationSerializer`
+    """
     permission_classes = (permissions.DjangoModelPermissions,)
     serializer_class = ConstraintViolationSerializer
 
-    def get_object(self):
-        return get_object_or_404(ConstraintViolation, pk=self.kwargs["pk"])
-
     def get_queryset(self):
-        return ConstraintViolation.objects.select_related('event', 'room').prefetch_related('aks', 'ak_slots', 'ak_owner', 'requirement', 'category').filter(event=self.event).order_by('manually_resolved', '-type', '-timestamp')
+        # Optimize query to reduce database load
+        return (ConstraintViolation.objects.select_related('event', 'room')
+                .prefetch_related('aks', 'ak_slots', 'ak_owner', 'requirement', 'category')
+                .filter(event=self.event).order_by('manually_resolved', '-type', '-timestamp'))

AKScheduling/apps.py

@@ -2,4 +2,7 @@ from django.apps import AppConfig
 
 
 class AkschedulingConfig(AppConfig):
+    """
+    App configuration (default, only specifies name of the app)
+    """
     name = 'AKScheduling'

AKScheduling/forms.py

 from django import forms
+from django.utils.translation import gettext_lazy as _
 
 from AKModel.models import AK
 
 
 class AKInterestForm(forms.ModelForm):
+    """
+    Form for quickly changing the interest count and notes of an AK
+    """
     required_css_class = 'required'
 
     class Meta:
@@ -11,3 +15,17 @@ class AKInterestForm(forms.ModelForm):
         fields = ['interest',
                   'notes',
                   ]
+
+
+class AKAddSlotForm(forms.Form):
+    """
+    Form to create a new slot for an existing AK directly from scheduling view
+    """
+    start = forms.CharField(label=_("Start"), disabled=True)
+    end = forms.CharField(label=_("End"), disabled=True)
+    duration = forms.CharField(label=_("Duration"), disabled=True)
+    room = forms.IntegerField(label=_("Room"), disabled=True)
+
+    def __init__(self, event):
+        super().__init__()
+        self.fields['ak'] = forms.ModelChoiceField(event.ak_set.all(), label=_("AK"))

AKScheduling/locale/de_DE/LC_MESSAGES/django.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-05-15 20:03+0200\n"
+"POT-Creation-Date: 2023-08-16 16:30+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -17,7 +17,28 @@ msgstr ""
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 
-#: AKScheduling/models.py:80
+#: AKScheduling/forms.py:24
+msgid "Start"
+msgstr "Start"
+
+#: AKScheduling/forms.py:25
+msgid "End"
+msgstr "Ende"
+
+#: AKScheduling/forms.py:26
+msgid "Duration"
+msgstr ""
+
+#: AKScheduling/forms.py:27
+#: AKScheduling/templates/admin/AKScheduling/scheduling.html:171
+msgid "Room"
+msgstr "Raum"
+
+#: AKScheduling/forms.py:31
+msgid "AK"
+msgstr "AK"
+
+#: AKScheduling/models.py:92
 #, python-format
 msgid ""
 "Not enough space for AK interest (Interest: %(interest)d, Capacity: "
@@ -26,7 +47,7 @@ msgstr ""
 "Nicht genug Platz für AK-Interesse (Interesse: %(interest)d, Kapazität: "
 "%(capacity)d)"
 
-#: AKScheduling/models.py:92
+#: AKScheduling/models.py:106
 #, python-format
 msgid ""
 "Space is too close to AK interest (Interest: %(interest)d, Capacity: "
@@ -147,10 +168,6 @@ msgstr "Event (horizontal)"
 msgid "Event (Vertical)"
 msgstr "Event (vertikal)"
 
-#: AKScheduling/templates/admin/AKScheduling/scheduling.html:171
-msgid "Room"
-msgstr "Raum"
-
 #: AKScheduling/templates/admin/AKScheduling/scheduling.html:267
 msgid "Please choose AK"
 msgstr "Bitte AK auswählen"
@@ -211,19 +228,19 @@ msgstr "Noch nicht geschedulte AK-Slots"
 msgid "Count"
 msgstr "Anzahl"
 
-#: AKScheduling/views.py:112
+#: AKScheduling/views.py:148
 msgid "Interest updated"
 msgstr "Interesse aktualisiert"
 
-#: AKScheduling/views.py:157
+#: AKScheduling/views.py:199
 msgid "Wishes"
 msgstr "Wünsche"
 
-#: AKScheduling/views.py:165
+#: AKScheduling/views.py:217
 msgid "Cleanup: Delete unscheduled slots for wishes"
 msgstr "Aufräumen: Noch nicht geplante Slots für Wünsche löschen"
 
-#: AKScheduling/views.py:172
+#: AKScheduling/views.py:224
 #, python-brace-format
 msgid ""
 "The following {count} unscheduled slots of wishes will be deleted:\n"
@@ -235,15 +252,15 @@ msgstr ""
 "\n"
 " {slots}"
 
-#: AKScheduling/views.py:179
+#: AKScheduling/views.py:231
 msgid "Unscheduled slots for wishes successfully deleted"
 msgstr "Noch nicht geplante Slots für Wünsche erfolgreich gelöscht"
 
-#: AKScheduling/views.py:184
+#: AKScheduling/views.py:245
 msgid "Create default availabilities for AKs"
 msgstr "Standardverfügbarkeiten für AKs anlegen"
 
-#: AKScheduling/views.py:191
+#: AKScheduling/views.py:252
 #, python-brace-format
 msgid ""
 "The following {count} AKs don't have any availability information. Create "
@@ -256,12 +273,12 @@ msgstr ""
 "\n"
 " {aks}"
 
-#: AKScheduling/views.py:209
+#: AKScheduling/views.py:272
 #, python-brace-format
 msgid "Could not create default availabilities for AK: {ak}"
 msgstr "Konnte keine Verfügbarkeit anlegen für AK: {ak}"
 
-#: AKScheduling/views.py:214
+#: AKScheduling/views.py:277
 #, python-brace-format
 msgid "Created default availabilities for {count} AKs"
 msgstr "Standardverfügbarkeiten für {count} AKs angelegt"

AKScheduling/models.py

+# This file mainly contains signal receivers, which follow a very strong interface, having e.g., a sender attribute
+# that is hardly used by us. Nevertheless, to follow the django receiver coding style and since changes might
+# cause issues when loading fixtures or model dumps, it is not wise to replace that attribute with "_".
+# Therefore, the check that finds unused arguments is disabled for this whole file:
+# pylint: disable=unused-argument
+
 from django.db.models.signals import post_save, m2m_changed, pre_delete
 from django.dispatch import receiver
 from django.utils.translation import gettext_lazy as _
 
 from AKModel.availability.models import Availability
-from AKModel.models import AK, AKSlot, Room, Event, AKOwner, ConstraintViolation
+from AKModel.models import AK, AKSlot, Room, Event, ConstraintViolation
 
 
 def update_constraint_violations(new_violations, existing_violations_to_check):
@@ -43,11 +49,15 @@ def update_cv_reso_deadline_for_slot(slot):
     :type slot: AKSlot
     """
     event = slot.event
-    if slot.ak.reso and slot.event.reso_deadline and slot.start:
+
     # Update only if reso_deadline exists
     # if event was changed and reso_deadline is removed, CVs will be deleted by event changed handler
+    # Update only has to be done for already scheduled slots with reso intention
+    if slot.ak.reso and slot.event.reso_deadline and slot.start:
         violation_type = ConstraintViolation.ViolationType.AK_AFTER_RESODEADLINE
         new_violations = []
+
+        # Violation?
         if slot.end > event.reso_deadline:
             c = ConstraintViolation(
                 type=violation_type,
@@ -69,8 +79,10 @@ def check_capacity_for_slot(slot: AKSlot):
     :return: Violation (if any) or None
     :rtype: ConstraintViolation or None
     """
-    if slot.room:
-        if slot.room.capacity >= 0:
+
+    # If slot is scheduled in a room
+    if slot.room and slot.room.capacity >= 0:
+        # Create a violation if interest exceeds room capacity
         if slot.room.capacity < slot.ak.interest:
             c = ConstraintViolation(
                 type=ConstraintViolation.ViolationType.ROOM_CAPACITY_EXCEEDED,
@@ -83,7 +95,9 @@ def check_capacity_for_slot(slot: AKSlot):
             c.ak_slots_tmp.add(slot)
             c.aks_tmp.add(slot.ak)
             return c
-            elif slot.room.capacity < slot.ak.interest + 5 or slot.room.capacity < slot.ak.interest * 1.25:
+
+        # Create a warning if interest is close to room capacity
+        if slot.room.capacity < slot.ak.interest + 5 or slot.room.capacity < slot.ak.interest * 1.25:
             c = ConstraintViolation(
                 type=ConstraintViolation.ViolationType.ROOM_CAPACITY_EXCEEDED,
                 level=ConstraintViolation.ViolationLevel.WARNING,
@@ -95,12 +109,17 @@ def check_capacity_for_slot(slot: AKSlot):
             c.ak_slots_tmp.add(slot)
             c.aks_tmp.add(slot.ak)
             return c
+
     return None
 
 
 @receiver(post_save, sender=AK)
 def ak_changed_handler(sender, instance: AK, **kwargs):
-    # Changes might affect: Reso intention, Category, Interest
+    """
+    Signal receiver: Check for violations after AK changed
+
+    Changes might affect: Reso intention, Category, Interest
+    """
     # TODO Reso intention changes
 
     # Check room capacities
@@ -118,14 +137,12 @@ def ak_changed_handler(sender, instance: AK, **kwargs):
 @receiver(m2m_changed, sender=AK.owners.through)
 def ak_owners_changed_handler(sender, instance: AK, action: str, **kwargs):
     """
-    Owners of AK changed
+    Signal receiver: Owners of AK changed
     """
     # Only signal after change (post_add, post_delete, post_clear) are relevant
     if not action.startswith("post"):
         return
 
-    # print(f"{instance} changed")
-
     event = instance.event
 
     # Owner(s) changed: Might affect multiple AKs by the same owner(s) at the same time
@@ -157,8 +174,6 @@ def ak_owners_changed_handler(sender, instance: AK, action: str, **kwargs):
                             c.ak_slots_tmp.add(other_slot)
                             new_violations.append(c)
 
-        #print(f"{owner} has the following conflicts: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the AK that was recently changed (important!)
     existing_violations_to_check = list(instance.constraintviolation_set.filter(type=violation_type))
@@ -169,14 +184,12 @@ def ak_owners_changed_handler(sender, instance: AK, action: str, **kwargs):
 @receiver(m2m_changed, sender=AK.conflicts.through)
 def ak_conflicts_changed_handler(sender, instance: AK, action: str, **kwargs):
     """
-    Conflicts of AK changed
+    Signal receiver: Conflicts of AK changed
     """
     # Only signal after change (post_add, post_delete, post_clear) are relevant
     if not action.startswith("post"):
         return
 
-    # print(f"{instance} changed")
-
     event = instance.event
 
     # Conflict(s) changed: Might affect multiple AKs that are conflicts of each other
@@ -186,6 +199,7 @@ def ak_conflicts_changed_handler(sender, instance: AK, action: str, **kwargs):
     slots_of_this_ak: [AKSlot] = instance.akslot_set.filter(start__isnull=False)
     conflicts_of_this_ak: [AK] = instance.conflicts.all()
 
+    # Loop over all existing conflicts
     for ak in conflicts_of_this_ak:
         if ak != instance:
             for other_slot in ak.akslot_set.filter(start__isnull=False):
@@ -203,8 +217,6 @@ def ak_conflicts_changed_handler(sender, instance: AK, action: str, **kwargs):
                         c.ak_slots_tmp.add(other_slot)
                         new_violations.append(c)
 
-        # print(f"{instance} has the following conflicts: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the AK that was recently changed (important!)
     existing_violations_to_check = list(instance.constraintviolation_set.filter(type=violation_type))
@@ -215,23 +227,22 @@ def ak_conflicts_changed_handler(sender, instance: AK, action: str, **kwargs):
 @receiver(m2m_changed, sender=AK.prerequisites.through)
 def ak_prerequisites_changed_handler(sender, instance: AK, action: str, **kwargs):
     """
-    Prerequisites of AK changed
+    Signal receiver: Prerequisites of AK changed
     """
     # Only signal after change (post_add, post_delete, post_clear) are relevant
     if not action.startswith("post"):
         return
 
-    # print(f"{instance} changed")
-
     event = instance.event
 
-    # Conflict(s) changed: Might affect multiple AKs that are conflicts of each other
+    # Prerequisite(s) changed: Might affect multiple AKs that should have a certain order
     violation_type = ConstraintViolation.ViolationType.AK_BEFORE_PREREQUISITE
     new_violations = []
 
     slots_of_this_ak: [AKSlot] = instance.akslot_set.filter(start__isnull=False)
     prerequisites_of_this_ak: [AK] = instance.prerequisites.all()
 
+    # Loop over all prerequisites
     for ak in prerequisites_of_this_ak:
         if ak != instance:
             for other_slot in ak.akslot_set.filter(start__isnull=False):
@@ -249,8 +260,6 @@ def ak_prerequisites_changed_handler(sender, instance: AK, action: str, **kwargs
                         c.ak_slots_tmp.add(other_slot)
                         new_violations.append(c)
 
-        # print(f"{instance} has the following conflicts: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the AK that was recently changed (important!)
     existing_violations_to_check = list(instance.constraintviolation_set.filter(type=violation_type))
@@ -261,14 +270,12 @@ def ak_prerequisites_changed_handler(sender, instance: AK, action: str, **kwargs
 @receiver(m2m_changed, sender=AK.requirements.through)
 def ak_requirements_changed_handler(sender, instance: AK, action: str, **kwargs):
     """
-    Requirements of AK changed
+    Signal receiver: Requirements of AK changed
     """
     # Only signal after change (post_add, post_delete, post_clear) are relevant
     if not action.startswith("post"):
         return
 
-    # print(f"{instance} changed")
-
     event = instance.event
 
     # Requirement(s) changed: Might affect slots and rooms
@@ -298,8 +305,6 @@ def ak_requirements_changed_handler(sender, instance: AK, action: str, **kwargs)
                 c.ak_slots_tmp.add(slot)
                 new_violations.append(c)
 
-    # print(f"{instance} has the following conflicts: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the AK that was recently changed (important!)
     existing_violations_to_check = list(instance.constraintviolation_set.filter(type=violation_type))
@@ -309,8 +314,13 @@ def ak_requirements_changed_handler(sender, instance: AK, action: str, **kwargs)
 
 @receiver(post_save, sender=AKSlot)
 def akslot_changed_handler(sender, instance: AKSlot, **kwargs):
-    # Changes might affect: Duplicate parallel, Two in room, Resodeadline
-    # print(f"{sender} changed")
+    """
+    Signal receiver: AKSlot changed
+
+    Changes might affect: Duplicate parallel, Two in room, Resodeadline
+    """
+    # TODO Consider rewriting this very long and complex method to resolve several (style) issues:
+    # pylint: disable=too-many-nested-blocks,too-many-locals,too-many-branches,too-many-statements
     event = instance.event
 
     # == Check for two parallel slots by one of the owners ==
@@ -341,8 +351,6 @@ def akslot_changed_handler(sender, instance: AKSlot, **kwargs):
                             c.ak_slots_tmp.add(other_slot)
                             new_violations.append(c)
 
-            # print(f"{owner} has the following conflicts: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the AK that was recently changed (important!)
     existing_violations_to_check = list(instance.constraintviolation_set.filter(type=violation_type))
@@ -373,8 +381,6 @@ def akslot_changed_handler(sender, instance: AKSlot, **kwargs):
                     c.ak_slots_tmp.add(other_slot)
                     new_violations.append(c)
 
-        # print(f"Multiple slots in room {instance.room}: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the slot that was recently changed (important!)
     existing_violations_to_check = list(instance.constraintviolation_set.filter(type=violation_type))
@@ -437,8 +443,6 @@ def akslot_changed_handler(sender, instance: AKSlot, **kwargs):
             c.ak_slots_tmp.add(instance)
             new_violations.append(c)
 
-    # print(f"{instance.ak} has the following slots outside availabilities: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the AK that was recently changed (important!)
     existing_violations_to_check = list(instance.constraintviolation_set.filter(type=violation_type))
@@ -470,8 +474,6 @@ def akslot_changed_handler(sender, instance: AKSlot, **kwargs):
                 c.ak_slots_tmp.add(instance)
                 new_violations.append(c)
 
-    # print(f"{instance} has the following conflicts: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the AK that was recently changed (important!)
     existing_violations_to_check = list(instance.constraintviolation_set.filter(type=violation_type))
@@ -502,8 +504,6 @@ def akslot_changed_handler(sender, instance: AKSlot, **kwargs):
                         c.ak_slots_tmp.add(other_slot)
                         new_violations.append(c)
 
-            # print(f"{instance} has the following conflicts: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the AK that was recently changed (important!)
     existing_violations_to_check = list(instance.ak.constraintviolation_set.filter(type=violation_type))
@@ -534,8 +534,6 @@ def akslot_changed_handler(sender, instance: AKSlot, **kwargs):
                         c.ak_slots_tmp.add(other_slot)
                         new_violations.append(c)
 
-            # print(f"{instance} has the following conflicts: {new_violations}")
-
     # ... and compare to/update list of existing violations of this type
     # belonging to the AK that was recently changed (important!)
     existing_violations_to_check = list(instance.ak.constraintviolation_set.filter(type=violation_type))
@@ -547,15 +545,21 @@ def akslot_changed_handler(sender, instance: AKSlot, **kwargs):
     new_violations = [cv] if cv is not None else []
 
     # Compare to/update list of existing violations of this type for this slot
-    existing_violations_to_check = list(instance.constraintviolation_set.filter(type=ConstraintViolation.ViolationType.ROOM_CAPACITY_EXCEEDED))
+    existing_violations_to_check = list(
+        instance.constraintviolation_set.filter(type=ConstraintViolation.ViolationType.ROOM_CAPACITY_EXCEEDED)
+    )
     update_constraint_violations(new_violations, existing_violations_to_check)
 
 
 @receiver(pre_delete, sender=AKSlot)
 def akslot_deleted_handler(sender, instance: AKSlot, **kwargs):
-    # Manually clean up or remove constraint violations that belong to this slot since there is no cascade deletion
-    # for many2many relationships. Explicitly listening for AK deletion signals is not necessary since they will
-    # transitively trigger this signal and we always set both AK and AKSlot references in a constraint violation
+    """
+    Signal receiver: AKSlot deleted
+
+    Manually clean up or remove constraint violations that belong to this slot since there is no cascade deletion
+    for many2many relationships. Explicitly listening for AK deletion signals is not necessary since they will
+    transitively trigger this signal and we always set both AK and AKSlot references in a constraint violation
+    """
     # print(f"{instance} deleted")
 
     for cv in instance.constraintviolation_set.all():
@@ -566,8 +570,11 @@ def akslot_deleted_handler(sender, instance: AKSlot, **kwargs):
 
 @receiver(post_save, sender=Room)
 def room_changed_handler(sender, instance: Room, **kwargs):
-    # Changes might affect: Room size
+    """
+    Signal receiver: Room changed
 
+    Changes might affect: Room size
+    """
     # Check room capacities
     violation_type = ConstraintViolation.ViolationType.ROOM_CAPACITY_EXCEEDED
     new_violations = []
@@ -583,24 +590,23 @@ def room_changed_handler(sender, instance: Room, **kwargs):
 @receiver(m2m_changed, sender=Room.properties.through)
 def room_requirements_changed_handler(sender, instance: Room, action: str, **kwargs):
     """
-    Requirements of room changed
+    Signal Receiver: Requirements of room changed
     """
     # Only signal after change (post_add, post_delete, post_clear) are relevant
     if not action.startswith("post"):
         return
 
-    # print(f"{instance} changed")
-
-    event = instance.event
-
+    # event = instance.event
     # TODO React to changes
 
 
 @receiver(post_save, sender=Availability)
 def availability_changed_handler(sender, instance: Availability, **kwargs):
-    # Changes might affect: category availability, AK availability, Room availability
-    # print(f"{instance} changed")
+    """
+    Signal receiver: Availalability changed
 
+    Changes might affect: category availability, AK availability, Room availability
+    """
     event = instance.event
 
     # An AK's availability changed: Might affect AK slots scheduled outside the permitted time
@@ -627,8 +633,6 @@ def availability_changed_handler(sender, instance: Availability, **kwargs):
                 c.ak_slots_tmp.add(slot)
                 new_violations.append(c)
 
-        # print(f"{instance.ak} has the following slots outside availabilities: {new_violations}")
-
         # ... and compare to/update list of existing violations of this type
         # belonging to the AK that was recently changed (important!)
         existing_violations_to_check = list(instance.ak.constraintviolation_set.filter(type=violation_type))
@@ -638,7 +642,12 @@ def availability_changed_handler(sender, instance: Availability, **kwargs):
 
 @receiver(post_save, sender=Event)
 def event_changed_handler(sender, instance: Event, **kwargs):
-    # == Check for reso ak after reso deadline (which might have changed) ==
+    """
+    Signal receiver: Event changed
+
+    Changes might affect: Reso deadline
+    """
+    # Check for reso ak after reso deadline (which might have changed)
     if instance.reso_deadline:
         for slot in instance.akslot_set.filter(start__isnull=False, ak__reso=True):
             update_cv_reso_deadline_for_slot(slot)

AKScheduling/tests.py

+import json
+from datetime import timedelta
+
 from django.test import TestCase
-from AKModel.tests import BasicViewTests
+from django.utils import timezone
 
+from AKModel.tests import BasicViewTests
+from AKModel.models import AKSlot, Event, Room
 
 class ModelViewTests(BasicViewTests, TestCase):
+    """
+    Tests for AKScheduling
+    """
     fixtures = ['model.json']
 
     VIEWS_STAFF_ONLY = [
+        # Views
         ('admin:schedule', {'event_slug': 'kif42'}),
         ('admin:slots_unscheduled', {'event_slug': 'kif42'}),
         ('admin:constraint-violations', {'slug': 'kif42'}),
@@ -14,4 +23,66 @@ class ModelViewTests(BasicViewTests, TestCase):
         ('admin:autocreate-availabilities', {'event_slug': 'kif42'}),
         ('admin:tracks_manage', {'event_slug': 'kif42'}),
         ('admin:enter-interest', {'event_slug': 'kif42', 'pk': 1}),
+        # API (Read)
+        ('model:scheduling-resources-list', {'event_slug': 'kif42'}, 403),
+        ('model:scheduling-constraint-violations-list', {'event_slug': 'kif42'}, 403),
+        ('model:scheduling-events', {'event_slug': 'kif42'}),
+        ('model:scheduling-room-availabilities', {'event_slug': 'kif42'}),
+        ('model:scheduling-default-slots', {'event_slug': 'kif42'}),
     ]
+
+    def test_scheduling_of_slot_update(self):
+        """
+        Test rescheduling a slot to a different time or room
+        """
+        self.client.force_login(self.admin_user)
+
+        event = Event.get_by_slug('kif42')
+
+        # Get the first already scheduled slot belonging to this event
+        slot = event.akslot_set.filter(start__isnull=False).first()
+        pk = slot.pk
+        room_id = slot.room_id
+        events_api_url = f"/kif42/api/scheduling-event/{pk}/"
+
+        # Create updated time
+        offset = timedelta(hours=1)
+        new_start_time = slot.start + offset
+        new_end_time = slot.end + offset
+        new_start_time_string = timezone.localtime(new_start_time, event.timezone).strftime("%Y-%m-%d %H:%M:%S")
+        new_end_time_string = timezone.localtime(new_end_time, event.timezone).strftime("%Y-%m-%d %H:%M:%S")
+
+        # Try API call
+        response = self.client.put(
+            events_api_url,
+            json.dumps({
+                'start': new_start_time_string,
+                'end': new_end_time_string,
+                'roomId': room_id,
+            }),
+            content_type = 'application/json'
+        )
+        self.assertEqual(response.status_code, 200, "PUT to API endpoint did not work")
+
+        # Make sure API call did update the slot as expected
+        slot = AKSlot.objects.get(pk=pk)
+        self.assertEqual(new_start_time, slot.start, "Update did not work")
+
+        # Test updating room
+        new_room = Room.objects.exclude(pk=room_id).first()
+
+        # Try second API call
+        response = self.client.put(
+            events_api_url,
+            json.dumps({
+                'start': new_start_time_string,
+                'end': new_end_time_string,
+                'roomId': new_room.pk,
+            }),
+            content_type = 'application/json'
+        )
+        self.assertEqual(response.status_code, 200, "Second PUT to API endpoint did not work")
+
+        # Make sure API call did update the slot as expected
+        slot = AKSlot.objects.get(pk=pk)
+        self.assertEqual(new_room.pk, slot.room.pk, "Update did not work")

AKScheduling/views.py

@@ -7,11 +7,13 @@ from django.views.generic import ListView, DetailView, UpdateView
 
 from AKModel.models import AKSlot, AKTrack, Event, AK, AKCategory
 from AKModel.metaviews.admin import EventSlugMixin, FilterByEventSlugMixin, AdminViewMixin, IntermediateAdminView
-from AKScheduling.forms import AKInterestForm
-from AKSubmission.forms import AKAddSlotForm
+from AKScheduling.forms import AKInterestForm, AKAddSlotForm
 
 
 class UnscheduledSlotsAdminView(AdminViewMixin, FilterByEventSlugMixin, ListView):
+    """
+    Admin view: Get a list of all unscheduled slots
+    """
     template_name = "admin/AKScheduling/unscheduled.html"
     model = AKSlot
     context_object_name = "akslots"
@@ -26,6 +28,12 @@ class UnscheduledSlotsAdminView(AdminViewMixin, FilterByEventSlugMixin, ListView
 
 
 class SchedulingAdminView(AdminViewMixin, FilterByEventSlugMixin, ListView):
+    """
+    Admin view: Scheduler
+
+    View and adapt the schedule of an event. This view heavily uses JavaScript to display a calendar view plus
+    a list of unscheduled slots and to allow dragging slots in and into the calendar
+    """
     template_name = "admin/AKScheduling/scheduling.html"
     model = AKSlot
     context_object_name = "slots_unscheduled"
@@ -47,6 +55,12 @@ class SchedulingAdminView(AdminViewMixin, FilterByEventSlugMixin, ListView):
 
 
 class TrackAdminView(AdminViewMixin, FilterByEventSlugMixin, ListView):
+    """
+    Admin view: Distribute AKs to tracks
+
+    Again using JavaScript, the user can here see a list of all AKs split-up by tracks and can move them to other or
+    even new tracks using drag and drop. The state is then automatically synchronized via API calls in the background
+    """
     template_name = "admin/AKScheduling/manage_tracks.html"
     model = AKTrack
     context_object_name = "tracks"
@@ -58,6 +72,12 @@ class TrackAdminView(AdminViewMixin, FilterByEventSlugMixin, ListView):
 
 
 class ConstraintViolationsAdminView(AdminViewMixin, DetailView):
+    """
+    Admin view: Inspect and adjust all constraint violations of the event
+
+    This view populates a table of constraint violations via background API call (JavaScript), offers the option to
+    see details or edit each of them and provides an auto-reload feature.
+    """
     template_name = "admin/AKScheduling/constraint_violations.html"
     model = Event
     context_object_name = "event"
@@ -69,6 +89,10 @@ class ConstraintViolationsAdminView(AdminViewMixin, DetailView):
 
 
 class SpecialAttentionAKsAdminView(AdminViewMixin, DetailView):
+    """
+    Admin view: List all AKs that require special attention via scheduling, e.g., because of free-form comments,
+    since there are slots even though it is a wish, or no slots even though it is an AK etc.
+    """
     template_name = "admin/AKScheduling/special_attention.html"
     model = Event
     context_object_name = "event"
@@ -77,12 +101,16 @@ class SpecialAttentionAKsAdminView(AdminViewMixin, DetailView):
         context = super().get_context_data(**kwargs)
         context["title"] = f"{_('AKs requiring special attention for')} {context['event']}"
 
-        aks = AK.objects.filter(event=context["event"]).annotate(Count('owners', distinct=True)).annotate(Count('akslot', distinct=True)).annotate(Count('availabilities', distinct=True))
+        # Load all "special" AKs from the database using annotations to reduce the amount of necessary queries
+        aks = (AK.objects.filter(event=context["event"]).annotate(Count('owners', distinct=True))
+               .annotate(Count('akslot', distinct=True)).annotate(Count('availabilities', distinct=True)))
         aks_with_comment = []
         ak_wishes_with_slots = []
         aks_without_availabilities = []
         aks_without_slots = []
 
+        # Loop over all AKs of this event and identify all relevant factors that make the AK "special" and add them to
+        # the respective lists if the AK fullfills an condition
         for ak in aks:
             if ak.notes != "":
                 aks_with_comment.append(ak)
@@ -105,6 +133,14 @@ class SpecialAttentionAKsAdminView(AdminViewMixin, DetailView):
 
 
 class InterestEnteringAdminView(SuccessMessageMixin, AdminViewMixin, EventSlugMixin, UpdateView):
+    """
+    Admin view: Form view to quickly store information about the interest in an AK
+    (e.g., during presentation of the AK list)
+
+    The view offers a field to update interest and manually set a comment for the current AK, but also features links
+    to the AKs before and probably coming up next, as well as links to other AKs sorted by category, for quick
+    and hazzle-free navigation during the AK presentation
+    """
     template_name = "admin/AKScheduling/interest.html"
     model = AK
     context_object_name = "ak"
@@ -127,6 +163,8 @@ class InterestEnteringAdminView(SuccessMessageMixin, AdminViewMixin, EventSlugMi
         last_ak = None
         next_is_next = False
 
+        # Building the right navigation is a bit tricky since wishes have to be treated as an own category here
+        # Hence, depending on the AK we are currently at (displaying the form for) we need to either:
         # Find other AK wishes (regardless of the category)...
         if context['ak'].wish:
             other_aks = [ak for ak in context['event'].ak_set.prefetch_related('owners').all() if ak.wish]
@@ -134,6 +172,7 @@ class InterestEnteringAdminView(SuccessMessageMixin, AdminViewMixin, EventSlugMi
         else:
             other_aks = [ak for ak in context['ak'].category.ak_set.prefetch_related('owners').all() if not ak.wish]
 
+        # Use that list of other AKs belonging to this category to identify the previous and next AK (if any)
         for other_ak in other_aks:
             if next_is_next:
                 context['next_ak'] = other_ak
@@ -143,6 +182,7 @@ class InterestEnteringAdminView(SuccessMessageMixin, AdminViewMixin, EventSlugMi
                 next_is_next = True
             last_ak = other_ak
 
+        # Gather information for link lists for all categories (and wishes)
         for category in context['event'].akcategory_set.prefetch_related('ak_set').all():
             aks_for_category = []
             for ak in category.ak_set.prefetch_related('owners').all():
@@ -152,6 +192,8 @@ class InterestEnteringAdminView(SuccessMessageMixin, AdminViewMixin, EventSlugMi
                     aks_for_category.append(ak)
             categories_with_aks.append((category, aks_for_category))
 
+        # Make sure wishes have the right order (since the list was filled category by category before, this requires
+        # explicitly reordering them by their primary key)
         ak_wishes.sort(key=lambda x: x.pk)
         categories_with_aks.append(
                 (AKCategory(name=_("Wishes"), pk=0, description="-"), ak_wishes))
@@ -162,6 +204,16 @@ class InterestEnteringAdminView(SuccessMessageMixin, AdminViewMixin, EventSlugMi
 
 
 class WishSlotCleanupView(EventSlugMixin, IntermediateAdminView):
+    """
+    Admin action view: Allow to delete all unscheduled slots for wishes
+
+    The view will render a preview of all slots that are affected by this. It is not possible to manually choose
+    which slots should be deleted (either all or none) and the functionality will therefore delete slots that were
+    created in the time between rendering of the preview and running the action ofter confirmation as well.
+
+    Due to the automated slot cleanup functionality for wishes in the AKSubmission app, this functionality should be
+    rarely needed/used
+    """
     title = _('Cleanup: Delete unscheduled slots for wishes')
 
     def get_success_url(self):
@@ -181,6 +233,15 @@ class WishSlotCleanupView(EventSlugMixin, IntermediateAdminView):
 
 
 class AvailabilityAutocreateView(EventSlugMixin, IntermediateAdminView):
+    """
+    Admin action view: Allow to automatically create default availabilities (event start to end) for all AKs without
+    any manually specified availability information
+
+    The view will render a preview of all AKs that are affected by this. It is not possible to manually choose
+    which AKs should be affected (either all or none) and the functionality will therefore create availability entries
+    for AKs that were created in the time between rendering of the preview and running the action ofter confirmation
+    as well.
+    """
     title = _('Create default availabilities for AKs')
 
     def get_success_url(self):
@@ -195,6 +256,8 @@ class AvailabilityAutocreateView(EventSlugMixin, IntermediateAdminView):
         )
 
     def form_valid(self, form):
+        # Local import to prevent cyclic imports
+        # pylint: disable=import-outside-toplevel
         from AKModel.availability.models import Availability
 
         success_count = 0
@@ -203,7 +266,7 @@ class AvailabilityAutocreateView(EventSlugMixin, IntermediateAdminView):
                 availability = Availability.with_event_length(event=self.event, ak=ak)
                 availability.save()
                 success_count += 1
-            except:
+            except: # pylint: disable=bare-except
                 messages.add_message(
                     self.request, messages.WARNING,
                     _("Could not create default availabilities for AK: {ak}").format(ak=ak)

AKSubmission/admin.py

-# Register your models here.

AKSubmission/api.py

@@ -25,9 +25,13 @@ def ak_interest_indication_active(event, current_timestamp):
 def increment_interest_counter(request, event_slug, pk, **kwargs):
     """
     Increment interest counter for AK
+
+    This view either returns a HTTP 200 if the counter was incremented,
+    an HTTP 403 if indicating interest is currently not allowed,
+    or an HTTP 404 if there is no matching AK for the given primary key and event slug.
     """
     try:
-        ak = AK.objects.get(pk=pk)
+        ak = AK.objects.get(pk=pk, event__slug=event_slug)
         # Check whether interest indication is currently allowed
         current_timestamp = datetime.now().astimezone(ak.event.timezone)
         if ak_interest_indication_active(ak.event, current_timestamp):

AKSubmission/apps.py

@@ -2,4 +2,7 @@ from django.apps import AppConfig
 
 
 class AksubmissionConfig(AppConfig):
+    """
+    App configuration (default, only specifies name of the app)
+    """
     name = 'AKSubmission'

AKSubmission/forms.py

+"""
+Submission-specific forms
+"""
+
 import itertools
 import re
 
@@ -7,10 +11,21 @@ from django.utils.translation import gettext_lazy as _
 
 from AKModel.availability.forms import AvailabilitiesFormMixin
 from AKModel.availability.models import Availability
-from AKModel.models import AK, AKOwner, AKCategory, AKRequirement, AKSlot, AKOrgaMessage, Event
+from AKModel.models import AK, AKOwner, AKCategory, AKRequirement, AKSlot, AKOrgaMessage
 
 
 class AKForm(AvailabilitiesFormMixin, forms.ModelForm):
+    """
+    Base form to add and edit AKs
+
+    Contains suitable widgets for the different data types, restricts querysets (e.g., of requirements) to entries
+    belonging to the event this AK belongs to.
+    Prepares initial slot creation (by accepting multiple input formats and a list of slots to generate),
+    automatically generate short names and wiki links if necessary
+
+    Will be modified/used by :class:`AKSubmissionForm` (that allows to add slots and excludes links)
+    and :class:`AKWishForm`
+    """
     required_css_class = 'required'
     split_string = re.compile('[,;]')
 
@@ -57,7 +72,14 @@ class AKForm(AvailabilitiesFormMixin, forms.ModelForm):
 
     @staticmethod
     def _clean_duration(duration):
-        # Handle different duration formats (h:mm and decimal comma instead of point)
+        """
+        Clean/convert input format for the duration(s) of the slot(s)
+
+        Handle different duration formats (h:mm and decimal comma instead of point)
+
+        :param duration: raw input, either with ":", "," or "."
+        :return: normalized duration (point-separated hour float)
+        """
         if ":" in duration:
             h, m = duration.split(":")
             duration = int(h) + int(m) / 60
@@ -66,31 +88,44 @@ class AKForm(AvailabilitiesFormMixin, forms.ModelForm):
 
         try:
             float(duration)
-        except ValueError:
+        except ValueError as exc:
             raise ValidationError(
                 _('"%(duration)s" is not a valid duration'),
                 code='invalid',
                 params={'duration': duration},
-            )
+            ) from exc
 
         return duration
 
     def clean(self):
+        """
+        Normalize/clean inputs
+
+        Generate a (not yet used) short name if field was left blank, generate a wiki link,
+        create a list of normalized slot durations
+
+        :return: cleaned inputs
+        """
         cleaned_data = super().clean()
 
         # Generate short name if not given
         short_name = self.cleaned_data["short_name"]
         if len(short_name) == 0:
             short_name = self.cleaned_data['name']
+            # First try to split AK name at positions with semantic value (e.g., where the full name is separated
+            # by a ':'), if not possible, do a hard cut at the maximum specified length
             short_name = short_name.partition(':')[0]
             short_name = short_name.partition(' - ')[0]
             short_name = short_name.partition(' (')[0]
             short_name = short_name[:AK._meta.get_field('short_name').max_length]
+            # Check whether this short name already exists...
             for i in itertools.count(1):
+                # ...and either use it...
                 if not AK.objects.filter(short_name=short_name, event=self.cleaned_data["event"]).exists():
                     break
+                # ... or postfix a number starting at 1 and growing until an unused short name is found
                 digits = len(str(i))
-                short_name = '{}-{}'.format(short_name[:-(digits + 1)], i)
+                short_name = f'{short_name[:-(digits + 1)]}-{i}'
             cleaned_data["short_name"] = short_name
 
         # Generate wiki link
@@ -106,35 +141,57 @@ class AKForm(AvailabilitiesFormMixin, forms.ModelForm):
 
 
 class AKSubmissionForm(AKForm):
+    """
+    Form for Submitting new AKs
+
+    Is a special variant of :class:`AKForm` that does not allow to manually edit wiki and protocol links and enforces
+    the generation of at least one slot.
+    """
     class Meta(AKForm.Meta):
-        exclude = ['link', 'protocol_link']
+        # Exclude fields again that were previously included in the parent class
+        exclude = ['link', 'protocol_link'] #pylint: disable=modelform-uses-exclude
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
-        # Add field for durations
+        # Add field for durations (cleaning will be handled by parent class)
         self.fields["durations"] = forms.CharField(
             widget=forms.Textarea,
             label=_("Duration(s)"),
             help_text=_(
-                "Enter at least one planned duration (in hours). If your AK should have multiple slots, use multiple lines"),
-            initial=
-            self.initial.get('event').default_slot
+                "Enter at least one planned duration (in hours). "
+                "If your AK should have multiple slots, use multiple lines"),
+            initial=self.initial.get('event').default_slot
         )
 
     def clean_availabilities(self):
+        """
+        Automatically improve availabilities entered.
+        If the user did not specify availabilities assume the full event duration is possible
+        :return: cleaned availabilities
+        (either user input or one availability for the full length of the event if user input was empty)
+        """
         availabilities = super().clean_availabilities()
-        # If the user did not specify availabilities assume the full event duration is possible
         if len(availabilities) == 0:
             availabilities.append(Availability.with_event_length(event=self.cleaned_data["event"]))
         return availabilities
 
 
 class AKWishForm(AKForm):
+    """
+    Form for submitting or editing wishes
+
+    Is a special variant of :class:`AKForm` that does not allow to specify owner(s) or
+    manually edit wiki and protocol links
+    """
     class Meta(AKForm.Meta):
-        exclude = ['owners', 'link', 'protocol_link']
+        # Exclude fields again that were previously included in the parent class
+        exclude = ['owners', 'link', 'protocol_link'] #pylint: disable=modelform-uses-exclude
 
 
 class AKOwnerForm(forms.ModelForm):
+    """
+    Form to create/edit AK owners
+    """
     required_css_class = 'required'
 
     class Meta:
@@ -146,6 +203,9 @@ class AKOwnerForm(forms.ModelForm):
 
 
 class AKDurationForm(forms.ModelForm):
+    """
+    Form to add an additional slot to a given AK
+    """
     class Meta:
         model = AKSlot
         fields = ['duration', 'ak', 'event']
@@ -156,6 +216,9 @@ class AKDurationForm(forms.ModelForm):
 
 
 class AKOrgaMessageForm(forms.ModelForm):
+    """
+    Form to create a confidential message to the organizers  belonging to a given AK
+    """
     class Meta:
         model = AKOrgaMessage
         fields = ['ak', 'text', 'event']
@@ -164,14 +227,3 @@ class AKOrgaMessageForm(forms.ModelForm):
             'event': forms.HiddenInput,
             'text': forms.Textarea,
         }
-
-
-class AKAddSlotForm(forms.Form):
-    start = forms.CharField(label=_("Start"), disabled=True)
-    end = forms.CharField(label=_("End"), disabled=True)
-    duration = forms.CharField(label=_("Duration"), disabled=True)
-    room = forms.IntegerField(label=_("Room"), disabled=True)
-
-    def __init__(self, event):
-        super().__init__()
-        self.fields['ak'] = forms.ModelChoiceField(event.ak_set.all(), label=_("AK"))