[1.8.x] Refs #14030 -- Improved expression support for python values

Backport of e2d6e14662d780383e18066a3182155fb5b7747b from master

2 files changed, 10 insertions, 6 deletions

diff --git a/docs/ref/models/conditional-expressions.txt b/docs/ref/models/conditional-expressions.txt
index 5692bc1968..b62f8a5c35 100644
--- a/docs/ref/models/conditional-expressions.txt
+++ b/docs/ref/models/conditional-expressions.txt
@@ -39,7 +39,7 @@ We'll be using the following model in the subsequent examples::
 When
 ----
 
-.. class:: When(condition=None, then=Value(None), **lookups)
+.. class:: When(condition=None, then=None, **lookups)
 
 A ``When()`` object is used to encapsulate a condition and its result for use
 in the conditional expression. Using a ``When()`` object is similar to using
@@ -73,8 +73,8 @@ Keep in mind that each of these values can be an expression.
     resolved in two ways::
 
         >>> from django.db.models import Value
-        >>> When(then__exact=0, then=Value(1))
-        >>> When(Q(then=0), then=Value(1))
+        >>> When(then__exact=0, then=1)
+        >>> When(Q(then=0), then=1)
 
 Case
 ----
@@ -197,15 +197,15 @@ What if we want to find out how many clients there are for each
     >>> from django.db.models import IntegerField, Sum
     >>> Client.objects.aggregate(
     ...     regular=Sum(
-    ...         Case(When(account_type=Client.REGULAR, then=Value(1)),
+    ...         Case(When(account_type=Client.REGULAR, then=1),
     ...              output_field=IntegerField())
     ...     ),
     ...     gold=Sum(
-    ...         Case(When(account_type=Client.GOLD, then=Value(1)),
+    ...         Case(When(account_type=Client.GOLD, then=1),
     ...              output_field=IntegerField())
     ...     ),
     ...     platinum=Sum(
-    ...         Case(When(account_type=Client.PLATINUM, then=Value(1)),
+    ...         Case(When(account_type=Client.PLATINUM, then=1),
     ...              output_field=IntegerField())
     ...     )
     ... )
diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index b6b4000278..f170af8510 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -221,6 +221,10 @@ function will be applied to. The expressions will be converted to strings,
 joined together with ``arg_joiner``, and then interpolated into the ``template``
 as the ``expressions`` placeholder.
 
+Positional arguments can be expressions or Python values. Strings are
+assumed to be column references and will be wrapped in ``F()`` expressions
+while other values will be wrapped in ``Value()`` expressions.
+
 The ``**extra`` kwargs are ``key=value`` pairs that can be interpolated
 into the ``template`` attribute. Note that the keywords ``function`` and
 ``template`` can be used to replace the ``function`` and ``template``