Refactored ModelDelta + ModelChange as dataclasses

This gives them useful methods like `__eq__()`, `__repr__()` and
`__hash__()` for free :)

Note that they have `frozen=True` (mainly to allow safe `__hash__()`
implementations), as I think the vast majority of users are in practice
treating these classes as read-only; modifying them serve no purpose
within this library, and should therefore be an incredibly niche use
case (except when comparing against expected mock objects while testing,
but then `dataclasses.replace()` can be used).

Author: ddabble

CHANGES.rst

@@ -15,6 +15,8 @@ Unreleased
   is used to list the historical records (gh-1128)
 - Added ``SimpleHistoryAdmin.get_history_list_display()`` which returns
   ``history_list_display`` by default, and made the latter into an actual field (gh-1128)
+- ``ModelDelta`` and ``ModelChange`` (in ``simple_history.models``) are now immutable
+  dataclasses; their signatures remain unchanged (gh-1128)
 
 3.5.0 (2024-02-19)
 ------------------

simple_history/models.py

@@ -2,7 +2,9 @@
 import importlib
 import uuid
 import warnings
+from dataclasses import dataclass
 from functools import partial
+from typing import Any, Dict, List, Sequence, Union
 
 import django
 from django.apps import apps
@@ -1006,16 +1008,16 @@ def diff_against(self, old_history, excluded_fields=None, included_fields=None):
         return ModelDelta(changes, changed_fields, old_history, self)
 
 
+@dataclass(frozen=True)
 class ModelChange:
-    def __init__(self, field_name, old_value, new_value):
-        self.field = field_name
-        self.old = old_value
-        self.new = new_value
+    field: str
+    old: Union[Any, List[Dict[str, Any]]]
+    new: Union[Any, List[Dict[str, Any]]]
 
 
+@dataclass(frozen=True)
 class ModelDelta:
-    def __init__(self, changes, changed_fields, old_record, new_record):
-        self.changes = changes
-        self.changed_fields = changed_fields
-        self.old_record = old_record
-        self.new_record = new_record
+    changes: Sequence[ModelChange]
+    changed_fields: Sequence[str]
+    old_record: HistoricalChanges
+    new_record: HistoricalChanges

simple_history/tests/tests/test_models.py

@@ -1,3 +1,4 @@
+import dataclasses
 import unittest
 import uuid
 import warnings
@@ -21,6 +22,7 @@
     SIMPLE_HISTORY_REVERSE_ATTR_NAME,
     HistoricalRecords,
     ModelChange,
+    ModelDelta,
     is_historic,
     to_historic,
 )
@@ -697,11 +699,13 @@ def test_history_diff_includes_changed_fields(self):
         new_record, old_record = p.history.all()
         with self.assertNumQueries(0):
             delta = new_record.diff_against(old_record)
-        expected_change = ModelChange("question", "what's up?", "what's up, man")
-        self.assertEqual(delta.changed_fields, ["question"])
-        self.assertEqual(delta.old_record, old_record)
-        self.assertEqual(delta.new_record, new_record)
-        self.assertEqual(expected_change.field, delta.changes[0].field)
+        expected_delta = ModelDelta(
+            [ModelChange("question", "what's up?", "what's up, man?")],
+            ["question"],
+            old_record,
+            new_record,
+        )
+        self.assertEqual(delta, expected_delta)
 
     def test_history_diff_does_not_include_unchanged_fields(self):
         p = Poll.objects.create(question="what's up?", pub_date=today)
@@ -720,11 +724,13 @@ def test_history_diff_includes_changed_fields_of_base_model(self):
         new_record, old_record = r.history.all()
         with self.assertNumQueries(0):
             delta = new_record.diff_against(old_record)
-        expected_change = ModelChange("name", "McDonna", "DonnutsKing")
-        self.assertEqual(delta.changed_fields, ["name"])
-        self.assertEqual(delta.old_record, old_record)
-        self.assertEqual(delta.new_record, new_record)
-        self.assertEqual(expected_change.field, delta.changes[0].field)
+        expected_delta = ModelDelta(
+            [ModelChange("name", "McDonna", "DonnutsKing")],
+            ["name"],
+            old_record,
+            new_record,
+        )
+        self.assertEqual(delta, expected_delta)
 
     def test_history_table_name_is_not_inherited(self):
         def assert_table_name(obj, expected_table_name):
@@ -759,8 +765,8 @@ def test_history_diff_with_excluded_fields(self):
         new_record, old_record = p.history.all()
         with self.assertNumQueries(0):
             delta = new_record.diff_against(old_record, excluded_fields=("question",))
-        self.assertEqual(delta.changed_fields, [])
-        self.assertEqual(delta.changes, [])
+        expected_delta = ModelDelta([], [], old_record, new_record)
+        self.assertEqual(delta, expected_delta)
 
     def test_history_diff_with_included_fields(self):
         p = Poll.objects.create(question="what's up?", pub_date=today)
@@ -769,13 +775,17 @@ def test_history_diff_with_included_fields(self):
         new_record, old_record = p.history.all()
         with self.assertNumQueries(0):
             delta = new_record.diff_against(old_record, included_fields=[])
-        self.assertEqual(delta.changed_fields, [])
-        self.assertEqual(delta.changes, [])
+        expected_delta = ModelDelta([], [], old_record, new_record)
+        self.assertEqual(delta, expected_delta)
 
         with self.assertNumQueries(0):
             delta = new_record.diff_against(old_record, included_fields=["question"])
-        self.assertEqual(delta.changed_fields, ["question"])
-        self.assertEqual(len(delta.changes), 1)
+        expected_delta = dataclasses.replace(
+            expected_delta,
+            changes=[ModelChange("question", "what's up?", "what's up, man?")],
+            changed_fields=["question"],
+        )
+        self.assertEqual(delta, expected_delta)
 
     def test_history_diff_with_non_editable_field(self):
         p = PollWithNonEditableField.objects.create(
@@ -786,8 +796,13 @@ def test_history_diff_with_non_editable_field(self):
         new_record, old_record = p.history.all()
         with self.assertNumQueries(0):
             delta = new_record.diff_against(old_record)
-        self.assertEqual(delta.changed_fields, ["question"])
-        self.assertEqual(len(delta.changes), 1)
+        expected_delta = ModelDelta(
+            [ModelChange("question", "what's up?", "what's up, man?")],
+            ["question"],
+            old_record,
+            new_record,
+        )
+        self.assertEqual(delta, expected_delta)
 
     def test_history_with_unknown_field(self):
         p = Poll.objects.create(question="what's up?", pub_date=today)
@@ -1922,7 +1937,6 @@ def test_self_field(self):
 class ManyToManyWithSignalsTest(TestCase):
     def setUp(self):
         self.model = PollWithManyToManyWithIPAddress
-        # self.historical_through_model = self.model.history.
         self.places = (
             Place.objects.create(name="London"),
             Place.objects.create(name="Paris"),
@@ -1963,9 +1977,26 @@ def test_diff(self):
         old = new.prev_record
 
         delta = new.diff_against(old)
-
-        self.assertEqual("places", delta.changes[0].field)
-        self.assertEqual(2, len(delta.changes[0].new))
+        expected_delta = ModelDelta(
+            [
+                ModelChange(
+                    "places",
+                    [],
+                    [
+                        {
+                            "pollwithmanytomanywithipaddress": self.poll.pk,
+                            "place": place.pk,
+                            "ip_address": "192.168.0.1",
+                        }
+                        for place in self.places
+                    ],
+                )
+            ],
+            ["places"],
+            old,
+            new,
+        )
+        self.assertEqual(delta, expected_delta)
 
 
 class ManyToManyCustomIDTest(TestCase):
@@ -2246,24 +2277,19 @@ def test_diff_against(self):
         expected_change = ModelChange(
             "places", [], [{"pollwithmanytomany": self.poll.pk, "place": self.place.pk}]
         )
-        self.assertEqual(delta.changed_fields, ["places"])
-        self.assertEqual(delta.old_record, create_record)
-        self.assertEqual(delta.new_record, add_record)
-        self.assertEqual(expected_change.field, delta.changes[0].field)
-
-        self.assertListEqual(expected_change.new, delta.changes[0].new)
-        self.assertListEqual(expected_change.old, delta.changes[0].old)
+        expected_delta = ModelDelta(
+            [expected_change], ["places"], create_record, add_record
+        )
+        self.assertEqual(delta, expected_delta)
 
         delta = add_record.diff_against(create_record, included_fields=["places"])
-        self.assertEqual(delta.changed_fields, ["places"])
-        self.assertEqual(delta.old_record, create_record)
-        self.assertEqual(delta.new_record, add_record)
-        self.assertEqual(expected_change.field, delta.changes[0].field)
+        self.assertEqual(delta, expected_delta)
 
         delta = add_record.diff_against(create_record, excluded_fields=["places"])
-        self.assertEqual(delta.changed_fields, [])
-        self.assertEqual(delta.old_record, create_record)
-        self.assertEqual(delta.new_record, add_record)
+        expected_delta = dataclasses.replace(
+            expected_delta, changes=[], changed_fields=[]
+        )
+        self.assertEqual(delta, expected_delta)
 
         self.poll.places.clear()
 
@@ -2272,18 +2298,16 @@ def test_diff_against(self):
         delta = del_record.diff_against(create_record)
         self.assertNotIn("places", delta.changed_fields)
 
+        delta = del_record.diff_against(add_record)
         # Second and third should have the same diffs as first and second, but with
         # old and new reversed
         expected_change = ModelChange(
             "places", [{"place": self.place.pk, "pollwithmanytomany": self.poll.pk}], []
         )
-        delta = del_record.diff_against(add_record)
-        self.assertEqual(delta.changed_fields, ["places"])
-        self.assertEqual(delta.old_record, add_record)
-        self.assertEqual(delta.new_record, del_record)
-        self.assertEqual(expected_change.field, delta.changes[0].field)
-        self.assertListEqual(expected_change.new, delta.changes[0].new)
-        self.assertListEqual(expected_change.old, delta.changes[0].old)
+        expected_delta = ModelDelta(
+            [expected_change], ["places"], add_record, del_record
+        )
+        self.assertEqual(delta, expected_delta)
 
 
 @override_settings(**database_router_override_settings)