Ticket #19326: 19326.diff

django/db/models/manager.py

@@ -139 +139 @@
     def extra(self, *args, **kwargs):
         return self.get_query_set().extra(*args, **kwargs)
 
+    def first(self, *args, **kwargs): 
+        return self.get_query_set().first(*args, **kwargs)
+
     def get(self, *args, **kwargs):
         return self.get_query_set().get(*args, **kwargs)
 

django/db/models/query.py

@@ -363 +363 @@
 
         return self.query.get_count(using=self.db)
 
+    def first(self, *args, **kwargs):
+        """
+        Performs the query and returns the first object matching the given
+        keyword arguments or None if no match is found.
+        """
+        clone = self.filter(*args, **kwargs)
+        if self.query.can_filter():
+            clone = clone.order_by()
+        if clone:
+            return clone._result_cache[0]
+        return None
+
     def get(self, *args, **kwargs):
         """
         Performs the query and returns a single object matching the given

docs/ref/models/querysets.txt

@@ -1238 +1238 @@
 These methods do not use a cache (see :ref:`caching-and-querysets`). Rather,
 they query the database each time they're called.
 
+first
+~~~
+.. method:: first(**kwargs)
+
+.. versionadded:: 1.6
+
+Returns the first of all objects matching the given lookup parameters, which 
+should be in the format described in `Field lookups`_. 
+
+``first()`` returns None if no object was found for the given parameters.
+
+``first()`` returns the first object in the QuerySet when multiple objects were
+found, as determined by the ordering in the model or in the query. 
+
+Example::
+    p = Person.objects.first(first_name="Paul")
+
 get
 ~~~
 

tests/modeltests/basic/tests.py

@@ -162 +162 @@
             pub_date__month=7,
         )
 
+        # First should return None when no object is found
+        self.assertEqual(
+            Article.objects.first(pub_date__year=2012),
+            None,
+        )
+
+        # First should return the first object when multiple objects are found
+        a = Article.objects.filter(pub_date__year=2005)[0]
+
+        self.assertEqual(
+            Article.objects.first(pub_date__year=2005),
+            a,
+        )
+
     def test_object_creation(self):
         # Create an Article.
         a = Article(