Debian Codegraph @

model_utils/models.py

raw
1 from __future__ import annotations
2
3 from typing import Any, Literal, TypeVar, overload
4
5 from django.core.exceptions import ImproperlyConfigured
6 from django.db import models
7 from django.db.models.functions import Now
8 from django.utils.translation import gettext_lazy as _
9
10 from model_utils.fields import (
11 AutoCreatedField,
12 AutoLastModifiedField,
13 MonitorField,
14 StatusField,
15 UUIDField,
16 )
17 from model_utils.managers import QueryManager, SoftDeletableManager
18
19 ModelT = TypeVar('ModelT', bound=models.Model, covariant=True)
20
21 now = Now()
22
23
24 class TimeStampedModel(models.Model):
25 """
26 An abstract base class model that provides self-updating
27 ``created`` and ``modified`` fields.
28
29 """
30 created = AutoCreatedField(_('created'))
31 modified = AutoLastModifiedField(_('modified'))
32
33 def save(self, *args: Any, **kwargs: Any) -> None:
34 """
35 Overriding the save method in order to make sure that
36 modified field is updated even if it is not given as
37 a parameter to the update field argument.
38 """
39 update_fields = kwargs.get('update_fields', None)
40 if update_fields:
41 kwargs['update_fields'] = set(update_fields).union({'modified'})
42
43 super().save(*args, **kwargs)
44
45 class Meta:
46 abstract = True
47
48
49 class TimeFramedModel(models.Model):
50 """
51 An abstract base class model that provides ``start``
52 and ``end`` fields to record a timeframe.
53
54 """
55 start = models.DateTimeField(_('start'), null=True, blank=True)
56 end = models.DateTimeField(_('end'), null=True, blank=True)
57
58 class Meta:
59 abstract = True
60
61
62 class StatusModel(models.Model):
63 """
64 An abstract base class model with a ``status`` field that
65 automatically uses a ``STATUS`` class attribute of choices, a
66 ``status_changed`` date-time field that records when ``status``
67 was last modified, and an automatically-added manager for each
68 status that returns objects with that status only.
69
70 """
71 status = StatusField(_('status'))
72 status_changed = MonitorField(_('status changed'), monitor='status')
73
74 def save(self, *args: Any, **kwargs: Any) -> None:
75 """
76 Overriding the save method in order to make sure that
77 status_changed field is updated even if it is not given as
78 a parameter to the update field argument.
79 """
80 update_fields = kwargs.get('update_fields', None)
81 if update_fields and 'status' in update_fields:
82 kwargs['update_fields'] = set(update_fields).union({'status_changed'})
83
84 super().save(*args, **kwargs)
85
86 class Meta:
87 abstract = True
88
89
90 def add_status_query_managers(sender: type[models.Model], **kwargs: Any) -> None:
91 """
92 Add a Querymanager for each status item dynamically.
93
94 """
95 if not issubclass(sender, StatusModel):
96 return
97
98 default_manager = sender._meta.default_manager
99 assert default_manager is not None
100
101 for value, display in getattr(sender, 'STATUS', ()):
102 if _field_exists(sender, value):
103 raise ImproperlyConfigured(
104 "StatusModel: Model '%s' has a field named '%s' which "
105 "conflicts with a status of the same name."
106 % (sender.__name__, value)
107 )
108 sender.add_to_class(value, QueryManager(status=value))
109
110 sender._meta.default_manager_name = default_manager.name
111
112
113 def add_timeframed_query_manager(sender: type[models.Model], **kwargs: Any) -> None:
114 """
115 Add a QueryManager for a specific timeframe.
116
117 """
118 if not issubclass(sender, TimeFramedModel):
119 return
120 if _field_exists(sender, 'timeframed'):
121 raise ImproperlyConfigured(
122 "Model '%s' has a field named 'timeframed' "
123 "which conflicts with the TimeFramedModel manager."
124 % sender.__name__
125 )
126 sender.add_to_class('timeframed', QueryManager(
127 (models.Q(start__lte=now) | models.Q(start__isnull=True))
128 & (models.Q(end__gte=now) | models.Q(end__isnull=True))
129 ))
130
131
132 models.signals.class_prepared.connect(add_status_query_managers)
133 models.signals.class_prepared.connect(add_timeframed_query_manager)
134
135
136 def _field_exists(model_class: type[models.Model], field_name: str) -> bool:
137 return field_name in [f.attname for f in model_class._meta.local_fields]
138
139
140 class SoftDeletableModel(models.Model):
141 """
142 An abstract base class model with a ``is_removed`` field that
143 marks entries that are not going to be used anymore, but are
144 kept in db for any reason.
145 Default manager returns only not-removed entries.
146 """
147 is_removed = models.BooleanField(default=False)
148
149 class Meta:
150 abstract = True
151
152 objects: models.Manager[SoftDeletableModel] = SoftDeletableManager(_emit_deprecation_warnings=True)
153 available_objects: models.Manager[SoftDeletableModel] = SoftDeletableManager()
154 all_objects = models.Manager()
155
156 # Note that soft delete does not return anything,
157 # which doesn't conform to Django's interface.
158 # https://github.com/jazzband/django-model-utils/issues/541
159 @overload # type: ignore[override]
160 def delete(
161 self, using: Any = None, *args: Any, soft: Literal[True] = True, **kwargs: Any
162 ) -> None:
163 ...
164
165 @overload
166 def delete(
167 self, using: Any = None, *args: Any, soft: Literal[False], **kwargs: Any
168 ) -> tuple[int, dict[str, int]]:
169 ...
170
171 def delete(
172 self, using: Any = None, *args: Any, soft: bool = True, **kwargs: Any
173 ) -> tuple[int, dict[str, int]] | None:
174 """
175 Soft delete object (set its ``is_removed`` field to True).
176 Actually delete object if setting ``soft`` to False.
177 """
178 if soft:
179 self.is_removed = True
180 self.save(using=using)
181 return None
182 else:
183 return super().delete(using, *args, **kwargs)
184
185
186 class UUIDModel(models.Model):
187 """
188 This abstract base class provides id field on any model that inherits from it
189 which will be the primary key.
190 """
191 id = UUIDField(
192 primary_key=True,
193 version=4,
194 editable=False,
195 )
196
197 class Meta:
198 abstract = True