From d508326e2f7d35973e2662109e34b425cb108b81 Mon Sep 17 00:00:00 2001 From: bphillips Date: Wed, 25 Nov 2015 11:25:21 -0500 Subject: [PATCH] Fixed #25672 -- Clarified why related ManyToManyFields with a custom intermediate model disable the remove() method. --- docs/topics/db/models.txt | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 28bbf89aa5..bb41dc6f6f 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -513,11 +513,11 @@ the intermediate model:: Unlike normal many-to-many fields, you *can't* use ``add()``, ``create()``, or ``set()`` to create relationships:: - # THIS WILL NOT WORK + >>> # THIS WILL NOT WORK >>> beatles.members.add(john) - # NEITHER WILL THIS + >>> # NEITHER WILL THIS >>> beatles.members.create(name="George Harrison") - # AND NEITHER WILL THIS + >>> # AND NEITHER WILL THIS >>> beatles.members.set([john, paul, ringo, george]) Why? You can't just create a relationship between a ``Person`` and a ``Group`` @@ -529,9 +529,21 @@ The only way to create this type of relationship is to create instances of the intermediate model. The :meth:`~django.db.models.fields.related.RelatedManager.remove` method is -disabled for similar reasons. However, the -:meth:`~django.db.models.fields.related.RelatedManager.clear` method can be -used to remove all many-to-many relationships for an instance:: +disabled for similar reasons. For example, if the custom through table defined +by the intermediate model does not enforce uniqueness on the +``(model1, model2)`` pair, a ``remove()`` call would not provide enough +information as to which intermediate model instance should be deleted:: + + >>> Membership.objects.create(person=ringo, group=beatles, + ... date_joined=date(1968, 9, 4), + ... invite_reason="You've been gone for a month and we miss you.") + >>> beatles.members.all() + , , ]> + >>> # THIS WILL NOT WORK BECAUSE IT CANNOT TELL WHICH MEMBERSHIP TO REMOVE + >>> beatles.members.remove(ringo) + +However, the :meth:`~django.db.models.fields.related.RelatedManager.clear` +method can be used to remove all many-to-many relationships for an instance:: >>> # Beatles have broken up >>> beatles.members.clear()