added the possibility to create a relation to the original model (#536)

* added the possibility to create a relation to the original model

* added some tests for related_name

* reformatted using black

* added myself to AUTHORS.rst

* Preventing the related name from being the same as the history manager

* Added test to check related name for equality to manager

* Rearranged myself in alphabetical order

* Added changes to CHANGES.rst

* Added some documentation

* db_constraint added and do not set instance of history_relation when deleting

* Keeping relation after delete

* Test if the relation works again after deleting and restoring the object

* Revert test extended

* Updated version in CHANGES to unreleased

Author: nick-traeger

AUTHORS.rst

@@ -68,6 +68,7 @@ Authors
 - Mike Spainhower
 - Nathan Villagaray-Carski (`ncvc <https://github.com/ncvc>`_)
 - Nianpeng Li
+- Nick Träger
 - Phillip Marshall
 - Rajesh Pappula
 - Ray Logel

CHANGES.rst

@@ -4,6 +4,10 @@ Changes
 - remove reference to vendored library ``django.utils.six`` in favor of ``six`` (gh-526)
 - Fixed hardcoded history manager (gh-540)
 
+Unreleased
+----------
+- Added the possibility to create a relation to the original model
+
 2.7.0 (2019-01-16)
 ------------------
 - Add support for ``using`` chained manager method and save/delete keyword argument (gh-507)

docs/querying_history.rst

@@ -147,3 +147,18 @@ If you want to save a model without a historical record, you can use the followi
 
     poll = Poll(question='something')
     poll.save_without_historical_record()
+
+
+Filtering data using a relationship to the model
+------------------------------------------------
+
+To filter changes to the data, a relationship to the history can be established. For example, all data records in which a particular user was involved.
+
+.. code-block:: python
+
+    class Poll(models.Model):
+        question = models.CharField(max_length=200)
+        log = HistoricalRecords(related_name='history')
+
+
+    Poll.objects.filter(history__history_user=4)

simple_history/exceptions.py

@@ -13,3 +13,9 @@ class NotHistoricalModelError(TypeError):
     """No related history model found."""
 
     pass
+
+
+class RelatedNameConflictError(Exception):
+    """Related name conflicting with history manager"""
+
+    pass

simple_history/models.py

@@ -78,6 +78,7 @@ def __init__(
         history_user_id_field=None,
         history_user_getter=_history_user_getter,
         history_user_setter=_history_user_setter,
+        related_name=None,
     ):
         self.user_set_verbose_name = verbose_name
         self.user_related_name = user_related_name
@@ -93,6 +94,7 @@ def __init__(
         self.user_id_field = history_user_id_field
         self.user_getter = history_user_getter
         self.user_setter = history_user_setter
+        self.related_name = related_name
 
         if excluded_fields is None:
             excluded_fields = []
@@ -315,6 +317,23 @@ def _get_history_user_fields(self):
 
         return history_user_fields
 
+    def _get_history_related_field(self, model):
+        if self.related_name:
+            if self.manager_name == self.related_name:
+                raise exceptions.RelatedNameConflictError(
+                    "The related name must not be called like the history manager."
+                )
+            return {
+                "history_relation": models.ForeignKey(
+                    model,
+                    on_delete=models.DO_NOTHING,
+                    related_name=self.related_name,
+                    db_constraint=False,
+                )
+            }
+        else:
+            return {}
+
     def get_extra_fields(self, model, fields):
         """Return dict of extra fields added to the historical record model"""
 
@@ -387,6 +406,7 @@ def get_prev_record(self):
             ),
         }
 
+        extra_fields.update(self._get_history_related_field(model))
         extra_fields.update(self._get_history_user_fields())
 
         return extra_fields
@@ -432,6 +452,10 @@ def create_historical_record(self, instance, history_type, using=None):
         for field in self.fields_included(instance):
             attrs[field.attname] = getattr(instance, field.attname)
 
+        relation_field = getattr(manager.model, "history_relation", None)
+        if relation_field is not None:
+            attrs["history_relation"] = instance
+
         history_instance = manager.model(
             history_date=history_date,
             history_type=history_type,

simple_history/tests/models.py

@@ -567,3 +567,8 @@ class ForeignKeyToSelfModel(models.Model):
         "self", null=True, related_name="+", on_delete=models.CASCADE
     )
     history = HistoricalRecords()
+
+
+class Street(models.Model):
+    name = models.CharField(max_length=150)
+    log = HistoricalRecords(related_name="history")

simple_history/tests/tests/test_models.py

@@ -15,6 +15,8 @@
 from django.test import TestCase, override_settings
 from django.urls import reverse
 
+from simple_history import register
+from simple_history.exceptions import RelatedNameConflictError
 from simple_history.models import HistoricalRecords, ModelChange
 from simple_history.signals import pre_create_historical_record
 from simple_history.tests.custom_user.models import CustomUser
@@ -74,6 +76,7 @@
     Series,
     SeriesWork,
     State,
+    Street,
     Temperature,
     UUIDDefaultModel,
     UUIDModel,
@@ -1413,3 +1416,65 @@ def test_history_user_does_not_exist(self):
 
         self.assertEqual(user_id, instance.history.first().history_user_id)
         self.assertIsNone(instance.history.first().history_user)
+
+
+class RelatedNameTest(TestCase):
+    def setUp(self):
+        self.user_one = get_user_model().objects.create(
+            username="username_one", email="[email protected]", password="top_secret"
+        )
+        self.user_two = get_user_model().objects.create(
+            username="username_two", email="[email protected]", password="top_secret"
+        )
+
+        self.one = Street(name="Test Street")
+        self.one._history_user = self.user_one
+        self.one.save()
+
+        self.two = Street(name="Sesame Street")
+        self.two._history_user = self.user_two
+        self.two.save()
+
+        self.one.name = "ABC Street"
+        self.one._history_user = self.user_two
+        self.one.save()
+
+    def test_relation(self):
+        self.assertEqual(self.one.history.count(), 2)
+        self.assertEqual(self.two.history.count(), 1)
+
+    def test_filter(self):
+        self.assertEqual(
+            Street.objects.filter(history__history_user=self.user_one.pk).count(), 1
+        )
+        self.assertEqual(
+            Street.objects.filter(history__history_user=self.user_two.pk).count(), 2
+        )
+
+    def test_name_equals_manager(self):
+        with self.assertRaises(RelatedNameConflictError):
+            register(Place, manager_name="history", related_name="history")
+
+    def test_deletion(self):
+        self.two.delete()
+
+        self.assertEqual(Street.log.filter(history_relation=2).count(), 2)
+        self.assertEqual(Street.log.count(), 4)
+
+    def test_revert(self):
+        id = self.one.pk
+
+        self.one.delete()
+        self.assertEqual(
+            Street.objects.filter(history__history_user=self.user_one.pk).count(), 0
+        )
+        self.assertEqual(Street.objects.filter(pk=id).count(), 0)
+
+        old = Street.log.filter(id=id).first()
+        old.history_object.save()
+        self.assertEqual(
+            Street.objects.filter(history__history_user=self.user_one.pk).count(), 1
+        )
+
+        self.one = Street.objects.get(pk=id)
+        self.assertEqual(self.one.history.count(), 4)