.docker/extra_requirements.txt

-uwsgi==2.0.22
+uwsgi==2.0.30

.gitlab-ci.yml

-image: python:3.9
+image: python:3.11
 
 services:
   - mysql
@@ -14,32 +14,30 @@ cache:
   paths:
     - ~/.cache/pip/
 
-before_script:
-  - python -V  # Print out python version for debugging
-  - apt-get -qq update
-  - apt-get -qq install -y python3-virtualenv python3 python3-dev python3-pip gettext default-mysql-client default-libmysqlclient-dev
-  - export DJANGO_SETTINGS_MODULE=AKPlanning.settings_ci
-  - ./Utils/setup.sh --prod
-  - mkdir -p public/badges public/lint
-  - echo undefined > public/badges/$CI_JOB_NAME.score
-  - source venv/bin/activate
-  - pip install pylint-gitlab pylint-django
-  - mysql --version
-
-check:
-  script:
-    - ./Utils/check.sh --all
+.before_script_template:
+  before_script:
+    - python -V  # Print out python version for debugging
+    - apt-get -qq update
+    - apt-get -qq install -y python3-virtualenv python3 python3-dev python3-pip gettext default-mysql-client default-libmysqlclient-dev
+    - ./Utils/setup.sh --ci
+    - mkdir -p public/badges public/lint
+    - echo undefined > public/badges/$CI_JOB_NAME.score
+    - source venv/bin/activate
+    - pip install pylint-gitlab pylint-django
+    - mysql --version
 
-check-migrations:
+migrations:
+  extends: .before_script_template
   script:
     - source venv/bin/activate
     - ./manage.py makemigrations --dry-run --check
 
 test:
+  extends: .before_script_template
   script:
     - source venv/bin/activate
     - echo "GRANT ALL on *.* to '${MYSQL_USER}';"| mysql -u root --password="${MYSQL_ROOT_PASSWORD}" -h mysql
-    - pip install pytest-cov unittest-xml-reporting
+    - pip install pytest-cov
     - coverage run --source='.' manage.py test --settings AKPlanning.settings_ci
   after_script:
     - source venv/bin/activate
@@ -54,12 +52,13 @@ test:
       junit: unit.xml
 
 lint:
+  extends: .before_script_template
   stage: test
   script:
-    - pylint --load-plugins pylint_django --exit-zero --output-format=text $(find -type f -name "*.py" ! -path "**/venv/**") | tee /tmp/pylint.txt
+    - pylint --load-plugins pylint_django --django-settings-module=AKPlanning.settings_ci --rcfile pylintrc --exit-zero --output-format=text AK* | tee /tmp/pylint.txt
     - sed -n 's/^Your code has been rated at \([-0-9.]*\)\/.*/\1/p' /tmp/pylint.txt > public/badges/$CI_JOB_NAME.score
-    - pylint --load-plugins pylint_django --exit-zero --output-format=pylint_gitlab.GitlabCodeClimateReporter $(find -type f -name "*.py" ! -path "**/venv/**") > codeclimate.json
-    - pylint --load-plugins pylint_django --exit-zero --output-format=pylint_gitlab.GitlabPagesHtmlReporter $(find -type f -name "*.py" ! -path "**/venv/**") > public/lint/index.html
+    - pylint --load-plugins pylint_django --django-settings-module=AKPlanning.settings_ci --rcfile pylintrc --exit-zero --output-format=pylint_gitlab.GitlabCodeClimateReporter AK* > codeclimate.json
+    - pylint --load-plugins pylint_django --django-settings-module=AKPlanning.settings_ci --rcfile pylintrc --exit-zero --output-format=pylint_gitlab.GitlabPagesHtmlReporter AK* > public/lint/index.html
   after_script:
    - |
       echo "Linting score: $(cat public/badges/$CI_JOB_NAME.score)"
@@ -70,6 +69,17 @@ lint:
       codequality: codeclimate.json
     when: always
 
+doc:
+  extends: .before_script_template
+  stage: test
+  script:
+    - cd docs
+    - make html
+    - cd ..
+  artifacts:
+    paths:
+      - docs/_build/html
+
 pages:
   stage: deploy
   image: alpine:latest

AKDashboard/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: 2025-01-01 17:28+0100\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,61 +17,66 @@ msgstr ""
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 
-#: AKDashboard/models.py:10
+#: AKDashboard/models.py:21
 msgid "Dashboard Button"
 msgstr "Dashboard-Button"
 
-#: AKDashboard/models.py:11
+#: AKDashboard/models.py:22
 msgid "Dashboard Buttons"
 msgstr "Dashboard-Buttons"
 
-#: AKDashboard/models.py:21
+#: AKDashboard/models.py:32
 msgid "Text"
 msgstr "Text"
 
-#: AKDashboard/models.py:22
+#: AKDashboard/models.py:33
 msgid "Text that will be shown on the button"
 msgstr "Text, der auf dem Button angezeigt wird"
 
-#: AKDashboard/models.py:23
+#: AKDashboard/models.py:34
 msgid "Link URL"
 msgstr "Link-URL"
 
-#: AKDashboard/models.py:23
+#: AKDashboard/models.py:34
 msgid "URL this button links to"
 msgstr "URL auf die der Button verweist"
 
-#: AKDashboard/models.py:24
+#: AKDashboard/models.py:35
 msgid "Icon"
 msgstr "Symbol"
 
-#: AKDashboard/models.py:26
+#: AKDashboard/models.py:37
 msgid "Button Style"
 msgstr "Stil des Buttons"
 
-#: AKDashboard/models.py:26
+#: AKDashboard/models.py:37
 msgid "Style (Color) of this button (bootstrap class)"
 msgstr "Stiel (Farbe) des Buttons (Bootstrap-Klasse)"
 
-#: AKDashboard/models.py:28
+#: AKDashboard/models.py:39
 msgid "Event"
 msgstr "Veranstaltung"
 
-#: AKDashboard/models.py:28
+#: AKDashboard/models.py:39
 msgid "Event this button belongs to"
 msgstr "Veranstaltung, zu der dieser Button gehört"
 
-#: AKDashboard/templates/AKDashboard/dashboard.html:17
+#: AKDashboard/templates/AKDashboard/dashboard.html:18
 #: AKDashboard/templates/AKDashboard/dashboard_event.html:29
+#: AKDashboard/templates/AKDashboard/dashboard_row_old_event.html:53
 msgid "Write to organizers of this event for questions and comments"
 msgstr ""
 "Kontaktiere die Organisator*innen des Events bei Fragen oder Kommentaren"
 
 #: AKDashboard/templates/AKDashboard/dashboard.html:24
+msgid "Old events"
+msgstr "Frühere Veranstaltungen"
+
+#: AKDashboard/templates/AKDashboard/dashboard.html:34
 msgid "Currently, there are no Events!"
 msgstr "Aktuell gibt es keine Events!"
 
-#: AKDashboard/templates/AKDashboard/dashboard.html:27
+#: AKDashboard/templates/AKDashboard/dashboard.html:37
 msgid "Please contact an administrator if you want to use AKPlanning."
 msgstr ""
 "Bitte kontaktiere eine*n Administrator*in, falls du AKPlanning verwenden "
@@ -81,46 +86,53 @@ msgstr ""
 msgid "Recent"
 msgstr "Kürzlich"
 
-#: AKDashboard/templates/AKDashboard/dashboard_row.html:12
+#: AKDashboard/templates/AKDashboard/dashboard_row.html:18
+#: AKDashboard/templates/AKDashboard/dashboard_row_old_event.html:20
 msgid "AK List"
 msgstr "AK-Liste"
 
-#: AKDashboard/templates/AKDashboard/dashboard_row.html:23
+#: AKDashboard/templates/AKDashboard/dashboard_row.html:29
 msgid "Current AKs"
 msgstr "Aktuelle AKs"
 
-#: AKDashboard/templates/AKDashboard/dashboard_row.html:30
+#: AKDashboard/templates/AKDashboard/dashboard_row.html:36
 msgid "AK Wall"
 msgstr "AK-Wall"
 
-#: AKDashboard/templates/AKDashboard/dashboard_row.html:38
+#: AKDashboard/templates/AKDashboard/dashboard_row.html:44
+#: AKDashboard/templates/AKDashboard/dashboard_row_old_event.html:30
 msgid "Schedule"
 msgstr "AK-Plan"
 
-#: AKDashboard/templates/AKDashboard/dashboard_row.html:49
+#: AKDashboard/templates/AKDashboard/dashboard_row.html:55
 msgid "AK Submission"
 msgstr "AK-Einreichung"
 
-#: AKDashboard/templates/AKDashboard/dashboard_row.html:57
+#: AKDashboard/templates/AKDashboard/dashboard_row.html:63
+#: AKDashboard/templates/AKDashboard/dashboard_row_old_event.html:39
 msgid "AK History"
 msgstr "AK-Verlauf"
 
-#: AKDashboard/views.py:42
+#: AKDashboard/templates/AKDashboard/dashboard_row.html:71
+msgid "AK Preferences"
+msgstr "AK-Präferenzen"
+
+#: AKDashboard/views.py:69
 #, python-format
 msgid "New AK: %(ak)s."
 msgstr "Neuer AK: %(ak)s."
 
-#: AKDashboard/views.py:45
+#: AKDashboard/views.py:72
 #, python-format
 msgid "AK \"%(ak)s\" edited."
 msgstr "AK \"%(ak)s\" bearbeitet."
 
-#: AKDashboard/views.py:48
+#: AKDashboard/views.py:75
 #, python-format
 msgid "AK \"%(ak)s\" deleted."
 msgstr "AK \"%(ak)s\" gelöscht."
 
-#: AKDashboard/views.py:60
+#: AKDashboard/views.py:90
 #, python-format
 msgid "AK \"%(ak)s\" (re-)scheduled."
 msgstr "AK \"%(ak)s\" (um-)geplant."

AKDashboard/static/AKDashboard/style.css

@@ -2,6 +2,10 @@
     margin-bottom: 5em;
 }
 
+.dashboard-row-small {
+    margin-bottom: 3em;
+}
+
 .dashboard-row > .row {
     margin-left: 0;
     padding-bottom: 1em;

AKDashboard/templates/AKDashboard/dashboard.html

@@ -9,16 +9,27 @@
 {% endblock %}
 
 {% block content %}
-    {% for event in events %}
-        <div class="dashboard-row">
-            {% include "AKDashboard/dashboard_row.html" %}
-            {% if event.contact_email %}
-                <p>
-                    <a href="mailto:{{ event.contact_email }}">{% fa6_icon "envelope" "fas" %} {% trans "Write to organizers of this event for questions and comments" %}</a>
-                </p>
-            {% endif %}
-        </div>
-    {% empty %}
+    {% include "messages.html" %}
+    {% if total_event_count > 0 %}
+        {% for event in active_and_current_events %}
+            <div class="dashboard-row">
+                {% include "AKDashboard/dashboard_row.html" %}
+                {% if event.contact_email %}
+                    <p>
+                        <a href="mailto:{{ event.contact_email }}">{% fa6_icon "envelope" "fas" %} {% trans "Write to organizers of this event for questions and comments" %}</a>
+                    </p>
+                {% endif %}
+            </div>
+        {% endfor %}
+        {% if old_event_count > 0 %}
+            <h2 class="mb-3">{% trans "Old events" %}</h2>
+            {% for event in old_events %}
+                <div class="dashboard-row-small">
+                    {% include "AKDashboard/dashboard_row_old_event.html" %}
+                </div>
+            {% endfor %}
+        {% endif %}
+    {% else %}
         <div class="jumbotron">
             <h2 class="display-4">
                 {% trans 'Currently, there are no Events!' %}
@@ -27,5 +38,5 @@
                 {% trans 'Please contact an administrator if you want to use AKPlanning.' %}
             </p>
         </div>
-    {% endfor %}
+    {% endif %}
 {% endblock %}

AKDashboard/templates/AKDashboard/dashboard_event.html

@@ -12,6 +12,7 @@
 {% endblock %}
 
 {% block content %}
+    {% include "messages.html" %}
     <div class="dashboard-row">
         {% include "AKDashboard/dashboard_row.html" %}
 

AKDashboard/templates/AKDashboard/dashboard_row.html

@@ -3,6 +3,12 @@
 {% load fontawesome_6 %}
 
 <h2><a href="{% url 'dashboard:dashboard_event' slug=event.slug %}">{{ event.name }}</a></h2>
+<h4 class="text-muted">
+    {% if event.place %}
+        <b>{{ event.place }} &middot;</b>
+    {% endif %}
+    {{ event | event_month_year }}
+</h4>
 <div class="mt-2">
     {% if 'AKSubmission'|check_app_installed %}
         <a class="dashboard-box btn btn-primary"
@@ -57,6 +63,17 @@
             <span class='text'>{% trans 'AK History' %}</span>
         </div>
     </a>
+    {% if 'AKPreference'|check_app_installed and event.active %}
+        {% if not event.poll_hidden or user.is_staff %}
+            <a class="dashboard-box btn btn-primary"
+            href="{% url 'poll:poll' event_slug=event.slug %}">
+                <div class="col-sm-12 col-md-3 col-lg-2 dashboard-button">
+                    <span class="fa fa-poll"></span>
+                    <span class='text'>{% trans 'AK Preferences' %}</span>
+                </div>
+            </a>
+        {% endif %}
+    {% endif %}
     {% for button in event.dashboardbutton_set.all %}
         <a class="dashboard-box btn btn-{{ button.get_color_display }}"
            href="{{ button.url }}">

AKDashboard/templates/AKDashboard/dashboard_row_old_event.html

+{% load i18n %}
+{% load tags_AKModel %}
+{% load fontawesome_6 %}
+
+<h3><a href="{% url 'dashboard:dashboard_event' slug=event.slug %}">{{ event.name }}</a>
+    <span class="text-muted">
+        &middot;
+        {% if event.place %}
+            {{ event.place }} &middot;
+        {% endif %}
+        {{ event | event_month_year }}
+    </span>
+</h3>
+<div class="mt-2">
+    {% if 'AKSubmission'|check_app_installed %}
+        <a class="btn btn-primary"
+           href="{% url 'submit:ak_list' event_slug=event.slug %}">
+            <div class="col-sm-12 col-md-3 col-lg-2 dashboard-button">
+                <span class="fa fa-list-ul"></span>
+                <span class='text'>{% trans 'AK List' %}</span>
+            </div>
+        </a>
+    {% endif %}
+    {% if 'AKPlan'|check_app_installed %}
+        {% if not event.plan_hidden or user.is_staff %}
+            <a class="btn btn-primary"
+               href="{% url 'plan:plan_overview' event_slug=event.slug %}">
+                <div class="col-sm-12 col-md-3 col-lg-2 dashboard-button">
+                    <span class="fa fa-calendar-alt"></span>
+                    <span class='text'>{% trans 'Schedule' %}</span>
+                </div>
+            </a>
+        {% endif %}
+    {% endif %}
+    <a class="btn btn-primary"
+       href="{% url 'dashboard:dashboard_event' slug=event.slug %}#history">
+        <div class="col-sm-12 col-md-3 col-lg-2 dashboard-button">
+            <span class="fa fa-history"></span>
+            <span class='text'>{% trans 'AK History' %}</span>
+        </div>
+    </a>
+    {% for button in event.dashboardbutton_set.all %}
+        <a class="btn btn-{{ button.get_color_display }}"
+           href="{{ button.url }}">
+            <div class="col-sm-12 col-md-3 col-lg-2 dashboard-button">
+                {% if button.icon %}<span class="fa">{{ button.icon.as_html }}</span>{% endif %}
+                <span class='text'>{{ button.text }}</span>
+            </div>
+        </a>
+    {% endfor %}
+    <a class="btn btn-info"
+       href=mailto:{{ event.contact_email }}"
+       title="{% trans 'Write to organizers of this event for questions and comments' %}">
+            {% fa6_icon "envelope" "fas" %}
+    </a>
+</div>

AKDashboard/tests.py

-import pytz
+import zoneinfo
+
 from django.apps import apps
-from django.test import TestCase, override_settings
+from django.test import override_settings, TestCase
 from django.urls import reverse
 from django.utils.timezone import now
 
 from AKDashboard.models import DashboardButton
-from AKModel.models import Event, AK, AKCategory
-from AKModel.tests import BasicViewTests
+from AKModel.models import AK, AKCategory, Event
+from AKModel.tests.test_views import BasicViewTests
 
 
 class DashboardTests(TestCase):
+    """
+    Specific Dashboard Tests
+    """
+
     @classmethod
     def setUpTestData(cls):
+        """
+        Initialize Test database
+        """
         super().setUpTestData()
         cls.event = Event.objects.create(
-            name="Dashboard Test Event",
-            slug="dashboardtest",
-            timezone=pytz.utc,
-            start=now(),
-            end=now(),
-            active=True,
-            plan_hidden=False,
+                name="Dashboard Test Event",
+                slug="dashboardtest",
+                timezone=zoneinfo.ZoneInfo("Europe/Berlin"),
+                start=now(),
+                end=now(),
+                active=True,
+                plan_hidden=False,
+                poll_hidden=False,
         )
         cls.default_category = AKCategory.objects.create(
-            name="Test Category",
-            event=cls.event,
+                name="Test Category",
+                event=cls.event,
         )
 
     def test_dashboard_view(self):
+        """
+        Check that the main dashboard is reachable
+        (would also be covered by generic view testcase below)
+        """
         url = reverse('dashboard:dashboard_event', kwargs={"slug": self.event.slug})
         response = self.client.get(url)
         self.assertEqual(response.status_code, 200)
 
     def test_nonexistent_dashboard_view(self):
+        """
+        Make sure there is no dashboard for an non-existing event
+        """
         url = reverse('dashboard:dashboard_event', kwargs={"slug": "nonexistent-event"})
         response = self.client.get(url)
         self.assertEqual(response.status_code, 404)
 
     @override_settings(DASHBOARD_SHOW_RECENT=True)
     def test_history(self):
+        """
+        Test displaying of history
+
+        For the sake of that test, the setting to show recent events in dashboard is enforced to be true
+        regardless of the default configuration currently in place
+        """
         url = reverse('dashboard:dashboard_event', kwargs={"slug": self.event.slug})
 
         # History should be empty
         response = self.client.get(url)
-        self.assertQuerysetEqual(response.context["recent_changes"], [])
+        self.assertQuerySetEqual(response.context["recent_changes"], [])
 
         AK.objects.create(
-            name="Test AK",
-            category=self.default_category,
-            event=self.event,
+                name="Test AK",
+                category=self.default_category,
+                event=self.event,
         )
 
         # History should now contain one AK (Test AK)
@@ -57,6 +79,11 @@ class DashboardTests(TestCase):
         self.assertEqual(response.context["recent_changes"][0]['text'], "New AK: Test AK.")
 
     def test_public(self):
+        """
+        Test handling of public and private events
+        (only public events should be part of the standard dashboard,
+        but there should be an individual dashboard for both public and private events)
+        """
         url_dashboard_index = reverse('dashboard:dashboard')
         url_event_dashboard = reverse('dashboard:dashboard_event', kwargs={"slug": self.event.slug})
 
@@ -66,7 +93,8 @@ class DashboardTests(TestCase):
         self.event.save()
         response = self.client.get(url_dashboard_index)
         self.assertEqual(response.status_code, 200)
-        self.assertFalse(self.event in response.context["events"])
+        self.assertFalse(self.event in response.context["active_and_current_events"])
+        self.assertFalse(self.event in response.context["old_events"])
         response = self.client.get(url_event_dashboard)
         self.assertEqual(response.status_code, 200)
         self.assertEqual(response.context["event"], self.event)
@@ -76,9 +104,12 @@ class DashboardTests(TestCase):
         self.event.save()
         response = self.client.get(url_dashboard_index)
         self.assertEqual(response.status_code, 200)
-        self.assertTrue(self.event in response.context["events"])
+        self.assertTrue(self.event in response.context["active_and_current_events"])
 
     def test_active(self):
+        """
+        Test existence of buttons with regard to activity status of the given event
+        """
         url_event_dashboard = reverse('dashboard:dashboard_event', kwargs={"slug": self.event.slug})
 
         if apps.is_installed('AKSubmission'):
@@ -95,6 +126,9 @@ class DashboardTests(TestCase):
             self.assertContains(response, "AK Submission")
 
     def test_plan_hidden(self):
+        """
+        Test visibility of plan buttons with regard to plan visibility status for a given event
+        """
         url_event_dashboard = reverse('dashboard:dashboard_event', kwargs={"slug": self.event.slug})
 
         if apps.is_installed('AKPlan'):
@@ -113,15 +147,38 @@ class DashboardTests(TestCase):
             self.assertContains(response, "Current AKs")
             self.assertContains(response, "AK Wall")
 
+    def test_poll_hidden(self):
+        """
+        Test visibility of poll buttons with regard to poll visibility status for a given event
+        """
+        url_event_dashboard = reverse('dashboard:dashboard_event', kwargs={"slug": self.event.slug})
+
+        if apps.is_installed('AKPreference'):
+            # Poll hidden? No buttons should show up
+            self.event.poll_hidden = True
+            self.event.save()
+            response = self.client.get(url_event_dashboard)
+            self.assertNotContains(response, "AK Preferences")
+
+            # Poll not hidden?
+            # Buttons to preference poll should be on the page
+            self.event.poll_hidden = False
+            self.event.save()
+            response = self.client.get(url_event_dashboard)
+            self.assertContains(response, "AK Preferences")
+
     def test_dashboard_buttons(self):
+        """
+        Make sure manually added buttons are displayed correctly
+        """
         url_event_dashboard = reverse('dashboard:dashboard_event', kwargs={"slug": self.event.slug})
 
         response = self.client.get(url_event_dashboard)
         self.assertNotContains(response, "Dashboard Button Test")
 
         DashboardButton.objects.create(
-            text="Dashboard Button Test",
-            event=self.event
+                text="Dashboard Button Test",
+                event=self.event
         )
 
         response = self.client.get(url_event_dashboard)
@@ -129,6 +186,9 @@ class DashboardTests(TestCase):
 
 
 class DashboardViewTests(BasicViewTests, TestCase):
+    """
+    Generic view tests, based on :class:`AKModel.BasicViewTests` as specified in this class in VIEWS
+    """
     fixtures = ['model.json', 'dashboard.json']
 
     APP_NAME = 'dashboard'

AKDashboard/views.py

@@ -22,7 +22,18 @@ class DashboardView(TemplateView):
 
     def get_context_data(self, **kwargs):
         context = super().get_context_data(**kwargs)
-        context['events'] = Event.objects.filter(public=True).prefetch_related('dashboardbutton_set')
+        # Load events and split between active and current/featured events and those that should show smaller below
+        context["active_and_current_events"] = []
+        context["old_events"] = []
+        events = Event.objects.filter(public=True).order_by("-active", "-pk").prefetch_related('dashboardbutton_set')
+        for event in events:
+            if event.active or len(context["active_and_current_events"]) < settings.DASHBOARD_MAX_FEATURED_EVENTS:
+                context["active_and_current_events"].append(event)
+            else:
+                context["old_events"].append(event)
+        context["active_event_count"] = len(context["active_and_current_events"])
+        context["old_event_count"] = len(context["old_events"])
+        context["total_event_count"] = context["active_event_count"] + context["old_event_count"]
         return context
 
 

AKModel/apps.py

@@ -3,8 +3,15 @@ from django.contrib.admin.apps import AdminConfig
 
 
 class AkmodelConfig(AppConfig):
+    """
+    App configuration (default, only specifies name of the app)
+    """
     name = 'AKModel'
 
 
 class AKAdminConfig(AdminConfig):
+    """
+    App configuration for admin
+    Loading a custom version here allows to add additional contex and further adapt the behavior of the admin interface
+    """
     default_site = 'AKModel.site.AKAdminSite'

AKModel/availability/forms.py

 # This part of the code was adapted from pretalx (https://github.com/pretalx/pretalx)
 # Copyright 2017-2019, Tobias Kunze
 # Original Copyrights licensed under the Apache License, Version 2.0 http://www.apache.org/licenses/LICENSE-2.0
-# Changes are marked in the code
+# Documentation was mainly added by us, other changes are marked in the code
 import datetime
 import json
 
@@ -12,11 +12,15 @@ from django.utils.dateparse import parse_datetime
 from django.utils.translation import gettext_lazy as _
 
 from AKModel.availability.models import Availability
-from AKModel.availability.serializers import AvailabilitySerializer
+from AKModel.availability.serializers import AvailabilityFormSerializer
 from AKModel.models import Event
 
 
 class AvailabilitiesFormMixin(forms.Form):
+    """
+    Mixin for forms to add availabilities functionality to it
+    Will handle the rendering and population of an availabilities field
+    """
     availabilities = forms.CharField(
         label=_('Availability'),
         help_text=_(
@@ -28,40 +32,46 @@ class AvailabilitiesFormMixin(forms.Form):
     )
 
     def _serialize(self, event, instance):
+        """
+        Serialize relevant availabilities into a JSON format to populate the text field in the form
+
+        :param event: event the availabilities belong to (relevant for start and end times)
+        :param instance: the entity availabilities in this form should belong to (e.g., an AK, or a Room)
+        :return: JSON serializiation of the relevant availabilities
+        :rtype: str
+        """
         if instance:
-            availabilities = AvailabilitySerializer(
-                instance.availabilities.all(), many=True
-            ).data
+            availabilities = instance.availabilities.all()
         else:
             availabilities = []
 
-        return json.dumps(
-            {
-                'availabilities': availabilities,
-                'event': {
-                    # 'timezone': event.timezone,
-                    'date_from': str(event.start),
-                    'date_to': str(event.end),
-                },
-            }
-        )
+        return json.dumps(AvailabilityFormSerializer((availabilities, event)).data)
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
+        # Load event information and populate availabilities text field
         self.event = self.initial.get('event')
         if isinstance(self.event, int):
             self.event = Event.objects.get(pk=self.event)
-        initial = kwargs.pop('initial', dict())
-        initial['availabilities'] = self._serialize(self.event, kwargs['instance'])
+        initial = kwargs.pop('initial', {})
+        if 'availabilities' not in initial:
+            initial['availabilities'] = self._serialize(self.event, kwargs.get('instance'))
         if not isinstance(self, forms.BaseModelForm):
-            kwargs.pop('instance')
+            kwargs.pop('instance', None)
         kwargs['initial'] = initial
 
     def _parse_availabilities_json(self, jsonavailabilities):
+        """
+        Turn raw JSON availabilities into a list of model instances
+
+        :param jsonavailabilities: raw json input
+        :return: a list of availability objects corresponding to the raw input
+        :rtype: List[Availability]
+        """
         try:
             rawdata = json.loads(jsonavailabilities)
-        except ValueError:
-            raise forms.ValidationError("Submitted availabilities are not valid json.")
+        except ValueError as exc:
+            raise forms.ValidationError("Submitted availabilities are not valid json.") from exc
         if not isinstance(rawdata, dict):
             raise forms.ValidationError(
                 "Submitted json does not comply with expected format, should be object."
@@ -74,17 +84,32 @@ class AvailabilitiesFormMixin(forms.Form):
         return availabilities
 
     def _parse_datetime(self, strdate):
+        """
+        Parse input date string
+        This will try to correct timezone information if needed
+
+        :param strdate: string representing a timestamp
+        :return: a timestamp object
+        """
         tz = self.event.timezone  # adapt to our event model
 
         obj = parse_datetime(strdate)
         if not obj:
             raise TypeError
         if obj.tzinfo is None:
+            # Adapt to new python timezone interface
             obj = obj.replace(tzinfo=tz)
 
         return obj
 
     def _validate_availability(self, rawavail):
+        """
+        Validate a raw availability instance input by making sure the relevant fields are present and can be parsed
+        The cleaned up values that are produced to test the validity of the input are stored in-place in the input
+        object for later usage in cleaning/parsing to availability objects
+
+        :param rawavail: object to validate/clean
+        """
         message = _("The submitted availability does not comply with the required format.")
         if not isinstance(rawavail, dict):
             raise forms.ValidationError(message)
@@ -96,12 +121,11 @@ class AvailabilitiesFormMixin(forms.Form):
         try:
             rawavail['start'] = self._parse_datetime(rawavail['start'])
             rawavail['end'] = self._parse_datetime(rawavail['end'])
-        except (TypeError, ValueError):
+        # Adapt: Better error handling
+        except (TypeError, ValueError) as exc:
             raise forms.ValidationError(
                 _("The submitted availability contains an invalid date.")
-            )
-
-        tz = self.event.timezone  # adapt to our event model
+            ) from exc
 
         timeframe_start = self.event.start  # adapt to our event model
         if rawavail['start'] < timeframe_start:
@@ -115,6 +139,10 @@ class AvailabilitiesFormMixin(forms.Form):
             rawavail['end'] = timeframe_end
 
     def clean_availabilities(self):
+        """
+        Turn raw availabilities into real availability objects
+        :return:
+        """
         data = self.cleaned_data.get('availabilities')
         required = (
                 'availabilities' in self.fields and self.fields['availabilities'].required
@@ -135,7 +163,8 @@ class AvailabilitiesFormMixin(forms.Form):
         return availabilities
 
     def _set_foreignkeys(self, instance, availabilities):
-        """Set the reference to `instance` in each given availability.
+        """
+        Set the reference to `instance` in each given availability.
         For example, set the availabilitiy.room_id to instance.id, in
         case instance of type Room.
         """
@@ -144,11 +173,21 @@ class AvailabilitiesFormMixin(forms.Form):
         for avail in availabilities:
             setattr(avail, reference_name, instance.id)
 
-    def _replace_availabilities(self, instance, availabilities: [Availability]):
+    def _replace_availabilities(self, instance, availabilities: list[Availability]):
+        """
+        Replace the existing list of availabilities belonging to an entity with a new, updated one
+
+        This will trigger a post_save signal for usage in constraint violation checking
+
+        :param instance: entity the availabilities belong to
+        :param availabilities: list of new availabilities
+        """
         with transaction.atomic():
-            # TODO: do not recreate objects unnecessarily, give the client the IDs, so we can track modifications and leave unchanged objects alone
+            # TODO: do not recreate objects unnecessarily, give the client the IDs, so we can track modifications and
+            #  leave unchanged objects alone
             instance.availabilities.all().delete()
             Availability.objects.bulk_create(availabilities)
+            # Adaption:
             # Trigger post save signal manually to make sure constraints are updated accordingly
             # Doing this one time is sufficient, since this will nevertheless update all availability constraint
             # violations of the corresponding AK
@@ -156,6 +195,9 @@ class AvailabilitiesFormMixin(forms.Form):
                 post_save.send(Availability, instance=availabilities[0], created=True)
 
     def save(self, *args, **kwargs):
+        """
+        Override the saving method of the (model) form
+        """
         instance = super().save(*args, **kwargs)
         availabilities = self.cleaned_data.get('availabilities')
 

AKModel/availability/models.py

@@ -11,6 +11,8 @@ from django.utils.functional import cached_property
 from django.utils.translation import gettext_lazy as _
 
 from AKModel.models import Event, AKOwner, Room, AK, AKCategory
+# TODO: Decouple from AKPreference app
+from AKPreference.models import EventParticipant
 
 zero_time = datetime.time(0, 0)
 
@@ -23,6 +25,10 @@ zero_time = datetime.time(0, 0)
 # add meta class
 # enable availabilities for AKs and AKCategories
 # add verbose names and help texts to model attributes
+# adapt or extemd documentation
+# add participants
+
+
 class Availability(models.Model):
     """The Availability class models when people or rooms are available for.
 
@@ -31,6 +37,8 @@ class Availability(models.Model):
     span multiple days, but due to our choice of input widget, it will
     usually only span a single day at most.
     """
+    # pylint: disable=broad-exception-raised
+
     event = models.ForeignKey(
         to=Event,
         related_name='availabilities',
@@ -74,20 +82,48 @@ class Availability(models.Model):
         verbose_name=_('AK Category'),
         help_text=_('AK Category whose availability this is'),
     )
+    participant = models.ForeignKey(
+        to=EventParticipant,
+        related_name='availabilities',
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        verbose_name=_('Participant'),
+        help_text=_('Participant whose availability this is'),
+    )
     start = models.DateTimeField()
     end = models.DateTimeField()
 
     def __str__(self) -> str:
         person = self.person.name if self.person else None
+        participant = str(self.participant) if self.participant else None
         room = getattr(self.room, 'name', None)
         event = getattr(getattr(self, 'event', None), 'name', None)
         ak = getattr(self.ak, 'name', None)
         ak_category = getattr(self.ak_category, 'name', None)
-        return f'Availability(event={event}, person={person}, room={room}, ak={ak}, ak category={ak_category})'
+        arg_list = [
+            f"event={event}",
+            f"person={person}",
+            f"room={room}",
+            f"ak={ak}",
+            f"ak category={ak_category}",
+            f"participant={participant}",
+        ]
+        return f'Availability({", ".join(arg_list)})'
 
     def __hash__(self):
         return hash(
-            (getattr(self, 'event', None), self.person, self.room, self.ak, self.ak_category, self.start, self.end))
+            (
+                getattr(self, 'event', None),
+                self.person,
+                self.room,
+                self.ak,
+                self.ak_category,
+                self.participant,
+                self.start,
+                self.end,
+            )
+        )
 
     def __eq__(self, other: 'Availability') -> bool:
         """Comparisons like ``availability1 == availability2``.
@@ -96,10 +132,10 @@ class Availability(models.Model):
         are the same.
         """
         return all(
-            [
+            (
                 getattr(self, attribute, None) == getattr(other, attribute, None)
-                for attribute in ['event', 'person', 'room', 'ak', 'ak_category', 'start', 'end']
-            ]
+                for attribute in ['event', 'person', 'room', 'ak', 'ak_category', 'participant', 'start', 'end']
+            )
         )
 
     @cached_property
@@ -146,9 +182,12 @@ class Availability(models.Model):
         if not other.overlaps(self, strict=False):
             raise Exception('Only overlapping Availabilities can be merged.')
 
-        return Availability(
+        avail = Availability(
             start=min(self.start, other.start), end=max(self.end, other.end)
         )
+        if self.event == other.event:
+            avail.event = self.event
+        return avail
 
     def __or__(self, other: 'Availability') -> 'Availability':
         """Performs the merge operation: ``availability1 | availability2``"""
@@ -163,9 +202,12 @@ class Availability(models.Model):
         if not other.overlaps(self, False):
             raise Exception('Only overlapping Availabilities can be intersected.')
 
-        return Availability(
+        avail = Availability(
             start=max(self.start, other.start), end=min(self.end, other.end)
         )
+        if self.event == other.event:
+            avail.event = self.event
+        return avail
 
     def __and__(self, other: 'Availability') -> 'Availability':
         """Performs the intersect operation: ``availability1 &
@@ -233,16 +275,66 @@ class Availability(models.Model):
 
     @property
     def simplified(self):
-        return f'{self.start.astimezone(self.event.timezone).strftime("%a %H:%M")}-{self.end.astimezone(self.event.timezone).strftime("%a %H:%M")}'
+        """
+        Get a simplified (only Weekday, hour and minute) string representation of an availability
+        :return: simplified string version
+        :rtype: str
+        """
+        return (f'{self.start.astimezone(self.event.timezone).strftime("%a %H:%M")}-'
+                f'{self.end.astimezone(self.event.timezone).strftime("%a %H:%M")}')
 
     @classmethod
-    def with_event_length(cls, event, person=None, room=None, ak=None, ak_category=None):
+    def with_event_length(
+        cls,
+        event: Event,
+        person: AKOwner | None = None,
+        room: Room | None = None,
+        ak: AK | None = None,
+        ak_category: AKCategory | None = None,
+        participant: EventParticipant | None = None,
+    ) -> "Availability":
+        """
+        Create an availability covering exactly the time between event start and event end.
+        Can e.g., be used to create default availabilities.
+
+        :param event: relevant event
+        :param person: person, if availability should be connected to a person
+        :param room: room, if availability should be connected to a room
+        :param ak: ak, if availability should be connected to a ak
+        :param ak_category: ak_category, if availability should be connected to a ak_category
+        :return: availability associated to the entity oder entities selected
+        :rtype: Availability
+        """
         timeframe_start = event.start  # adapt to our event model
         # add 1 day, not 24 hours, https://stackoverflow.com/a/25427822/2486196
         timeframe_end = event.end  # adapt to our event model
         timeframe_end = timeframe_end + datetime.timedelta(days=1)
         return Availability(start=timeframe_start, end=timeframe_end, event=event, person=person,
-                                    room=room, ak=ak, ak_category=ak_category)
+                                    room=room, ak=ak, ak_category=ak_category, participant=participant)
+
+    def is_covered(self, availabilities: List['Availability']):
+        """Check if list of availibilities cover this object.
+
+        :param availabilities: availabilities to check.
+        :return: whether the availabilities cover full event.
+        :rtype: bool
+        """
+        avail_union = Availability.union(availabilities)
+        return any(avail.contains(self) for avail in avail_union)
+
+    @classmethod
+    def is_event_covered(cls, event: Event, availabilities: List['Availability']) -> bool:
+        """Check if list of availibilities cover whole event.
+
+        :param event: event to check.
+        :param availabilities: availabilities to check.
+        :return: whether the availabilities cover full event.
+        :rtype: bool
+        """
+        # NOTE: Cannot use `Availability.with_event_length` as its end is the
+        #       event end + 1 day
+        full_event = Availability(event=event, start=event.start, end=event.end)
+        return full_event.is_covered(availabilities)
 
     class Meta:
         verbose_name = _('Availability')

AKModel/availability/serializers.py

 # This part of the code was adapted from pretalx (https://github.com/pretalx/pretalx)
 # Copyright 2017-2019, Tobias Kunze
 # Original Copyrights licensed under the Apache License, Version 2.0 http://www.apache.org/licenses/LICENSE-2.0
-# Changes are marked in the code
+# Documentation was mainly added by us, other changes are marked in the code
 from django.utils import timezone
 from rest_framework.fields import SerializerMethodField
-from rest_framework.serializers import ModelSerializer
+from rest_framework.serializers import BaseSerializer, ModelSerializer
 
 from AKModel.availability.models import Availability
+from AKModel.models import Event
 
 
 class AvailabilitySerializer(ModelSerializer):
+    """
+    REST Framework Serializer for Availability
+    """
     allDay = SerializerMethodField()
     start = SerializerMethodField()
     end = SerializerMethodField()
 
-    def get_allDay(self, obj):
+    def get_allDay(self, obj):  # pylint: disable=invalid-name
+        """
+        Bridge between naming conventions of python and fullcalendar by providing the all_day field as allDay, too
+        """
         return obj.all_day
 
-    # Use already localized strings in serialized field
-    # (default would be UTC, but that would require heavy timezone calculation on client side)
     def get_start(self, obj):
+        """
+        Get start timestamp
+
+        Use already localized strings in serialized field
+        (default would be UTC, but that would require heavy timezone calculation on client side)
+        """
         return timezone.localtime(obj.start, obj.event.timezone).strftime("%Y-%m-%dT%H:%M:%S")
 
     def get_end(self, obj):
+        """
+        Get end timestamp
+
+        Use already localized strings in serialized field
+        (default would be UTC, but that would require heavy timezone calculation on client side)
+        """
         return timezone.localtime(obj.end, obj.event.timezone).strftime("%Y-%m-%dT%H:%M:%S")
 
     class Meta:
         model = Availability
         fields = ('id', 'start', 'end', 'allDay')
+
+
+class AvailabilityFormSerializer(BaseSerializer):
+    """Serializer to configure an availability form."""
+
+    def create(self, validated_data):
+        raise ValueError("`AvailabilityFormSerializer` is read-only.")
+
+    def to_internal_value(self, data):
+        raise ValueError("`AvailabilityFormSerializer` is read-only.")
+
+    def update(self, instance, validated_data):
+        raise ValueError("`AvailabilityFormSerializer` is read-only.")
+
+    def to_representation(self, instance: tuple[Availability, Event], **kwargs):
+        availabilities, event = instance
+
+        return {
+            'availabilities': AvailabilitySerializer(availabilities, many=True).data,
+            'event': {
+                # 'timezone': event.timezone,
+                'date_from': str(event.start),
+                'date_to': str(event.end),
+            },
+        }

AKModel/environment.py

-# environment.py
+"""
+Environment definitions
+Needed for tex compilation
+"""
 import re
 
 from django_tex.environment import environment
 
 # Used to filter all very special UTF-8 chars that are probably not contained in the LaTeX fonts
 # and would hence cause compilation errors
-utf8_replace_pattern = re.compile(u'[^\u0000-\u206F]', re.UNICODE)
+utf8_replace_pattern = re.compile('[^\u0000-\u206F]', re.UNICODE)
 
 
 def latex_escape_utf8(value):
@@ -17,12 +20,14 @@ def latex_escape_utf8(value):
     :return: escaped string
     :rtype: str
     """
-    return utf8_replace_pattern.sub('', value).replace('&', '\&').replace('_', '\_').replace('#', '\#').replace('$',
-                                                                                                                '\$').replace(
-        '%', '\%').replace('{', '\{').replace('}', '\}')
+    return (utf8_replace_pattern.sub('', value).replace('&', r'\&').replace('_', r'\_').replace('#', r'\#').
+            replace('$', r'\$').replace('%', r'\%').replace('{', r'\{').replace('}', r'\}'))
 
 
 def improved_tex_environment(**options):
+    """
+    Encapsulate our improved latex environment for usage
+    """
     env = environment(**options)
     env.filters.update({
         'latex_escape_utf8': latex_escape_utf8,

AKModel/fixtures/model.json

@@ -93,7 +93,7 @@
     "model": "AKModel.akcategory",
     "pk": 1,
     "fields": {
-        "name": "Spa▀",
+        "name": "Spaß",
         "color": "275246",
         "description": "",
         "present_by_default": true,
@@ -115,7 +115,7 @@
     "model": "AKModel.akcategory",
     "pk": 3,
     "fields": {
-        "name": "Spa▀/Kultur",
+        "name": "Spaß/Kultur",
         "color": "333333",
         "description": "",
         "present_by_default": true,
@@ -193,6 +193,15 @@
         "event": 2
     }
 },
+{
+    "model": "AKModel.aktype",
+    "pk": 1,
+    "fields": {
+        "name": "Input",
+        "event": 2,
+        "slug": "input"
+    }
+},
 {
     "model": "AKModel.historicalak",
     "pk": 1,
@@ -206,7 +215,6 @@
         "reso": false,
         "present": true,
         "notes": "",
-        "interest": -1,
         "category": 4,
         "track": null,
         "event": 2,
@@ -229,7 +237,6 @@
         "reso": false,
         "present": true,
         "notes": "",
-        "interest": -1,
         "category": 4,
         "track": null,
         "event": 2,
@@ -252,7 +259,6 @@
         "reso": false,
         "present": null,
         "notes": "",
-        "interest": -1,
         "category": 5,
         "track": null,
         "event": 2,
@@ -275,7 +281,6 @@
         "reso": false,
         "present": null,
         "notes": "",
-        "interest": -1,
         "category": 5,
         "track": null,
         "event": 2,
@@ -298,7 +303,6 @@
         "reso": false,
         "present": null,
         "notes": "We need to find a volunteer first...",
-        "interest": -1,
         "category": 3,
         "track": null,
         "event": 2,
@@ -321,7 +325,6 @@
         "reso": false,
         "present": null,
         "notes": "We need to find a volunteer first...",
-        "interest": -1,
         "category": 3,
         "track": null,
         "event": 2,
@@ -344,7 +347,6 @@
         "reso": false,
         "present": null,
         "notes": "",
-        "interest": -1,
         "category": 5,
         "track": 1,
         "event": 2,
@@ -436,6 +438,62 @@
         ]
     }
 },
+{
+    "model": "AKModel.ak",
+    "pk": 4,
+    "fields": {
+        "name": "Test AK fixed slots",
+        "short_name": "testfixed",
+        "description": "",
+        "link": "",
+        "protocol_link": "",
+        "category": 4,
+        "track": null,
+        "reso": false,
+        "present": true,
+        "notes": "",
+        "interest": -1,
+        "interest_counter": 0,
+        "include_in_export": false,
+        "event": 2,
+        "owners": [
+            1
+        ],
+        "requirements": [
+            3
+        ],
+        "conflicts": [],
+        "prerequisites": []
+    }
+},
+{
+    "model": "AKModel.ak",
+    "pk": 5,
+    "fields": {
+        "name": "Test AK Ernst",
+        "short_name": "testernst",
+        "description": "",
+        "link": "",
+        "protocol_link": "",
+        "category": 2,
+        "track": null,
+        "reso": false,
+        "present": true,
+        "notes": "",
+        "interest": -1,
+        "interest_counter": 0,
+        "include_in_export": false,
+        "event": 1,
+        "owners": [
+            3
+        ],
+        "requirements": [
+            2
+        ],
+        "conflicts": [],
+        "prerequisites": []
+    }
+},
 {
     "model": "AKModel.room",
     "pk": 1,
@@ -460,6 +518,19 @@
         "properties": []
     }
 },
+{
+    "model": "AKModel.room",
+    "pk": 3,
+    "fields": {
+        "name": "BBB Session 1",
+        "location": "",
+        "capacity": -1,
+        "event": 1,
+        "properties": [
+            2
+        ]
+    }
+},
 {
     "model": "AKModel.akslot",
     "pk": 1,
@@ -525,6 +596,58 @@
         "updated": "2022-12-02T12:23:11.856Z"
     }
 },
+{
+    "model": "AKModel.akslot",
+    "pk": 6,
+    "fields": {
+        "ak": 4,
+        "room": null,
+        "start": "2020-11-08T18:30:00Z",
+        "duration": "2.00",
+        "fixed": true,
+        "event": 2,
+        "updated": "2022-12-02T12:23:11.856Z"
+    }
+},
+{
+    "model": "AKModel.akslot",
+    "pk": 7,
+    "fields": {
+        "ak": 4,
+        "room": 2,
+        "start": null,
+        "duration": "2.00",
+        "fixed": true,
+        "event": 2,
+        "updated": "2022-12-02T12:23:11.856Z"
+    }
+},
+{
+    "model": "AKModel.akslot",
+    "pk": 8,
+    "fields": {
+        "ak": 4,
+        "room": 2,
+        "start": "2020-11-07T16:00:00Z",
+        "duration": "2.00",
+        "fixed": true,
+        "event": 2,
+        "updated": "2022-12-02T12:23:11.856Z"
+    }
+},
+{
+    "model": "AKModel.akslot",
+    "pk": 9,
+    "fields": {
+        "ak": 5,
+        "room": null,
+        "start": null,
+        "duration": "2.00",
+        "fixed": false,
+        "event": 1,
+        "updated": "2022-12-02T12:23:11.856Z"
+    }
+},
 {
     "model": "AKModel.constraintviolation",
     "pk": 1,
@@ -668,5 +791,71 @@
         "start": "2020-11-07T18:30:00Z",
         "end": "2020-11-07T21:30:00Z"
     }
+},
+{
+    "model": "AKModel.availability",
+    "pk": 7,
+    "fields": {
+        "event": 1,
+        "person": null,
+        "room": null,
+        "ak": 5,
+        "ak_category": null,
+        "start": "2020-10-01T17:41:22Z",
+        "end": "2020-10-04T17:41:30Z"
+    }
+},
+{
+    "model": "AKModel.availability",
+    "pk": 8,
+    "fields": {
+        "event": 1,
+        "person": null,
+        "room": 3,
+        "ak": null,
+        "ak_category": null,
+        "start": "2020-10-01T17:41:22Z",
+        "end": "2020-10-04T17:41:30Z"
+    }
+},
+{
+    "model": "AKModel.defaultslot",
+    "pk": 1,
+    "fields": {
+        "event": 2,
+        "start": "2020-11-07T08:00:00Z",
+        "end": "2020-11-07T12:00:00Z",
+        "primary_categories": [5]
+    }
+},
+{
+    "model": "AKModel.defaultslot",
+    "pk": 2,
+    "fields": {
+        "event": 2,
+        "start": "2020-11-07T14:00:00Z",
+        "end": "2020-11-07T17:00:00Z",
+        "primary_categories": [4]
+    }
+},
+{
+    "model": "AKModel.defaultslot",
+    "pk": 3,
+    "fields": {
+        "event": 2,
+        "start": "2020-11-08T08:00:00Z",
+        "end": "2020-11-08T19:00:00Z",
+        "primary_categories": [4, 5]
+    }
+},
+{
+    "model": "AKModel.defaultslot",
+    "pk": 4,
+    "fields": {
+        "event": 2,
+        "start": "2020-11-09T17:00:00Z",
+        "end": "2020-11-10T01:00:00Z",
+        "primary_categories": [4, 5, 3]
+    }
 }
 ]

AKModel/forms.py

+"""
+Central and admin forms
+"""
+
 import csv
 import io
 
-from bootstrap_datepicker_plus.widgets import DateTimePickerInput
 from django import forms
 from django.forms.utils import ErrorList
 from django.utils.translation import gettext_lazy as _
 
 from AKModel.availability.forms import AvailabilitiesFormMixin
-from AKModel.models import Event, AKCategory, AKRequirement, Room
+from AKModel.models import Event, AKCategory, AKRequirement, Room, AKType
+
+
+class DateTimeInput(forms.DateInput):
+    """
+    Simple widget for datetime input fields using the HTML5 datetime-local input type
+    """
+    input_type = 'datetime-local'
 
 
 class NewEventWizardStartForm(forms.ModelForm):
+    """
+    Initial view of new event wizard
+
+    This form is a model form for Event, but only with a subset of the required fields.
+    It is therefore not possible to really create an event using this form, but only to enter
+    information, in particular the timezone, that is needed to correctly handle/parse the user
+    inputs for further required fields like start and end of the event.
+
+    The form will be used for this partial input, the input of the remaining required fields
+    will then be handled by :class:`NewEventWizardSettingsForm` (see below).
+    """
     class Meta:
         model = Event
-        fields = ['name', 'slug', 'timezone', 'plan_hidden']
+        fields = ['name', 'slug', 'timezone', 'plan_hidden', 'poll_hidden']
         widgets = {
             'plan_hidden': forms.HiddenInput(),
+            'poll_hidden': forms.HiddenInput(),
         }
 
+    # Special hidden field for wizard state handling
     is_init = forms.BooleanField(initial=True, widget=forms.HiddenInput)
 
 
 class NewEventWizardSettingsForm(forms.ModelForm):
+    """
+    Form for second view of the event creation wizard.
+
+    Will handle the input of the remaining required as well as some optional fields.
+    See also :class:`NewEventWizardStartForm`.
+    """
     class Meta:
         model = Event
-        exclude = []
+        fields = "__all__"
+        exclude = ['plan_published_at', 'poll_published_at']
         widgets = {
             'name': forms.HiddenInput(),
             'slug': forms.HiddenInput(),
             'timezone': forms.HiddenInput(),
             'active': forms.HiddenInput(),
-            'start': DateTimePickerInput(options={"format": "YYYY-MM-DD HH:mm"}),
-            'end': DateTimePickerInput(options={"format": "YYYY-MM-DD HH:mm"}),
-            'reso_deadline': DateTimePickerInput(options={"format": "YYYY-MM-DD HH:mm"}),
+            'start': DateTimeInput(),
+            'end': DateTimeInput(),
+            'interest_start': DateTimeInput(),
+            'interest_end': DateTimeInput(),
+            'reso_deadline': DateTimeInput(),
             'plan_hidden': forms.HiddenInput(),
+            'poll_hidden': forms.HiddenInput(),
         }
 
 
 class NewEventWizardPrepareImportForm(forms.Form):
+    """
+    Wizard form for choosing an event to import/copy elements (requirements, categories, etc) from.
+    Is used to restrict the list of elements to choose from in the next step (see :class:`NewEventWizardImportForm`).
+    """
     import_event = forms.ModelChoiceField(
         queryset=Event.objects.all(),
         label=_("Copy ak requirements and ak categories of existing event"),
@@ -46,6 +83,12 @@ class NewEventWizardPrepareImportForm(forms.Form):
 
 
 class NewEventWizardImportForm(forms.Form):
+    """
+    Wizard form for excaclty choosing which elemments to copy/import for the newly created event.
+    Possible elements are categories, requirements, and dashboard buttons if AKDashboard is active.
+    The lists are restricted to elements from the event selected in the previous step
+    (see :class:`NewEventWizardPrepareImportForm`).
+    """
     import_categories = forms.ModelMultipleChoiceField(
         queryset=AKCategory.objects.all(),
         widget=forms.CheckboxSelectMultiple,
@@ -60,6 +103,14 @@ class NewEventWizardImportForm(forms.Form):
         required=False,
     )
 
+    import_types = forms.ModelMultipleChoiceField(
+        queryset=AKType.objects.all(),
+        widget=forms.CheckboxSelectMultiple,
+        label=_("Copy types"),
+        required=False,
+    )
+
+    # pylint: disable=too-many-arguments
     def __init__(self, data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=ErrorList,
                  label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None,
                  renderer=None):
@@ -69,11 +120,15 @@ class NewEventWizardImportForm(forms.Form):
             event=self.initial["import_event"])
         self.fields["import_requirements"].queryset = self.fields["import_requirements"].queryset.filter(
             event=self.initial["import_event"])
+        self.fields["import_types"].queryset = self.fields["import_types"].queryset.filter(
+            event=self.initial["import_event"])
 
+        # pylint: disable=import-outside-toplevel
+        # Local imports used to prevent cyclic imports and to only import when AKDashboard is available
         from django.apps import apps
         if apps.is_installed("AKDashboard"):
+            # If AKDashboard is active, allow to copy dashboard buttons, too
             from AKDashboard.models import DashboardButton
-
             self.fields["import_buttons"] = forms.ModelMultipleChoiceField(
                 queryset=DashboardButton.objects.filter(event=self.initial["import_event"]),
                 widget=forms.CheckboxSelectMultiple,
@@ -83,26 +138,55 @@ class NewEventWizardImportForm(forms.Form):
 
 
 class NewEventWizardActivateForm(forms.ModelForm):
+    """
+    Wizard form to activate the newly created event
+    """
     class Meta:
         fields = ["active"]
         model = Event
 
 
 class AdminIntermediateForm(forms.Form):
-    pass
+    """
+    Base form for admin intermediate views (forms used there should inherit from this,
+    by default, the form is empty since it is only needed for the confirmation button)
+    """
 
 
 class AdminIntermediateActionForm(AdminIntermediateForm):
+    """
+    Form for Admin Action Confirmation views -- has a pks field needed to handle the serialization/deserialization of
+    the IDs of the entities the user selected for the admin action to be performed on
+    """
     pks = forms.CharField(widget=forms.HiddenInput)
 
 
 class SlideExportForm(AdminIntermediateForm):
+    """
+    Form to control the slides generated from the AK list of an event
+
+    The user can select how many upcoming AKs are displayed at the footer to inform people that it is their turn soon,
+    whether the AK list should be restricted to those AKs that where marked for presentation, and whether ther should
+    be a symbol and empty space to take notes on for wishes
+    """
     num_next = forms.IntegerField(
         min_value=0,
         max_value=6,
         initial=3,
         label=_("# next AKs"),
         help_text=_("How many next AKs should be shown on a slide?"))
+    types = forms.MultipleChoiceField(
+        label=_("AK Types"),
+        help_text=_("Which AK types should be included in the slides?"),
+        widget=forms.CheckboxSelectMultiple,
+        choices=[],
+        required=False)
+    types_all_selected_only = forms.BooleanField(
+        initial=False,
+        label=_("Only show AKs with all selected types?"),
+        help_text=_("If checked, only AKs that have all selected types will be shown in the slides. "
+                    "If unchecked, AKs with at least one of the selected types will be shown."),
+        required=False)
     presentation_mode = forms.TypedChoiceField(
         initial=False,
         label=_("Presentation only?"),
@@ -121,6 +205,9 @@ class SlideExportForm(AdminIntermediateForm):
 
 
 class DefaultSlotEditorForm(AdminIntermediateForm):
+    """
+    Form for default slot editor
+    """
     availabilities = forms.CharField(
         label=_('Default Slots'),
         help_text=_(
@@ -133,6 +220,12 @@ class DefaultSlotEditorForm(AdminIntermediateForm):
 
 
 class RoomBatchCreationForm(AdminIntermediateForm):
+    """
+    Form for room batch creation
+
+    Allows to input a list of room details and choose whether default availabilities should be generated for these
+    rooms. Will check that the input follows a CSV format with at least a name column present.
+    """
     rooms = forms.CharField(
         label=_('New rooms'),
         help_text=_('Enter room details in CSV format. Required colum is "name", optional colums are "location", '
@@ -147,6 +240,13 @@ class RoomBatchCreationForm(AdminIntermediateForm):
     )
 
     def clean_rooms(self):
+        """
+        Validate and transform the input for the rooms textfield
+        Treat the input as CSV and turn it into a dict containing the relevant information.
+
+        :return: a dict containing the raw room information
+        :rtype: dict[str, str]
+        """
         rooms_raw_text = self.cleaned_data["rooms"]
         rooms_raw_dict = csv.DictReader(io.StringIO(rooms_raw_text), delimiter=";")
 
@@ -157,6 +257,10 @@ class RoomBatchCreationForm(AdminIntermediateForm):
 
 
 class RoomForm(forms.ModelForm):
+    """
+    Room (creation) form (basic), will be extended for handling of availabilities
+    (see :class:`RoomFormWithAvailabilities`) and also for creating hybrid rooms in AKOnline (if active)
+    """
     class Meta:
         model = Room
         fields = ['name',
@@ -167,6 +271,9 @@ class RoomForm(forms.ModelForm):
 
 
 class RoomFormWithAvailabilities(AvailabilitiesFormMixin, RoomForm):
+    """
+    Room (update) form including handling of availabilities, extends :class:`RoomForm`
+    """
     class Meta:
         model = Room
         fields = ['name',
@@ -182,7 +289,7 @@ class RoomFormWithAvailabilities(AvailabilitiesFormMixin, RoomForm):
 
     def __init__(self, *args, **kwargs):
         # Init availability mixin
-        kwargs['initial'] = dict()
+        kwargs['initial'] = {}
         super().__init__(*args, **kwargs)
         self.initial = {**self.initial, **kwargs['initial']}
         # Filter possible values for m2m when event is specified

AKModel/management/commands/makemessages.py

-"""
-Ensure PO files are generated using forward slashes in the location comments on all operating systems
-"""
 import os
 
 from django.core.management.commands.makemessages import Command as MakeMessagesCommand
 
 
 class Command(MakeMessagesCommand):
+    """
+    Adapted version of the :class:`MakeMessagesCommand`
+    Ensure PO files are generated using forward slashes in the location comments on all operating systems
+    """
     def find_files(self, root):
+        # Replace backward slashes with forward slashes if necessary in file list
         all_files = super().find_files(root)
         if os.sep != "\\":
             return all_files
@@ -21,17 +23,19 @@ class Command(MakeMessagesCommand):
         return all_files
 
     def build_potfiles(self):
+        # Replace backward slashes with forward slashes if necessary in the files itself
         pot_files = super().build_potfiles()
         if os.sep != "\\":
             return pot_files
 
         for filename in pot_files:
-            lines = open(filename, "r", encoding="utf-8").readlines()
-            fixed_lines = []
-            for line in lines:
-                if line.startswith("#: "):
-                    line = line.replace("\\", "/")
-                fixed_lines.append(line)
+            with open(filename, "r", encoding="utf-8") as f:
+                lines = f.readlines()
+                fixed_lines = []
+                for line in lines:
+                    if line.startswith("#: "):
+                        line = line.replace("\\", "/")
+                    fixed_lines.append(line)
 
             with open(filename, "w", encoding="utf-8") as f:
                 f.writelines(fixed_lines)