Merged revisions 4186 to 4454 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/sqlalchemy@4455 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 58 insertions, 3 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 2f0c8b0589..99bb30054b 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -143,9 +143,9 @@ or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django
 follows this algorithm:
 
     * If the object's primary key attribute is set to a value that evaluates to
-      ``False`` (such as ``None`` or the empty string), Django executes a
-      ``SELECT`` query to determine whether a record with the given primary key
-      already exists.
+      ``True`` (i.e., a value other than ``None`` or the empty string), Django 
+      executes a ``SELECT`` query to determine whether a record with the given 
+      primary key already exists.
     * If the record with the given primary key does already exist, Django
       executes an ``UPDATE`` query.
     * If the object's primary key attribute is *not* set, or if it's set but a
@@ -525,6 +525,21 @@ Examples::
     [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
     >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
     [datetime.datetime(2005, 3, 20)]
+    
+``none()``
+~~~~~~~~~~
+
+**New in Django development version**
+
+Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to 
+an empty list. This can be used in cases where you know that you should
+return an empty result set and your caller is expecting a ``QuerySet``
+object (instead of returning an empty list, for example.)
+
+Examples::
+    
+    >>> Entry.objects.none()
+    []
 
 ``select_related()``
 ~~~~~~~~~~~~~~~~~~~~
@@ -1704,6 +1719,46 @@ For every ``ImageField``, the object will have ``get_FOO_height()`` and
 ``get_FOO_width()`` methods, where ``FOO`` is the name of the field. This
 returns the height (or width) of the image, as an integer, in pixels.
 
+Shortcuts
+=========
+
+As you develop views, you will discover a number of common idioms in the
+way you use the database API. Django encodes some of these idioms as
+shortcuts that can be used to simplify the process of writing views.
+
+get_object_or_404()
+-------------------
+
+One common idiom to use ``get()`` and raise ``Http404`` if the
+object doesn't exist. This idiom is captured by ``get_object_or_404()``. 
+This function takes a Django model as its first argument and an 
+arbitrary number of keyword arguments, which it passes to the manager's 
+``get()`` function. It raises ``Http404`` if the object doesn't
+exist. For example:: 
+    
+    # Get the Entry with a primary key of 3
+    e = get_object_or_404(Entry, pk=3)
+
+When you provide a model to this shortcut function, the default manager 
+is used to execute the underlying ``get()`` query. If you don't want to 
+use the default manager, or you want to search a list of related objects, 
+you can provide ``get_object_or_404()`` with a manager object, instead. 
+For example::
+
+    # Get the author of blog instance `e` with a name of 'Fred'
+    a = get_object_or_404(e.authors, name='Fred')
+
+    # Use a custom manager 'recent_entries' in the search for an
+    # entry with a primary key of 3
+    e = get_object_or_404(Entry.recent_entries, pk=3)
+
+get_list_or_404()
+-----------------
+
+``get_list_or_404`` behaves the same was as ``get_object_or_404()`` 
+-- except the it uses using ``filter()`` instead of ``get()``. It raises 
+``Http404`` if the list is empty.
+
 Falling back to raw SQL
 =======================