[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
This commit is contained in:
Tim Graham 2013-07-12 06:19:16 -04:00
parent 80a7dd6f7f
commit 61c8c1b6dc
1 changed files with 16 additions and 0 deletions

View File

@ -44,6 +44,14 @@ Related objects reference
>>> e = Entry.objects.get(id=234) >>> e = Entry.objects.get(id=234)
>>> b.entry_set.add(e) # Associates Entry e with Blog b. >>> 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()
<django.db.models.query.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) .. method:: create(**kwargs)
Creates a new object, saves it and puts it in the related object set. 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) >>> e = Entry.objects.get(id=234)
>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. >>> 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()<django.db.models.query.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 For :class:`~django.db.models.ForeignKey` objects, this method only
exists if ``null=True``. If the related field can't be set to ``None`` 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 (``NULL``), then an object can't be removed from a relation without