mirror of
https://github.com/Hopiu/django-model-utils.git
synced 2026-03-17 04:10:24 +00:00
212 lines
7.4 KiB
ReStructuredText
212 lines
7.4 KiB
ReStructuredText
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.
|
|
|
|
.. 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.
|
|
|
|
.. _contributed by Jeff Elmore: http://jeffelmore.org/2010/11/11/automatic-downcasting-of-inherited-models-in-django/
|
|
.. _Django bug #16572: https://code.djangoproject.com/ticket/16572
|
|
|
|
|
|
.. _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).
|
|
|
|
|
|
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.
|
|
|
|
.. _contributed by Paul McLanahan: http://paulm.us/post/3717466639/passthroughmanager-for-django
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
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.object.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
|
|
additonal functionality to any manager by composing that manager with InheritanceManagerMixin or QueryManagerMixin.
|