disable_history() context manager

CHANGES.rst

@@ -4,9 +4,40 @@ Changes
 Unreleased
 ----------
 
+**What's new:**
+
 - Made ``skip_history_when_saving`` work when creating an object - not just when
   updating an object (gh-1262)
+- Added ``delete_without_historical_record()`` to all history-tracked model objects,
+  which complements ``save_without_historical_record()`` (gh-1387)
+- Added a ``disable_history()`` context manager, which disables history record creation
+  while it's active; see usage in the docs under "Disable Creating Historical Records"
+  (gh-1387)
+
+**Breaking changes:**
+
+- Removed ``HistoryManager.get_super_queryset()`` (gh-1387)
+- Renamed the ``utils`` functions ``get_history_manager_from_history()``
+  to ``get_historical_records_of_instance()`` and ``get_app_model_primary_key_name()``
+  to ``get_pk_name()`` (gh-1387)
+
+**Deprecations:**
+
+- Deprecated the undocumented ``HistoricalRecords.thread`` - use
+  ``HistoricalRecords.context`` instead. The former attribute will be removed in
+  version 3.10 (gh-1387)
+- Deprecated ``skip_history_when_saving`` in favor of the newly added
+  ``disable_history()`` context manager. The former attribute will be removed in
+  version 4.0 (gh-1387)
+
+**Fixes and improvements:**
+
 - Improved performance of the ``latest_of_each()`` history manager method (gh-1360)
+- Moved the "Save without creating historical records" subsection of "Querying History"
+  in the docs to a new section: "Disable Creating Historical Records" (gh-1387)
+- The ``utils`` functions ``get_history_manager_for_model()`` and
+  ``get_history_model_for_model()`` now explicitly support being passed model instances
+  instead of just model types (gh-1387)
 
 3.7.0 (2024-05-29)
 ------------------

docs/disabling_history.rst

@@ -0,0 +1,77 @@
+Disable Creating Historical Records
+===================================
+
+``save_without_historical_record()`` and ``delete_without_historical_record()``
+-------------------------------------------------------------------------------
+
+These methods are automatically added to a model when registering it for history-tracking
+(i.e. defining a ``HistoricalRecords``  manager on the model),
+and can be called instead of ``save()`` and ``delete()``, respectively.
+
+Using the ``disable_history()`` context manager
+-----------------------------------------------
+
+``disable_history()`` has three ways of being called:
+
+#. With no arguments: This will disable all historical record creation
+   (as if the ``SIMPLE_HISTORY_ENABLED`` setting was set to ``False``; see below)
+   within the context manager's ``with`` block.
+#. With ``only_for_model``: Only disable history creation for the provided model type.
+#. With ``instance_predicate``: Only disable history creation for model instances passing
+   this predicate.
+
+See some examples below:
+
+.. code-block:: python
+
+    from simple_history.utils import disable_history
+
+    # No historical records are created
+    with disable_history():
+        User.objects.create(...)
+        Poll.objects.create(...)
+
+    # A historical record is only created for the poll
+    with disable_history(only_for_model=User):
+        User.objects.create(...)
+        Poll.objects.create(...)
+
+    # A historical record is created for the second poll, but not for the first poll
+    # (remember to check the instance type in the passed function if you expect
+    # historical records of more than one model to be created inside the `with` block)
+    with disable_history(instance_predicate=lambda poll: "ignore" in poll.question):
+        Poll.objects.create(question="ignore this")
+        Poll.objects.create(question="what's up?")
+
+Overriding ``create_historical_record()``
+-----------------------------------------
+
+For even more fine-grained control, you can subclass ``HistoricalRecords`` and override
+its ``create_historical_record()`` method, for example like this:
+
+.. code-block:: python
+
+    class CustomHistoricalRecords(HistoricalRecords):
+        def create_historical_record(
+            self, instance: models.Model, history_type: str, *args, **kwargs
+        ) -> None:
+        # Don't create records for "ignore" polls that are being deleted
+        if "ignore" in poll.question and history_type == "-":
+            return
+
+        super().create_historical_record(instance, history_type, *args, **kwargs)
+
+
+    class Poll(models.Model):
+        # ...
+        history = CustomHistoricalRecords()
+
+The ``SIMPLE_HISTORY_ENABLED`` setting
+--------------------------------------
+
+Disable the creation of historical records for *all* models
+by adding the following line to your settings:
+
+.. code-block:: python
+
+    SIMPLE_HISTORY_ENABLED = False

docs/index.rst

@@ -66,6 +66,7 @@ Documentation
    admin
    historical_model
    user_tracking
+   disabling_history
    signals
    history_diffing
    multiple_dbs

docs/querying_history.rst

@@ -175,56 +175,6 @@ model history.
     <Poll: Poll object as of 2010-10-25 18:04:13.814128>
 
 
-Save without creating historical records
-----------------------------------------
-
-If you want to save model objects without triggering the creation of any historical
-records, you can do the following:
-
-.. code-block:: python
-
-    poll.skip_history_when_saving = True
-    poll.save()
-    # We recommend deleting the attribute afterward
-    del poll.skip_history_when_saving
-
-This also works when creating an object, but only when calling ``save()``:
-
-.. code-block:: python
-
-    # Note that `Poll.objects.create()` is not called
-    poll = Poll(question="Why?")
-    poll.skip_history_when_saving = True
-    poll.save()
-    del poll.skip_history_when_saving
-
-.. note::
-    Historical records will always be created when calling the ``create()`` manager method.
-
-Alternatively, call the ``save_without_historical_record()`` method on each object
-instead of ``save()``.
-This method is automatically added to a model when registering it for history-tracking
-(i.e. defining a ``HistoricalRecords``  manager field on the model),
-and it looks like this:
-
-.. code-block:: python
-
-    def save_without_historical_record(self, *args, **kwargs):
-        self.skip_history_when_saving = True
-        try:
-            ret = self.save(*args, **kwargs)
-        finally:
-            del self.skip_history_when_saving
-        return ret
-
-Or disable the creation of historical records for *all* models
-by adding the following line to your settings:
-
-.. code-block:: python
-
-    SIMPLE_HISTORY_ENABLED = False
-
-
 Filtering data using a relationship to the model
 ------------------------------------------------
 

simple_history/manager.py

@@ -1,12 +1,8 @@
-from django.conf import settings
 from django.db import models
 from django.db.models import Exists, OuterRef, Q, QuerySet
 from django.utils import timezone
 
-from simple_history.utils import (
-    get_app_model_primary_key_name,
-    get_change_reason_from_object,
-)
+from . import utils
 
 # when converting a historical record to an instance, this attribute is added
 # to the instance so that code can reverse the instance to its historical record
@@ -118,16 +114,13 @@ def __init__(self, model, instance=None):
         self.model = model
         self.instance = instance
 
-    def get_super_queryset(self):
-        return super().get_queryset()
-
     def get_queryset(self):
-        qs = self.get_super_queryset()
+        qs = super().get_queryset()
         if self.instance is None:
             return qs
 
-        key_name = get_app_model_primary_key_name(self.instance)
-        return self.get_super_queryset().filter(**{key_name: self.instance.pk})
+        pk_name = utils.get_pk_name(self.instance._meta.model)
+        return qs.filter(**{pk_name: self.instance.pk})
 
     def most_recent(self):
         """
@@ -222,15 +215,19 @@ def bulk_history_create(
         If called by bulk_update_with_history, use the update boolean and
         save the history_type accordingly.
         """
-        if not getattr(settings, "SIMPLE_HISTORY_ENABLED", True):
-            return
+        info = utils.DisableHistoryInfo.get()
+        if info.disabled_globally:
+            return []
 
         history_type = "+"
         if update:
             history_type = "~"
 
         historical_instances = []
         for instance in objs:
+            if info.disabled_for(instance):
+                continue
+
             history_user = getattr(
                 instance,
                 "_history_user",
@@ -241,7 +238,7 @@ def bulk_history_create(
                     instance, "_history_date", default_date or timezone.now()
                 ),
                 history_user=history_user,
-                history_change_reason=get_change_reason_from_object(instance)
+                history_change_reason=utils.get_change_reason_from_object(instance)
                 or default_change_reason,
                 history_type=history_type,
                 **{