docs: move sphinx-doc to type annotations

move __str__'s from sphinx-doc to type annotations
move worktime_per_day and similar properties/lazy_attributes from sphinx-doc to annotations
serializers: move validate, clean from sphinx-doc to type annotations

timed/employment/admin.py

@@ -80,15 +80,11 @@ class EmploymentForm(forms.ModelForm):
 
     worktime_per_day = DurationInHoursField(label=_("Worktime per day in hours"))
 
-    def clean(self):
+    def clean(self) -> dict:
         """Validate the employment as a whole.
 
         Ensure the end date is after the start date and there is only one
         active employment per user and there are no overlapping employments.
-
-        :throws: django.core.exceptions.ValidationError
-        :return: The cleaned data
-        :rtype:  dict
         """
         data = super().clean()
 

timed/employment/factories.py

@@ -60,12 +60,8 @@ class EmploymentFactory(DjangoModelFactory):
     is_external = False
 
     @lazy_attribute
-    def worktime_per_day(self):
-        """Generate the worktime per day based on the percentage.
-
-        :return: The generated worktime
-        :rtype:  datetime.timedelta
-        """
+    def worktime_per_day(self) -> datetime.timedelta:
+        """Generate the worktime per day based on the percentage."""
         return datetime.timedelta(minutes=60 * 8.5 * self.percentage / 100)
 
     class Meta:
@@ -107,12 +103,8 @@ class OvertimeCreditFactory(DjangoModelFactory):
     date = Faker("date_object")
 
     @lazy_attribute
-    def duration(self):
-        """Generate a random duration.
-
-        :return: The generated duration
-        :rtype:  datetime.timedelta
-        """
+    def duration(self) -> datetime.timedelta:
+        """Generate a random duration."""
         return datetime.timedelta(hours=random.randint(5, 40))
 
     class Meta:

timed/employment/models.py

@@ -30,12 +30,8 @@ class Location(models.Model):
     class Meta:
         ordering = ("name",)
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return self.name
 
 
@@ -58,12 +54,8 @@ class Meta:
         indexes = (models.Index(fields=["date"]),)
         ordering = ("date",)
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return "{} {}".format(self.name, self.date.strftime("%Y"))
 
 
@@ -80,12 +72,8 @@ class AbsenceType(models.Model):
     class Meta:
         ordering = ("name",)
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return self.name
 
     def calculate_credit(self, user, start, end):
@@ -232,12 +220,8 @@ class Meta:
 
         indexes = (models.Index(fields=["start_date", "end_date"]),)
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return "{} ({} - {})".format(
             self.user.username,
             self.start_date.strftime("%d.%m.%Y"),

timed/employment/serializers.py

@@ -237,15 +237,11 @@ class EmploymentSerializer(ModelSerializer):
         "location": "timed.employment.serializers.LocationSerializer",
     }
 
-    def validate(self, data):
+    def validate(self, data: dict) -> dict:
         """Validate the employment as a whole.
 
         Ensure the end date is after the start date and there is only one
         active employment per user and there are no overlapping employments.
-
-        :throws: django.core.exceptions.ValidationError
-        :return: validated data
-        :rtype:  dict
         """
         instance = self.instance
         start_date = data.get("start_date", instance and instance.start_date)

timed/projects/models.py

@@ -37,11 +37,7 @@ class Meta:
         ordering = ("name",)
 
     def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+        """Represent the model as a string."""
         return self.name
 
 
@@ -68,6 +64,7 @@ class Meta:
         ordering = ("name",)
 
     def __str__(self):
+        """Represent the model as a string."""
         return self.name
 
 
@@ -119,12 +116,8 @@ class Project(models.Model):
     class Meta:
         ordering = ("name",)
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return f"{self.customer} > {self.name}"
 
 
@@ -167,12 +160,8 @@ class Meta:
 
         ordering = ("name",)
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return f"{self.project} > {self.name}"
 
 
@@ -188,12 +177,8 @@ class TaskTemplate(models.Model):
     class Meta:
         ordering = ("name",)
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return self.name
 
 
@@ -217,6 +202,7 @@ class CustomerAssignee(models.Model):
     is_customer = models.BooleanField(default=False)
 
     def __str__(self) -> str:
+        """Represent the model as a string."""
         return f"{self.user.username} {self.customer}"
 
 

timed/tracking/factories.py

@@ -36,12 +36,8 @@ class ReportFactory(DjangoModelFactory):
     user = SubFactory("timed.employment.factories.UserFactory")
 
     @lazy_attribute
-    def duration(self):
-        """Generate a random duration between 0 and 5 hours.
-
-        :return: The generated duration
-        :rtype:  datetime.timedelta
-        """
+    def duration(self) -> datetime.timedelta:
+        """Generate a random duration between 0 and 5 hours."""
         return datetime.timedelta(hours=randint(0, 4), minutes=randint(0, 59))
 
     class Meta:

timed/tracking/models.py

@@ -37,12 +37,8 @@ class Meta:
         verbose_name_plural = "activities"
         indexes = (models.Index(fields=["date"]),)
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return f"{self.user}: {self.task}"
 
 
@@ -61,12 +57,8 @@ class Attendance(models.Model):
         settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="attendances"
     )
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return "{}: {} {} - {}".format(
             self.user,
             self.date.strftime("%Y-%m-%d"),
@@ -108,12 +100,8 @@ class Meta:
 
         indexes = (models.Index(fields=["date"]),)
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return f"{self.user}: {self.task}"
 
     def save(self, *args, **kwargs):
@@ -153,12 +141,8 @@ class Meta:
             "user",
         )
 
-    def __str__(self):
-        """Represent the model as a string.
-
-        :return: The string representation
-        :rtype:  str
-        """
+    def __str__(self) -> str:
+        """Represent the model as a string."""
         return "{}: {} {}".format(
             self.user,
             self.date.strftime("%Y-%m-%d"),

timed/tracking/serializers.py

@@ -434,13 +434,10 @@ def validate_absence_type(self, value):
 
         return value
 
-    def validate(self, data):
+    def validate(self, data: dict) -> dict:
         """Validate the absence data.
 
         An absence should not be created on a public holiday or a weekend.
-
-        :returns: The validated data
-        :rtype:   dict
         """
         instance = self.instance
         user = data.get("user", instance and instance.user)