From 61e902c4c4445412142c22819dd8d160995db11d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicolas=20No=C3=A9?= Date: Fri, 24 Apr 2015 10:53:44 -0400 Subject: [PATCH] [1.8.x] Fixed #24656 -- Added missing imports to query expressions doc. Backport of 37682368a604e08f3135375c85529e566492a352 from master --- AUTHORS | 1 + docs/ref/models/expressions.txt | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/AUTHORS b/AUTHORS index 3e83984e6f..ba80d56195 100644 --- a/AUTHORS +++ b/AUTHORS @@ -517,6 +517,7 @@ answer newbie questions, and generally made Django that much better: Niclas Olofsson Nicola Larosa Nicolas Lara + Nicolas Noé Niran Babalola Nis Jørgensen Nowell Strite diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index f74c4f2051..f592bc3c1e 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -30,6 +30,9 @@ Some examples .. code-block:: python + from django.db.models import F, Count + from django.db.models.functions import Length + # Find companies that have more employees than chairs. Company.objects.filter(num_employees__gt=F('num_chairs')) @@ -66,6 +69,12 @@ Some examples Built-in Expressions ==================== +.. note:: + + These expressions are defined in ``django.db.models.expressions`` and + ``django.db.models.aggregates``, but for convenience they're available and + usually imported from :mod:`django.db.models`. + ``F()`` expressions ------------------- @@ -92,6 +101,7 @@ into memory and manipulated it using familiar Python operators, and then saved the object back to the database. But instead we could also have done:: from django.db.models import F + reporter = Reporters.objects.get(name='Tintin') reporter.stories_filed = F('stories_filed') + 1 reporter.save() @@ -198,6 +208,8 @@ directly support ``output_field`` you will need to wrap the expression with database functions like ``COALESCE`` and ``LOWER``, or aggregates like ``SUM``. They can be used directly:: + from django.db.models import Func, F + queryset.annotate(field_lower=Func(F('field'), function='LOWER')) or they can be used to build a library of database functions:: @@ -263,6 +275,8 @@ like ``Sum()`` and ``Count()``, inherit from ``Aggregate()``. Since ``Aggregate``\s are expressions and wrap expressions, you can represent some complex computations:: + from django.db.models import Count + Company.objects.annotate( managers_required=(Count('num_employees') / 4) + Count('num_managers')) @@ -318,6 +332,8 @@ Creating your own aggregate is extremely easy. At a minimum, you need to define ``function``, but you can also completely customize the SQL that is generated. Here's a brief example:: + from django.db.models import Aggregate + class Count(Aggregate): # supports COUNT(distinct field) function = 'COUNT' @@ -582,6 +598,7 @@ to play nice with other query expressions:: Let's see how it works:: + >>> from django.db.models import F, Value, CharField >>> qs = Company.objects.annotate( ... tagline=Coalesce([ ... F('motto'),