class Manager[源代码]

A Manager is the interface through which database query operations are provided to Django models. At least one Manager exists for every model in a Django application.

The way Manager classes work is documented in 进行查询; this document specifically touches on model options that customize Manager behavior.

Manager names

By default, Django adds a Manager with the name objects to every Django model class. However, if you want to use objects as a field name, or if you want to use a name other than objects for the Manager, you can rename it on a per-model basis. To rename the Manager for a given class, define a class attribute of type models.Manager() on that model. For example:

from django.db import models

class Person(models.Model):
    people = models.Manager()

Using this example model, Person.objects will generate an AttributeError exception, but Person.people.all() will provide a list of all Person objects.

Custom managers

You can use a custom Manager in a particular model by extending the base Manager class and instantiating your custom Manager in your model.

There are two reasons you might want to customize a Manager: to add extra Manager methods, and/or to modify the initial QuerySet the Manager returns.

Adding extra manager methods

Adding extra Manager methods is the preferred way to add "table-level" functionality to your models. (For "row-level" functionality -- i.e., functions that 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 return a QuerySet.

For example, this custom Manager offers a method with_counts(), which returns a list of all OpinionPoll objects, each with an extra num_responses attribute that is the result of an aggregate query:

from django.db import models

class PollManager(models.Manager):
    def with_counts(self):
        from django.db import connection
        with connection.cursor() as cursor:
                SELECT, p.question, p.poll_date, COUNT(*)
                FROM polls_opinionpoll p, polls_response r
                WHERE = r.poll_id
                GROUP BY, p.question, p.poll_date
                ORDER BY p.poll_date DESC""")
            result_list = []
            for row in cursor.fetchall():
                p = self.model(id=row[0], question=row[1], poll_date=row[2])
                p.num_responses = row[3]
        return result_list

class OpinionPoll(models.Model):
    question = models.CharField(max_length=200)
    poll_date = models.DateField()
    objects = PollManager()

class Response(models.Model):
    poll = models.ForeignKey(OpinionPoll, on_delete=models.CASCADE)
    person_name = models.CharField(max_length=50)
    response = models.TextField()

With this example, you'd use OpinionPoll.objects.with_counts() to return that list of OpinionPoll objects with num_responses attributes.

Another thing to note about this example is that Manager methods can access self.model to get the model class to which they're attached.

Modifying a manager's initial QuerySet

A Manager’s base QuerySet returns all objects in the system. For example, using this model:

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)

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

You can override a Manager’s base QuerySet by overriding the Manager.get_queryset() method. get_queryset() should return a QuerySet with the properties you require.

For example, the following model has two Managers -- one that returns all objects, and one that returns only the books by Roald Dahl:

# First, define the Manager subclass.
class DahlBookManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(author='Roald Dahl')

# Then hook it into the Book model explicitly.
class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)

    objects = models.Manager() # The default manager.
    dahl_objects = DahlBookManager() # The Dahl-specific manager.

With this sample model, Book.objects.all() will return all books in the database, but Book.dahl_objects.all() will only return the ones written by Roald Dahl.

Of course, because get_queryset() returns a QuerySet object, you can use filter(), exclude() and all the other QuerySet methods on it. So these statements are all legal:


This example also pointed out another interesting technique: using multiple managers on the same model. You can attach as many Manager() instances to a model as you'd like. This is an easy way to define common "filters" for your models.


class AuthorManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(role='A')

class EditorManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(role='E')

class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    role = models.CharField(max_length=1, choices=(('A', _('Author')), ('E', _('Editor'))))
    people = models.Manager()
    authors = AuthorManager()
    editors = EditorManager()

This example allows you to request Person.authors.all(), Person.editors.all(), and Person.people.all(), yielding predictable results.

Default managers


If you use custom Manager objects, take note that the first Manager Django encounters (in the order in which they're defined in the model) has a special status. Django interprets the first Manager defined in a class as the "default" Manager, and several parts of Django (including dumpdata) will use that Manager exclusively for that model. As a result, it's a good idea to be careful in your choice of default manager in order to avoid a situation where overriding get_queryset() results in an inability to retrieve objects you'd like to work with.

You can specify a custom default manager using Meta.default_manager_name.

If you're writing some code that must handle an unknown model, for example, in a third-party app that implements a generic view, use this manager (or _base_manager) rather than assuming the model has an objects manager.

Base managers


Don't filter away any results in this type of manager subclass

This manager is used to access objects that are related to from some other model. In those situations, Django has to be able to see all the objects for the model it is fetching, so that anything which is referred to can be retrieved.

If you override the get_queryset() method and filter out any rows, Django will return incorrect results. Don't do that. A manager that filters results in get_queryset() is not appropriate for use as a base manager.

Calling custom QuerySet methods from the manager

While most methods from the standard QuerySet are accessible directly from the Manager, this is only the case for the extra methods defined on a custom QuerySet if you also implement them on the Manager:

class PersonQuerySet(models.QuerySet):
    def authors(self):
        return self.filter(role='A')

    def editors(self):
        return self.filter(role='E')

class PersonManager(models.Manager):
    def get_queryset(self):
        return PersonQuerySet(self.model, using=self._db)

    def authors(self):
        return self.get_queryset().authors()

    def editors(self):
        return self.get_queryset().editors()

class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    role = models.CharField(max_length=1, choices=(('A', _('Author')), ('E', _('Editor'))))
    people = PersonManager()

This example allows you to call both authors() and editors() directly from the manager Person.people.

Creating a manager with QuerySet methods

In lieu of the above approach which requires duplicating methods on both the QuerySet and the Manager, QuerySet.as_manager() can be used to create an instance of Manager with a copy of a custom QuerySet’s methods:

class Person(models.Model):
    people = PersonQuerySet.as_manager()

The Manager instance created by QuerySet.as_manager() will be virtually identical to the PersonManager from the previous example.

Not every QuerySet method makes sense at the Manager level; for instance we intentionally prevent the QuerySet.delete() method from being copied onto the Manager class.

Methods are copied according to the following rules:

  • Public 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.


class CustomQuerySet(models.QuerySet):
    # Available on both Manager and QuerySet.
    def public_method(self):

    # Available only on QuerySet.
    def _private_method(self):

    # Available only on QuerySet.
    def opted_out_public_method(self):
    opted_out_public_method.queryset_only = True

    # Available on both Manager and QuerySet.
    def _opted_in_private_method(self):
    _opted_in_private_method.queryset_only = False


classmethod from_queryset(queryset_class)

For advanced usage you might want both a custom Manager and a custom QuerySet. You can do that by calling Manager.from_queryset() which returns a subclass of your base Manager with a copy of the custom QuerySet methods:

class BaseManager(models.Manager):
    def manager_only_method(self):

class CustomQuerySet(models.QuerySet):
    def manager_and_queryset_method(self):

class MyModel(models.Model):
    objects = BaseManager.from_queryset(CustomQuerySet)()


CustomManager = BaseManager.from_queryset(CustomQuerySet)

class MyModel(models.Model):
    objects = CustomManager()


下面是Django如何处理自定义管理器和 model inheritance

  1. 基类的管理者总是由子类继承,使用Python的正常名称解析顺序(子类上的名称覆盖所有其他类;然后在第一个父类上命名)等等。
  2. 如果没有在模型和/或其父母上宣布管理人员,Django就会自动创建``objects``管理器。
  3. 类上的默认管理器要么是使用:attr:Meta.default_manager_name <django.db.models.Options.default_manager_name>,要么是在模型上声明的第一个管理器,或者是第一个父模型的默认管理器。


class AbstractBase(models.Model):
    # ...
    objects = CustomManager()

    class Meta:
        abstract = True

如果您在子类中直接使用这一点,如果您在基类中没有声明任何管理器,那么 objects 将是默认的管理器:

class ChildA(AbstractBase):
    # ...
    # This class has CustomManager as the default manager.


class ChildB(AbstractBase):
    # ...
    # An explicit default manager.
    default_manager = OtherManager()

在这里,default_manager``是默认的。 ``objects 管理器仍然可用,因为它是继承的。它只是没有被用作默认值。


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 中添加了什么特性,都必须能够对 Manager 实例进行简单的复制;也就是说,以下代码必须有效:

>>> import copy
>>> manager = MyManager()
>>> my_copy = copy.copy(manager)


This won't be an issue for most custom managers. If you are just adding simple methods to your Manager, it is unlikely that you will inadvertently make instances of your Manager uncopyable. However, if you're overriding __getattr__ or some other private method of your Manager object that controls object state, you should ensure that you don't affect the ability of your Manager to be copied.