Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Documented patterns for adding extra managers to model subclasses.

This seems to have been a source of confusion, so now we have some explicit
examples. Fixed #9676.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@10058 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 24b9c65d3fd9b6fdff9397a03eb4ec9e6f1687c1 1 parent 292f503
@malcolmt malcolmt authored
Showing with 49 additions and 1 deletion.
  1. +49 −1 docs/topics/db/managers.txt
View
50 docs/topics/db/managers.txt
@@ -217,7 +217,7 @@ to be controlled. So here's how Django handles custom managers and
class, using Python's normal name resolution order (names on the child
class override all others; then come names on the first parent class,
and so on). Abstract base classes are designed to capture information
- and behaviour that is common to their child classes. Defining common
+ and behavior that is common to their child classes. Defining common
managers is an appropriate part of this common information.
3. The default manager on a class is either the first manager declared on
@@ -226,6 +226,54 @@ to be controlled. So here's how Django handles custom managers and
manager is explicitly declared, Django's normal default manager is
used.
+These rules provide the necessary flexibility if you want to install a
+collection of custom managers on a group of models, via an abstract base
+class, but still customize the default manager. For example, suppose you have
+this base class::
+
+ class AbstractBase(models.Model):
+ ...
+ objects = CustomerManager()
+
+ class Meta:
+ abstract = True
+
+If you use this directly in a subclass, ``objects`` will be the default
+manager if you declare no managers in the base class::
+
+ class ChildA(AbstractBase):
+ ...
+ # This class has CustomManager as the default manager.
+
+If you want to inherit from ``AbstractBase``, but provide a different default
+manager, you can provide the default manager on the child class::
+
+ class ChildB(AbstractBase):
+ ...
+ # An explicit default manager.
+ default_manager = OtherManager()
+
+Here, ``default_manager`` is the default. The ``objects`` manager is
+still available, since it's inherited. It just isn't used as the default.
+
+Finally for this example, suppose you want to add extra managers to the child
+class, but still use the default from ``AbstractBase``. You can't add the new
+manager directly in the child class, as that would override the default and you would
+have to also explicitly include all the managers from the abstract base class.
+The solution is to put the extra managers in another base class and introduce
+it into the inheritance hierarchy *after* the defaults::
+
+ class ExtraManager(models.Model):
+ extra_manager = OtherManager()
+
+ class Meta:
+ abstract = True
+
+ class ChildC(AbstractBase, ExtraManager):
+ ...
+ # Default manager is CustomManager, but OtherManager is
+ # also available via the "extra_manager" attribute.
+
.. _manager-types:
Controlling Automatic Manager Types
Please sign in to comment.
Something went wrong with that request. Please try again.