Compare revisions

Benjamin Hättasch · Benjamin Hättasch · Benjamin Hättasch · Benjamin Hättasch · Benjamin Hättasch · Benjamin Hättasch
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -18,16 +18,16 @@ 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 --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
-check-migrations:
-  script:
    - source venv/bin/activate
    - ./manage.py makemigrations --dry-run --check
@@ -48,3 +48,42 @@ test:
        coverage_format: cobertura
        path: coverage.xml
      junit: unit.xml
+lint:
+  stage: test
+  script:
+    - 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 --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)"
+  artifacts:
+    paths:
+      - public
+    reports:
+      codequality: codeclimate.json
+    when: always
+doc:
+  stage: test
+  script:
+    - cd docs
+    - make html
+    - cd ..
+  artifacts:
+    paths:
+      - docs/_build/html
+pages:
+  stage: deploy
+  image: alpine:latest
+  script:
+    - echo
+  artifacts:
+    paths:
+      - public
+  only:
+    refs:
+      - main
--- a/AKDashboard/admin.py
+++ b/AKDashboard/admin.py
@@ -4,6 +4,9 @@ from AKDashboard.models import DashboardButton
 @admin.register(DashboardButton)
 class DashboardButtonAdmin(admin.ModelAdmin):
+    """
+    Admin interface for dashboard buttons
+    """
    list_display = ['text', 'url', 'event']
    list_filter = ['event']
    search_fields = ['text', 'url']

--- a/AKDashboard/apps.py
+++ b/AKDashboard/apps.py
@@ -2,4 +2,7 @@ from django.apps import AppConfig
 class AkdashboardConfig(AppConfig):
+    """
+    App configuration for dashboard (default)
+    """
    name = 'AKDashboard'
--- a/AKDashboard/locale/de_DE/LC_MESSAGES/django.po
+++ b/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: 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,47 +17,47 @@ 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"
@@ -105,22 +105,22 @@ msgstr "AK-Einreichung"
 msgid "AK History"
 msgstr "AK-Verlauf"
-#: AKDashboard/views.py:42
+#: AKDashboard/views.py:59
 #, python-format
 msgid "New AK: %(ak)s."
 msgstr "Neuer AK: %(ak)s."
-#: AKDashboard/views.py:45
+#: AKDashboard/views.py:62
 #, python-format
 msgid "AK \"%(ak)s\" edited."
 msgstr "AK \"%(ak)s\" bearbeitet."
-#: AKDashboard/views.py:48
+#: AKDashboard/views.py:65
 #, python-format
 msgid "AK \"%(ak)s\" deleted."
 msgstr "AK \"%(ak)s\" gelöscht."
-#: AKDashboard/views.py:60
+#: AKDashboard/views.py:80
 #, python-format
 msgid "AK \"%(ak)s\" (re-)scheduled."
 msgstr "AK \"%(ak)s\" (um-)geplant."
--- a/AKDashboard/models.py
+++ b/AKDashboard/models.py
@@ -6,6 +6,17 @@ from AKModel.models import Event
 class DashboardButton(models.Model):
+    """
+    Model for a single dashboard button
+    Allows to specify
+    * a text (currently without possibility to translate),
+    * a color (based on predefined design colors)
+    * a url the button should point to (internal or external)
+    * an icon (from the collection of fontawesome)
+    Each button is associated with a single event and will be deleted when the event is deleted.
+    """
    class Meta:
        verbose_name = _("Dashboard Button")
        verbose_name_plural = _("Dashboard Buttons")

--- a/AKDashboard/tests.py
+++ b/AKDashboard/tests.py
@@ -10,8 +10,14 @@ from AKModel.tests 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",
@@ -28,17 +34,30 @@ class DashboardTests(TestCase):
        )
    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
@@ -57,6 +76,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})
@@ -79,6 +103,9 @@ class DashboardTests(TestCase):
        self.assertTrue(self.event in response.context["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 +122,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'):
@@ -114,6 +144,9 @@ class DashboardTests(TestCase):
            self.assertContains(response, "AK Wall")
    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)
@@ -129,6 +162,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'

--- a/AKDashboard/views.py
+++ b/AKDashboard/views.py
 from django.apps import apps
-from django.urls import reverse_lazy
 from django.utils.decorators import method_decorator
 from django.views.decorators.csrf import ensure_csrf_cookie
 from django.views.generic import TemplateView, DetailView
@@ -10,6 +9,11 @@ from AKPlanning import settings
 class DashboardView(TemplateView):
+    """
+    Index view of dashboard and therefore the main entry point for AKPlanning
+    Displays information and buttons for all public events
+    """
    template_name = 'AKDashboard/dashboard.html'
    @method_decorator(ensure_csrf_cookie)
@@ -23,6 +27,14 @@ class DashboardView(TemplateView):
 class DashboardEventView(DetailView):
+    """
+    Dashboard view for a single event
+    In addition to the basic information and the buttons,
+    an overview over recent events (new and changed AKs, moved AKSlots) for the given event is shown.
+    The event dashboard also exists for non-public events (one only needs to know the URL/slug of the event).
+    """
    template_name = 'AKDashboard/dashboard_event.html'
    context_object_name = 'event'
    model = Event
@@ -32,11 +44,16 @@ class DashboardEventView(DetailView):
        # Show feed of recent changes (if activated)
        if settings.DASHBOARD_SHOW_RECENT:
+            # Create a list of chronically sorted events (both AK and plan changes):
            recent_changes = []
-            # Newest AKs
+            # Newest AKs (if AKSubmission is used)
            if apps.is_installed("AKSubmission"):
-                submission_changes = AK.history.filter(event=context['event'])[:int(settings.DASHBOARD_RECENT_MAX)]
+                # Get the latest x changes (if there are that many),
+                # where x corresponds to the entry threshold configured in the settings
+                # (such that the list will be completely filled even if there are no (newer) plan changes)
+                submission_changes = AK.history.filter(event=context['event'])[:int(settings.DASHBOARD_RECENT_MAX)] # pylint: disable=no-member, line-too-long
+                # Create textual representation including icons
                for s in submission_changes:
                    if s.history_type == '+':
                        text = _('New AK: %(ak)s.') % {'ak': s.name}
@@ -48,18 +65,21 @@ class DashboardEventView(DetailView):
                        text = _('AK "%(ak)s" deleted.') % {'ak': s.name}
                        icon = ('times', 'fas')
-                    recent_changes.append({'icon': icon, 'text': text, 'link': s.instance.detail_url, 'timestamp': s.history_date})
+                    # Store representation in change list (still unsorted)
+                    recent_changes.append(
-            # Changes in plan
+                        {'icon': icon, 'text': text, 'link': s.instance.detail_url, 'timestamp': s.history_date}
-            if apps.is_installed("AKPlan"):
+                    )
-                if not context['event'].plan_hidden:
-                    last_changed_slots = AKSlot.objects.select_related('ak').filter(event=context['event'], start__isnull=False).order_by('-updated')[
+            # Changes in plan (if AKPlan is used and plan is publicly visible)
-                                         :int(settings.DASHBOARD_RECENT_MAX)]
+            if apps.is_installed("AKPlan") and not context['event'].plan_hidden:
-                    for changed_slot in last_changed_slots:
+                # Get the latest plan changes (again using a threshold, see above)
-                        recent_changes.append({'icon': ('clock', 'far'),
+                last_changed_slots = AKSlot.objects.select_related('ak').filter(event=context['event'], start__isnull=False).order_by('-updated')[:int(settings.DASHBOARD_RECENT_MAX)] #pylint: disable=line-too-long
-                                               'text': _('AK "%(ak)s" (re-)scheduled.') % {'ak': changed_slot.ak.name},
+                for changed_slot in last_changed_slots:
-                                               'link': changed_slot.ak.detail_url,
+                    # Create textual representation including icons and links and store in list (still unsorted)
-                                               'timestamp': changed_slot.updated})
+                    recent_changes.append({'icon': ('clock', 'far'),
+                                           'text': _('AK "%(ak)s" (re-)scheduled.') % {'ak': changed_slot.ak.name},
+                                           'link': changed_slot.ak.detail_url,
+                                           'timestamp': changed_slot.updated})
            # Sort by change date...
            recent_changes.sort(key=lambda x: x['timestamp'], reverse=True)

--- a/AKModel/admin.py
+++ b/AKModel/admin.py
--- a/AKModel/apps.py
+++ b/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'
--- a/AKModel/availability/forms.py
+++ b/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
@@ -17,6 +17,10 @@ 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,6 +32,14 @@ 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
@@ -48,20 +60,28 @@ class AvailabilitiesFormMixin(forms.Form):
    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 = kwargs.pop('initial', {})
        initial['availabilities'] = self._serialize(self.event, kwargs['instance'])
        if not isinstance(self, forms.BaseModelForm):
            kwargs.pop('instance')
        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:
+        except ValueError as exc:
-            raise forms.ValidationError("Submitted availabilities are not valid json.")
+            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 +94,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 +131,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.")
-            )
+            ) from exc
-        tz = self.event.timezone  # adapt to our event model
        timeframe_start = self.event.start  # adapt to our event model
        if rawavail['start'] < timeframe_start:
@@ -115,6 +149,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 +173,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.
        """
@@ -145,10 +184,20 @@ class AvailabilitiesFormMixin(forms.Form):
            setattr(avail, reference_name, instance.id)
    def _replace_availabilities(self, instance, availabilities: [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 +205,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')

--- a/AKModel/availability/models.py
+++ b/AKModel/availability/models.py
@@ -23,6 +23,9 @@ 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
 class Availability(models.Model):
    """The Availability class models when people or rooms are available for.
@@ -31,6 +34,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',
@@ -96,10 +101,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']
-            ]
+            )
        )
    @cached_property
@@ -233,10 +238,28 @@ 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):
+        """
+        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

--- a/AKModel/availability/serializers.py
+++ b/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
@@ -10,19 +10,35 @@ from AKModel.availability.models import Availability
 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:

--- a/AKModel/environment.py
+++ b/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('$',
+    return (utf8_replace_pattern.sub('', value).replace('&', r'\&').replace('_', r'\_').replace('#', r'\#').
-                                                                                                                '\$').replace(
+            replace('$', r'\$').replace('%', r'\%').replace('{', r'\{').replace('}', r'\}'))
-        '%', '\%').replace('{', '\{').replace('}', '\}')
 def improved_tex_environment(**options):
+    """
+    Encapsulate our improved latex environment for usage
+    """
    env = environment(**options)
    env.filters.update({
        'latex_escape_utf8': latex_escape_utf8,

--- a/AKModel/forms.py
+++ b/AKModel/forms.py
+"""
+Central and admin forms
+"""
 import csv
 import io
@@ -11,6 +15,17 @@ from AKModel.models import Event, AKCategory, AKRequirement, Room
 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']
@@ -18,13 +33,20 @@ class NewEventWizardStartForm(forms.ModelForm):
            'plan_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__"
        widgets = {
            'name': forms.HiddenInput(),
            'slug': forms.HiddenInput(),
@@ -38,6 +60,10 @@ class NewEventWizardSettingsForm(forms.ModelForm):
 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 +72,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 +92,7 @@ class NewEventWizardImportForm(forms.Form):
        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):
@@ -70,10 +103,12 @@ class NewEventWizardImportForm(forms.Form):
        self.fields["import_requirements"].queryset = self.fields["import_requirements"].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,20 +118,37 @@ 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,
@@ -121,6 +173,9 @@ class SlideExportForm(AdminIntermediateForm):
 class DefaultSlotEditorForm(AdminIntermediateForm):
+    """
+    Form for default slot editor
+    """
    availabilities = forms.CharField(
        label=_('Default Slots'),
        help_text=_(
@@ -133,6 +188,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 +208,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 +225,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 +239,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 +257,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

--- a/AKModel/locale/de_DE/LC_MESSAGES/django.po
+++ b/AKModel/locale/de_DE/LC_MESSAGES/django.po
--- a/AKModel/management/commands/makemessages.py
+++ b/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()
+            with open(filename, "r", encoding="utf-8") as f:
-            fixed_lines = []
+                lines = f.readlines()
-            for line in lines:
+                fixed_lines = []
-                if line.startswith("#: "):
+                for line in lines:
-                    line = line.replace("\\", "/")
+                    if line.startswith("#: "):
-                fixed_lines.append(line)
+                        line = line.replace("\\", "/")
+                    fixed_lines.append(line)
            with open(filename, "w", encoding="utf-8") as f:
                f.writelines(fixed_lines)

--- a/AKModel/metaviews/__init__.py
+++ b/AKModel/metaviews/__init__.py
 from AKModel.metaviews.status import StatusManager
+# create on instance of the :class:`AKModel.metaviews.status.StatusManager`
+# that can then be accessed everywhere (singleton pattern)
 status_manager = StatusManager()
--- a/AKModel/metaviews/admin.py
+++ b/AKModel/metaviews/admin.py
@@ -13,36 +13,61 @@ from AKModel.models import Event
 class EventSlugMixin:
    """
    Mixin to handle views with event slugs
+    This will make the relevant event available as self.event in all kind types of requests
+    (generic GET and POST views, list views, dispatching, create views)
    """
+    # pylint: disable=no-member
    event = None
    def _load_event(self):
+        """
+        Perform the real loading of the event data (as specified by event_slug in the URL) into self.event
+        """
        # Find event based on event slug
        if self.event is None:
            self.event = get_object_or_404(Event, slug=self.kwargs.get("event_slug", None))
    def get(self, request, *args, **kwargs):
+        """
+        Override GET request handling to perform loading event first
+        """
        self._load_event()
        return super().get(request, *args, **kwargs)
    def post(self, request, *args, **kwargs):
+        """
+        Override POST request handling to perform loading event first
+        """
        self._load_event()
        return super().post(request, *args, **kwargs)
    def list(self, request, *args, **kwargs):
+        """
+        Override list view request handling to perform loading event first
+        """
        self._load_event()
        return super().list(request, *args, **kwargs)
    def create(self, request, *args, **kwargs):
+        """
+        Override create view request handling to perform loading event first
+        """
        self._load_event()
        return super().create(request, *args, **kwargs)
    def dispatch(self, request, *args, **kwargs):
+        """
+        Override dispatch which is called in many generic views to perform loading event first
+        """
        if self.event is None:
            self._load_event()
        return super().dispatch(request, *args, **kwargs)
    def get_context_data(self, *, object_list=None, **kwargs):
+        """
+        Override `get_context_data` to make the event information available in the rendering context as `event`. too
+        """
        context = super().get_context_data(object_list=object_list, **kwargs)
        # Add event to context (to make it accessible in templates)
        context["event"] = self.event
@@ -55,15 +80,29 @@ class FilterByEventSlugMixin(EventSlugMixin):
    """
    def get_queryset(self):
-        # Filter current queryset based on url event slug or return 404 if event slug is invalid
+        """
+        Get adapted queryset:
+        Filter current queryset based on url event slug or return 404 if event slug is invalid
+        :return: Queryset
+        """
        return super().get_queryset().filter(event=self.event)
 class AdminViewMixin:
+    """
+    Mixin to provide context information needed in custom admin views
+    Will either use default information for `site_url` and `title` or allows to set own values for that
+    """
+    # pylint: disable=too-few-public-methods
    site_url = ''
    title = ''
    def get_context_data(self, **kwargs):
+        """
+        Extend context
+        """
        extra = admin.site.each_context(self.request)
        extra.update(super().get_context_data(**kwargs))
@@ -76,10 +115,19 @@ class AdminViewMixin:
 class IntermediateAdminView(AdminViewMixin, FormView):
+    """
+    Metaview: Handle typical "action but with preview and confirmation step before" workflow
+    """
    template_name = "admin/AKModel/action_intermediate.html"
    form_class = AdminIntermediateForm
    def get_preview(self):
+        """
+        Render a preview of the action to be performed.
+        Default is empty
+        :return: preview (html)
+        :rtype: str
+        """
        return ""
    def get_context_data(self, **kwargs):
@@ -90,7 +138,18 @@ class IntermediateAdminView(AdminViewMixin, FormView):
 class WizardViewMixin:
+    """
+    Mixin to create wizard-like views.
+    This visualizes the progress of the user in the creation process and provides the interlinking to the next step
+    In the current implementation, the steps of the wizard are hardcoded here,
+    hence this mixin can only be used for the event creation wizard
+    """
+    # pylint: disable=too-few-public-methods
    def get_context_data(self, **kwargs):
+        """
+        Extend context
+        """
        context = super().get_context_data(**kwargs)
        context["wizard_step"] = self.wizard_step
        context["wizard_steps"] = [
@@ -107,10 +166,23 @@ class WizardViewMixin:
 class IntermediateAdminActionView(IntermediateAdminView, ABC):
+    """
+    Abstract base view: Intermediate action view (preview & confirmation see :class:`IntermediateAdminView`)
+    for custom admin actions (marking multiple objects in a django admin model instances list with a checkmark and then
+    choosing an action from the dropdown).
+    This will automatically handle the decoding of the URL encoding of the list of primary keys django does to select
+    which objects the action should be run on, then display a preview, perform the action after confirmation and
+    redirect again to the object list including display of a confirmation message
+    """
+    # pylint: disable=no-member
    form_class = AdminIntermediateActionForm
    entities = None
    def get_queryset(self, pks=None):
+        """
+        Get the queryset of objects to perform the action on
+        """
        if pks is None:
            pks = self.request.GET['pks']
        return self.model.objects.filter(pk__in=pks.split(","))
@@ -130,7 +202,10 @@ class IntermediateAdminActionView(IntermediateAdminView, ABC):
    @abstractmethod
    def action(self, form):
-        pass
+        """
+        The real action to perform
+        :param form: form holding the data probably needed for the action
+        """
    def form_valid(self, form):
        self.entities = self.get_queryset(pks=form.cleaned_data['pks'])
@@ -140,7 +215,21 @@ class IntermediateAdminActionView(IntermediateAdminView, ABC):
 class LoopActionMixin(ABC):
-    def action(self, form):
+    """
+    Mixin for the typical kind of action where one needs to loop over all elements
+    and perform a certain function on each of them
+    The action is performed by overriding `perform_action(self, entity)`
+    further customization can be reached with the two callbacks `pre_action()` and `post_action()`
+    that are called before and after performing the action loop
+    """
+    def action(self, form):  # pylint: disable=unused-argument
+        """
+        The real action to perform.
+        Will perform the loop, perform the action on each aelement and call the callbacks
+        :param form: form holding the data probably needed for the action
+        """
        self.pre_action()
        for entity in self.entities:
            self.perform_action(entity)
@@ -149,10 +238,18 @@ class LoopActionMixin(ABC):
    @abstractmethod
    def perform_action(self, entity):
-        pass
+        """
+        Action to perform on each entity
+        :param entity: entity to perform the action on
+        """
    def pre_action(self):
-        pass
+        """
+        Callback for custom action before loop starts
+        """
    def post_action(self):
-        pass
+        """
+        Callback for custom action after loop finished
+        """
--- a/AKModel/metaviews/status.py
+++ b/AKModel/metaviews/status.py
@@ -8,6 +8,9 @@ from AKModel.metaviews.admin import AdminViewMixin
 class StatusWidget(ABC):
+    """
+    Abstract parent for status page widgets
+    """
    title = "Status Widget"
    actions = []
    status = "primary"
@@ -18,7 +21,6 @@ class StatusWidget(ABC):
        """
        Which model/context is needed to render this widget?
        """
-        pass
    def get_context_data(self, context) -> dict:
        """
@@ -32,6 +34,7 @@ class StatusWidget(ABC):
        Render widget based on context
        :param context: Context for rendering
+        :param request: HTTP request, needed for rendering
        :return: Dictionary containing the rendered/prepared information
        """
        context = self.get_context_data(context)
@@ -42,7 +45,7 @@ class StatusWidget(ABC):
            "status": self.render_status(context),
        }
-    def render_title(self, context: {}) -> str:
+    def render_title(self, context: {}) -> str:  # pylint: disable=unused-argument
        """
        Render title for widget based on context
@@ -52,7 +55,7 @@ class StatusWidget(ABC):
        """
        return self.title
-    def render_status(self, context: {}) -> str:
+    def render_status(self, context: {}) -> str:  # pylint: disable=unused-argument
        """
        Render status for widget based on context
@@ -63,16 +66,16 @@ class StatusWidget(ABC):
        return self.status
    @abstractmethod
-    def render_body(self, context: {}, request) -> str:
+    def render_body(self, context: {}, request) -> str:  # pylint: disable=unused-argument
        """
        Render body for widget based on context
        :param context: Context for rendering
+        :param request: HTTP request (needed for rendering)
        :return: Rendered widget body (HTML)
        """
-        pass
-    def render_actions(self, context: {}) -> list[dict]:
+    def render_actions(self, context: {}) -> list[dict]:  # pylint: disable=unused-argument
        """
        Render actions for widget based on context
@@ -81,16 +84,30 @@ class StatusWidget(ABC):
        :param context: Context for rendering
        :return: List of actions
        """
-        return [a for a in self.actions]
+        return self.actions
 class TemplateStatusWidget(StatusWidget):
+    """
+    A :class:`StatusWidget` that produces its content by rendering a given html template
+    """
    @property
    @abstractmethod
    def template_name(self) -> str:
-        pass
+        """
+        Configure the template to use
+        :return: name of the template to use
+        """
    def render_body(self, context: {}, request) -> str:
+        """
+        Render the body of the widget using the template rendering method from django
+        (load and render template using the provided context)
+        :param context: context to use for rendering
+        :param request: HTTP request (needed by django)
+        :return: rendered content (HTML)
+        """
        template = loader.get_template(self.template_name)
        return template.render(context, request)
@@ -98,6 +115,8 @@ class TemplateStatusWidget(StatusWidget):
 class StatusManager:
    """
    Registry for all status widgets
+    Allows to register status widgets using the `@status_manager.register(name="xyz")` decorator
    """
    widgets = {}
    widgets_by_context_type = defaultdict(list)
@@ -131,6 +150,9 @@ class StatusManager:
 class StatusView(ABC, AdminViewMixin, TemplateView):
+    """
+    Abstract view: A generic base view to create a status page holding multiple widgets
+    """
    template_name = "admin/AKModel/status/status.html"
    @property
@@ -139,12 +161,15 @@ class StatusView(ABC, AdminViewMixin, TemplateView):
        """
        Which model/context is provided by this status view?
        """
-        pass
    def get(self, request, *args, **kwargs):
        context = self.get_context_data(**kwargs)
-        from AKModel.metaviews import status_manager
+        # Load status manager (local import to prevent cyclic import)
-        context['widgets'] = [w.render(context, self.request) for w in status_manager.get_by_context_type(self.provided_context_type)]
+        from AKModel.metaviews import status_manager  # pylint: disable=import-outside-toplevel
+        # Render all widgets and provide them as part of the context
+        context['widgets'] = [w.render(context, self.request)
+                              for w in status_manager.get_by_context_type(self.provided_context_type)]
        return self.render_to_response(context)
--- a/AKModel/models.py
+++ b/AKModel/models.py
No results found