Ticket #11557: django-11557.patch

django/db/models/query.py

@@ -380 +380 @@
                 except self.model.DoesNotExist:
                     raise e
 
-    def latest(self, field_name=None):
+    def latest(self, *field_names, **kwargs):
         """
         Returns the latest object, according to the model's 'get_latest_by'
         option or optional given field_name.
         """
-        latest_by = field_name or self.model._meta.get_latest_by
-        assert bool(latest_by), "latest() requires either a field_name parameter or 'get_latest_by' in the model"
+        if field_names:
+            assert not kwargs, "latest(): keyword arguments should not be passed with positional arguments"
+        else:
+            try:
+                # For backwards compatibility, handle field_name keyword
+                # argument:
+                field_names = (kwargs['field_name'],)
+            except KeyError, e:
+                field_names = ()
+
+        if field_names:
+            latest_by = field_names
+        else:
+            latest_by = self.model._meta.get_latest_by
+            if isinstance(latest_by, basestring):
+                latest_by = (latest_by,)
+
+        assert bool(latest_by), "latest() requires one or more field_name parameters or 'get_latest_by' in the model"
         assert self.query.can_filter(), \
                 "Cannot change a query once a slice has been taken."
+
         obj = self._clone()
         obj.query.set_limits(high=1)
-        obj.query.add_ordering('-%s' % latest_by)
+        for s in latest_by:
+            obj.query.add_ordering('-%s' % s)
         return obj.get()
 
     def in_bulk(self, id_list):

docs/ref/models/options.txt

@@ -75 +75 @@
 
 .. attribute:: Options.get_latest_by
 
-The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
-specifies the default field to use in your model :class:`Manager`'s
-:class:`~QuerySet.latest` method.
-
-Example::
-
+The name of one or more fields (often a single :class:`DateField` or
+:class:`DateTimeField`) in the model. This specifies the default field(s)
+to use in your model :class:`Manager`'s :class:`~QuerySet.latest` method.
+
+This can either be a tuple or list of strings, or a string specifying a
+single column.
+
+Examples::
+
+    get_latest_by = ("pub_date", "sort_order")
     get_latest_by = "order_date"
 
 See the docs for :meth:`~django.db.models.QuerySet.latest` for more.

docs/ref/models/querysets.txt

@@ -1149 +1149 @@
 
 .. _iterator: http://www.python.org/dev/peps/pep-0234/
 
-``latest(field_name=None)``
+``latest(*field_names)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: latest(field_name=None)
+.. method:: latest(*field_names)
 
-Returns the latest object in the table, by date, using the ``field_name``
-provided as the date field.
+Returns the last object in the table with rows ordered according to
+``field_names``.  field_names is typically a single date field.
 
 This example returns the latest ``Entry`` in the table, according to the
 ``pub_date`` field::
 
     Entry.objects.latest('pub_date')
 
-If your model's ``Meta`` specifies ``get_latest_by``, you can leave off the
-``field_name`` argument to ``latest()``. Django will use the field specified in
+With multiple fields, arguments are interpreted as for the ``order_by`` method.
+
+If your model's ``Meta`` specifies ``get_latest_by``, no ``field_names`` need to
+be passed to ``latest()``.  Django will use the field(s) specified in
 ``get_latest_by`` by default.
 
 Like ``get()``, ``latest()`` raises ``DoesNotExist`` if an object doesn't

tests/modeltests/get_latest/models.py

@@ -28 +28 @@
 
     def __unicode__(self):
         return self.name
+
+class ArticleLatestByMultiple(Article):
+    class Meta:
+        get_latest_by = ('pub_date', 'headline')

tests/modeltests/get_latest/tests.py

@@ -2 +2 @@
 
 from django.test import TestCase
 
-from models import Article, Person
+from models import Article, Person, ArticleLatestByMultiple
 
 
 class LatestTests(TestCase):
@@ -38 +38 @@
         # Pass a custom field name to latest() to change the field that's used
         # to determine the latest object.
         self.assertEqual(Article.objects.latest('expire_date'), a1)
+        # Test backwards compatibility with keyword argument syntax:
+        self.assertEqual(Article.objects.latest(field_name='expire_date'), a1)
         self.assertEqual(
             Article.objects.filter(pub_date__gt=datetime(2005, 7, 26)).latest('expire_date'),
             a3,
@@ -51 +53 @@
         self.assertRaises(AssertionError, Person.objects.latest)
 
         self.assertEqual(Person.objects.latest("birthday"), p2)
+
+    def test_latest_by_multiple(self):
+        a4 = ArticleLatestByMultiple.objects.create(
+            headline="Article 4", pub_date=datetime(2005, 7, 26),
+            expire_date=datetime(2005, 9, 1)
+        )
+        a3 = ArticleLatestByMultiple.objects.create(
+            headline="Article 3", pub_date=datetime(2005, 7, 26),
+            expire_date=datetime(2005, 7, 28)
+        )
+        a2 = ArticleLatestByMultiple.objects.create(
+            headline="Article 2", pub_date=datetime(2005, 7, 27),
+            expire_date=datetime(2005, 8, 27)
+        )
+        a1 = ArticleLatestByMultiple.objects.create(
+            headline="Article 1", pub_date=datetime(2005, 7, 27),
+            expire_date=datetime(2005, 9, 30)
+        )
+
+        # Get the latest ArticleLatestByMultiple.
+        self.assertEqual(ArticleLatestByMultiple.objects.latest(), a2)
+        # Get the latest ArticleLatestByMultiple that matches certain filters.
+        self.assertEqual(
+            ArticleLatestByMultiple.objects.filter(pub_date__lt=datetime(2005, 7, 27)).latest(),
+            a4
+        )
+
+        # Pass a custom field name to latest() to change the field that's used
+        # to determine the latest object.
+        self.assertEqual(ArticleLatestByMultiple.objects.latest('expire_date', 'headline'), a1)
+        self.assertEqual(ArticleLatestByMultiple.objects.latest('headline', 'expire_date'), a4)