Skip to content

Commit b36a280

Browse files
committed
Moved disabling history docs to new section
It didn't really fit under the "Querying History" section.
1 parent 74a2e38 commit b36a280

File tree

4 files changed

+54
-50
lines changed

4 files changed

+54
-50
lines changed

CHANGES.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ Unreleased
1818
**Fixes and improvements:**
1919

2020
- Improved performance of the ``latest_of_each()`` history manager method (gh-1360)
21+
- Moved the "Save without creating historical records" subsection of "Querying History"
22+
in the docs to a new section: "Disable Creating Historical Records" (gh-1387)
2123

2224
3.7.0 (2024-05-29)
2325
------------------

docs/disabling_history.rst

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
Disable Creating Historical Records
2+
===================================
3+
4+
Save without creating historical records
5+
----------------------------------------
6+
7+
If you want to save model objects without triggering the creation of any historical
8+
records, you can do the following:
9+
10+
.. code-block:: python
11+
12+
poll.skip_history_when_saving = True
13+
poll.save()
14+
# We recommend deleting the attribute afterward
15+
del poll.skip_history_when_saving
16+
17+
This also works when creating an object, but only when calling ``save()``:
18+
19+
.. code-block:: python
20+
21+
# Note that `Poll.objects.create()` is not called
22+
poll = Poll(question="Why?")
23+
poll.skip_history_when_saving = True
24+
poll.save()
25+
del poll.skip_history_when_saving
26+
27+
.. note::
28+
Historical records will always be created when calling the ``create()`` manager method.
29+
30+
Alternatively, call the ``save_without_historical_record()`` method on each object
31+
instead of ``save()``.
32+
This method is automatically added to a model when registering it for history-tracking
33+
(i.e. defining a ``HistoricalRecords`` manager field on the model),
34+
and it looks like this:
35+
36+
.. code-block:: python
37+
38+
def save_without_historical_record(self, *args, **kwargs):
39+
self.skip_history_when_saving = True
40+
try:
41+
ret = self.save(*args, **kwargs)
42+
finally:
43+
del self.skip_history_when_saving
44+
return ret
45+
46+
Or disable the creation of historical records for *all* models
47+
by adding the following line to your settings:
48+
49+
.. code-block:: python
50+
51+
SIMPLE_HISTORY_ENABLED = False

docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ Documentation
6666
admin
6767
historical_model
6868
user_tracking
69+
disabling_history
6970
signals
7071
history_diffing
7172
multiple_dbs

docs/querying_history.rst

Lines changed: 0 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -175,56 +175,6 @@ model history.
175175
<Poll: Poll object as of 2010-10-25 18:04:13.814128>
176176
177177
178-
Save without creating historical records
179-
----------------------------------------
180-
181-
If you want to save model objects without triggering the creation of any historical
182-
records, you can do the following:
183-
184-
.. code-block:: python
185-
186-
poll.skip_history_when_saving = True
187-
poll.save()
188-
# We recommend deleting the attribute afterward
189-
del poll.skip_history_when_saving
190-
191-
This also works when creating an object, but only when calling ``save()``:
192-
193-
.. code-block:: python
194-
195-
# Note that `Poll.objects.create()` is not called
196-
poll = Poll(question="Why?")
197-
poll.skip_history_when_saving = True
198-
poll.save()
199-
del poll.skip_history_when_saving
200-
201-
.. note::
202-
Historical records will always be created when calling the ``create()`` manager method.
203-
204-
Alternatively, call the ``save_without_historical_record()`` method on each object
205-
instead of ``save()``.
206-
This method is automatically added to a model when registering it for history-tracking
207-
(i.e. defining a ``HistoricalRecords`` manager field on the model),
208-
and it looks like this:
209-
210-
.. code-block:: python
211-
212-
def save_without_historical_record(self, *args, **kwargs):
213-
self.skip_history_when_saving = True
214-
try:
215-
ret = self.save(*args, **kwargs)
216-
finally:
217-
del self.skip_history_when_saving
218-
return ret
219-
220-
Or disable the creation of historical records for *all* models
221-
by adding the following line to your settings:
222-
223-
.. code-block:: python
224-
225-
SIMPLE_HISTORY_ENABLED = False
226-
227-
228178
Filtering data using a relationship to the model
229179
------------------------------------------------
230180

0 commit comments

Comments
 (0)