feat(HistoryRecords): prev and next attributes (#365)

- New attributes on history model retrieve previous and next records

Closes #230

Author: SpainTrain

AUTHORS.rst

@@ -56,6 +56,7 @@ Authors
 - Shane Engelman
 - Ray Logel
 - Nathan Villagaray-Carski
+- Mike Spainhower
 
 Background
 ==========

CHANGES.rst

@@ -4,6 +4,7 @@ Changes
 Unreleased
 ----------
 - Add ability to specify custom history_id field (gh-368)
+- Add HistoricalRecord instance properties `prev_record` and `next_record` (gh-365)
 
 2.0 (2018-04-05)
 ----------------

docs/usage.rst

@@ -214,3 +214,26 @@ records for all ``Choice`` instances can be queried by using the manager on the
 
 Because the history is model, you can also filter it like regularly QuerySets,
 a.k. Choice.history.filter(choice_text='Not Much') will work!
+
+Getting previous and next historical record
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have a historical record for an instance and would like to retrieve the previous historical record (older) or next historical record (newer), `prev_record` and `next_record` read-only attributes can be used, respectively.
+
+.. code-block:: pycon
+
+    >>> from polls.models import Poll, Choice
+    >>> from datetime import datetime
+    >>> poll = Poll.objects.create(question="what's up?", pub_date=datetime.now())
+    >>>
+    >>> record = poll.history.first()
+    >>> record.prev_record
+    None
+    >>> record.next_record
+    None
+    >>> poll.question = "what is up?"
+    >>> poll.save()
+    >>> record.next_record
+    <HistoricalPoll: Poll object as of 2010-10-25 18:04:13.814128>
+
+If a historical record is the first record, `prev_record` will be `None`.  Similarly, if it is the latest record, `next_record` will be `None`

simple_history/models.py

@@ -9,6 +9,7 @@
 from django.conf import settings
 from django.contrib import admin
 from django.db import models, router
+from django.db.models import Q
 from django.db.models.fields.proxy import OrderWrt
 from django.urls import reverse
 from django.utils import six
@@ -222,6 +223,22 @@ def get_instance(self):
                 for field in fields.values()
             })
 
+        def get_next_record(self):
+            """
+            Get the next history record for the instance. `None` if last.
+            """
+            return self.instance.history.filter(
+                Q(history_date__gt=self.history_date)
+            ).order_by('history_date').first()
+
+        def get_prev_record(self):
+            """
+            Get the previous history record for the instance. `None` if first.
+            """
+            return self.instance.history.filter(
+                Q(history_date__lt=self.history_date)
+            ).order_by('history_date').last()
+
         if self.history_id_field:
             history_id_field = self.history_id_field
             history_id_field.primary_key = True
@@ -252,6 +269,8 @@ def get_instance(self):
             ),
             'instance': property(get_instance),
             'instance_type': model,
+            'next_record': property(get_next_record),
+            'prev_record': property(get_prev_record),
             'revert_url': revert_url,
             '__str__': lambda self: '%s as of %s' % (self.history_object,
                                                      self.history_date)

simple_history/tests/tests/test_models.py

@@ -382,6 +382,80 @@ def test_uuid_default_history_id(self):
         history = entry.history.all()[0]
         self.assertTrue(isinstance(history.history_id, uuid.UUID))
 
+    def test_get_prev_record(self):
+        poll = Poll(question="what's up?", pub_date=today)
+        poll.save()
+        poll.question = "ask questions?"
+        poll.save()
+        poll.question = "eh?"
+        poll.save()
+        poll.question = "one more?"
+        poll.save()
+        first_record = poll.history.filter(question="what's up?").get()
+        second_record = poll.history.filter(question="ask questions?").get()
+        third_record = poll.history.filter(question="eh?").get()
+        fourth_record = poll.history.filter(question="one more?").get()
+        self.assertIsNone(first_record.prev_record)
+
+        def assertRecordsMatch(record_a, record_b):
+            self.assertEqual(record_a, record_b)
+            self.assertEqual(record_a.question, record_b.question)
+        assertRecordsMatch(second_record.prev_record, first_record)
+        assertRecordsMatch(third_record.prev_record, second_record)
+        assertRecordsMatch(fourth_record.prev_record, third_record)
+
+    def test_get_prev_record_none_if_only(self):
+        poll = Poll(question="what's up?", pub_date=today)
+        poll.save()
+        self.assertEqual(poll.history.count(), 1)
+        record = poll.history.get()
+        self.assertIsNone(record.prev_record)
+
+    def test_get_prev_record_none_if_earliest(self):
+        poll = Poll(question="what's up?", pub_date=today)
+        poll.save()
+        poll.question = "ask questions?"
+        poll.save()
+        first_record = poll.history.filter(question="what's up?").get()
+        self.assertIsNone(first_record.prev_record)
+
+    def test_get_next_record(self):
+        poll = Poll(question="what's up?", pub_date=today)
+        poll.save()
+        poll.question = "ask questions?"
+        poll.save()
+        poll.question = "eh?"
+        poll.save()
+        poll.question = "one more?"
+        poll.save()
+        first_record = poll.history.filter(question="what's up?").get()
+        second_record = poll.history.filter(question="ask questions?").get()
+        third_record = poll.history.filter(question="eh?").get()
+        fourth_record = poll.history.filter(question="one more?").get()
+        self.assertIsNone(fourth_record.next_record)
+
+        def assertRecordsMatch(record_a, record_b):
+            self.assertEqual(record_a, record_b)
+            self.assertEqual(record_a.question, record_b.question)
+        assertRecordsMatch(first_record.next_record, second_record)
+        assertRecordsMatch(second_record.next_record, third_record)
+        assertRecordsMatch(third_record.next_record, fourth_record)
+
+    def test_get_next_record_none_if_only(self):
+        poll = Poll(question="what's up?", pub_date=today)
+        poll.save()
+        self.assertEqual(poll.history.count(), 1)
+        record = poll.history.get()
+        self.assertIsNone(record.next_record)
+
+    def test_get_next_record_none_if_most_recent(self):
+        poll = Poll(question="what's up?", pub_date=today)
+        poll.save()
+        poll.question = "ask questions?"
+        poll.save()
+        recent_record = poll.history.filter(question="ask questions?").get()
+        self.assertIsNone(recent_record.next_record)
+
 
 class CreateHistoryModelTests(unittest.TestCase):