Référence des objets liés¶
-
class
RelatedManager
¶ Un gestionnaire de liaison (« related manager ») est un gestionnaire utilisé dans un contexte de champ lié un-à-plusieurs ou plusieurs-à-plusieurs. Cela se produit dans deux cas :
Le « côté opposé » d’une relation
ForeignKey
. C’est-à-dire :from django.db import models class Reporter(models.Model): # ... pass class Article(models.Model): reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)
Dans l’exemple ci-dessus, les méthodes ci-dessous seront disponibles pour le gestionnaire
reporter.article_set
.Les deux côtés d’une relation
ManyToManyField
:class Topping(models.Model): # ... pass class Pizza(models.Model): toppings = models.ManyToManyField(Topping)
Dans cet exemple, les méthodes ci-dessous seront disponibles à la fois pour
topping.pizza_set
et pourpizza.toppings
.
-
add
(*objs, bulk=True)¶ Ajoute les objets modèles indiqués à l’ensemble des objets liés.
Exemple :
>>> b = Blog.objects.get(id=1) >>> e = Entry.objects.get(id=234) >>> b.entry_set.add(e) # Associates Entry e with Blog b.
Dans l’exemple ci-dessus, dans le cas d’une relation
ForeignKey
,QuerySet.update()
est utilisée pour effectuer la mise à jour. Ceci nécessite que les objets soient déjà enregistrés.Vous pouvez utiliser le paramètre
bulk=False
pour que la mise à jour soit effectuée plutôt par le gestionnaire de la relation en appelante.save()
.Cependant, l’emploi de
add()
avec une relation plusieurs-à-plusieurs n’appelle aucune méthodesave()
mais crée plutôt les relations en utilisantQuerySet.bulk_create()
. Si vous avez besoin de faire exécuter une certaine logique personnalisée lors de la création d’une relation, faites-le dans une fonction à l’écoute du signalm2m_changed
.Changed in Django 1.9:Le paramètre
bulk
a été ajouté. Dans les anciennes versions, les mises à jour de clé étrangère se faisaient toujours avecsave()
. Indiquezbulk=False
si vous avez besoin de l’ancien comportement.
-
create
(**kwargs)¶ Crée un nouvel objet, l’enregistre et le place dans l’ensemble des objets liés. Renvoie l’objet nouvellement créé :
>>> b = Blog.objects.get(id=1) >>> e = b.entry_set.create( ... headline='Hello', ... body_text='Hi', ... pub_date=datetime.date(2005, 1, 1) ... ) # No need to call e.save() at this point -- it's already been saved.
C’est équivalent à (mais beaucoup plus simple) :
>>> b = Blog.objects.get(id=1) >>> e = Entry( ... blog=b, ... headline='Hello', ... body_text='Hi', ... pub_date=datetime.date(2005, 1, 1) ... ) >>> e.save(force_insert=True)
Notez qu’il n’y a pas besoin de fournir le paramètre nommé du modèle qui définit la relation. Dans l’exemple ci-dessus, nous ne transmettons pas le paramètre
blog
àcreate()
. Django réalise lui-même que le champblog
du nouvel objetEntry
doit recevoir la valeurb
.
-
remove
(*objs)¶ Enlève les objets modèles indiqués de l’ensemble des objets liés :
>>> b = Blog.objects.get(id=1) >>> e = Entry.objects.get(id=234) >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
Comme avec
add()
, on appellee.save()
dans l’exemple ci-dessus pour effectuer la mise à jour. Cependant, l’emploi deremove()
avec une relation plusieurs-à-plusieurs supprime les relations avecQuerySet.delete()
, ce qui signifie qu’aucune méthodesave()
n’est appelée. Si vous avez besoin de faire exécuter du code personnalisé lors de la suppression d’une relation, faites-le dans une fonction à l’écoute du signalm2m_changed
.Pour les objets
ForeignKey
, cette méthode existe seulement quandnull=True
. Si le champ lié ne peut pas recevoir la valeurNone
(NULL
), alors un objet ne peut pas être enlevé d’une relation sans être ajouté à une autre. Dans l’exemple ci-dessus, enlevere
deb.entry_set()
est l’équivalent de la définitione.blog = None
, et comme la cléForeignKey
blog
n’a pas l’optionnull=True
, ce n’est pas valide.Pour les objets
ForeignKey
, cette méthode accepte un paramètrebulk
pour contrôler comment effectuer l’opération. AvecTrue
(valeur par défaut), c’estQuerySet.update()
qui est utilisé. Avecbulk=False
, c’est plutôt la méthodesave()
de chaque instance de modèle individuelle qui est appelée. Cela déclenche les signauxpre_save
etpost_save
au détriment d’une perte de performance.
-
clear
()¶ Enlève tous les objets de l’ensemble des objets liés :
>>> b = Blog.objects.get(id=1) >>> b.entry_set.clear()
Notez que cela ne supprime pas les objets liés, il ne fait que les dissocier.
Tout comme
remove()
,clear()
n’est disponible pour un champForeignKey
que lorsquenull=True
et il accepte également le paramètre nommébulk
.
-
set
(objs, bulk=True, clear=False)¶ - New in Django 1.9.
Remplace l’ensemble des objets liés :
>>> new_list = [obj1, obj2, obj3] >>> e.related_set.set(new_list)
Cette méthode accepte un paramètre
clear
pour contrôler le fonctionnement de l’opération. SiFalse
(par défaut), les éléments manquants dans le nouvel ensemble sont supprimés avecremove()
et seuls les nouveaux sont ajoutés. Siclear=True
, la méthodeclear()
est appelée à la place et l’ensemble est ajouté en une seule fois.Le paramètre
bulk
est transmis àadd()
.Notez que dans la mesure où
set()
est une opération composée, elle est sujette aux situations de concurrence. Par exemple, de nouveaux objets pourraient être ajoutés à la base de données entre l’appelclear()
et l’appeladd()
.
Note
Notez que
add()
,create()
,remove()
,clear()
etset()
appliquent tous immédiatement les modifications de base de données pour tous les types de champs de relation. En d’autres termes, il n’est pas nécessaire d’appelersave()
ni d’un côté de la relation, ni de l’autre.De même, si vous utilisez un modèle intermédiaire pour une relation plusieurs-à-plusieurs, les méthodes
add()
,create()
,remove()
etset()
sont désactivées.
Attribution directe¶
Un ensemble d’objets liés peut être remplacé en vrac en une seule opération en attribuant un nouvel ensemble d’objets itérable :
>>> new_list = [obj1, obj2, obj3]
>>> e.related_set = new_list
Si la relation de clé étrangère possède null=True
, le gestionnaire de la relation efface premièrement toute liaison avec des objets existants avant d’ajouter le contenu de new_list
. Sinon, les objets de new_list
seraient ajoutés à l’ensemble existant d’objets liés.
Dans les versions antérieures, l’affectation directe procédait à une opération d’effacement clear()
suivie d’une opération add()
. Dorénavant, elle appelle set()
avec le paramètre nommé clear=False
.
Obsolète depuis la version 1.10: L’attribution directe est obsolète et remplacée par la méthode set()
:
>>> e.related_set.set([obj1, obj2, obj3])
Cela évite de la confusion concernant l’enregistrement implicite provoqué par l’attribution directe.