Add pre and post create_historical_record signals (#426)

* Add signals to create_historical_record

* Update docs to include signals

* Update pre_create_historical_record sender class

* Add tests to signal sender

* Fix signal sender using the wrong class

* Add Matheus Cansian to AUTHORS

* Update CHANGES

Author: mscansian

AUTHORS.rst

@@ -65,6 +65,7 @@ Authors
 - Kyle Seever
 - Adnan Umer (@uadnan)
 - Jonathan Zvesper (@zvesp)
+- Matheus Cansian (@mscansian)
 
 Background
 ==========

CHANGES.rst

@@ -1,6 +1,10 @@
 Changes
 =======
 
+Unreleased
+------------------
+- Add pre and post create_historical_record signals (gh-426)
+
 2.3.0 (2018-07-19)
 ------------------
 - Add ability to diff HistoricalRecords (gh-244)

docs/advanced.rst

@@ -446,3 +446,23 @@ This may be useful when you want to construct timelines and need to get only the
     delta = new_record.diff_against(old_record)
     for change in delta.changes:
         print("{} changed from {} to {}".format(change.field, change.old, change.new))
+
+Using signals
+------------------------------------
+django-simple-history includes signals that helps you provide custom behaviour when saving a historical record. If you want to connect the signals you can do so using the following code:
+
+.. code-block:: python
+
+    from django.dispatch import receiver
+    from simple_history.signals import (
+        pre_create_historical_record,
+        post_create_historical_record
+    )
+
+    @receiver(pre_create_historical_record)
+    def pre_create_historical_record(sender, instance, **kwargs):
+        print("Sent before saving historical record")
+
+    @receiver(pre_create_historical_record)
+        def post_create_historical_record(sender, instance, history_instance, **kwargs):
+            print("Sent after saving historical record")

simple_history/models.py

@@ -20,6 +20,10 @@
 
 from . import exceptions
 from .manager import HistoryDescriptor
+from .signals import (
+    pre_create_historical_record,
+    post_create_historical_record,
+)
 
 registered_models = {}
 
@@ -342,14 +346,29 @@ def create_historical_record(self, instance, history_type):
         history_date = getattr(instance, '_history_date', now())
         history_user = self.get_history_user(instance)
         history_change_reason = getattr(instance, 'changeReason', None)
-
         manager = getattr(instance, self.manager_name)
+
+        pre_create_historical_record.send(
+            sender=manager.model, instance=instance,
+            history_date=history_date, history_user=history_user,
+            history_change_reason=history_change_reason,
+        )
+
         attrs = {}
         for field in self.fields_included(instance):
             attrs[field.attname] = getattr(instance, field.attname)
-        manager.create(history_date=history_date, history_type=history_type,
-                       history_user=history_user,
-                       history_change_reason=history_change_reason, **attrs)
+        history_instance = manager.create(
+            history_date=history_date, history_type=history_type,
+            history_user=history_user,
+            history_change_reason=history_change_reason, **attrs
+        )
+
+        post_create_historical_record.send(
+            sender=manager.model, instance=instance,
+            history_instance=history_instance,
+            history_date=history_date, history_user=history_user,
+            history_change_reason=history_change_reason,
+        )
 
     def get_history_user(self, instance):
         """Get the modifying user from instance or middleware."""

simple_history/signals.py

@@ -0,0 +1,10 @@
+import django.dispatch
+
+
+pre_create_historical_record = django.dispatch.Signal(providing_args=[
+    'instance', 'history_date', 'history_user', 'history_change_reason',
+])
+post_create_historical_record = django.dispatch.Signal(providing_args=[
+    'instance', 'history_instance', 'history_date', 'history_user',
+    'history_change_reason',
+])

simple_history/tests/tests/test_signals.py

@@ -0,0 +1,52 @@
+from __future__ import unicode_literals
+
+from datetime import datetime
+
+from django.test import TestCase
+
+from simple_history.signals import (
+    pre_create_historical_record,
+    post_create_historical_record,
+)
+
+from ..models import Poll
+
+today = datetime(2021, 1, 1, 10, 0)
+
+
+class PrePostCreateHistoricalRecordSignalTest(TestCase):
+    def setUp(self):
+        self.signal_was_called = False
+        self.signal_instance = None
+        self.signal_history_instance = None
+        self.signal_sender = None
+
+    def test_pre_create_historical_record_signal(self):
+        def handler(sender, instance, **kwargs):
+            self.signal_was_called = True
+            self.signal_instance = instance
+            self.signal_sender = sender
+        pre_create_historical_record.connect(handler)
+
+        p = Poll(question="what's up?", pub_date=today)
+        p.save()
+
+        self.assertTrue(self.signal_was_called)
+        self.assertEqual(self.signal_instance, p)
+        self.assertEqual(self.signal_sender, p.history.first().__class__)
+
+    def test_post_create_historical_record_signal(self):
+        def handler(sender, instance, history_instance, **kwargs):
+            self.signal_was_called = True
+            self.signal_instance = instance
+            self.signal_history_instance = history_instance
+            self.signal_sender = sender
+        post_create_historical_record.connect(handler)
+
+        p = Poll(question="what's up?", pub_date=today)
+        p.save()
+
+        self.assertTrue(self.signal_was_called)
+        self.assertEqual(self.signal_instance, p)
+        self.assertTrue(self.signal_history_instance is not None)
+        self.assertEqual(self.signal_sender, p.history.first().__class__)