Debian Codegraph @

docs/models.rst

raw
1 Models
2 ======
3
4 TimeFramedModel
5 ---------------
6
7 An abstract base class for any model that expresses a time-range. Adds
8 ``start`` and ``end`` nullable DateTimeFields, and provides a new
9 ``timeframed`` manager on the subclass whose queryset pre-filters results
10 to only include those which have a ``start`` which is not in the future,
11 and an ``end`` which is not in the past. If either ``start`` or ``end`` is
12 ``null``, the manager will include it.
13
14 .. code-block:: python
15
16 from model_utils.models import TimeFramedModel
17 from datetime import datetime, timedelta
18 class Post(TimeFramedModel):
19 pass
20
21 p = Post()
22 p.start = datetime.utcnow() - timedelta(days=1)
23 p.end = datetime.utcnow() + timedelta(days=7)
24 p.save()
25
26 # this query will return the above Post instance:
27 Post.timeframed.all()
28
29 p.start = None
30 p.end = None
31 p.save()
32
33 # this query will also return the above Post instance, because
34 # the `start` and/or `end` are NULL.
35 Post.timeframed.all()
36
37 p.start = datetime.utcnow() + timedelta(days=7)
38 p.save()
39
40 # this query will NOT return our Post instance, because
41 # the start date is in the future.
42 Post.timeframed.all()
43
44 TimeStampedModel
45 ----------------
46
47 This abstract base class just provides self-updating ``created`` and
48 ``modified`` fields on any model that inherits from it.
49
50
51 StatusModel
52 -----------
53
54 Pulls together :ref:`StatusField`, :ref:`MonitorField` and :ref:`QueryManager`
55 into an abstract base class for any model with a "status."
56
57 Just provide a ``STATUS`` class-attribute (a :ref:`Choices` object or a
58 list of two-tuples), and your model will have a ``status`` field with
59 those choices, a ``status_changed`` field containing the date-time the
60 ``status`` was last changed, and a manager for each status that
61 returns objects with that status only:
62
63 .. code-block:: python
64
65 from model_utils.models import StatusModel
66 from model_utils import Choices
67
68 class Article(StatusModel):
69 STATUS = Choices('draft', 'published')
70
71 # ...
72
73 a = Article()
74 a.status = Article.STATUS.published
75
76 # this save will update a.status_changed
77 a.save()
78
79 # this query will only return published articles:
80 Article.published.all()
81
82
83 SoftDeletableModel
84 ------------------
85
86 This abstract base class just provides a field ``is_removed`` which is
87 set to True instead of removing the instance. Entities returned in
88 manager ``available_objects`` are limited to not-deleted instances.
89
90 Note that relying on the default ``objects`` manager to filter out not-deleted
91 instances is deprecated. ``objects`` will include deleted objects in a future
92 release. Until then, the recommended course of action is to use the manager
93 ``all_objects`` when you want to include all instances.
94
95 UUIDModel
96 ------------------
97
98 This abstract base class provides ``id`` field on any model that inherits from it
99 which will be the primary key.
100
101 If you dont want to set ``id`` as primary key or change the field name, you can override it
102 with our `UUIDField`_
103
104 Also you can override the default uuid version. Versions 1,3,4 and 5 are now supported.
105
106 .. code-block:: python
107
108 from model_utils.models import UUIDModel
109
110 class MyAppModel(UUIDModel):
111 pass
112
113
114 .. _`UUIDField`: https://github.com/jazzband/django-model-utils/blob/master/docs/fields.rst#uuidfield