Fixed #27021 -- Allowed lookup expressions in annotations, aggregations, and QuerySet.filter().

Thanks Hannes Ljungberg and Simon Charette for reviews.

Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>

4 files changed, 38 insertions, 6 deletions

diff --git a/docs/ref/models/conditional-expressions.txt b/docs/ref/models/conditional-expressions.txt
index 546733dd8d..b7ab3ec3dc 100644
--- a/docs/ref/models/conditional-expressions.txt
+++ b/docs/ref/models/conditional-expressions.txt
@@ -48,6 +48,10 @@ objects that have an ``output_field`` that is a
 :class:`~django.db.models.BooleanField`. The result is provided using the
 ``then`` keyword.
 
+.. versionchanged:: 4.0
+
+    Support for lookup expressions was added.
+
 Some examples::
 
     >>> from django.db.models import F, Q, When
@@ -68,6 +72,13 @@ Some examples::
     ...     account_type=OuterRef('account_type'),
     ... ).exclude(pk=OuterRef('pk')).values('pk')
     >>> When(Exists(non_unique_account_type), then=Value('non unique'))
+    >>> # Condition can be created using lookup expressions.
+    >>> from django.db.models.lookups import GreaterThan, LessThan
+    >>> When(
+    ...     GreaterThan(F('registered_on'), date(2014, 1, 1)) &
+    ...     LessThan(F('registered_on'), date(2015, 1, 1)),
+    ...     then='account_type',
+    ... )
 
 Keep in mind that each of these values can be an expression.
 
diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index d45cfbe00a..845e734dc1 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -25,6 +25,7 @@ Some examples
 
     from django.db.models import Count, F, Value
     from django.db.models.functions import Length, Upper
+    from django.db.models.lookups import GreaterThan
 
     # Find companies that have more employees than chairs.
     Company.objects.filter(num_employees__gt=F('num_chairs'))
@@ -76,6 +77,13 @@ Some examples
         Exists(Employee.objects.filter(company=OuterRef('pk'), salary__gt=10))
     )
 
+    # Lookup expressions can also be used directly in filters
+    Company.objects.filter(GreaterThan(F('num_employees'), F('num_chairs')))
+    # or annotations.
+    Company.objects.annotate(
+        need_chairs=GreaterThan(F('num_employees'), F('num_chairs')),
+    )
+
 Built-in Expressions
 ====================
 
diff --git a/docs/ref/models/lookups.txt b/docs/ref/models/lookups.txt
index fdbde328de..f4fa0f899d 100644
--- a/docs/ref/models/lookups.txt
+++ b/docs/ref/models/lookups.txt
@@ -177,16 +177,21 @@ following methods:
     comparison between ``lhs`` and ``rhs`` such as ``lhs in rhs`` or
     ``lhs > rhs``.
 
-    The notation to use a lookup in an expression is
-    ``<lhs>__<lookup_name>=<rhs>``.
+    The primary notation to use a lookup in an expression is
+    ``<lhs>__<lookup_name>=<rhs>``. Lookups can also be used directly in
+    ``QuerySet`` filters::
 
-    This class acts as a query expression, but, since it has ``=<rhs>`` on its
-    construction, lookups must always be the end of a lookup expression.
+         Book.objects.filter(LessThan(F('word_count'), 7500))
+
+    …or annotations::
+
+         Book.objects.annotate(is_short_story=LessThan(F('word_count'), 7500))
 
     .. attribute:: lhs
 
-        The left-hand side - what is being looked up. The object must follow
-        the :ref:`Query Expression API <query-expression>`.
+        The left-hand side - what is being looked up. The object typically
+        follows the :ref:`Query Expression API <query-expression>`. It may also
+        be a plain value.
 
     .. attribute:: rhs
 
@@ -213,3 +218,8 @@ following methods:
     .. method:: process_rhs(compiler, connection)
 
         Behaves the same way as :meth:`process_lhs`, for the right-hand side.
+
+    .. versionchanged:: 4.0
+
+        Support for using lookups in ``QuerySet`` annotations, aggregations,
+        and directly in filters was added.
diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt
index 3ef008e5fe..be59681fda 100644
--- a/docs/releases/4.0.txt
+++ b/docs/releases/4.0.txt
@@ -277,6 +277,9 @@ Models
 * The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update()` is now
   allowed on MariaDB 10.6+.
 
+* :class:`~django.db.models.Lookup` expressions may now be used in ``QuerySet``
+  annotations, aggregations, and directly in filters.
+
 Requests and Responses
 ~~~~~~~~~~~~~~~~~~~~~~