From 84c195e590448df382e22cbcf11983ac9d1c0e99 Mon Sep 17 00:00:00 2001 From: Anders <6058745+ddabble@users.noreply.github.com> Date: Mon, 11 Mar 2024 14:28:58 +0100 Subject: [PATCH] Removed docs on select_related_history_tracked_objs() See discussion: https://github.com/jazzband/django-simple-history/pull/1128#discussion_r1518873565 Also prefixed the method with `_`, to mark it as not being part of the public API. --- CHANGES.rst | 2 -- docs/history_diffing.rst | 4 +-- docs/querying_history.rst | 30 ---------------------- simple_history/admin.py | 2 +- simple_history/manager.py | 2 +- simple_history/tests/tests/test_manager.py | 2 +- 6 files changed, 5 insertions(+), 37 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 5b79975d5..fe68c68ab 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 2ec809a5e..64585d199 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 2366f17d5..23b30f780 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 c5453d6bf..29cc0ef41 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 388830c9f..d8f0b53e8 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 369655ecb..0f5465b91 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)