Support passing a callable in "custom_model_name" feature (#490)

* Move paragraph on "custom_moel_name" to advanced.rst
Add extensive documetnation on additional functionality for
"custom_moel_name" usage.

* Document Issue 489 change

* Support callable for the "custom_moel_name" option

* Additional tests for "custom_model_name" option

* Formatting fixes

* Add additional tests for "custom_model_name" feature

* Refactor the create_history_model method to simplify

* Formatting fixes

* Further refactoring to reduce complexity of method

* Fix errors in documentation per PR review

* Fix the exception raise

* If using custom_model_name results in a history class name that is the
same as the models class it is tracking then throw an error.

* Update the "custom_model_name" documentation

* Merge upstream master

* Split into multiple tests

* Fix formatting issue

* Fix duplication of the class

* Change "clazz" to "cls"

* Change logic per review request

* Fix the rebase to use the new document structure.

Author: uhurusurfa

CHANGES.rst

@@ -7,6 +7,7 @@ Changes
 - Fix router backward-compatibility issue with 2.7.0 (gh-539, gh-547)
 - Fix hardcoded history manager (gh-542)
 - Replace deprecated `django.utils.six` with `six` (gh-526)
+- Allow `custom_model_name` parameter to be a callable (gh-489)
 
 2.7.0 (2019-01-16)
 ------------------

docs/historical_model.rst

@@ -122,13 +122,42 @@ Users can specify a custom model name via the constructor on
 ``HistoricalRecords``. The common use case for this is avoiding naming conflict
 if the user already defined a model named as 'Historical' + model name.
 
+This feature provides the ability to override the default model name used for the generated history model.
+
+To configure history models to use a different name for the history model class, use an option named ``custom_model_name``.
+The value for this option can be a `string` or a `callable`.
+A simple string replaces the default name of `'Historical' + model name` with the defined string.
+The most simple use case is illustrated below using a simple string:
+
 .. code-block:: python
 
     class ModelNameExample(models.Model):
         history = HistoricalRecords(
             custom_model_name='SimpleHistoricalModelNameExample'
         )
 
+If you are using a base class for your models and want to apply a name change for the historical model
+for all models using the base class then a callable can be used.
+The callable is passed the name of the model for which the history model will be created.
+As an example using the callable mechanism, the below changes the default prefix `Historical` to `Audit`:
+
+.. code-block:: python
+
+    class Poll(models.Model):
+        question = models.CharField(max_length=200)
+        history = HistoricalRecords(custom_model_name=lambda x:f'Audit{x}')
+
+    class Opinion(models.Model):
+        opinion = models.CharField(max_length=2000)
+
+    register(Opinion, custom_model_name=lambda x:f'Audit{x}')
+    
+The resulting history class names would be `AuditPoll` and `AuditOpinion`.
+If the app the models are defined in is `yoda` then the corresponding history table names would be `yoda_auditpoll` and `yoda_auditopinion`
+ 
+IMPORTANT: Setting `custom_model_name` to `lambda x:f'{x}'` is not permitted.
+           An error will be generated and no history model created if they are the same.
+
 
 TextField as `history_change_reason`
 ------------------------------------

simple_history/models.py

@@ -168,6 +168,28 @@ def finalize(self, sender, **kwargs):
         setattr(sender, self.manager_name, descriptor)
         sender._meta.simple_history_manager_attribute = self.manager_name
 
+    def get_history_model_name(self, model):
+        if not self.custom_model_name:
+            return "Historical{}".format(model._meta.object_name)
+        # Must be trying to use a custom history model name
+        if callable(self.custom_model_name):
+            name = self.custom_model_name(model._meta.object_name)
+        else:
+            #  simple string
+            name = self.custom_model_name
+        # Desired class name cannot be same as the model it is tracking
+        if not (
+            name.lower() == model._meta.object_name.lower()
+            and model.__module__ == self.module
+        ):
+            return name
+        raise ValueError(
+            "The 'custom_model_name' option '{}' evaluates to a name that is the same "
+            "as the model it is tracking. This is not permitted.".format(
+                self.custom_model_name
+            )
+        )
+
     def create_history_model(self, model, inherited):
         """
         Creates a historical model to associate with the model provided.
@@ -198,11 +220,10 @@ def create_history_model(self, model, inherited):
         attrs.update(Meta=type(str("Meta"), (), self.get_meta_options(model)))
         if self.table_name is not None:
             attrs["Meta"].db_table = self.table_name
-        name = (
-            self.custom_model_name
-            if self.custom_model_name is not None
-            else "Historical%s" % model._meta.object_name
-        )
+
+        # Set as the default then check for overrides
+        name = self.get_history_model_name(model)
+
         registered_models[model._meta.db_table] = model
         return python_2_unicode_compatible(type(str(name), self.bases, attrs))
 

simple_history/tests/external/models.py

@@ -14,6 +14,26 @@ class Meta:
         abstract = True
 
 
+class AbstractExternal2(models.Model):
+    history = HistoricalRecords(
+        inherit=True, custom_model_name=lambda x: "Audit{}".format(x)
+    )
+
+    class Meta:
+        abstract = True
+        app_label = "external"
+
+
+class AbstractExternal3(models.Model):
+    history = HistoricalRecords(
+        inherit=True, app="external", custom_model_name=lambda x: "Audit{}".format(x)
+    )
+
+    class Meta:
+        abstract = True
+        app_label = "external"
+
+
 class ExternalModel(models.Model):
     name = models.CharField(max_length=100)
     history = HistoricalRecords()

simple_history/tests/models.py

@@ -9,7 +9,10 @@
 from simple_history import register
 from simple_history.models import HistoricalRecords
 from .custom_user.models import CustomUser as User
+
 from .external.models import AbstractExternal
+from .external.models import AbstractExternal2
+from .external.models import AbstractExternal3
 
 get_model = apps.get_model
 
@@ -566,14 +569,59 @@ class CharFieldChangeReasonModel(models.Model):
     history = HistoricalRecords()
 
 
-class CustomNameModel(models.Model):
+class CustomManagerNameModel(models.Model):
+    name = models.CharField(max_length=15)
+    log = HistoricalRecords()
+
+
+"""
+Following classes test the "custom_model_name" option
+"""
+
+
+class OverrideModelNameAsString(models.Model):
     name = models.CharField(max_length=15, unique=True)
     history = HistoricalRecords(custom_model_name="MyHistoricalCustomNameModel")
 
 
-class CustomManagerNameModel(models.Model):
-    name = models.CharField(max_length=15)
-    log = HistoricalRecords()
+class OverrideModelNameAsCallable(models.Model):
+    name = models.CharField(max_length=15, unique=True)
+    history = HistoricalRecords(custom_model_name=lambda x: "Audit{}".format(x))
+
+
+class AbstractModelCallable1(models.Model):
+    history = HistoricalRecords(
+        inherit=True, custom_model_name=lambda x: "Audit{}".format(x)
+    )
+
+    class Meta:
+        abstract = True
+
+
+class OverrideModelNameUsingBaseModel1(AbstractModelCallable1):
+    name = models.CharField(max_length=15, unique=True)
+
+
+class OverrideModelNameUsingExternalModel1(AbstractExternal2):
+    name = models.CharField(max_length=15, unique=True)
+
+
+class OverrideModelNameUsingExternalModel2(AbstractExternal3):
+    name = models.CharField(max_length=15, unique=True)
+
+
+class OverrideModelNameRegisterMethod1(models.Model):
+    name = models.CharField(max_length=15, unique=True)
+
+
+register(
+    OverrideModelNameRegisterMethod1,
+    custom_model_name="MyOverrideModelNameRegisterMethod1",
+)
+
+
+class OverrideModelNameRegisterMethod2(models.Model):
+    name = models.CharField(max_length=15, unique=True)
 
 
 class ForeignKeyToSelfModel(models.Model):

simple_history/tests/tests/test_models.py

@@ -62,6 +62,9 @@
     HistoricalPoll,
     HistoricalPollWithHistoricalIPAddress,
     HistoricalState,
+    OverrideModelNameAsCallable,
+    OverrideModelNameUsingBaseModel1,
+    MyOverrideModelNameRegisterMethod1,
     Library,
     ModelWithFkToModelWithHistoryUsingBaseModelDb,
     ModelWithHistoryInDifferentDb,
@@ -711,17 +714,72 @@ def test_create_history_model_with_multiple_one_to_ones(self):
                 "exception."
             )
 
-    def test_instantiate_history_model_with_custom_model_name(self):
+
+class CustomModelNameTests(unittest.TestCase):
+    def verify_custom_model_name_feature(
+        self, model, expected_class_name, expected_table_name
+    ):
+        history_model = model.history.model
+        self.assertEqual(history_model.__name__, expected_class_name)
+        self.assertEqual(history_model._meta.db_table, expected_table_name)
+
+    def test_instantiate_history_model_with_custom_model_name_as_string(self):
         try:
-            from ..models import MyHistoricalCustomNameModel
+            from ..models import OverrideModelNameAsString
         except ImportError:
-            self.fail("MyHistoricalCustomNameModel is in wrong module")
-        historical_model = MyHistoricalCustomNameModel()
-        self.assertEqual(
-            historical_model.__class__.__name__, "MyHistoricalCustomNameModel"
+            self.fail("{}OverrideModelNameAsString is in wrong module")
+        expected_cls_name = "MyHistoricalCustomNameModel"
+        self.verify_custom_model_name_feature(
+            OverrideModelNameAsString(),
+            expected_cls_name,
+            "tests_{}".format(expected_cls_name.lower()),
         )
-        self.assertEqual(
-            historical_model._meta.db_table, "tests_myhistoricalcustomnamemodel"
+
+    def test_register_history_model_with_custom_model_name_override(self):
+        try:
+            from ..models import OverrideModelNameRegisterMethod1
+        except ImportError:
+            self.fail("OverrideModelNameRegisterMethod1 is in wrong module")
+
+        cls = OverrideModelNameRegisterMethod1()
+        expected_cls_name = "MyOverrideModelNameRegisterMethod1"
+        self.verify_custom_model_name_feature(
+            cls, expected_cls_name, "tests_{}".format(expected_cls_name.lower())
+        )
+
+        from simple_history import register
+        from ..models import OverrideModelNameRegisterMethod2
+
+        try:
+            register(
+                OverrideModelNameRegisterMethod2,
+                custom_model_name=lambda x: "{}".format(x),
+            )
+        except ValueError:
+            self.assertRaises(ValueError)
+
+    def test_register_history_model_with_custom_model_name_from_abstract_model(self):
+        cls = OverrideModelNameUsingBaseModel1
+        expected_cls_name = "Audit{}".format(cls.__name__)
+        self.verify_custom_model_name_feature(
+            cls, expected_cls_name, "tests_" + expected_cls_name.lower()
+        )
+
+    def test_register_history_model_with_custom_model_name_from_external_model(self):
+        from ..models import OverrideModelNameUsingExternalModel1
+
+        cls = OverrideModelNameUsingExternalModel1
+        expected_cls_name = "Audit{}".format(cls.__name__)
+        self.verify_custom_model_name_feature(
+            cls, expected_cls_name, "tests_" + expected_cls_name.lower()
+        )
+
+        from ..models import OverrideModelNameUsingExternalModel2
+
+        cls = OverrideModelNameUsingExternalModel2
+        expected_cls_name = "Audit{}".format(cls.__name__)
+        self.verify_custom_model_name_feature(
+            cls, expected_cls_name, "external_" + expected_cls_name.lower()
         )