Added Model Delta and HistoricalChanges

AUTHORS.rst

@@ -21,6 +21,7 @@ Authors
 - Jonathan Sanchez
 - Josh Fyne
 - Klaas van Schelven
+- Leticia Portella
 - Martin Bachwerk
 - Marty Alchin
 - Mauricio de Abreu Antunes

docs/advanced.rst

@@ -213,3 +213,22 @@ You can use the ``table_name`` parameter with both ``HistoricalRecords()`` or
         pub_date = models.DateTimeField('date published')
 
     register(Question, table_name='polls_question_history')
+
+
+History Subtraction
+-------------------
+
+When you have two instances of the same HistoricalRecord, such as HistoricalPoll example above,
+you can make subtractions. This will result in a ModelDelta containing some properties such as a
+dictionary with each field changed between this historical records, a list with all
+fields that suffered changes from one record to another and the date and user from the last change.
+This may be useful when you want timelines, and need to get only the model modifications. 
+
+.. code-block:: python
+
+    p = Poll.objects.create(question="what's up?")
+    p.question = "what's up, man?"
+    p.save()
+
+    new_record, old_record = p.history.all()
+    delta = new_record - old_record

simple_history/models.py

@@ -44,7 +44,7 @@ def __init__(self, verbose_name=None, bases=(models.Model,),
         try:
             if isinstance(bases, six.string_types):
                 raise TypeError
-            self.bases = tuple(bases)
+            self.bases = (HistoricalChanges,) + tuple(bases)
         except TypeError:
             raise TypeError("The `bases` option must be a list or a tuple.")
 
@@ -311,3 +311,46 @@ def __get__(self, instance, owner):
         values = (getattr(instance, f.attname)
                   for f in self.model._meta.fields)
         return self.model(*values)
+
+
+class HistoricalChanges(models.Model):
+
+    class Meta:
+        abstract = True
+
+    def __sub__(self, old_history):
+        if not isinstance(old_history, type(self)):
+            raise TypeError(("unsupported operand type(s) for -: "
+                             "'{}' and '{}'").format(
+                            type(self),
+                            type(old_history)))
+        model_delta_class = getattr(self, 'model_delta_class', ModelDelta)
+        changes = {}
+        changed_fields = []
+        for field in self._meta.fields:
+            if hasattr(self.instance, field.name) and \
+               hasattr(old_history.instance, field.name):
+                old_value = getattr(old_history, field.name, '')
+                new_value = getattr(self, field.name)
+                if old_value != new_value:
+                    changes[field.name] = {'old_value': old_value,
+                                           'new_value': new_value}
+                    changed_fields.append(field.name)
+        return model_delta_class(changes,
+                                 changed_fields=changed_fields,
+                                 date=self.history_date,
+                                 user=self.history_user,
+                                 old_history=old_history,
+                                 new_history=self)
+
+
+class ModelDelta:
+
+    def __init__(self, changes, changed_fields, date, user, old_history,
+                 new_history):
+        self.changes = changes
+        self.changed_fields = changed_fields
+        self.date = date
+        self.user = user
+        self.old_history = old_history
+        self.new_history = new_history

simple_history/tests/tests/test_models.py

@@ -307,6 +307,26 @@ def test_foreignkey_primarykey(self):
         poll_info = PollInfo(poll=poll)
         poll_info.save()
 
+    def test_history_subtraction(self):
+        p = Poll.objects.create(question="what's up?", pub_date=today)
+        p.question = "what's up, man?"
+        p.save()
+        new_record, old_record = p.history.all()
+        delta = new_record - old_record
+        expected_changes = {'old_value': "what's up?",
+                            'new_value': "what's up, man?"}
+        self.assertEqual(delta.changed_fields, ['question'])
+        self.assertEqual(delta.old_history, old_record)
+        self.assertEqual(delta.new_history, new_record)
+        self.assertEqual(delta.changes['question'], expected_changes)
+
+    def test_history_subtraction_wrong_type(self):
+        p = Poll.objects.create(question="what's up?", pub_date=today)
+        p.question = "what's up, man?"
+        p.save()
+        new_record, old_record = p.history.all()
+        with self.assertRaises(TypeError):
+            delta = new_record - 'something'
 
 class CreateHistoryModelTests(unittest.TestCase):