Ticket #11352: object_list_404-3.diff

django/shortcuts/__init__.py

@@ -89 +89 @@
     except queryset.model.DoesNotExist:
         raise Http404('No %s matches the given query.' % queryset.model._meta.object_name)
 
+def get_object_or_none(klass, *args, **kwargs):
+    """
+    Uses get() to return an object, or returns an empty QuerySet if the list is empty.
+
+    klass may be a Model, Manager, or QuerySet object. All other passed
+    arguments and keyword arguments are used in the get() query.
+
+    Note: Like with get(), an MultipleObjectsReturned will be raised if more than one
+    object is found.
+    """
+    queryset = _get_queryset(klass)
+    try:
+        return queryset.get(*args, **kwargs)
+    except queryset.model.DoesNotExist:
+        return queryset.none()
+
 def get_list_or_404(klass, *args, **kwargs):
     """
     Uses filter() to return a list of objects, or raise a Http404 exception if
@@ -101 +117 @@
     obj_list = list(queryset.filter(*args, **kwargs))
     if not obj_list:
         raise Http404('No %s matches the given query.' % queryset.model._meta.object_name)
+    return obj_list
+
+def get_list_or_none(klass, *args, **kwargs):
+    """
+    Uses filter() to return a list of objects, or return an empty QuerySet if
+    the list is empty.
+
+    klass may be a Model, Manager, or QuerySet object. All other passed
+    arguments and keyword arguments are used in the filter() query.
+    """
+    queryset = _get_queryset(klass)
+    obj_list = list(queryset.filter(*args, **kwargs))
+    if not obj_list:
+        return list(queryset.none())
     return obj_list
+ No newline at end of file

tests/modeltests/get_object_or_404/models.py

@@ -5 +5 @@
 performing a ``get()`` lookup and raising a ``Http404`` exception if a
 ``DoesNotExist`` exception was raised during the ``get()`` call.
 
+``get_object_or_none()`` is a shortcut function to be used in view functions for
+performing a ``get()`` lookup and returning an empty QuerySet if a
+``DoesNotExist`` exception was raised during the ``get()`` call.
+
 ``get_list_or_404()`` is a shortcut function to be used in view functions for
 performing a ``filter()`` lookup and raising a ``Http404`` exception if a
 ``DoesNotExist`` exception was raised during the ``filter()`` call.
+
+``get_list_or_none()`` is a shortcut function to be used in view functions for
+performing a ``filter()`` lookup and returning an empty QuerySet if a
+``DoesNotExist`` exception was raised during the ``filter()`` call.
 """
 
 from django.db import models
 from django.http import Http404
-from django.shortcuts import get_object_or_404, get_list_or_404
+from django.shortcuts import get_object_or_404, get_list_or_404, \
+                             get_object_or_none, get_list_or_none
 
 class Author(models.Model):
     name = models.CharField(max_length=50)
@@ -45 +54 @@
 Traceback (most recent call last):
 ...
 Http404: No Article matches the given query.
+>>> get_object_or_none(Article, title="Foo")
+[]
 
 # Create an Article.
 >>> article = Article.objects.create(title="Run away!")
@@ -54 +65 @@
 # get_object_or_404 can be passed a Model to query.
 >>> get_object_or_404(Article, title__contains="Run")
 <Article: Run away!>
+>>> get_object_or_none(Article, title__contains="Run")
+<Article: Run away!>
 
 # We can also use the Article manager through an Author object.
 >>> get_object_or_404(a.article_set, title__contains="Run")
 <Article: Run away!>
+>>> get_object_or_none(a.article_set, title__contains="Run")
+<Article: Run away!>
 
 # No articles containing "Camelot".  This should raise a Http404 error.
 >>> get_object_or_404(a.article_set, title__contains="Camelot")
 Traceback (most recent call last):
 ...
 Http404: No Article matches the given query.
+>>> get_object_or_none(a.article_set, title__contains="Camelot")
+[]
 
 # Custom managers can be used too.
 >>> get_object_or_404(Article.by_a_sir, title="Run away!")
 <Article: Run away!>
+>>> get_object_or_none(Article.by_a_sir, title="Run away!")
+<Article: Run away!>
 
 # QuerySets can be used too.
 >>> get_object_or_404(Article.objects.all(), title__contains="Run")
 <Article: Run away!>
+>>> get_object_or_none(Article.objects.all(), title__contains="Run")
+<Article: Run away!>
 
 # Just as when using a get() lookup, you will get an error if more than one
 # object is returned.
@@ -79 +100 @@
 Traceback (most recent call last):
 ...
 MultipleObjectsReturned: get() returned more than one Author -- it returned ...! Lookup parameters were {}
+>>> get_object_or_none(Author.objects.all())
+Traceback (most recent call last):
+...
+MultipleObjectsReturned: get() returned more than one Author -- it returned ...! Lookup parameters were {}
 
 # Using an EmptyQuerySet raises a Http404 error.
 >>> get_object_or_404(Article.objects.none(), title__contains="Run")
 Traceback (most recent call last):
 ...
 Http404: No Article matches the given query.
+>>> get_object_or_none(Article.objects.none(), title__contains="Run")
+[]
 
 # get_list_or_404 can be used to get lists of objects
 >>> get_list_or_404(a.article_set, title__icontains='Run')
 [<Article: Run away!>]
+>>> get_list_or_none(a.article_set, title__icontains='Run')
+[<Article: Run away!>]
 
 # Http404 is returned if the list is empty.
 >>> get_list_or_404(a.article_set, title__icontains='Shrubbery')
 Traceback (most recent call last):
 ...
 Http404: No Article matches the given query.
+>>> get_list_or_none(a.article_set, title__icontains='Shrubbery')
+[]
 
 # Custom managers can be used too.
 >>> get_list_or_404(Article.by_a_sir, title__icontains="Run")
 [<Article: Run away!>]
+>>> get_list_or_none(Article.by_a_sir, title__icontains="Run")
+[<Article: Run away!>]
 
 # QuerySets can be used too.
 >>> get_list_or_404(Article.objects.all(), title__icontains="Run")
 [<Article: Run away!>]
+>>> get_list_or_none(Article.objects.all(), title__icontains="Run")
+[<Article: Run away!>]
 
 """}

docs/topics/http/shortcuts.txt

@@ -189 +189 @@
 Note: As with ``get()``, an ``MultipleObjectsReturned`` exception will be
 raised if more than one object is found.
 
+``get_object_or_none``
+=====================
+
+.. function:: get_object_or_none(klass, *args, **kwargs)
+
+   Calls :meth:`~django.db.models.QuerySet.get()` on a given model manager,
+   but it returns an empty QuerySet rather than raising the model's
+   ``DoesNotExist`` exception.
+
+Required arguments
+------------------
+
+``klass``
+    A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
+    object.
+
+``**kwargs``
+    Lookup parameters, which should be in the format accepted by ``get()`` and
+    ``filter()``.
+
+Example
+-------
+
+The following example gets the object with the primary key of 1 from
+``MyModel``::
+
+    from django.shortcuts import get_object_or_none
+
+    def my_view(request):
+        my_object = get_object_or_none(MyModel, pk=1)
+
+This example is equivalent to::
+
+    def my_view(request):
+        try:
+            my_object = MyModel.objects.get(pk=1)
+        except MyModel.DoesNotExist:
+            my_object = MyModel.objects.none()
+
+Note: As with ``get()``, an ``MultipleObjectsReturned`` exception will be
+raised if more than one object is found.
+
 ``get_list_or_404``
 ===================
 
@@ -227 +269 @@
         my_objects = list(MyModel.objects.filter(published=True))
         if not my_objects:
             raise Http404
+
+``get_list_or_none``
+===================
+
+.. function:: get_list_or_none(klass, *args, **kwargs)
+
+   Returns the result of :meth:`~django.db.models.QuerySet.filter()` on a
+   given model manager or an empty QuerySet if the resulting list is empty.
+
+Required arguments
+------------------
+
+``klass``
+    A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
+    object.
+
+``**kwargs``
+    Lookup parameters, which should be in the format accepted by ``get()`` and
+    ``filter()``.
+
+Example
+-------
+
+The following example gets all published objects from ``MyModel``::
+
+    from django.shortcuts import get_list_or_none
+
+    def my_view(request):
+        my_objects = get_list_or_none(MyModel, published=True)
+
+This example is equivalent to::
+
+    def my_view(request):
+        my_objects = list(MyModel.objects.filter(published=True))
+        if not my_objects:
+            my_objects = list(MyModel.objects.none())

AUTHORS

@@ -204 +204 @@
     Scot Hacker <shacker@birdhouse.org>
     dAniel hAhler
     hambaloney
+    Chuck Harmston <chuck@chuckharmston.com>
     Brian Harring <ferringb@gmail.com>
     Brant Harris
     Ronny Haryanto <http://ronny.haryan.to/>