Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #17528 -- Documented that add() and remove() with a many-to-man…

…y relationship do not call Model.save()
  • Loading branch information...
commit 3cdeb572d73fca3d7966318c760f61ba73e5ad5f 1 parent d1d09fe
Tim Graham authored July 12, 2013

Showing 1 changed file with 16 additions and 0 deletions. Show diff stats Hide diff stats

  1. 16  docs/ref/models/relations.txt
16  docs/ref/models/relations.txt
@@ -48,6 +48,14 @@ Related objects reference
48 48
             >>> e = Entry.objects.get(id=234)
49 49
             >>> b.entry_set.add(e) # Associates Entry e with Blog b.
50 50
 
  51
+        In the example above, ``e.save()`` is called to perform the update.
  52
+        Using ``add()`` with a many-to-many relationship, however, will not
  53
+        call any ``save()`` methods, but rather create the relationships
  54
+        using :meth:`QuerySet.bulk_create()
  55
+        <django.db.models.query.QuerySet.bulk_create>`. If you need to execute
  56
+        some custom logic when a relationship is created, listen to the
  57
+        :data:`~django.db.models.signals.m2m_changed` signal.
  58
+
51 59
     .. method:: create(**kwargs)
52 60
 
53 61
         Creates a new object, saves it and puts it in the related object set.
@@ -86,6 +94,14 @@ Related objects reference
86 94
             >>> e = Entry.objects.get(id=234)
87 95
             >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
88 96
 
  97
+        Similar to :meth:`add()`, ``e.save()`` is called in the example above
  98
+        to perform the update. Using ``remove()`` with a many-to-many
  99
+        relationship, however, will delete the relationships using
  100
+        :meth:`QuerySet.delete()<django.db.models.query.QuerySet.delete>` which
  101
+        means no model ``save()`` methods are called; listen to the
  102
+        :data:`~django.db.models.signals.m2m_changed` signal if you wish to
  103
+        execute custom code when a relationship is deleted.
  104
+
89 105
         For :class:`~django.db.models.ForeignKey` objects, this method only
90 106
         exists if ``null=True``. If the related field can't be set to ``None``
91 107
         (``NULL``), then an object can't be removed from a relation without

0 notes on commit 3cdeb57

Please sign in to comment.
Something went wrong with that request. Please try again.