Resolve "Add export functionality to absence statistics page"

Closes #267 (closed)

aleksis/apps/alsijil/util/statistics.py

@@ -9,11 +9,22 @@ from ..models import Documentation, ExtraMark, NewPersonalNote, ParticipationSta
 
 
 class BuilderError(Exception):
+    """Error in building statistics using the StatisticsBuilder."""
+
     pass
 
 
 class StatisticsBuilder:
+    """Builder class for building queries with annotated statistics on persons.
+
+    To build queries, you can combine `use_` with multiple `annotate` or `prefetch`
+    methods. At the end, call `build` to get the actual queryset.
+
+    >>> StatisticsBuilder(person_qs).use_from_school_term(school_term).annotate_statistics().build()
+    """
+
     def __init__(self, persons: QuerySet[Person]) -> None:
+        """Intialize the builder with a persons queryset."""
         self.qs: QuerySet[Person] = persons
         self.participations_filter: Q | None = None
         self.personal_notes_filter: Q | None = None
@@ -76,7 +87,7 @@ class StatisticsBuilder:
     def _annotate_filtered_participations(self, condition: Q | None = None) -> "StatisticsBuilder":
         """Annotate a filtered relation for participations."""
         if not self.participations_filter and not condition:
-            raise BuilderError
+            raise BuilderError("Annotation of participations needs a participation filter.")
         self.qs = self.qs.annotate(
             filtered_participation_statuses=FilteredRelation(
                 "participations",
@@ -88,7 +99,7 @@ class StatisticsBuilder:
     def _annotate_filtered_personal_notes(self, condition: Q | None = None) -> "StatisticsBuilder":
         """Annotate a filtered relation for personal notes."""
         if not self.personal_notes_filter and not condition:
-            raise BuilderError
+            raise BuilderError("Annotation of personal notes needs a participation filter.")
         self.qs = self.qs.annotate(
             filtered_personal_notes=FilteredRelation(
                 "new_personal_notes",