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
This commit is contained in:
Gabriel Hurley 2011-03-08 19:51:19 +00:00
parent 8b22f7cf78
commit 409435440a
2 changed files with 46 additions and 19 deletions

View File

@ -2,7 +2,7 @@
QuerySet API reference 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 This document describes the details of the ``QuerySet`` API. It builds on the
material presented in the :doc:`model </topics/db/models>` and :doc:`database material presented in the :doc:`model </topics/db/models>` and :doc:`database
@ -120,12 +120,38 @@ QuerySet API
============ ============
Though you usually won't create one manually -- you'll go through a 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 Usually when you'll interact with a ``QuerySet`` you'll use it by
filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets. :ref:`chaining filters <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 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. ordering, call ``order_by()`` with no parameters.
You can tell if a query is ordered or not by checking the 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. ``QuerySet`` has been ordered in any way.
reverse reverse
@ -999,9 +1025,9 @@ The :ref:`force_insert <ref-models-force-insert>` parameter is documented
elsewhere, but all it means is that a new object will always be created. 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 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 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 database, a call to ``create()`` will fail with an
primary keys must be unique. So remember to be prepared to handle the exception :exc:`~django.db.IntegrityError` since primary keys must be unique. So remember
if you are using manual primary keys. to be prepared to handle the exception if you are using manual primary keys.
get_or_create get_or_create
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -1197,10 +1223,10 @@ exists
.. versionadded:: 1.2 .. 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 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 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 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 that it will be at some point, then using ``some_query_set.exists()`` will do
more overall work (an additional query) than simply using 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 Performs an SQL update query for the specified fields, and returns
the number of rows affected. The ``update()`` method is applied instantly and 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 only update columns in the model's main table. Filtering based on related
fields is still possible. You cannot call ``update()`` on a 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. filtered.
For example, if you wanted to update all the entries in a particular blog For example, if you wanted to update all the entries in a particular blog
@ -1236,9 +1262,9 @@ delete
.. method:: 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 ``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. filtered.
For example, to delete all the entries in a particular blog:: For example, to delete all the entries in a particular blog::

View File

@ -24,7 +24,7 @@ introduce controlled coupling for convenience's sake.
:func:`render()` is the same as a call to :func:`render()` is the same as a call to
:func:`render_to_response()` with a `context_instance` argument that :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 Required arguments
------------------ ------------------
@ -220,7 +220,7 @@ will be returned::
.. function:: get_object_or_404(klass, *args, **kwargs) .. 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 but it raises :class:`~django.http.Http404` instead of the model's
:class:`~django.core.exceptions.DoesNotExist` exception. :class:`~django.core.exceptions.DoesNotExist` exception.
@ -229,7 +229,8 @@ Required arguments
``klass`` ``klass``
A :class:`~django.db.models.Model`, :class:`~django.db.models.Manager` or 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`` ``**kwargs``
Lookup parameters, which should be in the format accepted by ``get()`` and 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) .. 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 given model manager, raising :class:`~django.http.Http404` if the resulting
list is empty. list is empty.