From 13bf3a8c91d15871b81c190d385180ced80ae19d Mon Sep 17 00:00:00 2001
From: Lorenz Zahn <lorenz.zahn@student.uni-halle.de>
Date: Sat, 29 Jul 2023 16:19:52 +0200
Subject: [PATCH] documentation
---
.../accounting/departments/__init__.py | 3 +++
.../workhours/accounting/departments/forms.py | 8 ++++++-
.../workhours/accounting/departments/urls.py | 4 ++++
.../workhours/accounting/departments/views.py | 24 ++++++++++++-------
.../accounting/mailing_list/__init__.py | 3 +++
.../accounting/mailing_list/forms.py | 7 ++++++
.../workhours/accounting/mailing_list/urls.py | 4 ++++
.../accounting/mailing_list/views.py | 15 ++++++++++++
8 files changed, 58 insertions(+), 10 deletions(-)
diff --git a/app/vkk/workhours/accounting/departments/__init__.py b/app/vkk/workhours/accounting/departments/__init__.py
index e69de29b..a195d436 100644
--- a/app/vkk/workhours/accounting/departments/__init__.py
+++ b/app/vkk/workhours/accounting/departments/__init__.py
@@ -0,0 +1,3 @@
+"""
+This module contains the utilities associated with the management of departments.
+"""
\ No newline at end of file
diff --git a/app/vkk/workhours/accounting/departments/forms.py b/app/vkk/workhours/accounting/departments/forms.py
index 2d82a22d..d6ba0e3e 100644
--- a/app/vkk/workhours/accounting/departments/forms.py
+++ b/app/vkk/workhours/accounting/departments/forms.py
@@ -1,8 +1,14 @@
+"""
+A collection of forms used for managing departments.
+"""
+
from django.forms import Form, ModelMultipleChoiceField, SelectMultiple
from vkk.models import Period
-
class EvaluationForm(Form):
+ """
+ A `Form` subclass for selecting one or more `Periods` for evaluation.
+ """
periods = ModelMultipleChoiceField(
widget=SelectMultiple(attrs={"style":"height: 20em;"}),
queryset=Period.objects.all().order_by('-start')
diff --git a/app/vkk/workhours/accounting/departments/urls.py b/app/vkk/workhours/accounting/departments/urls.py
index e0fd7e69..f1835be5 100644
--- a/app/vkk/workhours/accounting/departments/urls.py
+++ b/app/vkk/workhours/accounting/departments/urls.py
@@ -1,3 +1,7 @@
+"""
+This submodule contains the routing configuration.
+"""
+
from django.urls import path
from django.utils.translation import gettext_lazy as _
from ..views import *
diff --git a/app/vkk/workhours/accounting/departments/views.py b/app/vkk/workhours/accounting/departments/views.py
index 1fe9668b..f2625cc9 100644
--- a/app/vkk/workhours/accounting/departments/views.py
+++ b/app/vkk/workhours/accounting/departments/views.py
@@ -1,3 +1,7 @@
+"""
+This submodule contains class based views.
+"""
+
from django.template import loader
from django.db import connection
from django.http import HttpResponse
@@ -7,21 +11,20 @@ from .forms import EvaluationForm
class EvaluationView(AccountantRequiredMixin, FormView):
+ """
+ A class based `View` providing utilities for generating an evaluation of
+ the given `Department` over some `Periods`.
+ """
template_name = 'vkk/workhours/accounting/department/evaluation.html'
form_class = EvaluationForm
def get_queryset(self, periods):
+ """
+ Returns the result of an SQL query calculating the evaluation.
+ """
with connection.cursor() as cursor:
cursor.execute("WITH assignments AS ( \
- SELECT \
- vkk_project.id AS project_id, \
- vkk_project.start AS project_start, \
- vkk_project.end AS project_end, \
- vkk_projectassignment.id AS assignment_id, \
- salary_level_id \
- FROM vkk_project JOIN vkk_projectassignment \
- ON vkk_project.id = vkk_projectassignment.project_id \
- WHERE vkk_project.department_id = %s \
+ SELECT \periodsdepartment_id = %s \
), \
workhours AS ( \
SELECT \
@@ -249,6 +252,9 @@ class EvaluationView(AccountantRequiredMixin, FormView):
def form_valid(self, form):
+ """
+ Returns the result of the evaluation in shape of a `.csv` file.
+ """
periods = tuple(n[0] for n in form.cleaned_data['periods'].values_list('id'))
context = self.get_context_data()
context["projects"] = self.get_queryset(periods)
diff --git a/app/vkk/workhours/accounting/mailing_list/__init__.py b/app/vkk/workhours/accounting/mailing_list/__init__.py
index e69de29b..6bd44aa6 100644
--- a/app/vkk/workhours/accounting/mailing_list/__init__.py
+++ b/app/vkk/workhours/accounting/mailing_list/__init__.py
@@ -0,0 +1,3 @@
+"""
+This module contains the utilities associated with the management of mailing lists.
+"""
\ No newline at end of file
diff --git a/app/vkk/workhours/accounting/mailing_list/forms.py b/app/vkk/workhours/accounting/mailing_list/forms.py
index f1dfc3ef..47902d03 100644
--- a/app/vkk/workhours/accounting/mailing_list/forms.py
+++ b/app/vkk/workhours/accounting/mailing_list/forms.py
@@ -1,3 +1,7 @@
+"""
+A collection of forms used for managing mailing lists.
+"""
+
from smtplib import SMTPException
from django import forms
from django.core.mail import send_mail
@@ -11,6 +15,9 @@ MAILING_CHOICES = [
]
class MailingListForm(forms.Form):
+ """
+ A `Form` subclass for sending email to different groups `User`s.
+ """
mailing_list = forms.ChoiceField(label=_('Mailing List'), choices=MAILING_CHOICES)
subject = forms.CharField(label=_('Subject'), max_length=255, empty_value=True)
message = forms.CharField(label=_('Message'), max_length=16383, widget=forms.Textarea())
diff --git a/app/vkk/workhours/accounting/mailing_list/urls.py b/app/vkk/workhours/accounting/mailing_list/urls.py
index 6e3ec0e5..61882e89 100644
--- a/app/vkk/workhours/accounting/mailing_list/urls.py
+++ b/app/vkk/workhours/accounting/mailing_list/urls.py
@@ -1,3 +1,7 @@
+"""
+This submodule contains the routing configuration.
+"""
+
from django.urls import path
from django.utils.translation import gettext_lazy as _
from .views import MailingListView, MailingListSuccessView, MailingListFailedView
diff --git a/app/vkk/workhours/accounting/mailing_list/views.py b/app/vkk/workhours/accounting/mailing_list/views.py
index d389ca05..d1391be0 100644
--- a/app/vkk/workhours/accounting/mailing_list/views.py
+++ b/app/vkk/workhours/accounting/mailing_list/views.py
@@ -1,3 +1,7 @@
+"""
+This submodule contains class based views.
+"""
+
from smtplib import SMTPException
from django.urls import reverse_lazy, reverse
from django.http import HttpResponseRedirect
@@ -6,6 +10,9 @@ from vkk.workhours.accounting.mixins import AccountantRequiredMixin
from .forms import MailingListForm
class MailingListView(AccountantRequiredMixin, FormView):
+ """
+ A class based `View` providing the utilities to send out email to a mailing list.
+ """
form_class = MailingListForm
success_url = reverse_lazy('vkk:workhours:accounting:mailing_list:success')
template_name = 'vkk/workhours/accounting/mailing_list/form.html'
@@ -20,7 +27,15 @@ class MailingListView(AccountantRequiredMixin, FormView):
return super().form_valid(form)
class MailingListSuccessView(AccountantRequiredMixin, TemplateView):
+ """
+ A class based `View` providing the utilities to indicate the successful delivery
+ of email to a mailing list.
+ """
template_name = 'vkk/workhours/accounting/mailing_list/success.html'
class MailingListFailedView(AccountantRequiredMixin, TemplateView):
+ """
+ A class based `View` providing the utilities to indicate the failure to
+ send out email to a mailing list.
+ """
template_name = 'vkk/workhours/accounting/mailing_list/failed.html'
--
GitLab