A Manager is the interface through which database query operations are\nprovided to Django models. At least one Manager exists for every model in\na Django application.
The way Manager classes work is documented in Making queries;\nthis document specifically touches on model options that customize Manager\nbehavior.
By default, Django adds a Manager with the name objects to every Django\nmodel class. However, if you want to use objects as a field name, or if you\nwant to use a name other than objects for the Manager, you can rename\nit on a per-model basis. To rename the Manager for a given class, define a\nclass attribute of type models.Manager() on that model. For example:
from django.db import models\n\nclass Person(models.Model):\n #...\n people = models.Manager()\nUsing this example model, Person.objects will generate an\nAttributeError exception, but Person.people.all() will provide a list\nof all Person objects.
You can use a custom Manager in a particular model by extending the base\nManager class and instantiating your custom Manager in your model.
There are two reasons you might want to customize a Manager: to add extra\nManager methods, and/or to modify the initial QuerySet the Manager\nreturns.
Adding extra Manager methods is the preferred way to add “table-level”\nfunctionality to your models. (For “row-level” functionality – i.e., functions\nthat act on a single instance of a model object – use Model methods, not custom Manager methods.)
A custom Manager method can return anything you want. It doesn’t have to\nreturn a QuerySet.
For example, this custom Manager offers a method with_counts(), which\nreturns a list of all OpinionPoll objects, each with an extra\nnum_responses attribute that is the result of an aggregate query:
from django.db import models\n\nclass PollManager(models.Manager):\n def with_counts(self):\n from django.db import connection\n cursor = connection.cursor()\n cursor.execute("""\n SELECT p.id, p.question, p.poll_date, COUNT(*)\n FROM polls_opinionpoll p, polls_response r\n WHERE p.id = r.poll_id\n GROUP BY p.id, p.question, p.poll_date\n ORDER BY p.poll_date DESC""")\n result_list = []\n for row in cursor.fetchall():\n p = self.model(id=row[0], question=row[1], poll_date=row[2])\n p.num_responses = row[3]\n result_list.append(p)\n return result_list\n\nclass OpinionPoll(models.Model):\n question = models.CharField(max_length=200)\n poll_date = models.DateField()\n objects = PollManager()\n\nclass Response(models.Model):\n poll = models.ForeignKey(OpinionPoll)\n person_name = models.CharField(max_length=50)\n response = models.TextField()\nWith this example, you’d use OpinionPoll.objects.with_counts() to return\nthat list of OpinionPoll objects with num_responses attributes.
Another thing to note about this example is that Manager methods can\naccess self.model to get the model class to which they’re attached.
A Manager’s base QuerySet returns all objects in the system. For\nexample, using this model:
from django.db import models\n\nclass Book(models.Model):\n title = models.CharField(max_length=100)\n author = models.CharField(max_length=50)\n…the statement Book.objects.all() will return all books in the database.
You can override a Manager’s base QuerySet by overriding the\nManager.get_queryset() method. get_queryset() should return a\nQuerySet with the properties you require.
For example, the following model has two Managers – one that returns\nall objects, and one that returns only the books by Roald Dahl:
# First, define the Manager subclass.\nclass DahlBookManager(models.Manager):\n def get_queryset(self):\n return super(DahlBookManager, self).get_queryset().filter(author='Roald Dahl')\n\n# Then hook it into the Book model explicitly.\nclass Book(models.Model):\n title = models.CharField(max_length=100)\n author = models.CharField(max_length=50)\n\n objects = models.Manager() # The default manager.\n dahl_objects = DahlBookManager() # The Dahl-specific manager.\nWith this sample model, Book.objects.all() will return all books in the\ndatabase, but Book.dahl_objects.all() will only return the ones written by\nRoald Dahl.
Of course, because get_queryset() returns a QuerySet object, you can\nuse filter(), exclude() and all the other QuerySet methods on it.\nSo these statements are all legal:
Book.dahl_objects.all()\nBook.dahl_objects.filter(title='Matilda')\nBook.dahl_objects.count()\nThis example also pointed out another interesting technique: using multiple\nmanagers on the same model. You can attach as many Manager() instances to\na model as you’d like. This is an easy way to define common “filters” for your\nmodels.
For example:
\nclass AuthorManager(models.Manager):\n def get_queryset(self):\n return super(AuthorManager, self).get_queryset().filter(role='A')\n\nclass EditorManager(models.Manager):\n def get_queryset(self):\n return super(EditorManager, self).get_queryset().filter(role='E')\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n role = models.CharField(max_length=1, choices=(('A', _('Author')), ('E', _('Editor'))))\n people = models.Manager()\n authors = AuthorManager()\n editors = EditorManager()\nThis example allows you to request Person.authors.all(), Person.editors.all(),\nand Person.people.all(), yielding predictable results.
If you use custom Manager objects, take note that the first Manager\nDjango encounters (in the order in which they’re defined in the model) has a\nspecial status. Django interprets the first Manager defined in a class as\nthe “default” Manager, and several parts of Django\n(including dumpdata) will use that Manager\nexclusively for that model. As a result, it’s a good idea to be careful in\nyour choice of default manager in order to avoid a situation where overriding\nget_queryset() results in an inability to retrieve objects you’d like to\nwork with.
QuerySet methods from the ManagerLink to this heading#While most methods from the standard QuerySet are accessible directly from\nthe Manager, this is only the case for the extra methods defined on a\ncustom QuerySet if you also implement them on the Manager:
class PersonQuerySet(models.QuerySet):\n def authors(self):\n return self.filter(role='A')\n\n def editors(self):\n return self.filter(role='E')\n\nclass PersonManager(models.Manager):\n def get_queryset(self):\n return PersonQuerySet(self.model, using=self._db)\n\n def authors(self):\n return self.get_queryset().authors()\n\n def editors(self):\n return self.get_queryset().editors()\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n role = models.CharField(max_length=1, choices=(('A', _('Author')), ('E', _('Editor'))))\n people = PersonManager()\nThis example allows you to call both authors() and editors() directly from\nthe manager Person.people.
Manager with QuerySet methodsLink to this heading#In lieu of the above approach which requires duplicating methods on both the\nQuerySet and the Manager, QuerySet.as_manager() can be used to create an instance\nof Manager with a copy of a custom QuerySet’s methods:
class Person(models.Model):\n ...\n people = PersonQuerySet.as_manager()\nThe Manager instance created by QuerySet.as_manager() will be virtually\nidentical to the PersonManager from the previous example.
Not every QuerySet method makes sense at the Manager level; for\ninstance we intentionally prevent the QuerySet.delete() method from being copied onto\nthe Manager class.
Methods are copied according to the following rules:
\nPublic methods are copied by default.
Private methods (starting with an underscore) are not copied by default.
Methods with a queryset_only attribute set to False are always copied.
Methods with a queryset_only attribute set to True are never copied.
For example:
\nclass CustomQuerySet(models.QuerySet):\n # Available on both Manager and QuerySet.\n def public_method(self):\n return\n\n # Available only on QuerySet.\n def _private_method(self):\n return\n\n # Available only on QuerySet.\n def opted_out_public_method(self):\n return\n opted_out_public_method.queryset_only = True\n\n # Available on both Manager and QuerySet.\n def _opted_in_private_method(self):\n return\n _opted_in_private_method.queryset_only = False\nFor advanced usage you might want both a custom Manager and a custom\nQuerySet. You can do that by calling Manager.from_queryset() which\nreturns a subclass of your base Manager with a copy of the custom\nQuerySet methods:
class BaseManager(models.Manager):\n def manager_only_method(self):\n return\n\nclass CustomQuerySet(models.QuerySet):\n def manager_and_queryset_method(self):\n return\n\nclass MyModel(models.Model):\n objects = BaseManager.from_queryset(CustomQuerySet)()\nYou may also store the generated class into a variable:
\nCustomManager = BaseManager.from_queryset(CustomQuerySet)\n\nclass MyModel(models.Model):\n objects = CustomManager()\nClass inheritance and model managers aren’t quite a perfect match for each\nother. Managers are often specific to the classes they are defined on and\ninheriting them in subclasses isn’t necessarily a good idea. Also, because the\nfirst manager declared is the default manager, it is important to allow that\nto be controlled. So here’s how Django handles custom managers and\nmodel inheritance:
\nManagers defined on non-abstract base classes are not inherited by\nchild classes. If you want to reuse a manager from a non-abstract base,\nredeclare it explicitly on the child class. These sorts of managers are\nlikely to be fairly specific to the class they are defined on, so\ninheriting them can often lead to unexpected results (particularly as\nfar as the default manager goes). Therefore, they aren’t passed onto\nchild classes.
Managers from abstract base classes are always inherited by the child\nclass, using Python’s normal name resolution order (names on the child\nclass override all others; then come names on the first parent class,\nand so on). Abstract base classes are designed to capture information\nand behavior that is common to their child classes. Defining common\nmanagers is an appropriate part of this common information.
The default manager on a class is either the first manager declared on\nthe class, if that exists, or the default manager of the first abstract\nbase class in the parent hierarchy, if that exists. If no default\nmanager is explicitly declared, Django’s normal default manager is\nused.
These rules provide the necessary flexibility if you want to install a\ncollection of custom managers on a group of models, via an abstract base\nclass, but still customize the default manager. For example, suppose you have\nthis base class:
\nclass AbstractBase(models.Model):\n # ...\n objects = CustomManager()\n\n class Meta:\n abstract = True\nIf you use this directly in a subclass, objects will be the default\nmanager if you declare no managers in the base class:
class ChildA(AbstractBase):\n # ...\n # This class has CustomManager as the default manager.\n pass\nIf you want to inherit from AbstractBase, but provide a different default\nmanager, you can provide the default manager on the child class:
class ChildB(AbstractBase):\n # ...\n # An explicit default manager.\n default_manager = OtherManager()\nHere, default_manager is the default. The objects manager is\nstill 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\nclass, but still use the default from AbstractBase. You can’t add the new\nmanager directly in the child class, as that would override the default and you would\nhave to also explicitly include all the managers from the abstract base class.\nThe solution is to put the extra managers in another base class and introduce\nit into the inheritance hierarchy after the defaults:
class ExtraManager(models.Model):\n extra_manager = OtherManager()\n\n class Meta:\n abstract = True\n\nclass ChildC(AbstractBase, ExtraManager):\n # ...\n # Default manager is CustomManager, but OtherManager is\n # also available via the "extra_manager" attribute.\n pass\nNote that while you can define a custom manager on the abstract model, you\ncan’t invoke any methods using the abstract model. That is:
\nClassA.objects.do_something()\nis legal, but:
\nAbstractBase.objects.do_something()\nwill raise an exception. This is because managers are intended to encapsulate\nlogic for managing collections of objects. Since you can’t have a collection of\nabstract objects, it doesn’t make sense to be managing them. If you have\nfunctionality that applies to the abstract model, you should put that functionality\nin a staticmethod or classmethod on the abstract model.
Whatever features you add to your custom Manager, it must be\npossible to make a shallow copy of a Manager instance; i.e., the\nfollowing code must work:
>>> import copy\n>>> manager = MyManager()\n>>> my_copy = copy.copy(manager)\nDjango makes shallow copies of manager objects during certain queries;\nif your Manager cannot be copied, those queries will fail.
\nThis won’t be an issue for most custom managers. If you are just\nadding simple methods to your Manager, it is unlikely that you\nwill inadvertently make instances of your Manager uncopyable.\nHowever, if you’re overriding __getattr__ or some other private\nmethod of your Manager object that controls object state, you\nshould ensure that you don’t affect the ability of your Manager to\nbe copied.
This document has already mentioned a couple of places where Django creates a\nmanager class for you: default managers and the “plain” manager used to\naccess related objects. There are other places in the implementation of\nDjango where temporary plain managers are needed. Those automatically created\nmanagers will normally be instances of the django.db.models.Manager\nclass.
Throughout this section, we will use the term “automatic manager” to mean a\nmanager that Django creates for you – either as a default manager on a model\nwith no managers, or to use temporarily when accessing related objects.
\nSometimes this default class won’t be the right choice. One example is in the\ndjango.contrib.gis application that ships with Django itself. All gis\nmodels must use a special manager class (GeoManager)\nbecause they need a special queryset (GeoQuerySet)\nto be used for interacting with the database. It turns out that models which require\na special manager like this need to use the same manager class wherever an automatic\nmanager is created.
Django provides a way for custom manager developers to say that their manager\nclass should be used for automatic managers whenever it is the default manager\non a model. This is done by setting the use_for_related_fields attribute on\nthe manager class:
class MyManager(models.Manager):\n use_for_related_fields = True\n # ...\nIf this attribute is set on the default manager for a model (only the\ndefault manager is considered in these situations), Django will use that class\nwhenever it needs to automatically create a manager for the class. Otherwise,\nit will use django.db.models.Manager.
As already suggested by the django.contrib.gis example, above, the\nuse_for_related_fields feature is primarily for managers that need to\nreturn a custom QuerySet subclass. In providing this functionality in your\nmanager, there are a couple of things to remember.
One reason an automatic manager is used is to access objects that are related\nto from some other model. In those situations, Django has to be able to see\nall the objects for the model it is fetching, so that anything which is\nreferred to can be retrieved.
\nIf you override the get_queryset() method and filter out any rows, Django\nwill return incorrect results. Don’t do that. A manager that filters results\nin get_queryset() is not appropriate for use as an automatic manager.