From 32de39531d99105f5e1c35f257418297708a2a81 Mon Sep 17 00:00:00 2001
From: Dominik George <dominik.george@teckids.org>
Date: Sun, 27 Oct 2019 21:44:37 +0100
Subject: [PATCH] Add documentation for LessonPeriodQuerySet methods.
---
biscuit/apps/chronos/models.py | 33 +++++++++++++++++++++++++++++++++
1 file changed, 33 insertions(+)
diff --git a/biscuit/apps/chronos/models.py b/biscuit/apps/chronos/models.py
index e85a855b..0e054fb9 100644
--- a/biscuit/apps/chronos/models.py
+++ b/biscuit/apps/chronos/models.py
@@ -33,15 +33,21 @@ class LessonPeriodQuerySet(models.QuerySet):
""" Overrides default QuerySet to add specific methods for lesson data. """
def in_week(self, wanted_week: CalendarWeek):
+ """ Filter for all lessons within a calendar week. """
+
return self.filter(
lesson__date_start__lte=wanted_week[0] + timedelta(days=1) * (models.F('period__weekday') - 1),
lesson__date_end__gte=wanted_week[0] + timedelta(days=1) * (models.F('period__weekday') - 1)
).annotate_week(wanted_week)
def within_dates(self, start: date, end: date):
+ """ Filter for all lessons within a date range. """
+
return self.filter(lesson__date_start__gte=start, lesson__date_end__lte=end)
def on_day(self, day: date):
+ """ Filter for all lessons on a certain day. """
+
week, weekday = week_weekday_from_date(day)
return self.within_dates(day, day).filter(
@@ -49,6 +55,8 @@ class LessonPeriodQuerySet(models.QuerySet):
).annotate_week(week)
def at_time(self, when: Optional[datetime] = None):
+ """ Filter for the lessons taking place at a certain point in time. """
+
now = when or datetime.now()
week, weekday = week_weekday_from_date(now.date())
@@ -61,22 +69,32 @@ class LessonPeriodQuerySet(models.QuerySet):
).annotate_week(week)
def filter_participant(self, person: Union[Person, int]):
+ """ Filter for all lessons a participant (student) attends. """
+
return self.filter(
Q(lesson__groups__members=person) | Q(lesson__groups__parent_groups__members=person))
def filter_group(self, group: Union[Group, int]):
+ """ Filter for all lessons a group (class) regularly attends. """
+
return self.filter(
Q(lesson__groups=group) | Q(lesson__groups__parent_groups=group))
def filter_teacher(self, teacher: Union[Person, int]):
+ """ Filter for all lessons given by a certain teacher. """
+
return self.filter(
Q(substitutions__teachers=teacher, substitutions__week=models.F('_week')) | Q(lesson__teachers=teacher))
def filter_room(self, room: Union[Room, int]):
+ """ Filter for all lessons taking part in a certain room. """
+
return self.filter(
Q(substitutions__room=room, substitutions__week=models.F('_week')) | Q(room=room))
def annotate_week(self, week: Union[CalendarWeek, int]):
+ """ Annotate all lessons in the QuerySet with the number of the provided calendar week. """
+
if isinstance(week, CalendarWeek):
week_num = week.week
else:
@@ -87,6 +105,13 @@ class LessonPeriodQuerySet(models.QuerySet):
)
def next(self, reference: LessonPeriod, offset: Optional[int] = 1) -> LessonPeriod:
+ """ Get another lesson in an ordered set of lessons.
+
+ By default, it returns the next lesson in the set. By passing the offset argument,
+ the n-th next lesson can be selected. By passing a negative number, the n-th
+ previous lesson can be selected.
+ """
+
index = list(self.values_list('id', flat=True)).index(reference.id)
next_index = index + offset
@@ -99,6 +124,14 @@ class LessonPeriodQuerySet(models.QuerySet):
return self.annotate_week(week).all()[next_index]
def filter_from_query(self, query_data: QueryDict):
+ """ Apply all filters from a GET or POST query.
+
+ This method expects a QueryDict, like the GET or POST attribute of a Request
+ object, that contains one or more of the keys group, teacher or room.
+
+ All three fields are filtered, in order.
+ """
+
if query_data.get('group', None):
return self.filter_group(int(query_data['group']))
if query_data.get('teacher', None):
--
GitLab