Ticket #17813: t17813.diff

django/db/models/base.py

@@ -71 +71 @@
                 # method resolution order).
                 if not hasattr(meta, 'ordering'):
                     new_class._meta.ordering = base_meta.ordering
+                if not hasattr(meta, 'get_first_by'):
+                    new_class._meta.get_first_by = base_meta.get_first_by
                 if not hasattr(meta, 'get_latest_by'):
                     new_class._meta.get_latest_by = base_meta.get_latest_by
 

django/db/models/manager.py

@@ -160 +160 @@
     def iterator(self, *args, **kwargs):
         return self.get_query_set().iterator(*args, **kwargs)
 
+    def first(self, *args, **kwargs):
+        return self.get_query_set().first(*args, **kwargs)
+
     def latest(self, *args, **kwargs):
         return self.get_query_set().latest(*args, **kwargs)
 

django/db/models/options.py

@@ -15 +15 @@
 get_verbose_name = lambda class_name: re.sub('(((?<=[a-z])[A-Z])|([A-Z](?![A-Z]|$)))', ' \\1', class_name).lower().strip()
 
 DEFAULT_NAMES = ('verbose_name', 'verbose_name_plural', 'db_table', 'ordering',
-                 'unique_together', 'permissions', 'get_latest_by',
+                 'unique_together', 'permissions', 'get_first_by', 'get_latest_by',
                  'order_with_respect_to', 'app_label', 'db_tablespace',
                  'abstract', 'managed', 'proxy', 'auto_created')
 
@@ -30 +30 @@
         self.unique_together =  []
         self.permissions =  []
         self.object_name, self.app_label = None, app_label
+        self.get_first_by = None
         self.get_latest_by = None
         self.order_with_respect_to = None
         self.db_tablespace = settings.DEFAULT_TABLESPACE

django/db/models/query.py

@@ -458 +458 @@
                     # Re-raise the IntegrityError with its original traceback.
                     raise exc_info[1], None, exc_info[2]
 
-    def latest(self, field_name=None):
+    def _first_or_latest(self, field_name=None, direction="-",
+            get_by='get_latest_by'):
         """
-        Returns the latest object, according to the model's 'get_latest_by'
-        option or optional given field_name.
+        Returns the latest object, according to the model's 'get_first_by' or
+        '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"
+        order_by = field_name or getattr(self.model._meta, get_by)
+        assert bool(order_by), "_first_or_latest() requires either a "\
+            "field_name parameter or '%s' in the model" % get_by
         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.clear_ordering()
-        obj.query.add_ordering('-%s' % latest_by)
+        obj.query.add_ordering('%s%s' % (direction, order_by))     
         return obj.get()
 
+    def first(self, field_name=None):
+        return self._first_or_latest(field_name=field_name, direction="",
+            get_by='get_first_by')
+
+    def latest(self, field_name=None):
+        return self._first_or_latest(field_name=field_name, direction="-")
+
     def in_bulk(self, id_list):
         """
         Returns a dictionary mapping each of the given IDs to the object with

docs/ref/models/options.txt

@@ -78 +78 @@
     setting, if set. If the backend doesn't support tablespaces, this option is
     ignored.
 
+
+``get_first_by``
+-----------------
+
+.. attribute:: Options.get_first_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.first` method.
+
+    Example::
+
+        get_first_by = "order_date"
+
+    See the docs for :meth:`~django.db.models.query.QuerySet.first` for more.
+
+
 ``get_latest_by``
 -----------------
 

docs/ref/models/querysets.txt

@@ -1465 +1465 @@
     Entry.objects.latest('pub_date')
 
 If your model's :ref:`Meta <meta-options>` specifies
-:attr:`~django.db.models.Options.get_latest_by`, you can leave off the
-``field_name`` argument to ``latest()``. Django will use the field specified
-in :attr:`~django.db.models.Options.get_latest_by` by default.
+:attr:`~django.db.models.Options.get_first_by`, you can leave off the
+``field_name`` argument to ``first()``. Django will use the field specified
+in :attr:`~django.db.models.Options.get_first_by` by default.
 
-Like :meth:`get()`, ``latest()`` raises
-:exc:`~django.core.exceptions.DoesNotExist` if there is no object with the given
-parameters.
+Same goes for :attr:`~django.db.models.Options.get_first_by` and ``latest()``.
+
+Like :meth:`get()`, ``first()`` and ``latest()`` raise
+:exc:`~django.core.exceptions.DoesNotExist` if there is no object with the
+given parameters.
 
-Note ``latest()`` exists purely for convenience and readability.
+Note that ``first()`` and ``latest()`` exist purely for convenience and
+readability.
 
 aggregate
 ~~~~~~~~~

docs/topics/db/models.txt

@@ -991 +991 @@
 
 So a child model does not have access to its parent's :ref:`Meta
 <meta-options>` class. However, there are a few limited cases where the child
-inherits behavior from the parent: if the child does not specify an
-:attr:`~django.db.models.Options.ordering` attribute or a
-:attr:`~django.db.models.Options.get_latest_by` attribute, it will inherit
-these from its parent.
+inherits behavior from the parent: if the child does not specify an attribute
+:attr:`~django.db.models.Options.ordering`,
+:attr:`~django.db.models.Options.get_first_by`, or
+:attr:`~django.db.models.Options.get_latest_by`,
+, it will inherit these from its parent.
 
 If the parent has an ordering and you don't want the child to have any natural
 ordering, you can explicitly disable it::

new file tests/modeltests/get_first_or_latest/models.py

@@ +1 @@
+"""
+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 manager will get a ``latest()`` method, 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(max_length=100)
+    pub_date = models.DateField()
+    expire_date = models.DateField()
+    class Meta:
+        get_first_by = 'pub_date'
+        get_latest_by = 'pub_date'
+
+    def __unicode__(self):
+        return self.headline
+
+
+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 __unicode__(self):
+        return self.name

new file tests/modeltests/get_first_or_latest/tests.py

@@ +1 @@
+from __future__ import absolute_import
+
+from datetime import datetime
+
+from django.test import TestCase
+
+from .models import Article, Person
+
+
+class FirstOrLatestTests(TestCase):
+    """Tests for the first() and latest() objects methods"""
+
+    def test_first(self):
+        # Because no Articles exist yet, first() raises ArticleDoesNotExist.
+        self.assertRaises(Article.DoesNotExist, Article.objects.first)
+
+        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 first Article.
+        self.assertEqual(Article.objects.first(), a1)
+        # Get the first Article that matches certain filters.
+        self.assertEqual(
+            Article.objects.filter(pub_date__gt=datetime(2005, 7, 26)).first(),
+            a2
+        )
+
+        # Pass a custom field name to first() to change the field that's used
+        # to determine the first object.
+        self.assertEqual(Article.objects.first('expire_date'), a2)
+        self.assertEqual(Article.objects.filter(
+            pub_date__gt=datetime(2005, 7, 26)).first('expire_date'), a2)
+
+        # Ensure that first() overrides any other ordering specified on the
+        # query. Refs #11283.
+        self.assertEqual(Article.objects.order_by('id').first(), a1)
+
+        # Ensure that error is raised if the user forgot to add a get_first_by
+        # in the Model.Meta
+        Article.objects.model._meta.get_first_by = None
+        self.assertRaisesMessage(
+            AssertionError,
+            "_first_or_latest() requires either a field_name parameter or "\
+                "'get_first_by' in the model",
+            lambda: Article.objects.first(),
+        )
+
+
+    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,
+            "_first_or_latest() requires 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)

deleted file tests/modeltests/get_latest/models.py

@@ -1 @@
-"""
-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 manager will get a ``latest()`` method, 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(max_length=100)
-    pub_date = models.DateField()
-    expire_date = models.DateField()
-    class Meta:
-        get_latest_by = 'pub_date'
-
-    def __unicode__(self):
-        return self.headline
-
-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 __unicode__(self):
-        return self.name

deleted file tests/modeltests/get_latest/tests.py

@@ -1 @@
-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)