From 61c8c1b6dcd267a7d4777ff3b0a78eaedb9b95d3 Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Fri, 12 Jul 2013 06:19:16 -0400 Subject: [PATCH] [1.5.x] Fixed #17528 -- Documented that add() and remove() with a many-to-many relationship do not call Model.save() Backport of 3cdeb572d7 from master --- docs/ref/models/relations.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index c923961a194..c693f5fd9a6 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -44,6 +44,14 @@ Related objects reference >>> e = Entry.objects.get(id=234) >>> b.entry_set.add(e) # Associates Entry e with Blog b. + In the example above, ``e.save()`` is called to perform the update. + Using ``add()`` with a many-to-many relationship, however, will not + call any ``save()`` methods, but rather create the relationships + using :meth:`QuerySet.bulk_create() + `. If you need to execute + some custom logic when a relationship is created, listen to the + :data:`~django.db.models.signals.m2m_changed` signal. + .. method:: create(**kwargs) Creates a new object, saves it and puts it in the related object set. @@ -82,6 +90,14 @@ Related objects reference >>> e = Entry.objects.get(id=234) >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. + Similar to :meth:`add()`, ``e.save()`` is called in the example above + to perform the update. Using ``remove()`` with a many-to-many + relationship, however, will delete the relationships using + :meth:`QuerySet.delete()` which + means no model ``save()`` methods are called; listen to the + :data:`~django.db.models.signals.m2m_changed` signal if you wish to + execute custom code when a relationship is deleted. + For :class:`~django.db.models.ForeignKey` objects, this method only exists if ``null=True``. If the related field can't be set to ``None`` (``NULL``), then an object can't be removed from a relation without