From 113c0694740f01eb3b6da61a694d1d53d97ac708 Mon Sep 17 00:00:00 2001
From: Lorenz Zahn <lorenz.zahn@student.uni-halle.de>
Date: Sat, 29 Jul 2023 17:20:09 +0200
Subject: [PATCH] documentation
---
.../workhours/accounting/periods/__init__.py | 3 +
app/vkk/workhours/accounting/periods/urls.py | 4 +
app/vkk/workhours/accounting/periods/views.py | 24 ++++++
.../workhours/accounting/projects/__init__.py | 5 ++
.../accounting/projects/project/__init__.py | 5 ++
.../accounting/projects/project/forms.py | 14 ++++
.../accounting/projects/project/urls.py | 4 +
.../accounting/projects/project/views.py | 83 +++++++++++++++++++
app/vkk/workhours/accounting/projects/urls.py | 4 +
9 files changed, 146 insertions(+)
diff --git a/app/vkk/workhours/accounting/periods/__init__.py b/app/vkk/workhours/accounting/periods/__init__.py
index e69de29b..112edcd6 100644
--- a/app/vkk/workhours/accounting/periods/__init__.py
+++ b/app/vkk/workhours/accounting/periods/__init__.py
@@ -0,0 +1,3 @@
+"""
+This module contains the utilities associated with the management of periods.
+"""
\ No newline at end of file
diff --git a/app/vkk/workhours/accounting/periods/urls.py b/app/vkk/workhours/accounting/periods/urls.py
index 184cff00..d8b232af 100644
--- a/app/vkk/workhours/accounting/periods/urls.py
+++ b/app/vkk/workhours/accounting/periods/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 django.forms import modelform_factory
diff --git a/app/vkk/workhours/accounting/periods/views.py b/app/vkk/workhours/accounting/periods/views.py
index 6bc25289..0772674b 100644
--- a/app/vkk/workhours/accounting/periods/views.py
+++ b/app/vkk/workhours/accounting/periods/views.py
@@ -1,14 +1,26 @@
+"""
+This submodule contains class based views.
+"""
+
from django.shortcuts import get_object_or_404
from vkk.workhours.accounting.views import AccountingDetailView
from vkk.workhours.models import Period, Project, Department
class AccountingPeriodDetailView(AccountingDetailView):
+ """
+ This class based `View` provides an overview over a `Period` and whether
+ all projects for a department have been closed for said period.
+ """
model = Period
fields = ['start', 'end', 'dead_line', 'dead_line_final']
template_name = "vkk/workhours/accounting/period/details.html"
def get_context_data(self, **kwargs):
+ """
+ Returns a query set of `Departments` and whether all projects for the given
+ department and period have been closed.
+ """
context = super().get_context_data(**kwargs)
departments = Department.objects.raw(" \
WITH selected_period AS ( \
@@ -80,11 +92,19 @@ class AccountingPeriodDetailView(AccountingDetailView):
class AccountingPeriodDetailDepartmentView(AccountingDetailView):
+ """
+ A class based `View` offering an overview of all projects belonging to a
+ given department over a given period and whether they have been closed.
+ """
model = Period
fields = ['start', 'end', 'dead_line', 'dead_line_final']
template_name = "vkk/workhours/accounting/period/projects.html"
def get_context_data(self, **kwargs):
+ """
+ Returns a query set of `Projects` over a period and beloginging to a given
+ department with the added information whether they have been closed or not.
+ """
context = super().get_context_data(**kwargs)
department = get_object_or_404(
Department, pk=self.kwargs["department_pk"])
@@ -237,6 +257,10 @@ class AccountingPeriodDetailDepartmentView(AccountingDetailView):
return context
class AccountingPeriodDetailNoDepartmentView(AccountingDetailView):
+ """
+ A class based `View` providing an overview of projects which do not belong to any
+ department for the given period.
+ """
model = Period
fields = ['start', 'end', 'dead_line', 'dead_line_final']
template_name = "vkk/workhours/accounting/period/projects.html"
diff --git a/app/vkk/workhours/accounting/projects/__init__.py b/app/vkk/workhours/accounting/projects/__init__.py
index e69de29b..f4b75db0 100644
--- a/app/vkk/workhours/accounting/projects/__init__.py
+++ b/app/vkk/workhours/accounting/projects/__init__.py
@@ -0,0 +1,5 @@
+"""
+This module contains the utilities associated with the administration of projects.
+
+This module's substructure closely resembles the path substructure of the website.
+"""
diff --git a/app/vkk/workhours/accounting/projects/project/__init__.py b/app/vkk/workhours/accounting/projects/project/__init__.py
index e69de29b..03bd2a78 100644
--- a/app/vkk/workhours/accounting/projects/project/__init__.py
+++ b/app/vkk/workhours/accounting/projects/project/__init__.py
@@ -0,0 +1,5 @@
+"""
+This module contains the utilities associated with the administration of a project.
+
+This module's substructure closely resembles the path substructure of the website.
+"""
diff --git a/app/vkk/workhours/accounting/projects/project/forms.py b/app/vkk/workhours/accounting/projects/project/forms.py
index 74d2a84f..773a2327 100644
--- a/app/vkk/workhours/accounting/projects/project/forms.py
+++ b/app/vkk/workhours/accounting/projects/project/forms.py
@@ -1,3 +1,7 @@
+"""
+A collection of forms used in this module.
+"""
+
from django import forms
from django.core.exceptions import ValidationError
from django.utils.translation import gettext_lazy as _
@@ -5,16 +9,26 @@ from vkk.workhours.models import ProjectAssignment, WorkHours, WorkHoursCorrecti
class ContributorDeleteForm(forms.ModelForm):
+ """
+ A `ModelForm` subclass for deleting a `ProjectAssignment`.
+ """
id = None
class Meta:
model = ProjectAssignment
fields = []
def __init__(self, id, *args, **kwargs):
+ """
+ Initializes and returns an object of this class. An `id` of a `ProjectAssignment` must be provided.
+ """
self.id = id
super().__init__(*args, **kwargs)
def clean(self):
+ """
+ Cleans the form and returns its cleaned data as an dictionary. No additional data must be associated
+ with the given `ProjectAssignment` (ie. `WorkHours`) for this to be successfull.
+ """
workhours_exist = WorkHours.objects.filter(
project_assignment__id=self.id
).exists()
diff --git a/app/vkk/workhours/accounting/projects/project/urls.py b/app/vkk/workhours/accounting/projects/project/urls.py
index e04771bc..aec07c5d 100644
--- a/app/vkk/workhours/accounting/projects/project/urls.py
+++ b/app/vkk/workhours/accounting/projects/project/urls.py
@@ -1,3 +1,7 @@
+"""
+This submodule contains the routing configuration.
+"""
+
from django.urls import include, path
from django.utils.translation import gettext_lazy as _
from django.forms import modelform_factory
diff --git a/app/vkk/workhours/accounting/projects/project/views.py b/app/vkk/workhours/accounting/projects/project/views.py
index ca1072ac..f95e1c88 100644
--- a/app/vkk/workhours/accounting/projects/project/views.py
+++ b/app/vkk/workhours/accounting/projects/project/views.py
@@ -1,3 +1,7 @@
+"""
+This submodule contains class based views.
+"""
+
from django.utils.translation import gettext_lazy as _
from django.core.exceptions import ValidationError
from django.forms import modelform_factory, Form
@@ -17,6 +21,9 @@ from vkk.workhours.accounting.projects.project.forms import ContributorDeleteFor
class AccountingProjectOverView(AccountingDetailView):
+ """
+ A class based `View` providing an overview over the given project.
+ """
model = Project
slug_field = 'invoice_number'
slug_url_kwarg = 'invoice_number'
@@ -25,6 +32,9 @@ class AccountingProjectOverView(AccountingDetailView):
'department', 'contractor', 'start', 'end']
def get_context_data(self, **kwargs):
+ """
+ Returns additional context data as an dictionary. This is used for rendering the page.
+ """
context = super().get_context_data(**kwargs)
context["managers"] = ProjectManager.objects.filter(
project__invoice_number=self.kwargs['invoice_number']
@@ -36,20 +46,33 @@ class AccountingProjectOverView(AccountingDetailView):
class AccountingProjectUserFilterView(AccountingFilterView):
+ """
+ A class based `View` providing utilities for selecting a `User` which
+ is to be assigned to the given project.
+ """
model = User
fields = ['last_name', 'first_name', 'email']
action_options = None
to_exclude = None
def get(self, request, *args, invoice_number=None, **kwargs):
+ """
+ Handler for GET requests.
+ """
return super().get(request, *args, **kwargs)
def get_queryset(self):
+ """
+ Returns a query set of `Users` which are not assigned to the given Project.
+ """
kwarg = {self.to_exclude: self.kwargs['invoice_number']}
return super().get_queryset().exclude(**kwarg)
class AccountingProjectUpdateView(AccountingUpdateView):
+ """
+ A class based `UpdateView` for updating the given project.
+ """
model = Project
form_class = modelform_factory(
model=Project,
@@ -62,11 +85,17 @@ class AccountingProjectUpdateView(AccountingUpdateView):
slug_url_kwarg = 'invoice_number'
def form_valid(self, form):
+ """
+ Saves any changes to the associated `Project`.
+ """
self.kwarg_override = {'invoice_number': form.instance.invoice_number}
return super().form_valid(form)
class AccountingManagerCreateView(AccountingCreateView):
+ """
+ A class based `CreateView` providing utilities for creating new `ProjectManager`s.
+ """
model = ProjectManager
form_class = modelform_factory(
model=ProjectManager,
@@ -77,6 +106,9 @@ class AccountingManagerCreateView(AccountingCreateView):
drop_key = 'pk'
def form_valid(self, form):
+ """
+ Attempts to save the newly created `ProjectManager` to the database.
+ """
form.instance.manager = User.objects.get(pk=self.kwargs['pk'])
form.instance.project = Project.objects.get(
invoice_number=self.kwargs['invoice_number'])
@@ -89,12 +121,18 @@ class AccountingManagerCreateView(AccountingCreateView):
class AccountingContributorCreateView(AccountingCreateView):
+ """
+ A class based `CreateView` providing utilities for creating new `ProjectAssignment`s.
+ """
model = ProjectAssignment
fields = ['salary_level']
on_success = 'add_contributor_success'
drop_key = 'pk'
def form_valid(self, form):
+ """
+ Attempts to save the newly created `ProjectAssignment` to the database.
+ """
form.instance.contributor = User.objects.get(pk=self.kwargs['pk'])
form.instance.project = Project.objects.get(
invoice_number=self.kwargs['invoice_number'])
@@ -107,6 +145,9 @@ class AccountingContributorCreateView(AccountingCreateView):
class AccountingContributorDeleteView(AccountingDeleteView):
+ """
+ A class based `DeleteView` providing utilities for deleting `ProjectAssignment`s.
+ """
model = ProjectAssignment
form_class = ContributorDeleteForm
on_success = 'delete_contributor_success'
@@ -119,13 +160,22 @@ class AccountingContributorDeleteView(AccountingDeleteView):
return kwargs
class AccountingManagerDeleteView(AccountingDeleteView):
+ """
+ A class based `DeleteView` providing utilities for deleting `ProjectManager`s.
+ """
model = ProjectManager
on_success = 'delete_manager_success'
drop_key = 'pk'
class AccountingWorkhourSheetSelectionView(AccountantRequiredMixin, PeriodSelectorMixin, RedirectView):
+ """
+ A class based `View` for selecting a `Period` for a work hour sheet.
+ """
def get_redirect_url(self, *args, **kwargs):
+ """
+ Returns an URL to redirect to based on the given period.
+ """
# Catches Period Selection from GET
if 'period' in self.request.GET:
query_set = Period.objects.all()
@@ -148,11 +198,17 @@ class AccountingWorkhourSheetSelectionView(AccountantRequiredMixin, PeriodSelect
class AccountingWorkhourSheetView(AccountantRequiredMixin, PeriodSelectorMixin, FormView):
+ """
+ A class based `View` providing a work hours sheet for a given project and period.
+ """
form_class = WorkhourSheetForm
template_name = 'vkk/workhours/accounting/projects/project/workhours_sheet.html'
period_select_namespace = 'vkk:workhours:accounting:projects:project:workhours_sheet_selection'
def get_form_kwargs(self):
+ """
+ Returns a dictionary of keyword arguments for instatiating the associated form.
+ """
kwargs = super().get_form_kwargs()
self.assignments = ProjectAssignment.objects.filter(
project__invoice_number=self.kwargs['invoice_number']
@@ -166,6 +222,9 @@ class AccountingWorkhourSheetView(AccountantRequiredMixin, PeriodSelectorMixin,
return kwargs
def get_success_url(self):
+ """
+ Returns a URL to redirect to after a successful action.
+ """
return reverse(
'vkk:workhours:accounting:projects:project:workhours_sheet_success',
args=[
@@ -175,6 +234,9 @@ class AccountingWorkhourSheetView(AccountantRequiredMixin, PeriodSelectorMixin,
)
def get_context_data(self, **kwargs):
+ """
+ Returns additional context data as an dictionary. This is used for rendering the page.
+ """
context = super().get_context_data(**kwargs)
manager_closed_count = self.assignments.filter(
periodclosure__period=self.kwargs['period_pk'],
@@ -192,16 +254,26 @@ class AccountingWorkhourSheetView(AccountantRequiredMixin, PeriodSelectorMixin,
return context
def form_valid(self, form):
+ """
+ Saves all changes to work hours to the database.
+ """
form.save()
return super().form_valid(form)
class AccountingPeriodClosureView(AccountantRequiredMixin, OnSuccessMixin, FormView):
+ """
+ A class based `View` providing utilities to close the period for new entries
+ for all contributors of the given project.
+ """
template_name = 'vkk/workhours/contributor/closure.html'
form_class = Form
on_success = 'period_closure_success'
def post(self, request, *args, **kwargs):
+ """
+ Handler for POST rquests.
+ """
form = self.get_form()
if form.is_valid():
self.close_period()
@@ -210,6 +282,9 @@ class AccountingPeriodClosureView(AccountantRequiredMixin, OnSuccessMixin, FormV
return self.form_invalid(form)
def close_period(self):
+ """
+ Closes the period for all contributors to a project for a given period.
+ """
assignments = ProjectAssignment.objects.filter(
project__invoice_number=self.kwargs['invoice_number'],
)
@@ -231,6 +306,10 @@ class AccountingPeriodClosureView(AccountantRequiredMixin, OnSuccessMixin, FormV
class AccountingPeriodClosureSuccessView(AccountantRequiredMixin, CustomSuccessView):
+ """
+ A class based `View` providing utilities for displaying a successfull closing of a period
+ for all contributors to a given project.
+ """
template_name = 'vkk/workhours/contributor/closure_success.html'
model = PeriodClosure
on_success = 'workhours_sheet'
@@ -239,4 +318,8 @@ class AccountingPeriodClosureSuccessView(AccountantRequiredMixin, CustomSuccessV
# Export
class AccountingExportView(AccountantRequiredMixin, FormView):
+ """
+ A class based `View` providing an overview over all possible actions associated with the
+ export of project related data.
+ """
template_name = 'vkk/workhours/accounting/projects/project/export.html'
diff --git a/app/vkk/workhours/accounting/projects/urls.py b/app/vkk/workhours/accounting/projects/urls.py
index 3aa9c152..3bfaeead 100644
--- a/app/vkk/workhours/accounting/projects/urls.py
+++ b/app/vkk/workhours/accounting/projects/urls.py
@@ -1,3 +1,7 @@
+"""
+This submodule contains the routing configuration.
+"""
+
from django.urls import include, path
from django.utils.translation import gettext_lazy as _
from django.forms import modelform_factory
--
GitLab