2 files changed, 79 insertions, 0 deletions
diff --git a/tests/modeltests/get_latest/__init__.py b/tests/modeltests/get_latest/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/tests/modeltests/get_latest/__init__.py
diff --git a/tests/modeltests/get_latest/models.py b/tests/modeltests/get_latest/models.py
new file mode 100644
index 0000000000..4b81dc837c
--- /dev/null
+++ b/tests/modeltests/get_latest/models.py
@@ -0,0 +1,79 @@
+"""
+8. get_latest_by
+
+Models can have a ``get_latest_by`` attribute, which should be set to the name
+of a DateField or DateTimeField. If ``get_latest_by`` exists, the model's
+module will get a ``get_latest()`` function, which will return the latest
+object in the database according to that field. "Latest" means "having the
+date farthest into the future."
+"""
+
+from django.db import models
+
+class Article(models.Model):
+    headline = models.CharField(maxlength=100)
+    pub_date = models.DateField()
+    expire_date = models.DateField()
+    class Meta:
+        get_latest_by = 'pub_date'
+
+    def __repr__(self):
+        return self.headline
+
+class Person(models.Model):
+    name = models.CharField(maxlength=30)
+    birthday = models.DateField()
+
+    # Note that this model doesn't have "get_latest_by" set.
+
+    def __repr__(self):
+        return self.name
+
+API_TESTS = """
+# Because no Articles exist yet, get_latest() raises ArticleDoesNotExist.
+>>> Article.objects.latest()
+Traceback (most recent call last):
+    ...
+DoesNotExist: Article does not exist for ...
+
+# Create a couple of Articles.
+>>> from datetime import datetime
+>>> a1 = Article(headline='Article 1', pub_date=datetime(2005, 7, 26), expire_date=datetime(2005, 9, 1))
+>>> a1.save()
+>>> a2 = Article(headline='Article 2', pub_date=datetime(2005, 7, 27), expire_date=datetime(2005, 7, 28))
+>>> a2.save()
+>>> a3 = Article(headline='Article 3', pub_date=datetime(2005, 7, 27), expire_date=datetime(2005, 8, 27))
+>>> a3.save()
+>>> a4 = Article(headline='Article 4', pub_date=datetime(2005, 7, 28), expire_date=datetime(2005, 7, 30))
+>>> a4.save()
+
+# Get the latest Article.
+>>> Article.objects.latest()
+Article 4
+
+# Get the latest Article that matches certain filters.
+>>> Article.objects.filter(pub_date__lt=datetime(2005, 7, 27)).latest()
+Article 1
+
+# Pass a custom field name to latest() to change the field that's used to
+# determine the latest object.
+>>> Article.objects.latest('expire_date')
+Article 1
+
+>>> Article.objects.filter(pub_date__gt=datetime(2005, 7, 26)).latest('expire_date')
+Article 3
+
+# 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(name='Ralph', birthday=datetime(1950, 1, 1))
+>>> p1.save()
+>>> p2 = Person(name='Stephanie', birthday=datetime(1960, 2, 3))
+>>> p2.save()
+>>> Person.objects.latest()
+Traceback (most recent call last):
+    ...
+AssertionError: latest() requires either a field_name parameter or 'get_latest_by' in the model
+
+>>> Person.objects.latest('birthday')
+Stephanie
+"""