diff --git a/CHANGES.rst b/CHANGES.rst index 5b79975d..fe68c68a 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -25,8 +25,6 @@ Unreleased lists are sorted by the related object. This should help prevent flaky tests. (gh-1128) - ``diff_against()`` has a new keyword argument, ``foreign_keys_are_objs``; see usage in the docs under "History Diffing" (gh-1128) -- Added ``HistoricalQuerySet.select_related_history_tracked_objs()``; see usage in the - docs under "Prefetching Related Objects of Historical Records" (gh-1128) 3.5.0 (2024-02-19) ------------------ diff --git a/docs/history_diffing.rst b/docs/history_diffing.rst index 2ec809a5..64585d19 100644 --- a/docs/history_diffing.rst +++ b/docs/history_diffing.rst @@ -53,8 +53,8 @@ the model modifications. the value of the deleted object's primary key. Note that this will add extra database queries for each related field that's been - changed - as long as the related objects have not been prefetched (using e.g. - `select_related_history_tracked_objs() `_). + changed - as long as the related objects have not been prefetched + (using e.g. ``select_related()``). A couple examples showing the difference: diff --git a/docs/querying_history.rst b/docs/querying_history.rst index 2366f17d..23b30f78 100644 --- a/docs/querying_history.rst +++ b/docs/querying_history.rst @@ -225,33 +225,3 @@ You can also prefetch the objects with this relationship using something like th Poll.objects.filter(something).prefetch_related(Prefetch('history', queryset=Poll.history.order_by('-history_date'), to_attr='ordered_histories') - - -.. _`Prefetching Related Objects`: - -Prefetching Related Objects of Historical Records -------------------------------------------------- - -If you find yourself wanting to access the related objects of some historical records, -but without inducing additional database queries, -``HistoricalQuerySet`` has a method called ``select_related_history_tracked_objs()`` -that you can use. -This is a convenience method that calls `select_related()`_ with all the names of -the model's history-tracked ``ForeignKey`` fields. -For example: - -.. code-block:: python - - class Membership(models.Model): - person = models.ForeignKey(Person, on_delete=models.CASCADE) - group = models.ForeignKey(Group, on_delete=models.CASCADE) - - history = HistoricalRecords(excluded_fields=["person"]) - - - # This will prefetch `group` (not `person`, since it's excluded) - Membership.history.select_related_history_tracked_objs() - -Prefetching historical many-to-many relations is currently not supported. - -.. _select_related(): https://docs.djangoproject.com/en/stable/ref/models/querysets/#select-related diff --git a/simple_history/admin.py b/simple_history/admin.py index c5453d6b..29cc0ef4 100644 --- a/simple_history/admin.py +++ b/simple_history/admin.py @@ -129,7 +129,7 @@ def get_history_queryset( # Only select_related when history_user is a ForeignKey (not a property) qs = qs.select_related("history_user") # Prefetch related objects to reduce the number of DB queries when diffing - qs = qs.select_related_history_tracked_objs() + qs = qs._select_related_history_tracked_objs() return qs def get_history_list_display(self, request) -> Sequence[str]: diff --git a/simple_history/manager.py b/simple_history/manager.py index 388830c9..d8f0b53e 100644 --- a/simple_history/manager.py +++ b/simple_history/manager.py @@ -91,7 +91,7 @@ def latest_of_each(self): ) return latest_historics - def select_related_history_tracked_objs(self): + def _select_related_history_tracked_objs(self): """ A convenience method that calls ``select_related()`` with all the names of the model's history-tracked ``ForeignKey`` fields. diff --git a/simple_history/tests/tests/test_manager.py b/simple_history/tests/tests/test_manager.py index 369655ec..0f5465b9 100644 --- a/simple_history/tests/tests/test_manager.py +++ b/simple_history/tests/tests/test_manager.py @@ -399,7 +399,7 @@ def access_related_objs(records): # With prefetching: with self.assertNumQueries(1): - historical_records = Choice.history.select_related_history_tracked_objs() + historical_records = Choice.history._select_related_history_tracked_objs() self.assertEqual(len(historical_records), num_choices) with self.assertNumQueries(0): access_related_objs(historical_records)