From 8513231192aba4e52d51bbe708dc716f162e6a3a Mon Sep 17 00:00:00 2001
From: Anders <6058745+ddabble@users.noreply.github.com>
Date: Sun, 10 Mar 2024 23:00:38 +0100
Subject: [PATCH] Deprecated simple_history_admin_list.display_list

---
 CHANGES.rst                                       |  2 ++
 .../templatetags/simple_history_admin_list.py     | 15 +++++++++++++++
 simple_history/tests/tests/test_deprecation.py    | 13 +++++++++++++
 3 files changed, 30 insertions(+)
 create mode 100644 simple_history/templatetags/simple_history_admin_list.py
 create mode 100644 simple_history/tests/tests/test_deprecation.py

diff --git a/CHANGES.rst b/CHANGES.rst
index 14871005..5b79975d 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -12,6 +12,8 @@ Unreleased
   ``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
diff --git a/simple_history/templatetags/simple_history_admin_list.py b/simple_history/templatetags/simple_history_admin_list.py
new file mode 100644
index 00000000..b6546784
--- /dev/null
+++ b/simple_history/templatetags/simple_history_admin_list.py
@@ -0,0 +1,15 @@
+import warnings
+
+from django import template
+
+register = template.Library()
+
+
+@register.inclusion_tag("simple_history/object_history_list.html", takes_context=True)
+def display_list(context):
+    warnings.warn(
+        "'include' the context variable 'object_history_list_template' instead."
+        " This will be removed in version 3.8.",
+        DeprecationWarning,
+    )
+    return context
diff --git a/simple_history/tests/tests/test_deprecation.py b/simple_history/tests/tests/test_deprecation.py
new file mode 100644
index 00000000..7c8ca999
--- /dev/null
+++ b/simple_history/tests/tests/test_deprecation.py
@@ -0,0 +1,13 @@
+import unittest
+
+from simple_history import __version__
+from simple_history.templatetags.simple_history_admin_list import display_list
+
+
+class DeprecationWarningTest(unittest.TestCase):
+    def test__display_list__warns_deprecation_and_is_yet_to_be_removed(self):
+        with self.assertWarns(DeprecationWarning):
+            display_list({})
+        # DEV: `display_list()` (and the file `simple_history_admin_list.py`) should be
+        #      removed when 3.8 is released
+        self.assertLess(__version__, "3.8")