Spec-Zone.ru › Django 5.1

Менеджеры

class Manager [source]

Интерфейс Manager, через который предоставляются операции запроса к базе данных для моделей Django. Для каждой модели в приложении Django существует хотя бы один Manager.

Работа с классами Manager документирована в Создание запросов; этот документ подробно рассматривает параметры моделей, которые настраивают поведение Manager.

Имена менеджеров

По умолчанию Django добавляет менеджер с именем objects к каждому классу модели Django. Однако, если вы хотите использовать objects в качестве имени поля или хотите использовать имя, отличное от objects для Manager, вы можете переименовать его на уровне каждой модели. Чтобы переименовать менеджер для данного класса, определите атрибут класса типа models.Manager() в модели. Например:

from django.db import models


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

Используя эту модель, Person.objects сгенерирует исключение AttributeError, но Person.people.all() предоставит список всех объектов Person.

Пользовательские менеджеры

Вы можете использовать пользовательский менеджер в конкретной модели, расширив базовый класс менеджера и инициализировав свой пользовательский менеджер в вашей модели.

Есть две причины, по которым вам может потребоваться настройка менеджера: добавление дополнительных методов менеджера и/или изменение начального QuerySet объекта, возвращаемого менеджером.

Добавление дополнительных методов менеджера

Добавление дополнительных методов менеджера — это предпочтительный способ добавления функциональности на уровне таблицы в ваши модели. (Для функциональности на уровне строки — функций, которые действуют на единственный экземпляр объекта модели — используйте Методы модели, а не пользовательские методы менеджера.)

Например, этот пользовательский менеджер добавляет метод 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)
    # ...

В этом примере вы бы использовали OpinionPoll.objects.with_counts() для получения набора объектов OpinionPoll с дополнительным атрибутом num_responses.

Метод пользовательского менеджера может возвращать что угодно. Он не обязан возвращать QuerySet.

Следует также отметить, что методы пользовательского менеджера могут получить доступ к self.model для получения класса модели, к которому они прикреплены.

Изменение начального набора результатов менеджера

Базовый менеджер Manager возвращает все объекты в системе. Например, используя эту модель:

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(). get_queryset() должен возвращать QuerySet с требуемыми свойствами.

Например, у следующей модели две Manager — одна возвращает все объекты, а другая — только книги Роальда Даля:

# 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() вернет только написанные Роальдом Далем.

Поскольку get_queryset() возвращает объект набора результатов, вы можете использовать filter(), exclude() и все остальные методы набора результатов над ним. Следовательно, эти операторы допустимы:

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

Этот пример также продемонстрировал другую интересную технику: использование нескольких менеджеров для одной и той же модели. Вы можете присоединить любое количество экземпляров менеджера к модели. Это не повторяющийся способ определения общих «фильтров» для ваших моделей.

Например:

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

Этот пример позволяет запросить Person.authors.all(), Person.editors.all(), и Person.people.all(), обеспечивая предсказуемые результаты.

Менеджеры по умолчанию

Model._default_manager

Если вы используете пользовательские объекты менеджера, обратите внимание, что первый менеджер, который встречает Django (в порядке их определения в модели), имеет особый статус. Django интерпретирует первый определенный менеджер в классе как «по умолчанию» и несколько частей Django (включая dumpdata) будут использовать этот менеджер исключительно для этой модели. В результате, следует быть осторожным в выборе менеджера по умолчанию, чтобы избежать ситуации, когда переопределение get_queryset() приводит к невозможности получить доступ к нужным объектам.

Вы можете указать пользовательский менеджер по умолчанию с помощью Meta.default_manager_name.

Если вы пишете код, который должен обрабатывать неизвестную модель, например, в стороннем приложении, реализующем общий вид, используйте этот менеджер (или _base_manager), а не предполагайте, что у модели есть менеджер по умолчанию.

Базовые менеджеры

Model._base_manager

Использование менеджеров для доступа к связанным объектам

По умолчанию Django использует экземпляр класса менеджера Model._base_manager при доступе к связанным объектам (т. е. choice.question), а не _default_manager связанного объекта. Это необходимо, чтобы Django мог получить связанный объект, даже если бы он в противном случае был отфильтрован (и, следовательно, был недоступен) менеджером по умолчанию.

Если обычный базовый класс менеджера (django.db.models.Manager) не подходит для вашей ситуации, вы можете указать Django, какой класс использовать, установив Meta.base_manager_name.

Базовые менеджеры не используются при запросе связанных моделей или при доступе к отношению один-ко-многим или многие-ко-многим. Например, если модель Question из учебника имела поле deleted и базовый менеджер, который фильтровал экземпляры с deleted=True, запрос Choice.objects.filter(question__name__startswith='What') включал бы связанные варианты удаленных вопросов.

Не удаляйте результаты в подклассе менеджера

Этот менеджер используется для доступа к объектам, связанным с другой моделью. В таких случаях Django должен видеть все объекты модели, которую он получает, чтобы можно было получить любой объект, на который есть ссылка.

Следовательно, вы не должны переопределять get_queryset() для фильтрации строк. В противном случае Django вернет неполные результаты.

Вызов пользовательских методов набора результатов из менеджера

Хотя большинство методов стандартного набора результатов доступны напрямую из менеджера, это верно только для дополнительных методов, определенных в пользовательском менеджере, если вы также реализуете их в наборе результатов:

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

Этот пример позволяет вызывать как authors(), так и editors() напрямую из менеджера Person.people.

Создание менеджера с методами набора результатов

Вместо вышеупомянутого подхода, требующего дублирования методов как в менеджере, так и в наборе результатов, QuerySet.as_manager() можно использовать для создания экземпляра менеджера с копией методов пользовательского набора результатов:

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

Экземпляр менеджера, созданный с помощью QuerySet.as_manager(), будет практически идентичен PersonManager из предыдущего примера.

Не каждый метод набора результатов имеет смысл на уровне менеджера; например, мы намеренно не позволяем методу QuerySet.delete() копироваться в класс менеджера.

Методы копируются по следующим правилам:

  • Методы общего доступа копируются по умолчанию.
  • Методы, начинающиеся с подчеркивания, не копируются по умолчанию.
  • Методы с атрибутом queryset_only установленным в False всегда копируются.
  • Методы с атрибутом queryset_only установленным в True никогда не копируются.

Например:

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)

Для продвинутого использования вам может потребоваться как пользовательский менеджер, так и пользовательский набор результатов. Вы можете сделать это, вызвав Manager.from_queryset(), что вернёт подкласс вашего базового менеджера с копией методов пользовательского набора результатов:

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

Вы также можете сохранить сгенерированный класс в переменную:

MyManager = CustomManager.from_queryset(CustomQuerySet)


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

Пользовательские менеджеры и наследование моделей

Вот как Django обрабатывает пользовательские менеджеры и наследование моделей:

  1. Менеджеры из базовых классов всегда наследуются дочерним классом, используя стандартный порядок разрешения имен Python (имена в дочернем классе переопределяют все другие; затем следуют имена в первом родительском классе и так далее).
  2. Если менеджеры не объявлены в модели и/или её родителях, Django автоматически создаёт менеджер objects.
  3. По умолчанию менеджер класса выбирается с помощью Meta.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.
    pass

Если вы хотите унаследовать от AbstractBase, но предоставить другой менеджер по умолчанию, вы можете указать менеджер по умолчанию в дочернем классе:

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

Здесь, default_manager является менеджером по умолчанию. Менеджер objects всё ещё доступен, поскольку он унаследован, но не используется как менеджер по умолчанию.

Наконец, для этого примера, предположим, что вы хотите добавить дополнительные менеджеры в дочерний класс, но всё ещё использовать менеджер по умолчанию из AbstractBase. Вы не можете добавить новый менеджер непосредственно в дочерний класс, так как это переопределит менеджер по умолчанию, и вам нужно будет явно включить все менеджеры из абстрактного базового класса. Решением является размещение дополнительных менеджеров в другом базовом классе и добавление его в иерархию наследования *после* менеджеров по умолчанию:

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

Обратите внимание, что, хотя вы можете *определить* пользовательский менеджер в абстрактной модели, вы не можете *вызвать* какие-либо методы, используя абстрактную модель. То есть:

ClassA.objects.do_something()

является законным, но:

AbstractBase.objects.do_something()

вызовет исключение. Это потому, что менеджеры предназначены для инкапсуляции логики управления коллекциями объектов. Поскольку у вас не может быть коллекции абстрактных объектов, нет смысла управлять ими. Если у вас есть функциональность, которая относится к абстрактной модели, вы должны поместить эту функциональность в staticmethod или classmethod в абстрактной модели.

Вопросы реализации

Какие бы функции вы ни добавили в свой пользовательский Manager, необходимо, чтобы была возможна создание поверхностной копии экземпляра Manager; т.е. следующий код должен работать:

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

Django создаёт поверхностные копии объектов менеджеров во время определённых запросов; если ваш менеджер не может быть скопирован, эти запросы завершатся ошибкой.

Это не будет проблемой для большинства пользовательских менеджеров. Если вы просто добавляете простые методы в свой Manager, маловероятно, что вы непреднамеренно сделаете экземпляры вашего Manager некопируемыми. Однако, если вы переопределяете __getattr__ или какой-либо другой закрытый метод вашего объекта Manager, который контролирует состояние объекта, вы должны убедиться, что не повлияете на возможность копирования вашего объекта %%%CODE_BLOCK_143%%.

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/5.1/topics/db/managers/

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API