add custom_model_name to HistoricalRecords (#451)

* add custome_model_name to HistoricalRecords

* add usage documentation

* addressed review comments

* update test cases

* fix the formatting issue

* updated CHANGES.rst and AUTHORS.rst

Author: ChrisZhangCadre

AUTHORS.rst

@@ -69,6 +69,7 @@ Authors
 - Jonathan Zvesper (@zvesp)
 - Matheus Cansian (@mscansian)
 - Jim Gomez
+- Hanyin Zhang
 
 Background
 ==========

CHANGES.rst

@@ -1,6 +1,10 @@
 Changes
 =======
 
+Unreleased
+-----------
+- Add `custom_model_name` parameter to the constructor of `HistoricalRecords` (gh-451)
+
 2.5.1 (2018-10-19)
 ------------------
 - Add `'+'` as the `history_type` for each instance in `bulk_history_create` (gh-449)

docs/usage.rst

@@ -216,6 +216,23 @@ or
         )
 
 
+Custom model name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, historical model is named as 'Historical' + model name. For
+example, historical records for ``Choice`` is called ``HistoricalChoice``.
+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.
+
+.. code-block:: python
+
+    class ModelNameExample(models.Model):
+        history = HistoricalRecords(
+            custom_model_name='SimpleHistoricalModelNameExample'
+        )
+
+
 Querying history
 ----------------
 

simple_history/models.py

@@ -43,7 +43,7 @@ def __init__(self, verbose_name=None, bases=(models.Model,),
                  excluded_fields=None, history_id_field=None,
                  history_change_reason_field=None,
                  user_model=None, get_user=default_get_user,
-                 cascade_delete_history=False):
+                 cascade_delete_history=False, custom_model_name=None):
         self.user_set_verbose_name = verbose_name
         self.user_related_name = user_related_name
         self.table_name = table_name
@@ -53,6 +53,7 @@ def __init__(self, verbose_name=None, bases=(models.Model,),
         self.user_model = user_model
         self.get_user = get_user
         self.cascade_delete_history = cascade_delete_history
+        self.custom_model_name = custom_model_name
         if excluded_fields is None:
             excluded_fields = []
         self.excluded_fields = excluded_fields
@@ -150,7 +151,8 @@ 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 = 'Historical%s' % model._meta.object_name
+        name = self.custom_model_name if self.custom_model_name is not None \
+            else 'Historical%s' % model._meta.object_name
         registered_models[model._meta.db_table] = model
         return python_2_unicode_compatible(
             type(str(name), self.bases, attrs))

simple_history/tests/models.py

@@ -531,3 +531,10 @@ class UserTextFieldChangeReasonModel(models.Model):
 class CharFieldChangeReasonModel(models.Model):
     greeting = models.CharField(max_length=100)
     history = HistoricalRecords()
+
+
+class CustomNameModel(models.Model):
+    name = models.CharField(max_length=15, unique=True)
+    history = HistoricalRecords(
+        custom_model_name='MyHistoricalCustomNameModel'
+    )

simple_history/tests/tests/test_models.py

@@ -34,6 +34,7 @@
     Contact,
     ContactRegister,
     Country,
+    CustomNameModel,
     Document,
     Employee,
     ExternalModel1,
@@ -627,6 +628,17 @@ def test_create_history_model_with_multiple_one_to_ones(self):
                       "fields to one to one fields without throwing an "
                       "exception.")
 
+    def test_instantiate_history_model_with_custom_model_name(self):
+        try:
+            from ..models import MyHistoricalCustomNameModel
+        except ImportError:
+            self.fail("MyHistoricalCustomNameModel is in wrong module")
+        historical_model = MyHistoricalCustomNameModel()
+        self.assertEqual(historical_model.__class__.__name__,
+                         'MyHistoricalCustomNameModel')
+        self.assertEqual(historical_model._meta.db_table,
+                         'tests_myhistoricalcustomnamemodel')
+
 
 class AppLabelTest(TestCase):
     def get_table_name(self, manager):