1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
Model Managers
==============
InheritanceManager
------------------
This manager (`contributed by Jeff Elmore`_) should be attached to a base model
class in a model-inheritance tree. It allows queries on that base model to
return heterogenous results of the actual proper subtypes, without any
additional queries.
For instance, if you have a ``Place`` model with subclasses ``Restaurant`` and
``Bar``, you may want to query all Places:
.. code-block:: python
nearby_places = Place.objects.filter(location='here')
But when you iterate over ``nearby_places``, you'll get only ``Place``
instances back, even for objects that are "really" ``Restaurant`` or ``Bar``.
If you attach an ``InheritanceManager`` to ``Place``, you can just call the
``select_subclasses()`` method on the ``InheritanceManager`` or any
``QuerySet`` from it, and the resulting objects will be instances of
``Restaurant`` or ``Bar``:
.. code-block:: python
from model_utils.managers import InheritanceManager
class Place(models.Model):
# ...
objects = InheritanceManager()
class Restaurant(Place):
# ...
class Bar(Place):
# ...
nearby_places = Place.objects.filter(location='here').select_subclasses()
for place in nearby_places:
# "place" will automatically be an instance of Place, Restaurant, or Bar
The database query performed will have an extra join for each subclass; if you
want to reduce the number of joins and you only need particular subclasses to
be returned as their actual type, you can pass subclass names to
``select_subclasses()``, much like the built-in ``select_related()`` method:
.. code-block:: python
nearby_places = Place.objects.select_subclasses("restaurant")
# restaurants will be Restaurant instances, bars will still be Place instances
nearby_places = Place.objects.select_subclasses("restaurant", "bar")
# all Places will be converted to Restaurant and Bar instances.
It is also possible to use the subclasses themselves as arguments to
``select_subclasses``, leaving it to calculate the relationship for you:
.. code-block:: python
nearby_places = Place.objects.select_subclasses(Restaurant)
# restaurants will be Restaurant instances, bars will still be Place instances
nearby_places = Place.objects.select_subclasses(Restaurant, Bar)
# all Places will be converted to Restaurant and Bar instances.
It is even possible to mix and match the two:
.. code-block:: python
nearby_places = Place.objects.select_subclasses(Restaurant, "bar")
# all Places will be converted to Restaurant and Bar instances.
``InheritanceManager`` also provides a subclass-fetching alternative to the
``get()`` method:
.. code-block:: python
place = Place.objects.get_subclass(id=some_id)
# "place" will automatically be an instance of Place, Restaurant, or Bar
If you don't explicitly call ``select_subclasses()`` or ``get_subclass()``,
an ``InheritanceManager`` behaves identically to a normal ``Manager``; so
it's safe to use as your default manager for the model.
.. _contributed by Jeff Elmore: http://jeffelmore.org/2010/11/11/automatic-downcasting-of-inherited-models-in-django/
JoinManager
-----------
The ``JoinManager`` will create a temporary table of your current queryset
and join that temporary table with the model of your current queryset. This can
be advantageous if you have to page through your entire DB and using django's
slice mechanism to do that. ``LIMIT .. OFFSET ..`` becomes slower the bigger
offset you use.
.. code-block:: python
sliced_qs = Place.objects.all()[2000:2010]
qs = sliced_qs.join()
# qs contains 10 objects, and there will be a much smaller performance hit
# for paging through all of first 2000 objects.
Alternatively, you can give it a queryset and the manager will create a temporary
table and join that to your current queryset. This can work as a more performant
alternative to using django's ``__in`` as described in the following
(`StackExchange answer`_).
.. code-block:: python
big_qs = Restaurant.objects.filter(menu='vegetarian')
qs = Country.objects.filter(country_code='SE').join(big_qs)
.. _StackExchange answer: https://dba.stackexchange.com/questions/91247/optimizing-a-postgres-query-with-a-large-in
.. _QueryManager:
QueryManager
------------
Many custom model managers do nothing more than return a QuerySet that
is filtered in some way. ``QueryManager`` allows you to express this
pattern with a minimum of boilerplate:
.. code-block:: python
from django.db import models
from model_utils.managers import QueryManager
class Post(models.Model):
...
published = models.BooleanField()
pub_date = models.DateField()
...
objects = models.Manager()
public = QueryManager(published=True).order_by('-pub_date')
The kwargs passed to ``QueryManager`` will be passed as-is to the
``QuerySet.filter()`` method. You can also pass a ``Q`` object to
``QueryManager`` to express more complex conditions. Note that you can
set the ordering of the ``QuerySet`` returned by the ``QueryManager``
by chaining a call to ``.order_by()`` on the ``QueryManager`` (this is
not required).
SoftDeletableManager
--------------------
Returns only model instances that have the ``is_removed`` field set
to False. Uses ``SoftDeletableQuerySet``, which ensures model instances
won't be removed in bulk, but they will be marked as removed instead.
Mixins
------
Each of the above manager classes has a corresponding mixin that can be used to
add functionality to any manager.
Note that any manager class using ``InheritanceManagerMixin`` must return a
``QuerySet`` class using ``InheritanceQuerySetMixin`` from its ``get_queryset``
method.
|
