Merge pull request #615 from ProtixIT/deprecate-joinmanager

Deprecate `JoinManager` and `JoinManagerMixin`

CHANGES.rst

@@ -14,6 +14,8 @@ To be released
   forward additional arguments to Django
 - `SplitField` no longer accepts `no_excerpt_field` as a keyword argument
 - Make `soft` argument to `SoftDeletableModel.delete()` keyword-only
+- `JoinManager` and `JoinManagerMixin` have been deprecated;
+  please use ``JoinQueryset.as_manager()`` instead
 
 4.5.1 (2024-05-02)
 ------------------

docs/managers.rst

@@ -86,11 +86,11 @@ it's safe to use as your default manager for the model.
 
 .. _contributed by Jeff Elmore: https://jeffelmore.org/2010/11/11/automatic-downcasting-of-inherited-models-in-django/
 
-JoinManager
------------
+JoinQueryset
+------------
 
-The ``JoinManager`` will create a temporary table of your current queryset
-and join that temporary table with the model of your current queryset. This can
+A ``JoinQueryset`` will create a temporary table containing its own query result
+and join that temporary table with the model it is querying. This can
 be advantageous if you have to page through your entire DB and using django's
 slice mechanism to do that. ``LIMIT .. OFFSET ..`` becomes slower the bigger
 offset you use.
@@ -102,8 +102,9 @@ offset you use.
     # qs contains 10 objects, and there will be a much smaller performance hit
     # for paging through all of first 2000 objects.
 
-Alternatively, you can give it a queryset and the manager will create a temporary
-table and join that to your current queryset. This can work as a more performant
+Alternatively, you can give it another queryset and ``JoinQueryset`` will create
+a temporary table containing the result of the given queryset and
+join that temporary table to itself. This can work as a more performant
 alternative to using django's ``__in`` as described in the following
 (`StackExchange answer`_).
 
@@ -114,6 +115,8 @@ alternative to using django's ``__in`` as described in the following
 
 .. _StackExchange answer: https://dba.stackexchange.com/questions/91247/optimizing-a-postgres-query-with-a-large-in
 
+You can create a manager that produces ``JoinQueryset`` instances using ``JoinQueryset.as_manager()``.
+
 .. _QueryManager:
 
 QueryManager

model_utils/managers.py

@@ -377,6 +377,11 @@ class JoinManagerMixin:
     _queryset_class = JoinQueryset
 
     def get_queryset(self):
+        warnings.warn(
+            "JoinManager and JoinManagerMixin are deprecated. "
+            "Please use 'JoinQueryset.as_manager()' instead.",
+            DeprecationWarning
+        )
         return self._queryset_class(model=self.model, using=self._db)