From 39f35d4b9de223b72c67bb1d12e65669b4e1355b Mon Sep 17 00:00:00 2001
From: Ian Foote <python@ian.feete.org>
Date: Mon, 15 Aug 2016 11:35:12 +1000
Subject: Fixed #25871 -- Added expressions support to QuerySet.values().

---
 docs/ref/models/querysets.txt | 34 +++++++++++++++++++++++++++++++---
 docs/releases/1.11.txt        |  3 +++
 2 files changed, 34 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 8d2e3ebb3b..f11a09fb96 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -506,7 +506,7 @@ Examples (those after the first will only work on PostgreSQL)::
 ``values()``
 ~~~~~~~~~~~~
 
-.. method:: values(*fields)
+.. method:: values(*fields, **expressions)
 
 Returns a ``QuerySet`` that returns dictionaries, rather than model instances,
 when used as an iterable.
@@ -538,6 +538,23 @@ Example::
     >>> Blog.objects.values('id', 'name')
     <QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>
 
+The ``values()`` method also takes optional keyword arguments,
+``**expressions``, which are passed through to :meth:`annotate`::
+
+    >>> from django.db.models.functions import Lower
+    >>> Blog.objects.values(lower_name=Lower('name'))
+    <QuerySet [{'lower_name': 'beatles blog'}]>
+
+An aggregate within a ``values()`` clause is applied before other arguments
+within the same ``values()`` clause. If you need to group by another value,
+add it to an earlier ``values()`` clause instead. For example::
+
+    >>> from django.db.models import Count
+    >>> Blog.objects.values('author', entries=Count('entry'))
+    <QuerySet [{'author': 1, 'entries': 20}, {'author': 1, 'entries': 13}]>
+    >>> Blog.objects.values('author').annotate(entries=Count('entry'))
+    <QuerySet [{'author': 1, 'entries': 33}]>
+
 A few subtleties that are worth mentioning:
 
 * If you have a field called ``foo`` that is a
@@ -603,6 +620,10 @@ You can also refer to fields on related models with reverse relations through
    pronounced if you include multiple such fields in your ``values()`` query,
    in which case all possible combinations will be returned.
 
+.. versionchanged:: 1.11
+
+    Support for ``**expressions`` was added.
+
 ``values_list()``
 ~~~~~~~~~~~~~~~~~
 
@@ -610,11 +631,14 @@ You can also refer to fields on related models with reverse relations through
 
 This is similar to ``values()`` except that instead of returning dictionaries,
 it returns tuples when iterated over. Each tuple contains the value from the
-respective field passed into the ``values_list()`` call — so the first item is
-the first field, etc. For example::
+respective field or expression passed into the ``values_list()`` call — so the
+first item is the first field, etc. For example::
 
     >>> Entry.objects.values_list('id', 'headline')
     [(1, 'First entry'), ...]
+    >>> from django.db.models.functions import Lower
+    >>> Entry.objects.values_list('id', Lower('headline'))
+    [(1, 'first entry'), ...]
 
 If you only pass in a single field, you can also pass in the ``flat``
 parameter. If ``True``, this will mean the returned results are single values,
@@ -661,6 +685,10 @@ not having any author::
     >>> Entry.objects.values_list('authors')
     [('Noam Chomsky',), ('George Orwell',), (None,)]
 
+.. versionchanged:: 1.11
+
+    Support for expressions in ``*fields`` was added.
+
 ``dates()``
 ~~~~~~~~~~~
 
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index a09e38a3ae..c8fc03c2b6 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -227,6 +227,9 @@ Models
   to truncate :class:`~django.db.models.DateTimeField` to its time component
   and exposed it through the :lookup:`time` lookup.
 
+* Added support for expressions in :meth:`.QuerySet.values` and
+  :meth:`~.QuerySet.values_list`.
+
 Requests and Responses
 ~~~~~~~~~~~~~~~~~~~~~~
 
-- 
cgit v1.3