| 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 |