Django 4.0.6 ドキュメント

Home | Table of contents | Index | Modules

« previous | up | next »

マネージャ

class Manager

マネージャ (Manager) とは、Django のモデルに対するデータベースクエリの操作を提供するインターフェイスです。Django アプリケーション内の1つのモデルに対して、Manager は最低でも1つは存在します。

Manager クラスの詳細については、クエリを作成する に書かれています。ここでは、特に、Manager の動作をカスタマイズするモデルのオプションについて説明しています。

マネージャの名前

デフォルトでは、Django は objects という名前の Manager を各 Django モデルクラスに対して追加します。しかし、もし objects をフィールド名として使いたい場合や、あるいは、Manager に対して objects 以外の名前を使いたい場合には、各モデル単位で好きな名前を付けることができます。あるクラスの Manager の名前を変えるには、そのクラスの上で models.Manager() と書いて、クラス変数を定義します。たとえば、次のように書きます。

from django.db import models

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

このモデル例を使うと、Person.objects は AttributeError 例外を起こしますが、Person.people.all() と書けば、すべての Person オブジェクトのリストが得られます。

マネージャのカスタマイズ

Manager ベースクラスを拡張し、カスタマイズした Manager をモデル内でインスタンス化すれば、特定のモデル用にカスタマイズした Manager を使うことができます。

Manager をカスタマイズしたくなるシチュエーションとしては、たとえば次の2つのような場合が考えられます。1つ目は、Manager に新しいメソッドを追加したい場合、もう1つは、Manager が最初に返す QuerySet を修正したい場合です。

マネージャに新しいメソッドを追加する

Manager に新しいメソッドを追加するのがふさわしいのは、モデルに対する「テーブルレベル」での操作を追加したい場合です。(「低レベル」の機能、たとえば、あるモデルオブジェクトの1つのインスタンスに作用するような関数の場合には、Manager をカスタマイズするのではなく、モデルメソッド を使ってください。

For example, this custom Manager adds a method with_counts():

from django.db import models
from django.db.models.functions import Coalesce

class PollManager(models.Manager):
    def with_counts(self):
        return self.annotate(
            num_responses=Coalesce(models.Count("response"), 0)
        )

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

class Response(models.Model):
    poll = models.ForeignKey(OpinionPoll, on_delete=models.CASCADE)
    # ...

With this example, you'd use OpinionPoll.objects.with_counts() to get a QuerySet of OpinionPoll objects with the extra num_responses attribute attached.

Manager のカスタマイズメソッドは、どんなオブジェクトを返しても構いませんが、QuerySet だけは返してはいけません。

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

マネージャが初めに返す 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)

Book.objects.all() は、データベース内の全ての本を返します。

Manager.get_queryset() メソッドをオーバーライドすることで、 Manager のベース``QuerySet`` を上書きできます。 get_queryset() は、必要な属性を含む QuerySet を返す必要があります。

例えば、次のモデルには*2つ*の``Manager``があります。片方はすべてのオブジェクトを返し、もう片方は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.

このモデルの例では、 Book.objects.all() はデータベース上の本を全て返 しますが、 Book.dahl_objects.all() は Roald Dahl の書いた本だけを返しま す。

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:

Book.dahl_objects.all()
Book.dahl_objects.filter(title='Matilda')
Book.dahl_objects.count()

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 a non-repetitive 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

Model._default_manager

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

Model._base_manager

Using managers for related object access

By default, Django uses an instance of the Model._base_manager manager class when accessing related objects (i.e. choice.question), not the _default_manager on the related object. This is because Django needs to be able to retrieve the related object, even if it would otherwise be filtered out (and hence be inaccessible) by the default manager.

If the normal base manager class (django.db.models.Manager) isn't appropriate for your circumstances, you can tell Django which class to use by setting Meta.base_manager_name.

Base managers aren't used when querying on related models, or when accessing a one-to-many or many-to-many relationship. For example, if the Question model from the tutorial had a deleted field and a base manager that filters out instances with deleted=True, a queryset like Choice.objects.filter(question__name__startswith='What') would include choices related to deleted questions.

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.

Therefore, you should not override get_queryset() to filter out any rows. If you do so, Django will return incomplete results.

カスタマイズした``QuerySet``のメソッド をマネージャから呼び出す

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.

QuerySet のメソッドで、マネージャを生成する

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):
        return

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

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

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

from_queryset()

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 CustomManager(models.Manager):
    def manager_only_method(self):
        return

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

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

You may also store the generated class into a variable:

MyManager = CustomManager.from_queryset(CustomQuerySet)

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

Custom managers and model inheritance

Here's how Django handles custom managers and model inheritance:

1. Managers from base classes are always inherited by the child 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).
2. If no managers are declared on a model and/or its parents, Django automatically creates the objects manager.
3. The default manager on a class is either the one chosen with Meta.default_manager_name, or the first manager declared on the model, or the default manager of the first parent model.

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 = CustomManager()

    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.
    pass

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, but 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.
    pass

Note that while you can define a custom manager on the abstract model, you can't invoke any methods using the abstract model. That is:

ClassA.objects.do_something()

is legal, but:

AbstractBase.objects.do_something()

will raise an exception. This is because managers are intended to encapsulate logic for managing collections of objects. Since you can't have a collection of abstract objects, it doesn't make sense to be managing them. If you have functionality that applies to the abstract model, you should put that functionality in a staticmethod or classmethod on the abstract model.

Implementation concerns

Whatever features you add to your custom Manager, it must be possible to make a shallow copy of a Manager instance; i.e., the following code must work:

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

Django makes shallow copies of manager objects during certain queries; if your Manager cannot be copied, those queries will fail.

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.

Last update:

2022年6月01日

« previous | up | next »