Historical Model Customizations
===============================

Custom ``history_id``
---------------------
By default, the historical table of a model will use an ``AutoField`` for the table's
``history_id`` (the history table's primary key). However, you can specify a different
type of field for ``history_id`` by passing a different field to ``history_id_field``
parameter.

The example below uses a ``UUIDField`` instead of an ``AutoField``:


.. code-block:: python

    import uuid
    from django.db import models
    from simple_history.models import HistoricalRecords

    class Poll(models.Model):
        question = models.CharField(max_length=200)
        pub_date = models.DateTimeField('date published')
        history = HistoricalRecords(
            history_id_field=models.UUIDField(default=uuid.uuid4)
        )


Since using a ``UUIDField`` for the ``history_id`` is a common use case, there is a
``SIMPLE_HISTORY_HISTORY_ID_USE_UUID`` setting that will set all instances of ``history_id`` to UUIDs.
Set this with the following line in your ``settings.py`` file:


.. code-block:: python

    SIMPLE_HISTORY_HISTORY_ID_USE_UUID = True



This setting can still be overridden using the ``history_id_field`` parameter on a per model basis.

You can use the ``history_id_field`` parameter with both ``HistoricalRecords()`` or
``register()`` to change this behavior.

Note: regardless of what field type you specify as your history_id field, that field will
automatically set ``primary_key=True`` and ``editable=False``.


Custom ``history_date``
-----------------------

You're able to set a custom ``history_date`` attribute for the historical
record, by defining the property ``_history_date`` in your model. That's
helpful if you want to add versions to your model, which happened before the
current model version, e.g. when batch importing historical data. The content
of the property ``_history_date`` has to be a ``datetime``-object, but setting the
value of the property to a ``DateTimeField``, which is already defined in the
model, will work too.

.. code-block:: python

    from django.db import models
    from simple_history.models import HistoricalRecords

    class Poll(models.Model):
        question = models.CharField(max_length=200)
        pub_date = models.DateTimeField('date published')
        changed_by = models.ForeignKey('auth.User')
        history = HistoricalRecords()
        __history_date = None

        @property
        def _history_date(self):
            return self.__history_date

        @_history_date.setter
        def _history_date(self, value):
            self.__history_date = value

.. code-block:: python

    from datetime import datetime
    from models import Poll

    my_poll = Poll(question="what's up?")
    my_poll._history_date = datetime.now()
    my_poll.save()


Indexed ``history_date``
------------------------

Many queries use ``history_date`` as a filter.  The as_of queries combine this with the
original model's primary key to extract point-in-time snapshots of history.  By default
the ``history_date`` field is indexed.  You can control this behavior using settings.py.

.. code-block:: python

    # disable indexing on history_date
    SIMPLE_HISTORY_DATE_INDEX = False

    # enable indexing on history_date (default setting)
    SIMPLE_HISTORY_DATE_INDEX = True

    # enable composite indexing on history_date and model pk (to improve as_of queries)
    # the string is case-insensitive
    SIMPLE_HISTORY_DATE_INDEX = "Composite"


Custom history table name
-------------------------

By default, the table name for historical models follow the Django convention
and just add ``historical`` before model name. For instance, if your application
name is ``polls`` and your model name ``Question``, then the table name will be
``polls_historicalquestion``.

You can use the ``table_name`` parameter with both ``HistoricalRecords()`` or
``register()`` to change this behavior.

.. code-block:: python

    class Question(models.Model):
        question_text = models.CharField(max_length=200)
        pub_date = models.DateTimeField('date published')
        history = HistoricalRecords(table_name='polls_question_history')

.. code-block:: python

    class Question(models.Model):
        question_text = models.CharField(max_length=200)
        pub_date = models.DateTimeField('date published')

    register(Question, table_name='polls_question_history')


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.

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.


Custom History Manager and Historical QuerySets
-----------------------------------------------

To manipulate the history ``Manager`` or the historical ``QuerySet`` of
``HistoricalRecords``, you can specify the ``history_manager`` and
``historical_queryset`` options. The values must be subclasses
of ``simple_history.manager.HistoryManager`` and
``simple_history.manager.HistoricalQuerySet``, respectively.

Keep in mind, you can use either or both of these options. To understand the
difference between a ``Manager`` and a ``QuerySet``,
see `Django's Manager documentation`_.

.. code-block:: python

    from datetime import timedelta
    from django.db import models
    from django.utils import timezone
    from simple_history.manager import HistoryManager, HistoricalQuerySet
    from simple_history.models import HistoricalRecords


    class HistoryQuestionManager(HistoryManager):
        def published(self):
            return self.filter(pub_date__lte=timezone.now())


    class HistoryQuestionQuerySet(HistoricalQuerySet):
        def question_prefixed(self):
            return self.filter(question__startswith="Question: ")


    class Question(models.Model):
        pub_date = models.DateTimeField("date published")
        history = HistoricalRecords(
            history_manager=HistoryQuestionManager,
            historical_queryset=HistoryQuestionQuerySet,
        )

    # This is now possible:
    queryset = Question.history.published().question_prefixed()


To reuse a ``QuerySet`` from the model, see the following code example:

.. code-block:: python

    from datetime import timedelta
    from django.db import models
    from django.utils import timezone
    from simple_history.models import HistoricalRecords
    from simple_history.manager import HistoryManager, HistoricalQuerySet


    class QuestionQuerySet(models.QuerySet):
        def question_prefixed(self):
            return self.filter(question__startswith="Question: ")


    class HistoryQuestionQuerySet(QuestionQuerySet, HistoricalQuerySet):
        """Redefine ``QuerySet`` with base class ``HistoricalQuerySet``."""


    class Question(models.Model):
        pub_date = models.DateTimeField("date published")
        history = HistoricalRecords(historical_queryset=HistoryQuestionQuerySet)
        manager = QuestionQuerySet.as_manager()

.. _Django's Manager documentation: https://docs.djangoproject.com/en/stable/topics/db/managers/


TextField as `history_change_reason`
------------------------------------

The ``HistoricalRecords`` object can be customized to accept a
``TextField`` model field for saving the
`history_change_reason` either through settings or via the constructor on the
model. The common use case for this is for supporting larger model change
histories to support changelog-like features.

.. code-block:: python

    SIMPLE_HISTORY_HISTORY_CHANGE_REASON_USE_TEXT_FIELD=True

or

.. code-block:: python

    class TextFieldExample(models.Model):
        greeting = models.CharField(max_length=100)
        history = HistoricalRecords(
            history_change_reason_field=models.TextField(null=True)
        )



Change Base Class of HistoricalRecord Models
--------------------------------------------

To change the auto-generated HistoricalRecord models base class from
``models.Model``, pass in the abstract class in a list to ``bases``.

.. code-block:: python

    class RoutableModel(models.Model):
        class Meta:
            abstract = True


    class Poll(models.Model):
        question = models.CharField(max_length=200)
        pub_date = models.DateTimeField('date published')
        changed_by = models.ForeignKey('auth.User')
        history = HistoricalRecords(bases=[RoutableModel])


Excluded Fields
--------------------------------

It is possible to use the parameter ``excluded_fields`` to choose which fields
will be stored on every create/update/delete.

For example, if you have the model:

.. code-block:: python

    class PollWithExcludeFields(models.Model):
        question = models.CharField(max_length=200)
        pub_date = models.DateTimeField('date published')

And you don't want to store the changes for the field ``pub_date``, it is necessary to update the model to:

.. code-block:: python

    class PollWithExcludeFields(models.Model):
        question = models.CharField(max_length=200)
        pub_date = models.DateTimeField('date published')

        history = HistoricalRecords(excluded_fields=['pub_date'])

By default, django-simple-history stores the changes for all fields in the model.

Adding additional fields to historical models
---------------------------------------------

Sometimes it is useful to be able to add additional fields to historical models that do not exist on the
source model. This is possible by combining the ``bases`` functionality with the ``pre_create_historical_record`` signal.

.. code-block:: python

    # in models.py
    class IPAddressHistoricalModel(models.Model):
        """
        Abstract model for history models tracking the IP address.
        """
        ip_address = models.GenericIPAddressField(_('IP address'))

        class Meta:
            abstract = True


    class PollWithExtraFields(models.Model):
        question = models.CharField(max_length=200)
        pub_date = models.DateTimeField('date published')

        history = HistoricalRecords(bases=[IPAddressHistoricalModel,])


.. code-block:: python

    # define your signal handler/callback anywhere outside of models.py
    def add_history_ip_address(sender, **kwargs):
        history_instance = kwargs['history_instance']
        # context.request for use only when the simple_history middleware is on and enabled
        history_instance.ip_address = HistoricalRecords.context.request.META['REMOTE_ADDR']


.. code-block:: python

    # in apps.py
    class TestsConfig(AppConfig):
        def ready(self):
            from simple_history.tests.models \
                import HistoricalPollWithExtraFields

            pre_create_historical_record.connect(
                add_history_ip_address,
                sender=HistoricalPollWithExtraFields
            )


More information on signals in ``django-simple-history`` is available in :doc:`/signals`.

Change Reason
-------------

Change reason is a message to explain why the change was made in the instance. It is stored in the
field ``history_change_reason`` and its default value is ``None``.

By default, the django-simple-history gets the change reason in the field ``_change_reason`` of the instance. Also, it is possible to pass
the ``_change_reason`` explicitly. For this, after a save or delete in an instance, it is necessary to call the
function ``utils.update_change_reason``. The first argument of this function is the instance and the second
is the message that represents the change reason.

For instance, for the model:

.. code-block:: python

    from django.db import models
    from simple_history.models import HistoricalRecords

    class Poll(models.Model):
        question = models.CharField(max_length=200)
        history = HistoricalRecords()

You can create an instance with an implicit change reason.

.. code-block:: python

    poll = Poll(question='Question 1')
    poll._change_reason = 'Add a question'
    poll.save()

Or you can pass the change reason explicitly:

.. code-block:: python

    from simple_history.utils import update_change_reason

    poll = Poll(question='Question 1')
    poll.save()
    update_change_reason(poll, 'Add a question')


Deleting historical record
--------------------------

In some circumstances you may want to delete all the historical records when the master record is deleted.  This can
be accomplished by setting ``cascade_delete_history=True``.

.. code-block:: python

    class Poll(models.Model):
        question = models.CharField(max_length=200)
        history = HistoricalRecords(cascade_delete_history=True)



Allow tracking to be inherited
---------------------------------

By default history tracking is only added for the model that is passed
to ``register()`` or has the ``HistoricalRecords`` descriptor. By
passing ``inherit=True`` to either way of registering, you can change
that behavior so that any child model inheriting from it will have
historical tracking as well. Be careful though, in cases where a model
can be tracked more than once, ``MultipleRegistrationsError`` will be
raised.

.. code-block:: python

    from django.contrib.auth.models import User
    from django.db import models
    from simple_history import register
    from simple_history.models import HistoricalRecords

    # register() example
    register(User, inherit=True)

    # HistoricalRecords example
    class Poll(models.Model):
        history = HistoricalRecords(inherit=True)

Both ``User`` and ``Poll`` in the example above will cause any model
inheriting from them to have historical tracking as well.

**Note:** For parent models having a ``HistoricalRecords`` field with ``inherit=True``
*and* a ``table_name``, the latter option will not be inherited by child models.

History Model In Different App
------------------------------

By default the app_label for the history model is the same as the base model.
In some circumstances you may want to have the history models belong in a different app.
This will support creating history models in a different database to the base model using
database routing functionality based on app_label.
To configure history models in a different app, add this to the HistoricalRecords instantiation
or the record invocation: ``app="SomeAppName"``.

.. code-block:: python

    class Poll(models.Model):
        question = models.CharField(max_length=200)
        history = HistoricalRecords(app="SomeAppName")

    class Opinion(models.Model):
        opinion = models.CharField(max_length=2000)

    register(Opinion, app="SomeAppName")


`FileField` as a `CharField`
----------------------------

By default a ``FileField`` in the base model becomes a ``TextField`` in the history model.
This is a historical choice that django-simple-history preserves for backwards
compatibility; it is more correct for a ``FileField`` to be converted to a
``CharField`` instead. To opt into the new behavior, set the following line in your
``settings.py`` file:

.. code-block:: python

    SIMPLE_HISTORY_FILEFIELD_TO_CHARFIELD = True


Drop Database Indices
--------------------------------

It is possible to use the parameter ``no_db_index`` to choose which fields
that will not create a database index.

For example, if you have the model:

.. code-block:: python

    class PollWithExcludeFields(models.Model):
        question = models.CharField(max_length=200, db_index=True)



And you don't want to create database index for ``question``, it is necessary to update the model to:

.. code-block:: python

    class PollWithExcludeFields(models.Model):
        question = models.CharField(max_length=200, db_index=True)

        history = HistoricalRecords(no_db_index=['question'])


By default, django-simple-history keeps all indices. and even forces them on unique fields and relations.
WARNING: This will drop performance on historical lookups

Tracking many to many relationships
-----------------------------------
By default, many to many fields are ignored when tracking changes.
If you want to track many to many relationships, you need to define them explicitly:

.. code-block:: python

    class Category(models.Model):
        name = models.CharField(max_length=200)

    class Poll(models.Model):
        question = models.CharField(max_length=200)
        categories = models.ManyToManyField(Category)
        history = HistoricalRecords(m2m_fields=[categories])

This will create a historical intermediate model that tracks each relational change
between `Poll` and `Category`.

You may use either the name of the field or the field instance itself.

You may also define these fields in a class attribute (by default on `_history_m2m_fields`).
This is mainly used by inherited models not declaring their own `HistoricalRecord`.
You can override the attribute name by setting your own `m2m_fields_model_field_name`
argument on the `HistoricalRecord` instance.

You will see the many to many changes when diffing between two historical records:

.. code-block:: python

    informal = Category.objects.create(name="informal questions")
    official = Category.objects.create(name="official questions")
    p = Poll.objects.create(question="what's up?")
    p.categories.add(informal, official)
    p.categories.remove(informal)

    last_record = p.history.latest()
    previous_record = last_record.prev_record
    delta = last_record.diff_against(previous_record)

    for change in delta.changes:
        print("{} changed from {} to {}".format(change.field, change.old, change.new))

    # Output:
    # categories changed from [{'poll': 1, 'category': 1}, { 'poll': 1, 'category': 2}] to [{'poll': 1, 'category': 2}]