Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #15558 -- Improved QuerySet reference docs and cleaned up numer…

…ous reST/sphinx problems.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15776 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 409435440a8f8d453fa88aae9afb7799972b4422 1 parent 8b22f7c
authored March 08, 2011
56  docs/ref/models/querysets.txt
@@ -2,7 +2,7 @@
2 2
 QuerySet API reference
3 3
 ======================
4 4
 
5  
-.. currentmodule:: django.db.models.QuerySet
  5
+.. currentmodule:: django.db.models.query
6 6
 
7 7
 This document describes the details of the ``QuerySet`` API. It builds on the
8 8
 material presented in the :doc:`model </topics/db/models>` and :doc:`database
@@ -120,12 +120,38 @@ QuerySet API
120 120
 ============
121 121
 
122 122
 Though you usually won't create one manually -- you'll go through a
123  
-:class:`Manager` -- here's the formal declaration of a ``QuerySet``:
  123
+:class:`~django.db.models.Manager` -- here's the formal declaration of a
  124
+``QuerySet``:
124 125
 
125  
-.. class:: QuerySet([model=None])
  126
+.. class:: QuerySet([model=None, query=None, using=None])
126 127
 
127  
-Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining
128  
-filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets.
  128
+    Usually when you'll interact with a ``QuerySet`` you'll use it by
  129
+    :ref:`chaining filters <chaining-filters>`. To make this work, most
  130
+    ``QuerySet`` methods return new querysets. These methods are covered in
  131
+    detail later in this section.
  132
+
  133
+    The ``QuerySet`` class has two public attributes you can use for
  134
+    introspection:
  135
+
  136
+    .. attribute:: ordered
  137
+
  138
+        ``True`` if the ``QuerySet`` is ordered -- i.e. has an order_by()
  139
+        clause or a default ordering on the model. ``False`` otherwise.
  140
+
  141
+    .. attribute:: db
  142
+    
  143
+        The database that will be used if this query is executed now.
  144
+
  145
+    .. note::
  146
+
  147
+        The ``query`` parameter to :class:`QuerySet` exists so that specialized
  148
+        query subclasses such as
  149
+        :class:`~django.contrib.gis.db.models.GeoQuerySet` can reconstruct
  150
+        internal query state. The value of the parameter is an opaque
  151
+        representation of that query state and is not part of a public API.
  152
+        To put it simply: if you need to ask, you don't need to use it.
  153
+
  154
+.. currentmodule:: django.db.models.query.QuerySet
129 155
 
130 156
 Methods that return new QuerySets
131 157
 ---------------------------------
@@ -285,7 +311,7 @@ If you don't want any ordering to be applied to a query, not even the default
285 311
 ordering, call ``order_by()`` with no parameters.
286 312
 
287 313
 You can tell if a query is ordered or not by checking the
288  
-:attr:`QuerySet.ordered` attribute, which will be ``True`` if the
  314
+:attr:`.QuerySet.ordered` attribute, which will be ``True`` if the
289 315
 ``QuerySet`` has been ordered in any way.
290 316
 
291 317
 reverse
@@ -999,9 +1025,9 @@ The :ref:`force_insert <ref-models-force-insert>` parameter is documented
999 1025
 elsewhere, but all it means is that a new object will always be created.
1000 1026
 Normally you won't need to worry about this. However, if your model contains a
1001 1027
 manual primary key value that you set and if that value already exists in the
1002  
-database, a call to ``create()`` will fail with an :exc:`IntegrityError` since
1003  
-primary keys must be unique. So remember to be prepared to handle the exception
1004  
-if you are using manual primary keys.
  1028
+database, a call to ``create()`` will fail with an
  1029
+:exc:`~django.db.IntegrityError` since primary keys must be unique. So remember
  1030
+to be prepared to handle the exception if you are using manual primary keys.
1005 1031
 
1006 1032
 get_or_create
1007 1033
 ~~~~~~~~~~~~~
@@ -1197,10 +1223,10 @@ exists
1197 1223
 
1198 1224
 .. versionadded:: 1.2
1199 1225
 
1200  
-Returns ``True`` if the :class:`QuerySet` contains any results, and ``False``
  1226
+Returns ``True`` if the :class:`.QuerySet` contains any results, and ``False``
1201 1227
 if not. This tries to perform the query in the simplest and fastest way
1202 1228
 possible, but it *does* execute nearly the same query. This means that calling
1203  
-:meth:`QuerySet.exists()` is faster than ``bool(some_query_set)``, but not by
  1229
+:meth:`.QuerySet.exists` is faster than ``bool(some_query_set)``, but not by
1204 1230
 a large degree.  If ``some_query_set`` has not yet been evaluated, but you know
1205 1231
 that it will be at some point, then using ``some_query_set.exists()`` will do
1206 1232
 more overall work (an additional query) than simply using
@@ -1213,10 +1239,10 @@ update
1213 1239
 
1214 1240
 Performs an SQL update query for the specified fields, and returns
1215 1241
 the number of rows affected. The ``update()`` method is applied instantly and
1216  
-the only restriction on the :class:`QuerySet` that is updated is that it can
  1242
+the only restriction on the :class:`.QuerySet` that is updated is that it can
1217 1243
 only update columns in the model's main table. Filtering based on related
1218 1244
 fields is still possible. You cannot call ``update()`` on a
1219  
-:class:`QuerySet` that has had a slice taken or can otherwise no longer be
  1245
+:class:`.QuerySet` that has had a slice taken or can otherwise no longer be
1220 1246
 filtered.
1221 1247
 
1222 1248
 For example, if you wanted to update all the entries in a particular blog
@@ -1236,9 +1262,9 @@ delete
1236 1262
 
1237 1263
 .. method:: delete()
1238 1264
 
1239  
-Performs an SQL delete query on all rows in the :class:`QuerySet`. The
  1265
+Performs an SQL delete query on all rows in the :class:`.QuerySet`. The
1240 1266
 ``delete()`` is applied instantly. You cannot call ``delete()`` on a
1241  
-:class:`QuerySet` that has had a slice taken or can otherwise no longer be
  1267
+:class:`.QuerySet` that has had a slice taken or can otherwise no longer be
1242 1268
 filtered.
1243 1269
 
1244 1270
 For example, to delete all the entries in a particular blog::
9  docs/topics/http/shortcuts.txt
@@ -24,7 +24,7 @@ introduce controlled coupling for convenience's sake.
24 24
 
25 25
    :func:`render()` is the same as a call to
26 26
    :func:`render_to_response()` with a `context_instance` argument that
27  
-   that forces the use of a :class:`RequestContext`.
  27
+   that forces the use of a :class:`~django.template.RequestContext`.
28 28
 
29 29
 Required arguments
30 30
 ------------------
@@ -220,7 +220,7 @@ will be returned::
220 220
 
221 221
 .. function:: get_object_or_404(klass, *args, **kwargs)
222 222
 
223  
-   Calls :meth:`~django.db.models.QuerySet.get()` on a given model manager,
  223
+   Calls :meth:`~django.db.models.query.QuerySet.get()` on a given model manager,
224 224
    but it raises :class:`~django.http.Http404` instead of the model's
225 225
    :class:`~django.core.exceptions.DoesNotExist` exception.
226 226
 
@@ -229,7 +229,8 @@ Required arguments
229 229
 
230 230
 ``klass``
231 231
     A :class:`~django.db.models.Model`, :class:`~django.db.models.Manager` or
232  
-    :class:`~django.db.models.QuerySet` instance from which to get the object.
  232
+    :class:`~django.db.models.query.QuerySet` instance from which to get the
  233
+    object.
233 234
 
234 235
 ``**kwargs``
235 236
     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.
265 266
 
266 267
 .. function:: get_list_or_404(klass, *args, **kwargs)
267 268
 
268  
-   Returns the result of :meth:`~django.db.models.QuerySet.filter()` on a
  269
+   Returns the result of :meth:`~django.db.models.query.QuerySet.filter()` on a
269 270
    given model manager, raising :class:`~django.http.Http404` if the resulting
270 271
    list is empty.
271 272
 

0 notes on commit 4094354

Please sign in to comment.
Something went wrong with that request. Please try again.