From 409435440a8f8d453fa88aae9afb7799972b4422 Mon Sep 17 00:00:00 2001 From: Gabriel Hurley Date: Tue, 8 Mar 2011 19:51:19 +0000 Subject: [PATCH] Fixed #15558 -- Improved QuerySet reference docs and cleaned up numerous reST/sphinx problems. git-svn-id: http://code.djangoproject.com/svn/django/trunk@15776 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/querysets.txt | 56 +++++++++++++++++++++++++--------- docs/topics/http/shortcuts.txt | 9 +++--- 2 files changed, 46 insertions(+), 19 deletions(-) diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index cacc5e7ec3..badcf38f53 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -2,7 +2,7 @@ QuerySet API reference ====================== -.. currentmodule:: django.db.models.QuerySet +.. currentmodule:: django.db.models.query This document describes the details of the ``QuerySet`` API. It builds on the material presented in the :doc:`model ` and :doc:`database @@ -120,12 +120,38 @@ QuerySet API ============ Though you usually won't create one manually -- you'll go through a -:class:`Manager` -- here's the formal declaration of a ``QuerySet``: +:class:`~django.db.models.Manager` -- here's the formal declaration of a +``QuerySet``: -.. class:: QuerySet([model=None]) +.. class:: QuerySet([model=None, query=None, using=None]) -Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining -filters `. To make this work, most ``QuerySet`` methods return new querysets. + Usually when you'll interact with a ``QuerySet`` you'll use it by + :ref:`chaining filters `. To make this work, most + ``QuerySet`` methods return new querysets. These methods are covered in + detail later in this section. + + The ``QuerySet`` class has two public attributes you can use for + introspection: + + .. attribute:: ordered + + ``True`` if the ``QuerySet`` is ordered -- i.e. has an order_by() + clause or a default ordering on the model. ``False`` otherwise. + + .. attribute:: db + + The database that will be used if this query is executed now. + + .. note:: + + The ``query`` parameter to :class:`QuerySet` exists so that specialized + query subclasses such as + :class:`~django.contrib.gis.db.models.GeoQuerySet` can reconstruct + internal query state. The value of the parameter is an opaque + representation of that query state and is not part of a public API. + To put it simply: if you need to ask, you don't need to use it. + +.. currentmodule:: django.db.models.query.QuerySet Methods that return new QuerySets --------------------------------- @@ -285,7 +311,7 @@ If you don't want any ordering to be applied to a query, not even the default ordering, call ``order_by()`` with no parameters. You can tell if a query is ordered or not by checking the -:attr:`QuerySet.ordered` attribute, which will be ``True`` if the +:attr:`.QuerySet.ordered` attribute, which will be ``True`` if the ``QuerySet`` has been ordered in any way. reverse @@ -999,9 +1025,9 @@ The :ref:`force_insert ` parameter is documented elsewhere, but all it means is that a new object will always be created. Normally you won't need to worry about this. However, if your model contains a manual primary key value that you set and if that value already exists in the -database, a call to ``create()`` will fail with an :exc:`IntegrityError` since -primary keys must be unique. So remember to be prepared to handle the exception -if you are using manual primary keys. +database, a call to ``create()`` will fail with an +:exc:`~django.db.IntegrityError` since primary keys must be unique. So remember +to be prepared to handle the exception if you are using manual primary keys. get_or_create ~~~~~~~~~~~~~ @@ -1197,10 +1223,10 @@ exists .. versionadded:: 1.2 -Returns ``True`` if the :class:`QuerySet` contains any results, and ``False`` +Returns ``True`` if the :class:`.QuerySet` contains any results, and ``False`` if not. This tries to perform the query in the simplest and fastest way possible, but it *does* execute nearly the same query. This means that calling -:meth:`QuerySet.exists()` is faster than ``bool(some_query_set)``, but not by +:meth:`.QuerySet.exists` is faster than ``bool(some_query_set)``, but not by a large degree. If ``some_query_set`` has not yet been evaluated, but you know that it will be at some point, then using ``some_query_set.exists()`` will do more overall work (an additional query) than simply using @@ -1213,10 +1239,10 @@ update Performs an SQL update query for the specified fields, and returns the number of rows affected. The ``update()`` method is applied instantly and -the only restriction on the :class:`QuerySet` that is updated is that it can +the only restriction on the :class:`.QuerySet` that is updated is that it can only update columns in the model's main table. Filtering based on related fields is still possible. You cannot call ``update()`` on a -:class:`QuerySet` that has had a slice taken or can otherwise no longer be +:class:`.QuerySet` that has had a slice taken or can otherwise no longer be filtered. For example, if you wanted to update all the entries in a particular blog @@ -1236,9 +1262,9 @@ delete .. method:: delete() -Performs an SQL delete query on all rows in the :class:`QuerySet`. The +Performs an SQL delete query on all rows in the :class:`.QuerySet`. The ``delete()`` is applied instantly. You cannot call ``delete()`` on a -:class:`QuerySet` that has had a slice taken or can otherwise no longer be +:class:`.QuerySet` that has had a slice taken or can otherwise no longer be filtered. For example, to delete all the entries in a particular blog:: diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt index b228d0b13c..cc24560295 100644 --- a/docs/topics/http/shortcuts.txt +++ b/docs/topics/http/shortcuts.txt @@ -24,7 +24,7 @@ introduce controlled coupling for convenience's sake. :func:`render()` is the same as a call to :func:`render_to_response()` with a `context_instance` argument that - that forces the use of a :class:`RequestContext`. + that forces the use of a :class:`~django.template.RequestContext`. Required arguments ------------------ @@ -220,7 +220,7 @@ will be returned:: .. function:: get_object_or_404(klass, *args, **kwargs) - Calls :meth:`~django.db.models.QuerySet.get()` on a given model manager, + Calls :meth:`~django.db.models.query.QuerySet.get()` on a given model manager, but it raises :class:`~django.http.Http404` instead of the model's :class:`~django.core.exceptions.DoesNotExist` exception. @@ -229,7 +229,8 @@ Required arguments ``klass`` A :class:`~django.db.models.Model`, :class:`~django.db.models.Manager` or - :class:`~django.db.models.QuerySet` instance from which to get the object. + :class:`~django.db.models.query.QuerySet` instance from which to get the + object. ``**kwargs`` Lookup parameters, which should be in the format accepted by ``get()`` and @@ -265,7 +266,7 @@ will be raised if more than one object is found. .. function:: get_list_or_404(klass, *args, **kwargs) - Returns the result of :meth:`~django.db.models.QuerySet.filter()` on a + Returns the result of :meth:`~django.db.models.query.QuerySet.filter()` on a given model manager, raising :class:`~django.http.Http404` if the resulting list is empty.