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:
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
:
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:
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:
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:
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:
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.
Note
Due to Django bug #16572, on Django versions prior to 1.6
InheritanceManager
only supports a single level of model inheritance;
it won’t work for grandchild models.
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:
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).
PassThroughManager¶
A common “gotcha” when defining methods on a custom manager class is that those
same methods are not automatically also available on the QuerySets returned by
that manager, so are not “chainable”. This can be counterintuitive, as most of
the public QuerySet API is mirrored on managers. It is possible to create a
custom Manager that returns QuerySets that have the same additional methods,
but this requires boilerplate code. The PassThroughManager
class
(contributed by Paul McLanahan) removes this boilerplate.
To use PassThroughManager
, rather than defining a custom manager with
additional methods, define a custom QuerySet
subclass with the additional
methods you want, and pass that QuerySet
subclass to the
PassThroughManager.for_queryset_class()
class method. The returned
PassThroughManager
subclass will always return instances of your custom
QuerySet
, and you can also call methods of your custom QuerySet
directly on the manager:
from datetime import datetime
from django.db import models
from django.db.models.query import QuerySet
from model_utils.managers import PassThroughManager
class PostQuerySet(QuerySet):
def by_author(self, user):
return self.filter(user=user)
def published(self):
return self.filter(published__lte=datetime.now())
def unpublished(self):
return self.filter(published__gte=datetime.now())
class Post(models.Model):
user = models.ForeignKey(User)
published = models.DateTimeField()
objects = PassThroughManager.for_queryset_class(PostQuerySet)()
Post.objects.published()
Post.objects.by_author(user=request.user).unpublished()
Mixins¶
Each of the above manager classes has a corresponding mixin that can be used to
add functionality to any manager. For example, to create a GeoDjango
GeoManager
that includes “pass through” functionality, you can write the
following code:
from django.contrib.gis.db import models
from django.contrib.gis.db.models.query import GeoQuerySet
from model_utils.managers import PassThroughManagerMixin
class PassThroughGeoManager(PassThroughManagerMixin, models.GeoManager):
pass
class LocationQuerySet(GeoQuerySet):
def within_boundary(self, geom):
return self.filter(point__within=geom)
def public(self):
return self.filter(public=True)
class Location(models.Model):
point = models.PointField()
public = models.BooleanField(default=True)
objects = PassThroughGeoManager.for_queryset_class(LocationQuerySet)()
Location.objects.public()
Location.objects.within_boundary(geom=geom)
Location.objects.within_boundary(geom=geom).public()
Now you have a “pass through manager” that can also take advantage of
GeoDjango’s spatial lookups. You can similarly add additional functionality to
any manager by composing that manager with InheritanceManagerMixin
or
QueryManagerMixin
.