Un gestionnaire (objet Manager) est l’interface par laquelle les opérations de requêtes de base de données sont mises à disposition des modèles Django. Il existe au moins un Manager pour chaque modèle d’une application Django.
Le fonctionnement des classes Manager est documenté dans Création de requêtes; ce document aborde spécifiquement les options de modèles qui personnalisent le comportement des gestionnaires.
Par défaut, Django ajoute un gestionnaire nommé objects à chaque classe de modèle Django. Cependant, si vous aimeriez utiliser objects comme nom de champ ou que vous aimeriez nommer le gestionnaire autrement que objects, vous pouvez le renommer au niveau du modèle. Pour renommer le gestionnaire d’une classe donnée, définissez un attribut de classe de type models.Manager() dans le modèle. Par exemple :
from django.db import models\n\nclass Person(models.Model):\n #...\n people = models.Manager()\nEn utilisant cet exemple de modèle, Person.objects générera une exception AttributeError, mais Person.people.all() fournira effectivement la liste de tous les objets Person.
Vous pouvez utiliser un gestionnaire personnalisé dans un modèle particulier en étendant la classe Manager de base et en créant votre propre instance de Manager dans votre modèle.
Il y a deux raisons de vouloir personnaliser un gestionnaire : pour lui ajouter des méthodes supplémentaires ou pour modifier l’objet QuerySet initial que le gestionnaire renvoie.
L’ajout de méthodes de gestionnaire supplémentaires est la façon privilégiée d’ajouter des fonctionnalités au « niveau table » à des modèles (pour les fonctionnalités au « niveau ligne », c’est-à-dire les fonctions qui agissent sur une seule instance d’un objet de modèle, utilisez les méthodes de modèles et non pas des méthodes de gestionnaire personnalisées).
\nUne méthode de gestionnaire personnalisée peut renvoyer tout ce qu’on veut, elle n’est pas tenue de renvoyer un objet QuerySet.
Par exemple, cette méthode de gestionnaire personnalisée offre une méthode with_counts() qui renvoie une liste de tous les objets OpinionPoll, chacun recevant un attribut supplémentaire num_responses qui est le résultat d’une requête d’agrégation :
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, on_delete=models.CASCADE)\n person_name = models.CharField(max_length=50)\n response = models.TextField()\nAvec cet exemple, vous écririez OpinionPoll.objects.with_counts() pour obtenir la liste des objets OpinionPoll comportant l’attribut num_responses.
Une autre chose à relever au sujet de cet exemple est que les méthodes de gestionnaire ont accès à self.model pour obtenir la classe de modèle à laquelle elles sont liées.
QuerySet initiaux des gestionnairesLien vers cette rubrique#Le QuerySet de base d’un gestionnaire renvoie tous les objets du système. Par exemple, en utilisant ce modèle :
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…l’instruction Book.objects.all() renvoie tous les livres de la base de données.
Vous pouvez surcharger le QuerySet de base d’un gestionnaire en surchargeant la méthode Manager.get_queryset(). get_queryset() doit renvoyer un objet QuerySet doté des propriétés nécessaires.
Par exemple, le modèle suivant possède deux gestionnaires, un qui renvoie tous les objets et un autre qui ne renvoie que les livres de Roald Dahl :
\n# 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.\nAvec cet exemple de modèle, Book.objects.all() renvoie tous les livres de la base de données, mais Book.dahl_objects.all() ne retourne que ceux qui ont été écrits par Roald Dahl.
Naturellement, comme get_queryset() renvoie un objet QuerySet, vous pouvez appliquer filter(), exclude() et toutes les autres méthodes de QuerySet. Ainsi, ces instructions sont toutes valables :
Book.dahl_objects.all()\nBook.dahl_objects.filter(title='Matilda')\nBook.dahl_objects.count()\nCet exemple a aussi mis en évidence une autre technique intéressante : l’emploi de plusieurs gestionnaires dans un même modèle. Vous pouvez lier autant d’instances de gestionnaires que vous voulez à un modèle. C’est une manière simple de définir des « filtres » fréquemment utilisés dans des modèles.
\nPar exemple :
\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()\nCet exemple permet d’effectuer les requêtes Person.authors.all(), Person.editors.all() et Person.people.all() en sachant à quoi vous attendre au niveau des résultats.
Si vous utilisez des objets Manager personnalisés, sachez que le premier Manager que Django rencontre (dans l’ordre où ils ont été définis dans le modèle) reçoit un statut spécial. Django interprète le premier gestionnaire défini dans une classe comme le gestionnaire par défaut, et plusieurs parties de Django (y compris dumpdata) utilisent exclusivement ce gestionnaire pour le modèle en question. En conséquence, il est conseillé de choisir avec prudence le gestionnaire par défaut afin d’éviter une situation où la surcharge de get_queryset() aboutit à l’incapacité de récupérer des objets avec lesquels vous avez besoin de travailler.
QuerySet depuis le gestionnaireLien vers cette rubrique#Alors que la plupart des méthodes d’un QuerySet standard sont directement accessibles à partir d’un Manager, ce n’est le cas pour les méthodes supplémentaires définies sur un QuerySet personnalisé que si vous les implémentez également sur le 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()\nCet exemple permet d’appeler authors() et editors() directement depuis le gestionnaire Person.people.
Manager avec des méthodes de QuerySetLien vers cette rubrique#En lieu et place de l’approche ci-dessus qui nécessite de dupliquer les méthodes à la fois sur les objets QuerySet et Manager, QuerySet.as_manager() peut être utilisé pour créer une instance de Manager avec une copie des méthodes d’un objet QuerySet personnalisé :
class Person(models.Model):\n ...\n people = PersonQuerySet.as_manager()\nL’instance de Manager créée par QuerySet.as_manager() sera pratiquement identique au PersonManager de l’exemple précédent.
Toutes les méthodes QuerySet n’ont pas forcément de sens au niveau Manager; par exemple, nous empêchons volontairement la méthode QuerySet.delete() d’être copiée vers la classe Manager.
Les méthodes sont copiées selon les règles suivantes :
\nLes méthodes publiques sont copiées par défaut.
Les méthodes privées (commençant par un soulignement) ne sont pas copiées par défaut.
Les méthodes avec un attribut queryset_only à False sont toujours copiées.
Les méthodes avec un attribut queryset_only à True ne sont jamais copiées.
Par exemple :
\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\nfrom_queryset()Lien vers cette rubrique#Pour une utilisation plus avancée, il peut être souhaitable d’avoir à la fois un Manager personnalisé et un QuerySet personnalisé. Vous pouvez le faire en appelant Manager.from_queryset() qui renvoie une sous-classe du Manager de base avec une copie des méthodes QuerySet personnalisées :
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)()\nVous pouvez également stocker la classe générée dans une variable :
\nCustomManager = BaseManager.from_queryset(CustomQuerySet)\n\nclass MyModel(models.Model):\n objects = CustomManager()\nL’héritage de classes et les gestionnaires de modèle ne font pas très bon ménage. Les gestionnaires sont souvent spécifiques aux classes dans lesquelles ils sont définis et leur héritage dans des sous-classes n’est pas forcément toujours une bonne idée. Et comme le premier gestionnaire défini devient le gestionnaire par défaut, il est important de pouvoir contrôler cet ordre de définition. Voici donc comment Django se comporte face aux gestionnaires personnalisés et à l’héritage de modèles:
\nLes gestionnaires définis dans les classes de base non abstraites ne sont pas hérités par les classes enfants. Si vous souhaitez réutiliser un gestionnaire d’une base non abstraite, il faut le redéclarer explicitement dans la classe enfant. Ce type de gestionnaire est généralement très spécifique à la classe dans laquelle il est défini, c’est pourquoi leur héritage pourrait produire des résultats inattendus (particulièrement lorsqu’il s’agit du gestionnaire par défaut). Ils ne sont donc pas transmis à leurs classes enfants.
Les gestionnaires des classes de base abstraites sont toujours hérités par les classes enfants, par le moyen Python habituel de l’ordre de résolution de nom (les noms des classes enfants surchargent ceux de leurs parents). Les classes de base abstraites sont conçues pour centraliser les informations et les comportements communs à leurs classes enfants. La définition de gestionnaires communs est un aspect entrant tout à fait dans ces informations communes.
Le gestionnaire par défaut d’une classe est soit le premier gestionnaire déclaré dans la classe, s’il y en a un, ou le gestionnaire par défaut de la première classe de base abstraite dans la hiérarchie d’héritage, le cas échéant. Si aucun gestionnaire par défaut n’est explicitement déclaré, c’est le gestionnaire par défaut habituel de Django qui est utilisé.
Ces règles assurent la souplesse nécessaire permettant d’installer un ensemble de gestionnaires personnalisés sur un groupe de modèles via une classe de base abstraite, tout en personnalisant aussi le gestionnaire par défaut. Prenons l’exemple de cette classe de base :
\nclass AbstractBase(models.Model):\n # ...\n objects = CustomManager()\n\n class Meta:\n abstract = True\nSi vous l’utilisez directement dans une sous-classe, objects sera le gestionnaire par défaut si aucun gestionnaire n’est déclaré dans la classe de base :
class ChildA(AbstractBase):\n # ...\n # This class has CustomManager as the default manager.\n pass\nSi vous voulez hériter de AbstractBase, mais avec un autre gestionnaire par défaut, vous pouvez définir le gestionnaire par défaut dans la classe enfant :
class ChildB(AbstractBase):\n # ...\n # An explicit default manager.\n default_manager = OtherManager()\nIci, default_manager est le gestionnaire par défaut. Le gestionnaire objects est toujours disponible, puisqu’il est hérité. Il n’est juste plus le gestionnaire par défaut.
Pour terminer avec cet exemple, supposons que vous vouliez ajouter des gestionnaires supplémentaires dans la classe enfant tout en conservant le gestionnaire par défaut de AbstractBase. Vous ne pouvez pas ajouter directement le nouveau gestionnaire dans la classe enfant, car cela surchargerait le gestionnaire par défaut et vous devriez aussi inclure explicitement tous les gestionnaires de la classe de base abstraite. La solution est de placer les gestionnaires supplémentaires dans une autre classe de base et introduire celle-ci dans la hiérarchie d’héritage après ceux par défaut :
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\nNotez que même si vous pouvez définir un gestionnaire personnalisé dans le modèle abstrait, vous ne pouvez appeler aucune de ses méthodes au travers du modèle abstrait. C’est-à-dire :
\nClassA.objects.do_something()\nest légal, mais :
\nAbstractBase.objects.do_something()\ngénérera une exception. C’est parce que les gestionnaires sont censés intégrer la logique de gestion d’ensembles d’objets. Comme il n’est pas possible d’avoir un ensemble d’objets abstraits, leur gestion n’a pas de sens. Si vous gérez des fonctionnalités s’appliquant au modèle abstrait, vous devriez les placer dans une méthode staticmethod ou classmethod du modèle abstrait.
Quelles que soient les fonctionnalités ajoutées à un gestionnaire personnalisé, il doit toujours être possible de faire une copie légère (« shallow ») d’une de ses instances ; c’est-à-dire que le code suivant doit fonctionner :
\n>>> import copy\n>>> manager = MyManager()\n>>> my_copy = copy.copy(manager)\nDjango effectue des copies légères des objets de gestionnaire durant certaines requêtes ; si votre gestionnaire ne peut pas être copié, ces requêtes échoueront.
\nCe ne sera pas un problème pour la plupart des gestionnaires personnalisés. Si vous ne faites qu’ajouter des méthodes simples à votre classe Manager, il est improbable que vous empêchiez la copie de votre gestionnaire sans le vouloir. Cependant, si vous surchargez __getattr__ ou d’autres méthodes privées de l’objet Manager qui contrôlent l’état de l’objet, il faut vous assurer que vous n’altériez pas la capacité de votre gestionnaire d’être copié.
Ce document a déjà mentionné quelques endroits où Django crée automatiquement une classe de gestionnaire : gestionnaires par défaut et le gestionnaire « de base » utilisé pour accéder aux objets liés. Il y a d’autres endroits dans l’implémentation de Django où des gestionnaires de base temporaires sont nécessaires. Ces gestionnaires automatiquement créés sont normalement des instances de la classe django.db.models.Manager.
Tout au long de cette section, nous utiliserons le terme « gestionnaire automatique » pour désigner les gestionnaires que Django crée pour vous, soit comme un gestionnaire par défaut d’un modèle sans gestionnaire ou pour un usage temporaire lors de l’accès à des objets liés.
\nCette classe par défaut n’est parfois pas le bon choix. Le gestionnaire par défaut peut ne pas disposer de toutes les méthodes nécessaires à la manipulation des données. Une classe de gestionnaire personnalisée selon vos besoins permet de créer des objets QuerySet personnalisés pour obtenir les informations dont vous avez besoin.
Django propose aux développeurs de gestionnaires personnalisés une manière d’indiquer que leur classe de gestionnaire doit être utilisée pour les gestionnaires automatiques chaque fois qu’ils deviennent le gestionnaire par défaut d’un modèle. Ceci se fait en définissant l’attribut use_for_related_fields dans la classe du gestionnaire :
class MyManager(models.Manager):\n use_for_related_fields = True\n # ...\nSi cet attribut est défini dans le gestionnaire par défaut d’un modèle (seul le gestionnaire par défaut est considéré dans ces situations), Django utilise cette classe chaque fois qu’il a besoin de créer automatiquement un gestionnaire pour la classe. Sinon, il utilise django.db.models.Manager.
La fonctionnalité use_for_related_fields est principalement axée sur les gestionnaires qui ont besoin de renvoyer une sous-classe de QuerySet personnalisée. Lorsque vous utilisez cette fonctionnalité dans un gestionnaire, il ne fait pas oublier certaines choses.
L’une des raisons pour lesquelles un gestionnaire automatique est utilisé est le besoin d’accéder aux objets liés à partir d’un autre modèle. Dans ces situations, Django doit être capable de voir tous les objets du modèle qu’il récupère, afin que tout ce qui est référencé puisse être récupéré.
\nSi vous surchargez la méthode get_queryset() et que vous excluez certaines lignes, Django renverra des résultats incorrects. Ne faites pas cela. Un gestionnaire excluant des résultats dans get_queryset() n’est pas approprié comme gestionnaire automatique.