From 78cd741caf2add4c1bde1c12065a5d0a2ae445d2 Mon Sep 17 00:00:00 2001 From: Arthur Deierlein Date: Mon, 22 Apr 2024 11:35:39 +0200 Subject: [PATCH] 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 | 6 +----- timed/employment/factories.py | 16 ++++------------ timed/employment/models.py | 32 ++++++++------------------------ timed/employment/serializers.py | 6 +----- timed/projects/models.py | 32 +++++++++----------------------- timed/tracking/factories.py | 8 ++------ timed/tracking/models.py | 32 ++++++++------------------------ timed/tracking/serializers.py | 5 +---- 8 files changed, 34 insertions(+), 103 deletions(-) diff --git a/timed/employment/admin.py b/timed/employment/admin.py index db6c2866..aa683f08 100644 --- a/timed/employment/admin.py +++ b/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() diff --git a/timed/employment/factories.py b/timed/employment/factories.py index 2fd347ac..667c8fa7 100644 --- a/timed/employment/factories.py +++ b/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: diff --git a/timed/employment/models.py b/timed/employment/models.py index a8fb5dda..704be41a 100644 --- a/timed/employment/models.py +++ b/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"), diff --git a/timed/employment/serializers.py b/timed/employment/serializers.py index e5c3d78f..fd097c9f 100644 --- a/timed/employment/serializers.py +++ b/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) diff --git a/timed/projects/models.py b/timed/projects/models.py index 443909a4..92e3b920 100644 --- a/timed/projects/models.py +++ b/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}" diff --git a/timed/tracking/factories.py b/timed/tracking/factories.py index ce537137..a4e8ba47 100644 --- a/timed/tracking/factories.py +++ b/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: diff --git a/timed/tracking/models.py b/timed/tracking/models.py index e8c9b226..7bb1cf13 100644 --- a/timed/tracking/models.py +++ b/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"), diff --git a/timed/tracking/serializers.py b/timed/tracking/serializers.py index e46b1417..41d7a129 100644 --- a/timed/tracking/serializers.py +++ b/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)