From 36f260341a1720d7a38e482234c84ff8e73eab85 Mon Sep 17 00:00:00 2001 From: Loic Bistuer Date: Thu, 6 Feb 2014 02:27:01 +0700 Subject: [PATCH] Extended the release notes for chainable Manager/QuerySet methods. Refs #20625. --- docs/releases/1.7.txt | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index 41ad106232..1bd38d9c8e 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -127,9 +127,40 @@ to call the method on the superclass and simply add or remove extra arguments. Calling custom ``QuerySet`` methods from the ``Manager`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historically, the recommended way to make reusable model queries was to create +methods on a custom ``Manager`` class. The problem with this approach was that +after the first method call, you'd get back a ``QuerySet`` instance and +couldn't call additional custom manager methods. + +Though not documented, it was common to work around this issue by creating a +custom ``QuerySet`` so that custom methods could be chained; but the solution +had a number of drawbacks: + +* The custom ``QuerySet`` and its custom methods were lost after the first + call to ``values()`` or ``values_list()``. + +* Writing a custom ``Manager`` was still necessary to return the custom + ``QuerySet`` class and all methods that were desired on the ``Manager`` + had to be proxied to the ``QuerySet``. The whole process went against + the DRY principle. + The :meth:`QuerySet.as_manager() ` -class method has been added to :ref:`create Manager with QuerySet methods -`. +class method can now directly :ref:`create Manager with QuerySet methods +`:: + + class FoodQuerySet(models.QuerySet): + def pizzas(self): + return self.filter(kind='pizza') + + def vegetarian(self): + return self.filter(vegetarian=True) + + class Food(models.Model): + kind = models.CharField(max_length=50) + vegetarian = models.BooleanField() + objects = FoodQuerySet.as_manager() + + Food.objects.pizzas().vegetarian() Using a custom manager when traversing reverse relations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~