diff options
| author | bphillips <bphillips@caktusgroup.com> | 2015-11-25 11:25:21 -0500 |
|---|---|---|
| committer | Tim Graham <timograham@gmail.com> | 2015-12-08 18:00:10 -0500 |
| commit | d508326e2f7d35973e2662109e34b425cb108b81 (patch) | |
| tree | ca9a9aec52335a94aa89e0272dee3da9ff73e01b /docs | |
| parent | cd40d9e721eb4f5d05f57a74c6f1fd5d4aaef444 (diff) | |
Fixed #25672 -- Clarified why related ManyToManyFields with a custom intermediate model disable the remove() method.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/topics/db/models.txt | 24 |
1 files 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() + <QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>, <Person: Ringo Starr>]> + >>> # 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() |