[1.2.X] Fixed #14120 - Document get() in Making Queries - thanks danielr and adamv for work on the patch.

Backport of r14820 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@14821 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 37 insertions, 5 deletions

diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index 18a96459fc..923b1e4a16 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -163,6 +163,7 @@ That's because ``Entry.objects``, the root ``QuerySet``, is a special case
 that cannot be evaluated. The ``all()`` method returns a ``QuerySet`` that
 *can* be evaluated.)
 
+
 Retrieving specific objects with filters
 ----------------------------------------
 
@@ -258,12 +259,43 @@ aren't fetched from the database until you "ask" for them. When you do, the
 ``QuerySet`` is *evaluated* by accessing the database. For more details on
 exactly when evaluation takes place, see :ref:`when-querysets-are-evaluated`.
 
+
+.. _retrieving-single-object-with-get:
+
+Retrieving a single object with get
+-----------------------------------
+
+``.filter()`` will always give you a ``QuerySet``, even if only a single
+object matches the query - in this case, it will be a ``QuerySet`` containing
+a single element.
+
+If you know there is only one object that matches your query, you can use
+the ``get()`` method on a `Manager` which returns the object directly::
+
+    >>> one_entry = Entry.objects.get(pk=1)
+
+You can use any query expression with ``get()``, just like with ``filter()`` -
+again, see `Field lookups`_ below.
+
+Note that there is a difference between using ``.get()``, and using
+``.filter()`` with a slice of ``[0]``. If there are no results that match the
+query, ``.get()`` will raise a ``DoesNotExist`` exception. This exception is an
+attribute of the model class that the query is being performed on - so in the
+code above, if there is no ``Entry`` object with a primary key of 1, Django will
+raise ``Entry.DoesNotExist``.
+
+Similarly, Django will complain if more than one item matches the ``get()``
+query. In this case, it will raise ``MultipleObjectsReturned``, which again is
+an attribute of the model class itself.
+
+
 Other QuerySet methods
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
-Most of the time you'll use ``all()``, ``filter()`` and ``exclude()`` when you
-need to look up objects from the database. However, that's far from all there is; see the :ref:`QuerySet API Reference <queryset-api>` for a complete list
-of all the various ``QuerySet`` methods.
+Most of the time you'll use ``all()``, ``get()``, ``filter()`` and ``exclude()``
+when you need to look up objects from the database. However, that's far from all
+there is; see the :ref:`QuerySet API Reference <queryset-api>` for a complete
+list of all the various ``QuerySet`` methods.
 
 .. _limiting-querysets:
 
@@ -304,7 +336,7 @@ This is roughly equivalent to::
 
 Note, however, that the first of these will raise ``IndexError`` while the
 second will raise ``DoesNotExist`` if no objects match the given criteria. See
-``get()`` for more details.
+:meth:`~django.db.models.QuerySet.get` for more details.
 
 .. _field-lookups-intro: