Update statistic docs

main/extra_func.py

@@ -2,7 +2,7 @@
 Вспомогательные функции.
 """
 import logging
-from datetime import timedelta
+from datetime import timedelta, date
 from typing import Union, Optional
 
 from django.contrib.auth import get_user_model
@@ -219,7 +219,7 @@ def update_users_in_model() -> list:
     return users
 
 
-def daterange(start_date: timedelta, end_date: timedelta) -> list:
+def daterange(start_date: date, end_date: date) -> list:
     """
     Функция возвращает список дней с start_date по end_date, исключая правую границу.
 

main/statistic_data.py

@@ -1,6 +1,9 @@
 """
 Обработка статистики.
+
+Обнаруживает факт изменения роли пользователя и вычисляет отработанное на смене время.
 """
+
 from datetime import date, datetime, timedelta
 from typing import Optional
 
@@ -14,7 +17,7 @@ from main.models import RoleChangeLogs
 
 class StatisticData:
     """
-    Класс для учета статистики интервалов работы пользователей.
+    Класс для учета статистики времени работы пользователей.
     Передаваемые параметры: start_date, end_date, email, stat.
 
     :param display: Формат отображения времени (часы, минуты)
@@ -37,7 +40,7 @@ class StatisticData:
     :type statistic: :class:`dict`
     """
 
-    def __init__(self, start_date, end_date, user_email, stat=None):
+    def __init__(self, start_date, end_date, user_email: str, stat=None):
         self.display = None
         self.interval = None
         self.start_date = start_date
@@ -57,7 +60,8 @@ class StatisticData:
         """
         Функция возвращает статистику работы пользователя.
 
-        :return: Словарь statistic с применением формата отображения и интервала работы(если они есть).
+        :return: Словарь statistic с применением формата отображения
+                 и интервала работы (если они есть).
                  None, если были ошибки при создании.
         """
         if self.is_valid_statistic():
@@ -117,7 +121,7 @@ class StatisticData:
         """
         return not self.errors
 
-    def _use_display(self, stat: list) -> list:
+    def _use_display(self, stat: dict) -> dict:
         """
         Функция приводит данные к формату отображения.
 
@@ -136,7 +140,9 @@ class StatisticData:
 
     def _use_interval(self, stat: dict) -> dict:
         """
-        Функция объединяет ключи и значения в соответствии с интервалом работы.
+        Переупаковка результата в соответствии с указанным временным диапазоном
+
+        Сжимает набор дней в месяцы, если указан режим работы "по месяцам"
 
         :param stat: Статистика работы пользователя
         :return: Обновленная статистика
@@ -210,7 +216,7 @@ class StatisticData:
 
     def engineer_logic(self, log_index: int) -> None:
         """
-        Функция обрабатывает подсчета времени работы инженера.
+        Функция вычисляет время работы инженера.
 
         :param log_index: Индекс текущего лога
         :return: Дополняет статистику работы инженера временем между текущим и последующим логом
@@ -227,7 +233,9 @@ class StatisticData:
 
     def post_engineer_logic(self, last_log: RoleChangeLogs) -> None:
         """
-        Функция обрабатывает случай, когда пользователя назначили инженером в последнем логе.
+        Обработка случая, в котором инженер не закрыл смену.
+
+        В таком случае считается всё время от момента открытия смены до текущего момента.
 
         :param last_log: Последний лог изменения роли, в результате которого пользователь назначен инженером.
         :return: Дополняет статистику работы
@@ -245,16 +253,23 @@ class StatisticData:
 
     def prev_engineer_logic(self, first_log: RoleChangeLogs) -> None:
         """
-        Функция обрабатывает случай, когда пользователь в первом логе диапазона был назначен легким агентом.
+        Обработка случая, в котором инженер закрыл смену в отражаемом периоде, а открыл её до этого периода.
+
+        В таком случае должен быть учтён только период от начала отображаемого диапазона до закрытия смены.
 
         :param first_log_log: Первый лог в диапазоне, в результате которого пользователь назначен легким агентом.
         :return: Дополняет статистику работы
         """
-        self.fill_daterange(max(get_user_model().objects.get(email=self.email).date_joined.date(), self.start_date),
-                            first_log.change_time.date())
+        self.fill_daterange(
+            max(
+                get_user_model().objects.get(email=self.email).date_joined.date(),
+                self.start_date
+            ),
+            first_log.change_time.date()
+        )
         self.statistic[first_log.change_time.date()] += get_timedelta(first_log).total_seconds()
 
-    def fill_daterange(self, first: date, last: date, val: int = 24 * 3600) -> dict:
+    def fill_daterange(self, first: date, last: date, val: int = 24 * 3600) -> None:
         """
         Функция заполняет диапазон дат значением val (по умолчанию val = кол-во секунд в 1 дне).
 
@@ -265,12 +280,11 @@ class StatisticData:
         for day in daterange(first, last):
             self.statistic[day] = val
 
-    def clear_statistic(self) -> dict:
+    def clear_statistic(self) -> None:
         """
-        Функция осуществляет очищает статистику и устанавливает время в диапазоне start_date - end_date в количестве
-        24*3600 секунд.
+        Чистка статистики и установка времени по умолчанию.
 
-        :return: Обновленная статистика
+        Устанавливает время смены в 0
         """
         self.statistic.clear()
         self.fill_daterange(self.start_date, self.end_date + timedelta(days=1), 0)