Merge pull request #85 from filipeximenes/master

Adding 'when' parameter to MonitorField

AUTHORS.rst

@@ -22,3 +22,4 @@ Tony Aldridge <zaragopha@hotmail.com>
 Travis Swicegood <travis@domain51.com>
 Trey Hunner <trey@treyhunner.com>
 zyegfryed
+Filipe Ximenes <filipeximenes@gmail.com>

CHANGES.rst

@@ -15,6 +15,9 @@ master (unreleased)
   `select_subclasses('child', 'child__grandchild')` would only ever get to the
   child class. Thanks Keryn Knight for report and proposed fix.
 
+* MonitorField now accepts a 'when' parameter. It will update only when the field 
+  changes to one of the values specified.
+
 
 1.5.0 (2013.08.29)
 ------------------

docs/fields.rst

@@ -53,6 +53,19 @@ field changes:
 (A ``MonitorField`` can monitor any type of field for changes, not only a
 ``StatusField``.)
 
+If a list is passed to the ``when`` parameter, the field will only 
+update when it matches one of the specified values:
+
+.. code-block:: python
+
+    from model_utils.fields import MonitorField, StatusField
+
+    class Article(models.Model):
+        STATUS = Choices('draft', 'published')
+
+        status = StatusField()
+        published_at = MonitorField(monitor='status', when=['published'])
+
 
 SplitField
 ----------

model_utils/fields.py

@@ -82,6 +82,10 @@ class MonitorField(models.DateTimeField):
             raise TypeError(
                 '%s requires a "monitor" argument' % self.__class__.__name__)
         self.monitor = monitor
+        when = kwargs.pop('when', None)
+        if when is not None:
+            when = set(when)
+        self.when = when
         super(MonitorField, self).__init__(*args, **kwargs)
 
     def contribute_to_class(self, cls, name):
@@ -101,8 +105,9 @@ class MonitorField(models.DateTimeField):
         previous = getattr(model_instance, self.monitor_attname, None)
         current = self.get_monitored_value(model_instance)
         if previous != current:
-            setattr(model_instance, self.attname, value)
-            self._save_initial(model_instance.__class__, model_instance)
+            if self.when is None or current in self.when:
+                setattr(model_instance, self.attname, value)
+                self._save_initial(model_instance.__class__, model_instance)
         return super(MonitorField, self).pre_save(model_instance, add)
 
 

model_utils/tests/models.py

@@ -77,6 +77,18 @@ class Monitored(models.Model):
 
 
 
+class MonitorWhen(models.Model):
+    name = models.CharField(max_length=25)
+    name_changed = MonitorField(monitor="name", when=["Jose", "Maria"])
+
+
+
+class MonitorWhenEmpty(models.Model):
+    name = models.CharField(max_length=25)
+    name_changed = MonitorField(monitor="name", when=[])
+
+
+
 class Status(StatusModel):
     STATUS = Choices(
         ("active", _("active")),

model_utils/tests/tests.py

@@ -23,7 +23,7 @@ from model_utils.tests.models import (
     InheritanceManagerTestGrandChild1_2,
     InheritanceManagerTestParent, InheritanceManagerTestChild1,
     InheritanceManagerTestChild2, TimeStamp, Post, Article, Status,
-    StatusPlainTuple, TimeFrame, Monitored, StatusManagerAdded,
+    StatusPlainTuple, TimeFrame, Monitored, MonitorWhen, MonitorWhenEmpty, StatusManagerAdded,
     TimeFrameManagerAdded, Dude, SplitFieldAbstractParent, Car, Spot,
     ModelTracked, ModelTrackedFK, ModelTrackedNotDefault, ModelTrackedMultiple, InheritedModelTracked,
     Tracked, TrackedFK, TrackedNotDefault, TrackedNonFieldAttr, TrackedMultiple,
@@ -170,6 +170,75 @@ class MonitorFieldTests(TestCase):
             MonitorField()
 
 
+
+class MonitorWhenFieldTests(TestCase):
+    """
+    Will record changes only when name is 'Jose' or 'Maria'
+    """
+    def setUp(self):
+        self.instance = MonitorWhen(name='Charlie')
+        self.created = self.instance.name_changed
+
+
+    def test_save_no_change(self):
+        self.instance.save()
+        self.assertEqual(self.instance.name_changed, self.created)
+
+
+    def test_save_changed_to_Jose(self):
+        self.instance.name = 'Jose'
+        self.instance.save()
+        self.assertTrue(self.instance.name_changed > self.created)
+
+
+    def test_save_changed_to_Maria(self):
+        self.instance.name = 'Maria'
+        self.instance.save()
+        self.assertTrue(self.instance.name_changed > self.created)
+
+
+    def test_save_changed_to_Pedro(self):
+        self.instance.name = 'Pedro'
+        self.instance.save()
+        self.assertEqual(self.instance.name_changed, self.created)
+
+
+    def test_double_save(self):
+        self.instance.name = 'Jose'
+        self.instance.save()
+        changed = self.instance.name_changed
+        self.instance.save()
+        self.assertEqual(self.instance.name_changed, changed)
+
+
+
+class MonitorWhenEmptyFieldTests(TestCase):
+    """
+    Monitor should never be updated id when is an empty list.
+    """
+    def setUp(self):
+        self.instance = MonitorWhenEmpty(name='Charlie')
+        self.created = self.instance.name_changed
+
+
+    def test_save_no_change(self):
+        self.instance.save()
+        self.assertEqual(self.instance.name_changed, self.created)
+
+
+    def test_save_changed_to_Jose(self):
+        self.instance.name = 'Jose'
+        self.instance.save()
+        self.assertEqual(self.instance.name_changed, self.created)
+
+
+    def test_save_changed_to_Maria(self):
+        self.instance.name = 'Maria'
+        self.instance.save()
+        self.assertEqual(self.instance.name_changed, self.created)
+
+
+
 class StatusFieldTests(TestCase):
 
     def test_status_with_default_filled(self):