Ticket #14150: get_objects_or_404.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_list_or_404(klass, *args, **kwargs):
+def get_objects_or_404(klass, *args, **kwargs):
     """
-    Uses filter() to return a list of objects, or raise a Http404 exception if
-    the list is empty.
+    Get a set of filtered objects
 
+    Uses filter() to return objects, or raise a Http404 exception if
+    no objects matches.
+
     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:
+    objects = queryset.filter(*args, **kwargs)
+    if not objects:
         raise Http404('No %s matches the given query.' % queryset.model._meta.object_name)
-    return obj_list
- No newline at end of file
+    return objects
+
+def get_list_or_404(klass, *args, **kwargs):
+    """
+    Get a list of filtered objects
+
+    Uses get_object_or_404 to get a set of objects, which will raise a Http404 exception if
+    no objects matches, then returns that set as a list.
+
+    klass may be a Model, Manager, or QuerySet object. All other passed
+    arguments and keyword arguments are used in the filter() query
+    with get_objects_or_404.
+    """
+    return list(get_objects_or_404(klass, *args, **kwargs))

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_objects_or_404``
+===================
+
+.. function:: get_objects_or_404(klass, *args, **kwargs)
+
+   Returns the result of :meth:`~django.db.models.QuerySet.filter()` on a
+   given model manager, raising ``django.http.Http404`` if no objects matched.
+
+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_objects_or_404
+
+    def my_view(request):
+        my_objects = get_objects_or_404(MyModel, published=True)
+
+This example is equivalent to::
+
+    from django.http import Http404
+
+    def my_view(request):
+        my_objects = MyModel.objects.filter(published=True)
+        if not my_objects:
+            raise Http404
+
+Because get_objects_or_404 returns a queryset, it's possible to continue
+editing it:
+
+    from django.shortcuts import get_objects_or_404
+
+    def my_view(request):
+        my_objects = get_objects_or_404(MyModel, published=True).order_by('pub_date')
+
 ``get_list_or_404``
 ===================