Merge pull request #1128 from raunaq-sailo/feat/adding-history-diff

Add history diff column to admin change history table

Author: ddabble

.pre-commit-config.yaml

@@ -4,8 +4,7 @@ repos:
     rev: 1.7.8
     hooks:
       - id: bandit
-        args:
-          - "-x *test*.py"
+        exclude: /.*tests/
 
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 24.3.0

CHANGES.rst

@@ -5,6 +5,26 @@ Unreleased
 ----------
 
 - Support custom History ``Manager`` and ``QuerySet`` classes (gh-1280)
+- Renamed the (previously internal) admin template
+  ``simple_history/_object_history_list.html`` to
+  ``simple_history/object_history_list.html``, and added the field
+  ``SimpleHistoryAdmin.object_history_list_template`` for overriding it (gh-1128)
+- Deprecated the undocumented template tag ``simple_history_admin_list.display_list()``;
+  it will be removed in version 3.8 (gh-1128)
+- Added ``SimpleHistoryAdmin.get_history_queryset()`` for overriding which ``QuerySet``
+  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)
+- ``ModelDelta``'s ``changes`` and ``changed_fields`` are now sorted alphabetically by
+  field name. Also, if ``ModelChange`` is for an M2M field, its ``old`` and ``new``
+  lists are sorted by the related object. This should help prevent flaky tests. (gh-1128)
+- ``diff_against()`` has a new keyword argument, ``foreign_keys_are_objs``;
+  see usage in the docs under "History Diffing" (gh-1128)
+- Added a "Changes" column to ``SimpleHistoryAdmin``'s object history table, listing
+  the changes between each historical record of the object; see the docs under
+  "Customizing the History Admin Templates" for overriding its template context (gh-1128)
 
 3.5.0 (2024-02-19)
 ------------------

docs/admin.rst

@@ -69,6 +69,43 @@ admin class
 
 .. image:: screens/5_history_list_display.png
 
+
+Customizing the History Admin Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you'd like to customize the HTML of ``SimpleHistoryAdmin``'s object history pages,
+you can override the following attributes with the names of your own templates:
+
+- ``object_history_template``: The main object history page, which includes (inserts)
+  ``object_history_list_template``.
+- ``object_history_list_template``: The table listing an object's historical records and
+  the changes made between them.
+- ``object_history_form_template``: The form pre-filled with the details of an object's
+  historical record, which also allows you to revert the object to a previous version.
+
+If you'd like to only customize certain parts of the mentioned templates, look for
+``block`` template tags in the source code that you can override - like the
+``history_delta_changes`` block in ``simple_history/object_history_list.html``,
+which lists the changes made between each historical record.
+
+Customizing Context
+^^^^^^^^^^^^^^^^^^^
+
+You can also customize the template context by overriding the following methods:
+
+- ``render_history_view()``: Called by both ``history_view()`` and
+  ``history_form_view()`` before the templates are rendered. Customize the context by
+  changing the ``context`` parameter.
+- ``history_view()``: Returns a rendered ``object_history_template``.
+  Inject context by calling the super method with the ``extra_context`` argument.
+- ``get_historical_record_context_helper()``: Returns an instance of
+  ``simple_history.template_utils.HistoricalRecordContextHelper`` that's used to format
+  some template context for each historical record displayed through ``history_view()``.
+  Customize the context by extending the mentioned class and overriding its methods.
+- ``history_form_view()``: Returns a rendered ``object_history_form_template``.
+  Inject context by calling the super method with the ``extra_context`` argument.
+
+
 Disabling the option to revert an object
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/historical_model.rst

@@ -554,7 +554,6 @@ You will see the many to many changes when diffing between two historical record
     informal = Category.objects.create(name="informal questions")
     official = Category.objects.create(name="official questions")
     p = Poll.objects.create(question="what's up?")
-    p.save()
     p.categories.add(informal, official)
     p.categories.remove(informal)
 

docs/history_diffing.rst

@@ -1,24 +1,110 @@
 History Diffing
 ===============
 
-When you have two instances of the same ``HistoricalRecord`` (such as the ``HistoricalPoll`` example above),
-you can perform diffs to see what changed. This will result in a ``ModelDelta`` containing the following properties:
+When you have two instances of the same historical model
+(such as the ``HistoricalPoll`` example above),
+you can perform a diff using the ``diff_against()`` method to see what changed.
+This will return a ``ModelDelta`` object with the following attributes:
 
-1. A list with each field changed between the two historical records
-2. A list with the names of all fields that incurred changes from one record to the other
-3. the old and new records.
+- ``old_record`` and ``new_record``: The old and new history records
+- ``changed_fields``: A list of the names of all fields that were changed between
+  ``old_record`` and ``new_record``, in alphabetical order
+- ``changes``: A list of ``ModelChange`` objects - one for each field in
+  ``changed_fields``, in the same order.
+  These objects have the following attributes:
 
-This may be useful when you want to construct timelines and need to get only the model modifications.
+  - ``field``: The name of the changed field
+    (this name is equal to the corresponding field in ``changed_fields``)
+  - ``old`` and ``new``: The old and new values of the changed field
+
+    - For many-to-many fields, these values will be lists of dicts from the through
+      model field names to the primary keys of the through model's related objects.
+      The lists are sorted by the value of the many-to-many related object.
+
+This may be useful when you want to construct 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()
+    poll = Poll.objects.create(question="what's up?")
+    poll.question = "what's up, man?"
+    poll.save()
 
-    new_record, old_record = p.history.all()
+    new_record, old_record = poll.history.all()
     delta = new_record.diff_against(old_record)
     for change in delta.changes:
-        print("{} changed from {} to {}".format(change.field, change.old, change.new))
+        print(f"'{change.field}' changed from '{change.old}' to '{change.new}'")
+
+    # Output:
+    # 'question' changed from 'what's up?' to 'what's up, man?'
+
+``diff_against()`` also accepts the following additional arguments:
+
+- ``excluded_fields`` and ``included_fields``: These can be used to either explicitly
+  exclude or include fields from being diffed, respectively.
+- ``foreign_keys_are_objs``:
+
+  - If ``False`` (default): The diff will only contain the raw primary keys of any
+    ``ForeignKey`` fields.
+  - If ``True``: The diff will contain the actual related model objects instead of just
+    the primary keys.
+    Deleted related objects (both foreign key objects and many-to-many objects)
+    will be instances of ``DeletedObject``, which only contain a ``model`` field with a
+    reference to the deleted object's model, as well as a ``pk`` field with the value of
+    the deleted object's primary key.
+
+    Note that this will add extra database queries for each related field that's been
+    changed - as long as the related objects have not been prefetched
+    (using e.g. ``select_related()``).
+
+  A couple examples showing the difference:
+
+  .. code-block:: python
+
+      # --- Effect on foreign key fields ---
+
+      whats_up = Poll.objects.create(pk=15, name="what's up?")
+      still_around = Poll.objects.create(pk=31, name="still around?")
+
+      choice = Choice.objects.create(poll=whats_up)
+      choice.poll = still_around
+      choice.save()
+
+      new, old = choice.history.all()
+
+      default_delta = new.diff_against(old)
+      # Printing the changes of `default_delta` will output:
+      # 'poll' changed from '15' to '31'
+
+      delta_with_objs = new.diff_against(old, foreign_keys_are_objs=True)
+      # Printing the changes of `delta_with_objs` will output:
+      # 'poll' changed from 'what's up?' to 'still around?'
+
+      # Deleting all the polls:
+      Poll.objects.all().delete()
+      delta_with_objs = new.diff_against(old, foreign_keys_are_objs=True)
+      # Printing the changes of `delta_with_objs` will now output:
+      # 'poll' changed from 'Deleted poll (pk=15)' to 'Deleted poll (pk=31)'
+
+
+      # --- Effect on many-to-many fields ---
+
+      informal = Category.objects.create(pk=63, name="informal questions")
+      whats_up.categories.add(informal)
+
+      new = whats_up.history.latest()
+      old = new.prev_record
+
+      default_delta = new.diff_against(old)
+      # Printing the changes of `default_delta` will output:
+      # 'categories' changed from [] to [{'poll': 15, 'category': 63}]
+
+      delta_with_objs = new.diff_against(old, foreign_keys_are_objs=True)
+      # Printing the changes of `delta_with_objs` will output:
+      # 'categories' changed from [] to [{'poll': <Poll: what's up?>, 'category': <Category: informal questions>}]
 
-``diff_against`` also accepts 2 arguments ``excluded_fields`` and ``included_fields`` to either explicitly include or exclude fields from being diffed.
+      # Deleting all the categories:
+      Category.objects.all().delete()
+      delta_with_objs = new.diff_against(old, foreign_keys_are_objs=True)
+      # Printing the changes of `delta_with_objs` will now output:
+      # 'categories' changed from [] to [{'poll': <Poll: what's up?>, 'category': DeletedObject(model=<class 'models.Category'>, pk=63)}]