Ticket #5390: complete-patch.diff

File complete-patch.diff, 16.7 KB (added by rvdrijst, 7 years ago)

A complete patch with code, docs and tests for an m2m_changed signal.

  • django/db/models/signals.py

     
    1212post_delete = Signal(providing_args=["instance"])
    1313
    1414post_syncdb = Signal(providing_args=["class", "app", "created_models", "verbosity", "interactive"])
     15
     16m2m_changed = Signal(providing_args=["instance", "action", "model", "field_name", "reverse", "objects"])
  • django/db/models/fields/related.py

     
    360360    """Creates a manager that subclasses 'superclass' (which is a Manager)
    361361    and adds behavior for many-to-many related objects."""
    362362    class ManyRelatedManager(superclass):
    363         def __init__(self, model=None, core_filters=None, instance=None, symmetrical=None,
    364                 join_table=None, source_col_name=None, target_col_name=None):
     363        def __init__(self, model=None, core_filters=None, instance=None,
     364                     symmetrical=None, join_table=None, source_col_name=None,
     365                     target_col_name=None, field_name=None, reverse=False):
    365366            super(ManyRelatedManager, self).__init__()
    366367            self.core_filters = core_filters
    367368            self.model = model
     
    372373            self.target_col_name = target_col_name
    373374            self.through = through
    374375            self._pk_val = self.instance._get_pk_val()
     376            self.field_name = field_name
     377            self.reverse = reverse
    375378            if self._pk_val is None:
    376379                raise ValueError("%r instance needs to have a primary key value before a many-to-many relationship can be used." % instance.__class__.__name__)
    377380
     
    450453                existing_ids = set([row[0] for row in cursor.fetchall()])
    451454
    452455                # Add the ones that aren't there already
    453                 for obj_id in (new_ids - existing_ids):
     456                new_ids = new_ids - existing_ids
     457                for obj_id in new_ids:
    454458                    cursor.execute("INSERT INTO %s (%s, %s) VALUES (%%s, %%s)" % \
    455459                        (self.join_table, source_col_name, target_col_name),
    456460                        [self._pk_val, obj_id])
     461                added_objs = [obj for obj in objs if \
     462                        (isinstance(obj, self.model) and obj._get_pk_val() in new_ids) \
     463                        or obj in new_ids]
     464                if self.reverse:
     465                    sender = self.model
     466                else:
     467                    sender = self.instance.__class__
     468                signals.m2m_changed.send(sender=sender, action='add',
     469                    instance=self.instance, model=self.model,
     470                    reverse=self.reverse, field_name=self.field_name,
     471                    objects=added_objs)
    457472                transaction.commit_unless_managed()
    458473
    459474        def _remove_items(self, source_col_name, target_col_name, *objs):
     
    476491                    (self.join_table, source_col_name,
    477492                    target_col_name, ",".join(['%s'] * len(old_ids))),
    478493                    [self._pk_val] + list(old_ids))
     494                if self.reverse:
     495                    sender = self.model
     496                else:
     497                    sender = self.instance.__class__
     498                signals.m2m_changed.send(sender=sender, action="remove",
     499                    instance=self.instance, model=self.model,
     500                    reverse=self.reverse, field_name=self.field_name,
     501                    objects=list(objs))
    479502                transaction.commit_unless_managed()
    480503
    481504        def _clear_items(self, source_col_name):
     505            if self.reverse:
     506                    sender = self.model
     507            else:
     508                    sender = self.instance.__class__
     509            signals.m2m_changed.send(sender=sender, action="clear",
     510                instance=self.instance, model=self.model, reverse=self.reverse,
     511                field_name=self.field_name, objects=None)
    482512            # source_col_name: the PK colname in join_table for the source object
    483513            cursor = connection.cursor()
    484514            cursor.execute("DELETE FROM %s WHERE %s = %%s" % \
     
    516546            symmetrical=False,
    517547            join_table=qn(self.related.field.m2m_db_table()),
    518548            source_col_name=qn(self.related.field.m2m_reverse_name()),
    519             target_col_name=qn(self.related.field.m2m_column_name())
     549            target_col_name=qn(self.related.field.m2m_column_name()),
     550            field_name=self.related.field.name,
     551            reverse=True
    520552        )
    521553
    522554        return manager
     
    561593            symmetrical=(self.field.rel.symmetrical and instance.__class__ == rel_model),
    562594            join_table=qn(self.field.m2m_db_table()),
    563595            source_col_name=qn(self.field.m2m_column_name()),
    564             target_col_name=qn(self.field.m2m_reverse_name())
     596            target_col_name=qn(self.field.m2m_reverse_name()),
     597            field_name=self.field.name,
     598            reverse=False
    565599        )
    566600
    567601        return manager
     
    923957        # A ManyToManyField is not represented by a single column,
    924958        # so return None.
    925959        return None
    926 
  • docs/ref/signals.txt

     
    163163        Note that the object will no longer be in the database, so be very
    164164        careful what you do with this instance.
    165165
     166m2m_changed
     167-----------
     168
     169.. data:: django.db.models.signals.m2m_changed
     170   :module:
     171
     172Sent when a :class:`ManyToManyField` is changed on a model instance.
     173Strictly speaking, this is not a model signal since it is sent by the
     174:class:`ManyToManyField`, but since it complements the
     175:data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete`
     176when it comes to tracking changes to models, it is included here.
     177
     178Arguments sent with this signal:
     179
     180    ``sender``
     181        The model class containing the :class:`ManyToManyField`.
     182
     183    ``instance``
     184        The instance whose many-to-many relation is updated. This can be an
     185        instance of the ``sender``, or of the class the :class:`ManyToManyField`
     186        is related to.
     187
     188    ``action``
     189        A string indicating the type of update that is done on the relation.
     190        This can be one of the following:
     191       
     192        ``"add"``
     193            Sent *after* one or more objects are added to the relation,
     194        ``"remove"``       
     195            Sent *after* one or more objects are removed from the relation,
     196        ``"clear"``
     197            Sent *before* the relation is cleared.
     198       
     199    ``model``
     200        The class of the objects that are added to, removed from or cleared
     201        from the relation.
     202       
     203    ``field_name``
     204        The name of the :class:`ManyToManyField` in the ``sender`` class.
     205        This can be used to identify which relation has changed
     206        when multiple many-to-many relations to the same model
     207        exist in ``sender``.
     208       
     209    ``reverse``
     210        Indicates which side of the relation is updated.
     211        It is ``False`` for updates on an instance of the ``sender`` and
     212        ``True`` for updates on an instance of the related class.
     213       
     214    ``objects``
     215        With the ``"add"`` and ``"remove"`` action, this is a list of
     216        objects that have been added to or removed from the relation.
     217        The class of these objects is given in the ``model`` argument.
     218       
     219        For the ``"clear"`` action, this is ``None`` .
     220       
     221        Note that if you pass primary keys to the ``add`` or ``remove`` method
     222        of a relation, ``objects`` will contain primary keys, not instances.
     223        Also note that if you pass objects to the ``add`` method that are
     224        already in the relation, they will not be in the ``objects`` list.
     225        (This doesn't apply to ``remove``.)
     226       
     227For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled
     228like this:
     229
     230.. code-block:: python
     231
     232    class Topping(models.Model):
     233        # ...
     234
     235    class Pizza(models.Model):
     236        # ...
     237        toppings = models.ManyToManyField(Topping)
     238
     239If we would do something like this:
     240
     241.. code-block:: python
     242
     243    >>> p = Pizza.object.create(...)
     244    >>> t = Topping.objects.create(...)
     245    >>> p.toppings.add(t)
     246       
     247the arguments sent to a :data:`m2m_changed` handler would be:
     248
     249    ==============  ============================================================
     250    Argument        Value
     251    ==============  ============================================================
     252    ``sender``      ``Pizza`` (the class containing the field)
     253
     254    ``instance``    ``p`` (the ``Pizza`` instance being modified)
     255
     256    ``action``      ``"add"`` since the ``add`` method was called
     257   
     258    ``model``       ``Topping`` (the class of the objects added to the
     259                    ``Pizza``)
     260   
     261    ``reverse``     ``False`` (since ``Pizza`` contains the
     262                    :class:`ManyToManyField`)
     263   
     264    ``field_name``  ``"topping"`` (the name of the :class:`ManyToManyField`)
     265   
     266    ``objects``     ``[t]`` (since only ``Topping t`` was added to the relation)
     267    ==============  ============================================================
     268
     269And if we would then do something like this:
     270
     271.. code-block:: python
     272
     273    >>> t.pizza_set.remove(p)
     274       
     275the arguments sent to a :data:`m2m_changed` handler would be:
     276
     277    ==============  ============================================================
     278    Argument        Value
     279    ==============  ============================================================
     280    ``sender``      ``Pizza`` (the class containing the field)
     281
     282    ``instance``    ``t`` (the ``Topping`` instance being modified)
     283
     284    ``action``      ``"remove"`` since the ``remove`` method was called
     285   
     286    ``model``       ``Pizza`` (the class of the objects removed from the
     287                    ``Topping``)
     288   
     289    ``reverse``     ``True`` (since ``Pizza`` contains the
     290                    :class:`ManyToManyField` but the relation is modified
     291                    through ``Topping``)
     292   
     293    ``field_name``  ``"topping"`` (the name of the :class:`ManyToManyField`)
     294   
     295    ``objects``     ``[p]`` (since only ``Pizza p`` was removed from the
     296                    relation)
     297    ==============  ============================================================
     298
    166299class_prepared
    167300--------------
    168301
  • docs/topics/signals.txt

     
    2828
    2929      Sent before or after a model's :meth:`~django.db.models.Model.delete`
    3030      method is called.
     31     
     32    * :data:`django.db.models.signals.m2m_changed`
    3133
     34      Sent when a :class:`ManyToManyField` on a model is changed.
    3235
    3336    * :data:`django.core.signals.request_started` &
    3437      :data:`django.core.signals.request_finished`
  • tests/modeltests/m2m_signals/models.py

    Property changes on: tests/modeltests/m2m_signals/__init__.py
    ___________________________________________________________________
    Added: svn:keywords
       + Id
    Added: svn:eol-style
       + native
    
     
     1"""
     2Testing signals emitted on changing m2m relations.
     3"""
     4
     5from django.db import models
     6
     7class Part(models.Model):
     8    name = models.CharField(max_length=20)
     9       
     10    def __unicode__(self):
     11        return self.name
     12
     13class Car(models.Model):
     14    name = models.CharField(max_length=20)
     15    default_parts = models.ManyToManyField(Part)
     16    optional_parts = models.ManyToManyField(Part, related_name='cars_optional')
     17
     18    def __unicode__(self):
     19        return self.name
     20
     21def m2m_changed_test(signal, sender, **kwargs):
     22    print 'm2m_changed signal'
     23    print 'instance:', kwargs['instance']
     24    print 'action:', kwargs['action']
     25    print 'reverse:', kwargs['reverse']
     26    print 'field_name:', kwargs['field_name']
     27    print 'model:', kwargs['model']
     28    print 'objects:',kwargs['objects']
     29   
     30
     31__test__ = {'API_TESTS':"""
     32>>> models.signals.m2m_changed.connect(m2m_changed_test, Car)
     33
     34# Test the add, remove and clear methods on both sides of the
     35# many-to-many relation
     36
     37>>> c1 = Car.objects.create(name='VW')
     38>>> c2 = Car.objects.create(name='BMW')
     39>>> c3 = Car.objects.create(name='Toyota')
     40>>> p1 = Part.objects.create(name='Wheelset')
     41>>> p2 = Part.objects.create(name='Doors')
     42>>> p3 = Part.objects.create(name='Engine')
     43>>> p4 = Part.objects.create(name='Airbag')
     44>>> p5 = Part.objects.create(name='Sunroof')
     45
     46# adding some default parts to our car
     47>>> c1.default_parts.add(p1, p2, p3)
     48m2m_changed signal
     49instance: VW
     50action: add
     51reverse: False
     52field_name: default_parts
     53model: <class 'modeltests.m2m_signals.models.Part'>
     54objects: [<Part: Wheelset>, <Part: Doors>, <Part: Engine>]
     55
     56# give the BMW and Toyata some doors as well
     57>>> p2.car_set.add(c2, c3)
     58m2m_changed signal
     59instance: Doors
     60action: add
     61reverse: True
     62field_name: default_parts
     63model: <class 'modeltests.m2m_signals.models.Car'>
     64objects: [<Car: BMW>, <Car: Toyota>]
     65
     66# remove the engine from the VW and the airbag (which is not set but is returned)
     67>>> c1.default_parts.remove(p3, p4)
     68m2m_changed signal
     69instance: VW
     70action: remove
     71reverse: False
     72field_name: default_parts
     73model: <class 'modeltests.m2m_signals.models.Part'>
     74objects: [<Part: Engine>, <Part: Airbag>]
     75
     76# give the VW some optional parts (second relation to same model)
     77>>> c1.optional_parts.add(p4,p5)
     78m2m_changed signal
     79instance: VW
     80action: add
     81reverse: False
     82field_name: optional_parts
     83model: <class 'modeltests.m2m_signals.models.Part'>
     84objects: [<Part: Airbag>, <Part: Sunroof>]
     85
     86# add airbag to all the cars (even though the VW already has one)
     87>>> p4.cars_optional.add(c1, c2, c3)
     88m2m_changed signal
     89instance: Airbag
     90action: add
     91reverse: True
     92field_name: optional_parts
     93model: <class 'modeltests.m2m_signals.models.Car'>
     94objects: [<Car: BMW>, <Car: Toyota>]
     95
     96# remove airbag from the VW (reverse relation with custom related_name)
     97>>> p4.cars_optional.remove(c1)
     98m2m_changed signal
     99instance: Airbag
     100action: remove
     101reverse: True
     102field_name: optional_parts
     103model: <class 'modeltests.m2m_signals.models.Car'>
     104objects: [<Car: VW>]
     105
     106# clear all parts of the VW
     107>>> c1.default_parts.clear()
     108m2m_changed signal
     109instance: VW
     110action: clear
     111reverse: False
     112field_name: default_parts
     113model: <class 'modeltests.m2m_signals.models.Part'>
     114objects: None
     115
     116# take all the doors off of cars
     117>>> p2.car_set.clear()
     118m2m_changed signal
     119instance: Doors
     120action: clear
     121reverse: True
     122field_name: default_parts
     123model: <class 'modeltests.m2m_signals.models.Car'>
     124objects: None
     125
     126# take all the airbags off of cars (clear reverse relation with custom related_name)
     127>>> p4.cars_optional.clear()
     128m2m_changed signal
     129instance: Airbag
     130action: clear
     131reverse: True
     132field_name: optional_parts
     133model: <class 'modeltests.m2m_signals.models.Car'>
     134objects: None
     135
     136# alternative ways of setting relation:
     137
     138>>> c1.default_parts.create(name='Windows')
     139m2m_changed signal
     140instance: VW
     141action: add
     142reverse: False
     143field_name: default_parts
     144model: <class 'modeltests.m2m_signals.models.Part'>
     145objects: [<Part: Windows>]
     146<Part: Windows>
     147
     148# direct assignment clears the set first, then adds
     149>>> c1.default_parts = [p1,p2,p3]
     150m2m_changed signal
     151instance: VW
     152action: clear
     153reverse: False
     154field_name: default_parts
     155model: <class 'modeltests.m2m_signals.models.Part'>
     156objects: None
     157m2m_changed signal
     158instance: VW
     159action: add
     160reverse: False
     161field_name: default_parts
     162model: <class 'modeltests.m2m_signals.models.Part'>
     163objects: [<Part: Wheelset>, <Part: Doors>, <Part: Engine>]
     164
     165>>> models.signals.m2m_changed.disconnect(m2m_changed_test)
     166"""}
  • tests/modeltests/m2m_signals/__init__.py

    Property changes on: tests/modeltests/m2m_signals/models.py
    ___________________________________________________________________
    Added: svn:keywords
       + Id
    Added: svn:eol-style
       + native
     
     1
Back to Top