diff -r 891a2658613f django/db/models/fields/related.py --- a/django/db/models/fields/related.py Fri Jan 08 00:43:14 2010 +0000 +++ b/django/db/models/fields/related.py Fri Jan 08 19:51:13 2010 +0800 @@ -513,14 +513,16 @@ source_field_name: self._pk_val, '%s__in' % target_field_name: new_ids, }) - vals = set(vals) - + new_ids = new_ids - set(vals) # Add the ones that aren't there already - for obj_id in (new_ids - vals): + for obj_id in new_ids: self.through._default_manager.using(self.instance._state.db).create(**{ '%s_id' % source_field_name: self._pk_val, '%s_id' % target_field_name: obj_id, }) + signals.m2m_changed.send(sender=rel.through, action='add', + instance=self.instance, reverse=(rel.to != self.model), + model=self.model, pk_set=new_ids) def _remove_items(self, source_field_name, target_field_name, *objs): # source_col_name: the PK colname in join_table for the source object @@ -541,9 +543,15 @@ source_field_name: self._pk_val, '%s__in' % target_field_name: old_ids }).delete() + signals.m2m_changed.send(sender=rel.through, action="remove", + instance=self.instance, reverse=(rel.to != self.model), + model=self.model, pk_set=old_ids) def _clear_items(self, source_field_name): # source_col_name: the PK colname in join_table for the source object + signals.m2m_changed.send(sender=rel.through, action="clear", + instance=self.instance, reverse=(rel.to != self.model), + model=self.model, pk_set=None) self.through._default_manager.using(self.instance._state.db).filter(**{ source_field_name: self._pk_val }).delete() @@ -593,6 +601,7 @@ manager.clear() manager.add(*value) + class ReverseManyRelatedObjectsDescriptor(object): # This class provides the functionality that makes the related-object # managers available as attributes on a model class, for fields that have diff -r 891a2658613f django/db/models/signals.py --- a/django/db/models/signals.py Fri Jan 08 00:43:14 2010 +0000 +++ b/django/db/models/signals.py Fri Jan 08 19:51:13 2010 +0800 @@ -12,3 +12,5 @@ post_delete = Signal(providing_args=["instance"]) post_syncdb = Signal(providing_args=["class", "app", "created_models", "verbosity", "interactive"]) + +m2m_changed = Signal(providing_args=["action", "instance", "reverse", "model", "pk_set"]) diff -r 891a2658613f docs/ref/signals.txt --- a/docs/ref/signals.txt Fri Jan 08 00:43:14 2010 +0000 +++ b/docs/ref/signals.txt Fri Jan 08 19:51:13 2010 +0800 @@ -170,6 +170,123 @@ Note that the object will no longer be in the database, so be very careful what you do with this instance. +m2m_changed +----------- + +.. data:: django.db.models.signals.m2m_changed + :module: + +Sent when a :class:`ManyToManyField` is changed on a model instance. +Strictly speaking, this is not a model signal since it is sent by the +:class:`ManyToManyField`, but since it complements the +:data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete` +when it comes to tracking changes to models, it is included here. + +Arguments sent with this signal: + + ``sender`` + The intermediate model class describing the :class:`ManyToManyField`. + This class is automatically created when a many-to-many field is + defined; it you can access it using the ``through`` attribute on the + many-to-many field. + + ``instance`` + The instance whose many-to-many relation is updated. This can be an + instance of the ``sender``, or of the class the :class:`ManyToManyField` + is related to. + + ``action`` + A string indicating the type of update that is done on the relation. + This can be one of the following: + + ``"add"`` + Sent *after* one or more objects are added to the relation + ``"remove"`` + Sent *after* one or more objects are removed from the relation + ``"clear"`` + Sent *before* the relation is cleared + + ``reverse`` + Indicates which side of the relation is updated (i.e., if it is the + forward or reverse relation that is being modified). + + ``model`` + The class of the objects that are added to, removed from or cleared + from the relation. + + ``pk_set`` + With the ``"add"`` and ``"remove"`` action, this is a list of + primary key values that have been added to or removed from the relation. + + For the ``"clear"`` action, this is ``None``. + +For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled +like this: + +.. code-block:: python + + class Topping(models.Model): + # ... + + class Pizza(models.Model): + # ... + toppings = models.ManyToManyField(Topping) + +If we would do something like this: + +.. code-block:: python + + >>> p = Pizza.object.create(...) + >>> t = Topping.objects.create(...) + >>> p.toppings.add(t) + +the arguments sent to a :data:`m2m_changed` handler would be: + + ============== ============================================================ + Argument Value + ============== ============================================================ + ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class) + + ``instance`` ``p`` (the ``Pizza`` instance being modified) + + ``action`` ``"add"`` + + ``reverse`` ``False`` (``Pizza`` contains the :class:`ManyToManyField`, + so this call modifies the forward relation) + + ``model`` ``Topping`` (the class of the objects added to the + ``Pizza``) + + ``pk_set`` ``[t.id]`` (since only ``Topping t`` was added to the relation) + ============== ============================================================ + +And if we would then do something like this: + +.. code-block:: python + + >>> t.pizza_set.remove(p) + +the arguments sent to a :data:`m2m_changed` handler would be: + + ============== ============================================================ + Argument Value + ============== ============================================================ + ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class) + + ``instance`` ``t`` (the ``Topping`` instance being modified) + + ``action`` ``"remove"`` + + ``reverse`` ``True`` (``Pizza`` contains the :class:`ManyToManyField`, + so this call modifies the reverse relation) + + ``model`` ``Pizza`` (the class of the objects removed from the + ``Topping``) + + ``pk_set`` ``[p.id]`` (since only ``Pizza p`` was removed from the + relation) + ============== ============================================================ + class_prepared -------------- diff -r 891a2658613f docs/topics/signals.txt --- a/docs/topics/signals.txt Fri Jan 08 00:43:14 2010 +0000 +++ b/docs/topics/signals.txt Fri Jan 08 19:51:13 2010 +0800 @@ -29,6 +29,9 @@ Sent before or after a model's :meth:`~django.db.models.Model.delete` method is called. + * :data:`django.db.models.signals.m2m_changed` + + Sent when a :class:`ManyToManyField` on a model is changed. * :data:`django.core.signals.request_started` & :data:`django.core.signals.request_finished` diff -r 891a2658613f tests/modeltests/m2m_signals/__init__.py --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tests/modeltests/m2m_signals/__init__.py Fri Jan 08 19:51:13 2010 +0800 @@ -0,0 +1,1 @@ + diff -r 891a2658613f tests/modeltests/m2m_signals/models.py --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tests/modeltests/m2m_signals/models.py Fri Jan 08 19:51:13 2010 +0800 @@ -0,0 +1,183 @@ +""" +Testing signals emitted on changing m2m relations. +""" + +from django.db import models + +class Part(models.Model): + name = models.CharField(max_length=20) + + def __unicode__(self): + return self.name + +class Car(models.Model): + name = models.CharField(max_length=20) + default_parts = models.ManyToManyField(Part) + optional_parts = models.ManyToManyField(Part, related_name='cars_optional') + + def __unicode__(self): + return self.name + +class SportsCar(Car): + price = models.IntegerField(max_length=20) + +def m2m_changed_test(signal, sender, **kwargs): + print 'm2m_changed signal' + print 'instance:', kwargs['instance'] + print 'action:', kwargs['action'] + print 'reverse:', kwargs['reverse'] + print 'model:', kwargs['model'] + if kwargs['pk_set']: + print 'objects:',kwargs['model'].objects.filter(pk__in=kwargs['pk_set']) + + +__test__ = {'API_TESTS':""" +# Install a listener on one of the two m2m relations. +>>> models.signals.m2m_changed.connect(m2m_changed_test, Car.optional_parts.through) + +# Test the add, remove and clear methods on both sides of the +# many-to-many relation + +>>> c1 = Car.objects.create(name='VW') +>>> c2 = Car.objects.create(name='BMW') +>>> c3 = Car.objects.create(name='Toyota') +>>> p1 = Part.objects.create(name='Wheelset') +>>> p2 = Part.objects.create(name='Doors') +>>> p3 = Part.objects.create(name='Engine') +>>> p4 = Part.objects.create(name='Airbag') +>>> p5 = Part.objects.create(name='Sunroof') + +# adding some default parts to our car - no signal listener installed +>>> c1.default_parts.add(p4, p5) + +# Now install a listener +>>> models.signals.m2m_changed.connect(m2m_changed_test, Car.default_parts.through) + +>>> c1.default_parts.add(p1, p2, p3) +m2m_changed signal +instance: VW +action: add +reverse: False +model: +objects: [, , ] + +# give the BMW and Toyata some doors as well +>>> p2.car_set.add(c2, c3) +m2m_changed signal +instance: Doors +action: add +reverse: True +model: +objects: [, ] + +# remove the engine from the VW and the airbag (which is not set but is returned) +>>> c1.default_parts.remove(p3, p4) +m2m_changed signal +instance: VW +action: remove +reverse: False +model: +objects: [, ] + +# give the VW some optional parts (second relation to same model) +>>> c1.optional_parts.add(p4,p5) +m2m_changed signal +instance: VW +action: add +reverse: False +model: +objects: [, ] + +# add airbag to all the cars (even though the VW already has one) +>>> p4.cars_optional.add(c1, c2, c3) +m2m_changed signal +instance: Airbag +action: add +reverse: True +model: +objects: [, ] + +# remove airbag from the VW (reverse relation with custom related_name) +>>> p4.cars_optional.remove(c1) +m2m_changed signal +instance: Airbag +action: remove +reverse: True +model: +objects: [] + +# clear all parts of the VW +>>> c1.default_parts.clear() +m2m_changed signal +instance: VW +action: clear +reverse: False +model: + +# take all the doors off of cars +>>> p2.car_set.clear() +m2m_changed signal +instance: Doors +action: clear +reverse: True +model: + +# take all the airbags off of cars (clear reverse relation with custom related_name) +>>> p4.cars_optional.clear() +m2m_changed signal +instance: Airbag +action: clear +reverse: True +model: + +# alternative ways of setting relation: + +>>> c1.default_parts.create(name='Windows') +m2m_changed signal +instance: VW +action: add +reverse: False +model: +objects: [] + + +# direct assignment clears the set first, then adds +>>> c1.default_parts = [p1,p2,p3] +m2m_changed signal +instance: VW +action: clear +reverse: False +model: +m2m_changed signal +instance: VW +action: add +reverse: False +model: +objects: [, , ] + +# Check that signals still work when model inheritance is involved +>>> c4 = SportsCar.objects.create(name='Bugatti', price='1000000') +>>> c4.default_parts = [p2] +m2m_changed signal +instance: Bugatti +action: clear +reverse: False +model: +m2m_changed signal +instance: Bugatti +action: add +reverse: False +model: +objects: [] + +>>> p3.car_set.add(c4) +m2m_changed signal +instance: Engine +action: add +reverse: True +model: +objects: [] + +>>> models.signals.m2m_changed.disconnect(m2m_changed_test) + +"""}