Add system-wide custom bases settings for HistoricalRecords

- Add SIMPLE_HISTORY_CUSTOM_BASES setting for default historical model bases
- Add SIMPLE_HISTORY_CUSTOM_M2M_BASES setting for M2M historical model bases
- Explicit bases/m2m_bases parameters override settings (backward compatible)
- Add comprehensive documentation with examples
- Add test models and test cases for both settings
- All 342 tests passing

Fixes #1574

Author: rodrigo.nogueira

docs/historical_model.rst

@@ -295,6 +295,24 @@ To change the auto-generated HistoricalRecord models base class from
         history = HistoricalRecords(bases=[RoutableModel])
 
 
+You can also set a system-wide default for all HistoricalRecord base classes using
+the ``SIMPLE_HISTORY_CUSTOM_BASES`` setting in your ``settings.py`` file:
+
+.. code-block:: python
+
+    SIMPLE_HISTORY_CUSTOM_BASES = [RoutableModel, AuditModel]
+
+This setting will be used for all ``HistoricalRecords`` instances that don't explicitly
+specify a ``bases`` parameter. The explicit ``bases`` parameter always takes precedence
+over this setting, allowing you to override the global default on a per-model basis.
+
+For many-to-many historical models, you can use:
+
+.. code-block:: python
+
+    SIMPLE_HISTORY_CUSTOM_M2M_BASES = [M2MRoutableModel]
+
+
 Excluded Fields
 --------------------------------
 

simple_history/models.py

@@ -153,12 +153,26 @@ def __init__(
         if excluded_field_kwargs is None:
             excluded_field_kwargs = {}
         self.excluded_field_kwargs = excluded_field_kwargs
+
+        if bases == (models.Model,):
+            custom_bases = getattr(settings, "SIMPLE_HISTORY_CUSTOM_BASES", None)
+            if custom_bases is not None:
+                bases = custom_bases
+
         try:
             if isinstance(bases, str):
                 raise TypeError
             self.bases = (HistoricalChanges,) + tuple(bases)
         except TypeError:
             raise TypeError("The `bases` option must be a list or a tuple.")
+
+        if m2m_bases == (models.Model,):
+            custom_m2m_bases = getattr(
+                settings, "SIMPLE_HISTORY_CUSTOM_M2M_BASES", None
+            )
+            if custom_m2m_bases is not None:
+                m2m_bases = custom_m2m_bases
+
         try:
             if isinstance(m2m_bases, str):
                 raise TypeError

simple_history/tests/models.py

@@ -479,6 +479,43 @@ class ConcreteUtil(AbstractBase):
 register(ConcreteUtil, bases=[AbstractBase])
 
 
+# Test SIMPLE_HISTORY_CUSTOM_BASES setting
+setattr(settings, "SIMPLE_HISTORY_CUSTOM_BASES", [IPAddressHistoricalModel])
+
+
+class PollWithDefaultCustomBases(models.Model):
+    question = models.CharField(max_length=200)
+    history = HistoricalRecords()
+
+
+class PollWithExplicitBasesOverride(models.Model):
+    question = models.CharField(max_length=200)
+    history = HistoricalRecords(bases=[SessionsHistoricalModel])
+
+
+delattr(settings, "SIMPLE_HISTORY_CUSTOM_BASES")
+
+
+# Test SIMPLE_HISTORY_CUSTOM_M2M_BASES setting
+setattr(settings, "SIMPLE_HISTORY_CUSTOM_M2M_BASES", [IPAddressHistoricalModel])
+
+
+class PollWithDefaultCustomM2MBases(models.Model):
+    question = models.CharField(max_length=200)
+    places = models.ManyToManyField("Place")
+    history = HistoricalRecords(m2m_fields=[places])
+
+
+class PollWithExplicitM2MBasesOverride(models.Model):
+    question = models.CharField(max_length=200)
+    places = models.ManyToManyField("Place")
+    history = HistoricalRecords(m2m_fields=[places], m2m_bases=[SessionsHistoricalModel])
+
+
+delattr(settings, "SIMPLE_HISTORY_CUSTOM_M2M_BASES")
+
+
+
 class MultiOneToOne(models.Model):
     fk = models.ForeignKey(SecondLevelInheritedModel, on_delete=models.CASCADE)
 

simple_history/tests/tests/test_models.py

@@ -97,6 +97,10 @@
     PollWithManyToMany,
     PollWithManyToManyCustomHistoryID,
     PollWithManyToManyWithIPAddress,
+    PollWithDefaultCustomBases,
+    PollWithExplicitBasesOverride,
+    PollWithDefaultCustomM2MBases,
+    PollWithExplicitM2MBasesOverride,
     PollWithNonEditableField,
     PollWithQuerySetCustomizations,
     PollWithSelfManyToMany,
@@ -1476,6 +1480,65 @@ def test_invalid_bases(self):
         for bases in invalid_bases:
             self.assertRaises(TypeError, HistoricalRecords, bases=bases)
 
+    def test_custom_bases_from_settings(self):
+        """Test that SIMPLE_HISTORY_CUSTOM_BASES setting is correctly applied."""
+        # PollWithDefaultCustomBases was created with SIMPLE_HISTORY_CUSTOM_BASES=[IPAddressHistoricalModel]
+        history_model = PollWithDefaultCustomBases.history.model
+        # Check that IPAddressHistoricalModel is in the MRO
+        self.assertIn(
+            "IPAddressHistoricalModel",
+            [cls.__name__ for cls in history_model.__mro__],
+        )
+        # Verify the historical model has ip_address field from IPAddressHistoricalModel
+        self.assertTrue(hasattr(history_model, "ip_address"))
+
+    def test_custom_bases_explicit_overrides_setting(self):
+        """Test that explicit bases parameter overrides SIMPLE_HISTORY_CUSTOM_BASES."""
+        # PollWithExplicitBasesOverride was created with explicit bases=[SessionsHistoricalModel]
+        # even though SIMPLE_HISTORY_CUSTOM_BASES was set to [IPAddressHistoricalModel]
+        history_model = PollWithExplicitBasesOverride.history.model
+        # Should have SessionsHistoricalModel, not IPAddressHistoricalModel
+        self.assertIn(
+            "SessionsHistoricalModel",
+            [cls.__name__ for cls in history_model.__mro__],
+        )
+        self.assertTrue(hasattr(history_model, "session"))
+        # Should NOT have ip_address from IPAddressHistoricalModel
+        self.assertFalse(hasattr(history_model, "ip_address"))
+
+    def test_custom_m2m_bases_from_settings(self):
+        """Test that SIMPLE_HISTORY_CUSTOM_M2M_BASES setting is correctly applied."""
+        # PollWithDefaultCustomM2MBases was created with SIMPLE_HISTORY_CUSTOM_M2M_BASES=[IPAddressHistoricalModel]
+        # Get the M2M historical model by its generated name
+        from django.apps import apps
+        m2m_history_model = apps.get_model(
+            "tests", "HistoricalPollWithDefaultCustomM2MBases_places"
+        )
+        # Check that IPAddressHistoricalModel is in the MRO
+        self.assertIn(
+            "IPAddressHistoricalModel",
+            [cls.__name__ for cls in m2m_history_model.__mro__],
+        )
+        # Verify the M2M historical model has ip_address field
+        self.assertTrue(hasattr(m2m_history_model, "ip_address"))
+
+    def test_custom_m2m_bases_explicit_overrides_setting(self):
+        """Test that explicit m2m_bases parameter overrides SIMPLE_HISTORY_CUSTOM_M2M_BASES."""
+        # PollWithExplicitM2MBasesOverride was created with explicit m2m_bases=[SessionsHistoricalModel]
+        # even though SIMPLE_HISTORY_CUSTOM_M2M_BASES was set to [IPAddressHistoricalModel]
+        from django.apps import apps
+        m2m_history_model = apps.get_model(
+            "tests", "HistoricalPollWithExplicitM2MBasesOverride_places"
+        )
+        # Should have SessionsHistoricalModel, not IPAddressHistoricalModel
+        self.assertIn(
+            "SessionsHistoricalModel",
+            [cls.__name__ for cls in m2m_history_model.__mro__],
+        )
+        self.assertTrue(hasattr(m2m_history_model, "session"))
+        # Should NOT have ip_address from IPAddressHistoricalModel
+        self.assertFalse(hasattr(m2m_history_model, "ip_address"))
+
     def test_import_related(self):
         field_object = HistoricalChoice._meta.get_field("poll")
         related_model = field_object.remote_field.related_model