1 ========

     2 Managers

     3 ========

     4 

     5 .. currentmodule:: django.db.models

     6 

     7 .. class:: Manager()

     8 

     9 A ``Manager`` is the interface through which database query operations are

    10 provided to Django models. At least one ``Manager`` exists for every model in

    11 a Django application.

    12 

    13 The way ``Manager`` classes work is documented in :doc:`/topics/db/queries`;

    14 this document specifically touches on model options that customize ``Manager``

    15 behavior.

    16 

    17 .. _manager-names:

    18 

    19 Manager names

    20 =============

    21 

    22 By default, Django adds a ``Manager`` with the name ``objects`` to every Django

    23 model class. However, if you want to use ``objects`` as a field name, or if you

    24 want to use a name other than ``objects`` for the ``Manager``, you can rename

    25 it on a per-model basis. To rename the ``Manager`` for a given class, define a

    26 class attribute of type ``models.Manager()`` on that model. For example::

    27 

    28     from django.db import models

    29 

    30     class Person(models.Model):

    31         #...

    32         people = models.Manager()

    33 

    34 Using this example model, ``Person.objects`` will generate an

    35 ``AttributeError`` exception, but ``Person.people.all()`` will provide a list

    36 of all ``Person`` objects.

    37 

    38 .. _custom-managers:

    39 

    40 Custom Managers

    41 ===============

    42 

    43 You can use a custom ``Manager`` in a particular model by extending the base

    44 ``Manager`` class and instantiating your custom ``Manager`` in your model.

    45 

    46 There are two reasons you might want to customize a ``Manager``: to add extra

    47 ``Manager`` methods, and/or to modify the initial ``QuerySet`` the ``Manager``

    48 returns.

    49 

    50 Adding extra Manager methods

    51 ----------------------------

    52 

    53 Adding extra ``Manager`` methods is the preferred way to add "table-level"

    54 functionality to your models. (For "row-level" functionality -- i.e., functions

    55 that act on a single instance of a model object -- use :ref:`Model methods

    56 <model-methods>`, not custom ``Manager`` methods.)

    57 

    58 A custom ``Manager`` method can return anything you want. It doesn't have to

    59 return a ``QuerySet``.

    60 

    61 For example, this custom ``Manager`` offers a method ``with_counts()``, which

    62 returns a list of all ``OpinionPoll`` objects, each with an extra

    63 ``num_responses`` attribute that is the result of an aggregate query::

    64 

    65     class PollManager(models.Manager):

    66         def with_counts(self):

    67             from django.db import connection

    68             cursor = connection.cursor()

    69             cursor.execute("""

    70                 SELECT p.id, p.question, p.poll_date, COUNT(*)

    71                 FROM polls_opinionpoll p, polls_response r

    72                 WHERE p.id = r.poll_id

    73                 GROUP BY 1, 2, 3

    74                 ORDER BY 3 DESC""")

    75             result_list = []

    76             for row in cursor.fetchall():

    77                 p = self.model(id=row[0], question=row[1], poll_date=row[2])

    78                 p.num_responses = row[3]

    79                 result_list.append(p)

    80             return result_list

    81 

    82     class OpinionPoll(models.Model):

    83         question = models.CharField(max_length=200)

    84         poll_date = models.DateField()

    85         objects = PollManager()

    86 

    87     class Response(models.Model):

    88         poll = models.ForeignKey(Poll)

    89         person_name = models.CharField(max_length=50)

    90         response = models.TextField()

    91 

    92 With this example, you'd use ``OpinionPoll.objects.with_counts()`` to return

    93 that list of ``OpinionPoll`` objects with ``num_responses`` attributes.

    94 

    95 Another thing to note about this example is that ``Manager`` methods can

    96 access ``self.model`` to get the model class to which they're attached.

    97 

    98 Modifying initial Manager QuerySets

    99 -----------------------------------

   100 

   101 A ``Manager``'s base ``QuerySet`` returns all objects in the system. For

   102 example, using this model::

   103 

   104     class Book(models.Model):

   105         title = models.CharField(max_length=100)

   106         author = models.CharField(max_length=50)

   107 

   108 ...the statement ``Book.objects.all()`` will return all books in the database.

   109 

   110 You can override a ``Manager``\'s base ``QuerySet`` by overriding the

   111 ``Manager.get_query_set()`` method. ``get_query_set()`` should return a

   112 ``QuerySet`` with the properties you require.

   113 

   114 For example, the following model has *two* ``Manager``\s -- one that returns

   115 all objects, and one that returns only the books by Roald Dahl::

   116 

   117     # First, define the Manager subclass.

   118     class DahlBookManager(models.Manager):

   119         def get_query_set(self):

   120             return super(DahlBookManager, self).get_query_set().filter(author='Roald Dahl')

   121 

   122     # Then hook it into the Book model explicitly.

   123     class Book(models.Model):

   124         title = models.CharField(max_length=100)

   125         author = models.CharField(max_length=50)

   126 

   127         objects = models.Manager() # The default manager.

   128         dahl_objects = DahlBookManager() # The Dahl-specific manager.

   129 

   130 With this sample model, ``Book.objects.all()`` will return all books in the

   131 database, but ``Book.dahl_objects.all()`` will only return the ones written by

   132 Roald Dahl.

   133 

   134 Of course, because ``get_query_set()`` returns a ``QuerySet`` object, you can

   135 use ``filter()``, ``exclude()`` and all the other ``QuerySet`` methods on it.

   136 So these statements are all legal::

   137 

   138     Book.dahl_objects.all()

   139     Book.dahl_objects.filter(title='Matilda')

   140     Book.dahl_objects.count()

   141 

   142 This example also pointed out another interesting technique: using multiple

   143 managers on the same model. You can attach as many ``Manager()`` instances to

   144 a model as you'd like. This is an easy way to define common "filters" for your

   145 models.

   146 

   147 For example::

   148 

   149     class MaleManager(models.Manager):

   150         def get_query_set(self):

   151             return super(MaleManager, self).get_query_set().filter(sex='M')

   152 

   153     class FemaleManager(models.Manager):

   154         def get_query_set(self):

   155             return super(FemaleManager, self).get_query_set().filter(sex='F')

   156 

   157     class Person(models.Model):

   158         first_name = models.CharField(max_length=50)

   159         last_name = models.CharField(max_length=50)

   160         sex = models.CharField(max_length=1, choices=(('M', 'Male'), ('F', 'Female')))

   161         people = models.Manager()

   162         men = MaleManager()

   163         women = FemaleManager()

   164 

   165 This example allows you to request ``Person.men.all()``, ``Person.women.all()``,

   166 and ``Person.people.all()``, yielding predictable results.

   167 

   168 If you use custom ``Manager`` objects, take note that the first ``Manager``

   169 Django encounters (in the order in which they're defined in the model) has a

   170 special status. Django interprets the first ``Manager`` defined in a class as

   171 the "default" ``Manager``, and several parts of Django

   172 (including :djadmin:`dumpdata`) will use that ``Manager``

   173 exclusively for that model. As a result, it's a good idea to be careful in

   174 your choice of default manager in order to avoid a situation where overriding

   175 ``get_query_set()`` results in an inability to retrieve objects you'd like to

   176 work with.

   177 

   178 .. _managers-for-related-objects:

   179 

   180 Using managers for related object access

   181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   182 

   183 By default, Django uses an instance of a "plain" manager class when accessing

   184 related objects (i.e. ``choice.poll``), not the default manager on the related

   185 object. This is because Django needs to be able to retrieve the related

   186 object, even if it would otherwise be filtered out (and hence be inaccessible)

   187 by the default manager.

   188 

   189 If the normal plain manager class (:class:`django.db.models.Manager`) is not

   190 appropriate for your circumstances, you can force Django to use the same class

   191 as the default manager for your model by setting the `use_for_related_fields`

   192 attribute on the manager class. This is documented fully below_.

   193 

   194 .. _below: manager-types_

   195 

   196 .. _custom-managers-and-inheritance:

   197 

   198 Custom managers and model inheritance

   199 -------------------------------------

   200 

   201 Class inheritance and model managers aren't quite a perfect match for each

   202 other. Managers are often specific to the classes they are defined on and

   203 inheriting them in subclasses isn't necessarily a good idea. Also, because the

   204 first manager declared is the *default manager*, it is important to allow that

   205 to be controlled. So here's how Django handles custom managers and

   206 :ref:`model inheritance <model-inheritance>`:

   207 

   208     1. Managers defined on non-abstract base classes are *not* inherited by

   209        child classes. If you want to reuse a manager from a non-abstract base,

   210        redeclare it explicitly on the child class. These sorts of managers are

   211        likely to be fairly specific to the class they are defined on, so

   212        inheriting them can often lead to unexpected results (particularly as

   213        far as the default manager goes). Therefore, they aren't passed onto

   214        child classes.

   215 

   216     2. Managers from abstract base classes are always inherited by the child

   217        class, using Python's normal name resolution order (names on the child

   218        class override all others; then come names on the first parent class,

   219        and so on). Abstract base classes are designed to capture information

   220        and behavior that is common to their child classes. Defining common

   221        managers is an appropriate part of this common information.

   222 

   223     3. The default manager on a class is either the first manager declared on

   224        the class, if that exists, or the default manager of the first abstract

   225        base class in the parent hierarchy, if that exists. If no default

   226        manager is explicitly declared, Django's normal default manager is

   227        used.

   228 

   229 These rules provide the necessary flexibility if you want to install a

   230 collection of custom managers on a group of models, via an abstract base

   231 class, but still customize the default manager. For example, suppose you have

   232 this base class::

   233 

   234     class AbstractBase(models.Model):

   235         ...

   236         objects = CustomManager()

   237 

   238         class Meta:

   239             abstract = True

   240 

   241 If you use this directly in a subclass, ``objects`` will be the default

   242 manager if you declare no managers in the base class::

   243 

   244     class ChildA(AbstractBase):

   245         ...

   246         # This class has CustomManager as the default manager.

   247 

   248 If you want to inherit from ``AbstractBase``, but provide a different default

   249 manager, you can provide the default manager on the child class::

   250 

   251     class ChildB(AbstractBase):

   252         ...

   253         # An explicit default manager.

   254         default_manager = OtherManager()

   255 

   256 Here, ``default_manager`` is the default. The ``objects`` manager is

   257 still available, since it's inherited. It just isn't used as the default.

   258 

   259 Finally for this example, suppose you want to add extra managers to the child

   260 class, but still use the default from ``AbstractBase``. You can't add the new

   261 manager directly in the child class, as that would override the default and you would

   262 have to also explicitly include all the managers from the abstract base class.

   263 The solution is to put the extra managers in another base class and introduce

   264 it into the inheritance hierarchy *after* the defaults::

   265 

   266     class ExtraManager(models.Model):

   267         extra_manager = OtherManager()

   268 

   269         class Meta:

   270             abstract = True

   271 

   272     class ChildC(AbstractBase, ExtraManager):

   273         ...

   274         # Default manager is CustomManager, but OtherManager is

   275         # also available via the "extra_manager" attribute.

   276 

   277 .. _manager-types:

   278 

   279 Controlling Automatic Manager Types

   280 ===================================

   281 

   282 This document has already mentioned a couple of places where Django creates a

   283 manager class for you: `default managers`_ and the "plain" manager used to

   284 `access related objects`_. There are other places in the implementation of

   285 Django where temporary plain managers are needed. Those automatically created

   286 managers will normally be instances of the :class:`django.db.models.Manager`

   287 class.

   288 

   289 .. _default managers: manager-names_

   290 .. _access related objects: managers-for-related-objects_

   291 

   292 Throughout this section, we will use the term "automatic manager" to mean a

   293 manager that Django creates for you -- either as a default manager on a model

   294 with no managers, or to use temporarily when accessing related objects.

   295 

   296 Sometimes this default class won't be the right choice. One example is in the

   297 :mod:`django.contrib.gis` application that ships with Django itself. All ``gis``

   298 models must use a special manager class (:class:`~django.contrib.gis.db.models.GeoManager`)

   299 because they need a special queryset (:class:`~django.contrib.gis.db.models.GeoQuerySet`)

   300 to be used for interacting with the database.  It turns out that models which require

   301 a special manager like this need to use the same manager class wherever an automatic

   302 manager is created.

   303 

   304 Django provides a way for custom manager developers to say that their manager

   305 class should be used for automatic managers whenever it is the default manager

   306 on a model. This is done by setting the ``use_for_related_fields`` attribute on

   307 the manager class::

   308 

   309     class MyManager(models.Manager):

   310         use_for_related_fields = True

   311 

   312         ...

   313 

   314 If this attribute is set on the *default* manager for a model (only the

   315 default manager is considered in these situations), Django will use that class

   316 whenever it needs to automatically create a manager for the class.  Otherwise,

   317 it will use :class:`django.db.models.Manager`.

   318 

   319 .. admonition:: Historical Note

   320 

   321     Given the purpose for which it's used, the name of this attribute

   322     (``use_for_related_fields``) might seem a little odd. Originally, the

   323     attribute only controlled the type of manager used for related field

   324     access, which is where the name came from. As it became clear the concept

   325     was more broadly useful, the name hasn't been changed. This is primarily

   326     so that existing code will :doc:`continue to work </misc/api-stability>` in

   327     future Django versions.

   328 

   329 Writing Correct Managers For Use In Automatic Manager Instances

   330 ---------------------------------------------------------------

   331 

   332 As already suggested by the `django.contrib.gis` example, above, the

   333 ``use_for_related_fields`` feature is primarily for managers that need to

   334 return a custom ``QuerySet`` subclass. In providing this functionality in your

   335 manager, there are a couple of things to remember.

   336 

   337 Do not filter away any results in this type of manager subclass

   338 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   339 

   340 One reason an automatic manager is used is to access objects that are related

   341 to from some other model. In those situations, Django has to be able to see

   342 all the objects for the model it is fetching, so that *anything* which is

   343 referred to can be retrieved.

   344 

   345 If you override the ``get_query_set()`` method and filter out any rows, Django

   346 will return incorrect results. Don't do that. A manager that filters results

   347 in ``get_query_set()`` is not appropriate for use as an automatic manager.

   348 

   349 Set ``use_for_related_fields`` when you define the class

   350 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   351 

   352 The ``use_for_related_fields`` attribute must be set on the manager *class*,

   353 object not on an *instance* of the class. The earlier example shows the

   354 correct way to set it, whereas the following will not work::

   355 

   356     # BAD: Incorrect code

   357     class MyManager(models.Manager):

   358         ...

   359 

   360     # Sets the attribute on an instance of MyManager. Django will

   361     # ignore this setting.

   362     mgr = MyManager()

   363     mgr.use_for_related_fields = True

   364 

   365     class MyModel(models.Model):

   366         ...

   367         objects = mgr

   368 

   369     # End of incorrect code.

   370 

   371 You also shouldn't change the attribute on the class object after it has been

   372 used in a model, since the attribute's value is processed when the model class

   373 is created and not subsequently reread. Set the attribute on the manager class

   374 when it is first defined, as in the initial example of this section and

   375 everything will work smoothly.

   376