Fixed #24141 -- Added QuerySet.contains().

3 files changed, 42 insertions, 18 deletions

diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 97bdfcd992..68f964faf5 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -2516,24 +2516,11 @@ if not. This tries to perform the query in the simplest and fastest way
 possible, but it *does* execute nearly the same query as a normal
 :class:`.QuerySet` query.
 
-:meth:`~.QuerySet.exists` is useful for searches relating to both
-object membership in a :class:`.QuerySet` and to the existence of any objects in
-a :class:`.QuerySet`, particularly in the context of a large :class:`.QuerySet`.
+:meth:`~.QuerySet.exists` is useful for searches relating to the existence of
+any objects in a :class:`.QuerySet`, particularly in the context of a large
+:class:`.QuerySet`.
 
-The most efficient method of finding whether a model with a unique field
-(e.g. ``primary_key``) is a member of a :class:`.QuerySet` is::
-
-    entry = Entry.objects.get(pk=123)
-    if some_queryset.filter(pk=entry.pk).exists():
-        print("Entry contained in queryset")
-
-Which will be faster than the following which requires evaluating and iterating
-through the entire queryset::
-
-    if entry in some_queryset:
-       print("Entry contained in QuerySet")
-
-And to find whether a queryset contains any items::
+To find whether a queryset contains any items::
 
     if some_queryset.exists():
         print("There is at least one object in some_queryset")
@@ -2552,6 +2539,35 @@ more overall work (one query for the existence check plus an extra one to later
 retrieve the results) than using ``bool(some_queryset)``, which retrieves the
 results and then checks if any were returned.
 
+``contains()``
+~~~~~~~~~~~~~~
+
+.. method:: contains(obj)
+
+.. versionadded:: 4.0
+
+Returns ``True`` if the :class:`.QuerySet` contains ``obj``, and ``False`` if
+not. This tries to perform the query in the simplest and fastest way possible.
+
+:meth:`contains` is useful for checking an object membership in a
+:class:`.QuerySet`, particularly in the context of a large :class:`.QuerySet`.
+
+To check whether a queryset contains a specific item::
+
+    if some_queryset.contains(obj):
+        print('Entry contained in queryset')
+
+This will be faster than the following which requires evaluating and iterating
+through the entire queryset::
+
+    if obj in some_queryset:
+        print('Entry contained in queryset')
+
+Like :meth:`exists`, if ``some_queryset`` has not yet been evaluated, but you
+know that it will be at some point, then using ``some_queryset.contains(obj)``
+will make an additional database query, generally resulting in slower overall
+performance.
+
 ``update()``
 ~~~~~~~~~~~~
 
diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt
index 7fca85f8f9..27f19043a9 100644
--- a/docs/releases/4.0.txt
+++ b/docs/releases/4.0.txt
@@ -216,7 +216,9 @@ Migrations
 Models
 ~~~~~~
 
-* ...
+* New :meth:`QuerySet.contains(obj) <.QuerySet.contains>` method returns
+  whether the queryset contains the given object. This tries to perform the
+  query in the simplest and fastest way possible.
 
 Requests and Responses
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt
index 69eb58212a..180cd60a46 100644
--- a/docs/topics/db/optimization.txt
+++ b/docs/topics/db/optimization.txt
@@ -240,6 +240,12 @@ row in the results, even if it ends up only using a few columns. The
 lot of text data or for fields that might take a lot of processing to convert
 back to Python. As always, profile first, then optimize.
 
+Use ``QuerySet.contains(obj)``
+------------------------------
+
+...if you only want to find out if ``obj`` is in the queryset, rather than
+``if obj in queryset``.
+
 Use ``QuerySet.count()``
 ------------------------