Fixed #17813 -- Added a .earliest() method to QuerySet

Thanks a lot to everybody participating in developing this feature.
The patch was developed by multiple people, at least Trac aliases
tonnzor, jimmysong, Fandekasp and slurms.

Stylistic changes added by committer.

4 files changed, 126 insertions, 63 deletions

diff --git a/tests/modeltests/get_latest/__init__.py b/tests/modeltests/get_earliest_or_latest/__init__.py
index e69de29bb2..e69de29bb2 100644
--- a/tests/modeltests/get_latest/__init__.py
+++ b/tests/modeltests/get_earliest_or_latest/__init__.py
diff --git a/tests/modeltests/get_latest/models.py b/tests/modeltests/get_earliest_or_latest/models.py
index fe594dd802..2453eaaccd 100644
--- a/tests/modeltests/get_latest/models.py
+++ b/tests/modeltests/get_earliest_or_latest/models.py
@@ -9,10 +9,8 @@ farthest into the future."
 """
 
 from django.db import models
-from django.utils.encoding import python_2_unicode_compatible
 
 
-@python_2_unicode_compatible
 class Article(models.Model):
     headline = models.CharField(max_length=100)
     pub_date = models.DateField()
@@ -20,15 +18,15 @@ class Article(models.Model):
     class Meta:
         get_latest_by = 'pub_date'
 
-    def __str__(self):
+    def __unicode__(self):
         return self.headline
 
-@python_2_unicode_compatible
+
 class Person(models.Model):
     name = models.CharField(max_length=30)
     birthday = models.DateField()
 
     # Note that this model doesn't have "get_latest_by" set.
 
-    def __str__(self):
+    def __unicode__(self):
         return self.name
diff --git a/tests/modeltests/get_earliest_or_latest/tests.py b/tests/modeltests/get_earliest_or_latest/tests.py
new file mode 100644
index 0000000000..6317a0974c
--- /dev/null
+++ b/tests/modeltests/get_earliest_or_latest/tests.py
@@ -0,0 +1,123 @@
+from __future__ import absolute_import
+
+from datetime import datetime
+
+from django.test import TestCase
+
+from .models import Article, Person
+
+
+class EarliestOrLatestTests(TestCase):
+    """Tests for the earliest() and latest() objects methods"""
+
+    def tearDown(self):
+        """Makes sure Article has a get_latest_by"""
+        if not Article._meta.get_latest_by:
+            Article._meta.get_latest_by = 'pub_date'
+
+    def test_earliest(self):
+        # Because no Articles exist yet, earliest() raises ArticleDoesNotExist.
+        self.assertRaises(Article.DoesNotExist, Article.objects.earliest)
+
+        a1 = Article.objects.create(
+            headline="Article 1", pub_date=datetime(2005, 7, 26),
+            expire_date=datetime(2005, 9, 1)
+        )
+        a2 = Article.objects.create(
+            headline="Article 2", pub_date=datetime(2005, 7, 27),
+            expire_date=datetime(2005, 7, 28)
+        )
+        a3 = Article.objects.create(
+            headline="Article 3", pub_date=datetime(2005, 7, 28),
+            expire_date=datetime(2005, 8, 27)
+        )
+        a4 = Article.objects.create(
+            headline="Article 4", pub_date=datetime(2005, 7, 28),
+            expire_date=datetime(2005, 7, 30)
+        )
+
+        # Get the earliest Article.
+        self.assertEqual(Article.objects.earliest(), a1)
+        # Get the earliest Article that matches certain filters.
+        self.assertEqual(
+            Article.objects.filter(pub_date__gt=datetime(2005, 7, 26)).earliest(),
+            a2
+        )
+
+        # Pass a custom field name to earliest() to change the field that's used
+        # to determine the earliest object.
+        self.assertEqual(Article.objects.earliest('expire_date'), a2)
+        self.assertEqual(Article.objects.filter(
+            pub_date__gt=datetime(2005, 7, 26)).earliest('expire_date'), a2)
+
+        # Ensure that earliest() overrides any other ordering specified on the
+        # query. Refs #11283.
+        self.assertEqual(Article.objects.order_by('id').earliest(), a1)
+
+        # Ensure that error is raised if the user forgot to add a get_latest_by
+        # in the Model.Meta
+        Article.objects.model._meta.get_latest_by = None
+        self.assertRaisesMessage(
+            AssertionError,
+            "earliest() and latest() require either a field_name parameter or "
+            "'get_latest_by' in the model",
+            lambda: Article.objects.earliest(),
+        )
+
+    def test_latest(self):
+        # Because no Articles exist yet, latest() raises ArticleDoesNotExist.
+        self.assertRaises(Article.DoesNotExist, Article.objects.latest)
+
+        a1 = Article.objects.create(
+            headline="Article 1", pub_date=datetime(2005, 7, 26),
+            expire_date=datetime(2005, 9, 1)
+        )
+        a2 = Article.objects.create(
+            headline="Article 2", pub_date=datetime(2005, 7, 27),
+            expire_date=datetime(2005, 7, 28)
+        )
+        a3 = Article.objects.create(
+            headline="Article 3", pub_date=datetime(2005, 7, 27),
+            expire_date=datetime(2005, 8, 27)
+        )
+        a4 = Article.objects.create(
+            headline="Article 4", pub_date=datetime(2005, 7, 28),
+            expire_date=datetime(2005, 7, 30)
+        )
+
+        # Get the latest Article.
+        self.assertEqual(Article.objects.latest(), a4)
+        # Get the latest Article that matches certain filters.
+        self.assertEqual(
+            Article.objects.filter(pub_date__lt=datetime(2005, 7, 27)).latest(),
+            a1
+        )
+
+        # 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)
+        self.assertEqual(
+            Article.objects.filter(pub_date__gt=datetime(2005, 7, 26)).latest('expire_date'),
+            a3,
+        )
+
+        # Ensure that latest() overrides any other ordering specified on the query. Refs #11283.
+        self.assertEqual(Article.objects.order_by('id').latest(), a4)
+
+        # Ensure that error is raised if the user forgot to add a get_latest_by
+        # in the Model.Meta
+        Article.objects.model._meta.get_latest_by = None
+        self.assertRaisesMessage(
+            AssertionError,
+            "earliest() and latest() require either a field_name parameter or "
+            "'get_latest_by' in the model",
+            lambda: Article.objects.latest(),
+        )
+
+    def test_latest_manual(self):
+        # You can still use latest() with a model that doesn't have
+        # "get_latest_by" set -- just pass in the field name manually.
+        p1 = Person.objects.create(name="Ralph", birthday=datetime(1950, 1, 1))
+        p2 = Person.objects.create(name="Stephanie", birthday=datetime(1960, 2, 3))
+        self.assertRaises(AssertionError, Person.objects.latest)
+        self.assertEqual(Person.objects.latest("birthday"), p2)
diff --git a/tests/modeltests/get_latest/tests.py b/tests/modeltests/get_latest/tests.py
deleted file mode 100644
index 948af6045a..0000000000
--- a/tests/modeltests/get_latest/tests.py
+++ /dev/null
@@ -1,58 +0,0 @@
-from __future__ import absolute_import
-
-from datetime import datetime
-
-from django.test import TestCase
-
-from .models import Article, Person
-
-
-class LatestTests(TestCase):
-    def test_latest(self):
-        # Because no Articles exist yet, latest() raises ArticleDoesNotExist.
-        self.assertRaises(Article.DoesNotExist, Article.objects.latest)
-
-        a1 = Article.objects.create(
-            headline="Article 1", pub_date=datetime(2005, 7, 26),
-            expire_date=datetime(2005, 9, 1)
-        )
-        a2 = Article.objects.create(
-            headline="Article 2", pub_date=datetime(2005, 7, 27),
-            expire_date=datetime(2005, 7, 28)
-        )
-        a3 = Article.objects.create(
-            headline="Article 3", pub_date=datetime(2005, 7, 27),
-            expire_date=datetime(2005, 8, 27)
-        )
-        a4 = Article.objects.create(
-            headline="Article 4", pub_date=datetime(2005, 7, 28),
-            expire_date=datetime(2005, 7, 30)
-        )
-
-        # Get the latest Article.
-        self.assertEqual(Article.objects.latest(), a4)
-        # Get the latest Article that matches certain filters.
-        self.assertEqual(
-            Article.objects.filter(pub_date__lt=datetime(2005, 7, 27)).latest(),
-            a1
-        )
-
-        # 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)
-        self.assertEqual(
-            Article.objects.filter(pub_date__gt=datetime(2005, 7, 26)).latest('expire_date'),
-            a3,
-        )
-
-        # Ensure that latest() overrides any other ordering specified on the query. Refs #11283.
-        self.assertEqual(Article.objects.order_by('id').latest(), a4)
-
-    def test_latest_manual(self):
-        # You can still use latest() with a model that doesn't have
-        # "get_latest_by" set -- just pass in the field name manually.
-        p1 = Person.objects.create(name="Ralph", birthday=datetime(1950, 1, 1))
-        p2 = Person.objects.create(name="Stephanie", birthday=datetime(1960, 2, 3))
-        self.assertRaises(AssertionError, Person.objects.latest)
-
-        self.assertEqual(Person.objects.latest("birthday"), p2)