Sign up
This repository

public / django Octocat-spinner-32

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #17794 - Added a bunch of cross-reference links to the DB queri… 

…es topic documentation. Thanks guettli for the initial patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17624 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 7b624c6c3205094b4fbf2ef2b7164ff7668665a5 1 parent 8cadf1d
Carl Meyer authored

Showing 1 changed file with 294 additions and 221 deletions. Show Diff Stats Hide Diff Stats

  1. 515  docs/topics/db/queries.txt
515  docs/topics/db/queries.txt
View 
@@ -53,7 +53,7 @@ system: A model class represents a database table, and an instance of that
53 53 
 class represents a particular record in the database table.
54 54
55 55 
 To create an object, instantiate it using keyword arguments to the model class,
56   
-then call ``save()`` to save it to the database.
  56 
+then call :meth:`~django.db.models.Model.save` to save it to the database.
57 57
58 58 
 You import the model class from wherever it lives on the Python path, as you
59 59 
 may expect. (We point this out here because previous Django versions required
 
@@ -66,22 +66,24 @@ Assuming models live in a file ``mysite/blog/models.py``, here's an example::
66 66 
     >>> b.save()
67 67
68 68 
 This performs an ``INSERT`` SQL statement behind the scenes. Django doesn't hit
69   
-the database until you explicitly call ``save()``.
  69 
+the database until you explicitly call :meth:`~django.db.models.Model.save`.
70 70
71   
-The ``save()`` method has no return value.
  71 
+The :meth:`~django.db.models.Model.save` method has no return value.
72 72
73 73 
 .. seealso::
74 74
75   
-    ``save()`` takes a number of advanced options not described here.
76   
-    See the documentation for ``save()`` for complete details.
  75 
+    :meth:`~django.db.models.Model.save` takes a number of advanced options not
  76 
+    described here.  See the documentation for
  77 
+    :meth:`~django.db.models.Model.save` for complete details.
77 78
78   
-    To create an object and save it all in one step see the ``create()``
79   
-    method.
  79 
+    To create an object and save it all in one step see the
  80 
+    :meth:`~django.db.models.query.QuerySet.create()` method.
80 81
81 82 
 Saving changes to objects
82 83 
 =========================
83 84
84   
-To save changes to an object that's already in the database, use ``save()``.
  85 
+To save changes to an object that's already in the database, use
  86 
+:meth:`~django.db.models.Model.save`.
85 87
86 88 
 Given a ``Blog`` instance ``b5`` that has already been saved to the database,
87 89 
 this example changes its name and updates its record in the database::
 
@@ -90,14 +92,15 @@ this example changes its name and updates its record in the database::
90 92 
     >> b5.save()
91 93
92 94 
 This performs an ``UPDATE`` SQL statement behind the scenes. Django doesn't hit
93   
-the database until you explicitly call ``save()``.
  95 
+the database until you explicitly call :meth:`~django.db.models.Model.save`.
94 96
95 97 
 Saving ``ForeignKey`` and ``ManyToManyField`` fields
96 98 
 ----------------------------------------------------
97 99
98   
-Updating a ``ForeignKey`` field works exactly the same way as saving a normal
99   
-field; simply assign an object of the right type to the field in question.
100   
-This example updates the ``blog`` attribute of an ``Entry`` instance ``entry``::
  100 
+Updating a :class:`~django.db.models.ForeignKey` field works exactly the same
  101 
+way as saving a normal field; simply assign an object of the right type to the
  102 
+field in question.  This example updates the ``blog`` attribute of an ``Entry``
  103 
+instance ``entry``::
101 104
102 105 
     >>> from blog.models import Entry
103 106 
     >>> entry = Entry.objects.get(pk=1)
 
@@ -105,16 +108,19 @@ This example updates the ``blog`` attribute of an ``Entry`` instance ``entry``::
105 108 
     >>> entry.blog = cheese_blog
106 109 
     >>> entry.save()
107 110
108   
-Updating a ``ManyToManyField`` works a little differently; use the ``add()``
109   
-method on the field to add a record to the relation. This example adds the
110   
-``Author`` instance ``joe`` to the ``entry`` object::
  111 
+Updating a :class:`~django.db.models.ManyToManyField` works a little
  112 
+differently; use the
  113 
+:meth:`~django.db.models.fields.related.RelatedManager.add` method on the field
  114 
+to add a record to the relation. This example adds the ``Author`` instance
  115 
+``joe`` to the ``entry`` object::
111 116
112 117 
     >>> from blog.models import Author
113 118 
     >>> joe = Author.objects.create(name="Joe")
114 119 
     >>> entry.authors.add(joe)
115 120
116   
-To add multiple records to a ``ManyToManyField`` in one go, include multiple
117   
-arguments in the call to ``add()``, like this::
  121 
+To add multiple records to a :class:`~django.db.models.ManyToManyField` in one
  122 
+go, include multiple arguments in the call to
  123 
+:meth:`~django.db.models.fields.related.RelatedManager.add`, like this::
118 124
119 125 
     >>> john = Author.objects.create(name="John")
120 126 
     >>> paul = Author.objects.create(name="Paul")
 
@@ -127,17 +133,20 @@ Django will complain if you try to assign or add an object of the wrong type.
127 133 
 Retrieving objects
128 134 
 ==================
129 135
130   
-To retrieve objects from your database, you construct a ``QuerySet`` via a
131   
-``Manager`` on your model class.
  136 
+To retrieve objects from your database, you construct a
  137 
+:class:`~django.db.models.query.QuerySet` via a
  138 
+:class:`~django.db.models.Manager` on your model class.
132 139
133   
-A ``QuerySet`` represents a collection of objects from your database. It can
134   
-have zero, one or many *filters* -- criteria that narrow down the collection
135   
-based on given parameters. In SQL terms, a ``QuerySet`` equates to a ``SELECT``
136   
-statement, and a filter is a limiting clause such as ``WHERE`` or ``LIMIT``.
  140 
+A :class:`~django.db.models.query.QuerySet` represents a collection of objects
  141 
+from your database. It can have zero, one or many *filters* -- criteria that
  142 
+narrow down the collection based on given parameters. In SQL terms, a
  143 
+:class:`~django.db.models.query.QuerySet` equates to a ``SELECT`` statement,
  144 
+and a filter is a limiting clause such as ``WHERE`` or ``LIMIT``.
137 145
138   
-You get a ``QuerySet`` by using your model's ``Manager``. Each model has at
139   
-least one ``Manager``, and it's called ``objects`` by default. Access it
140   
-directly via the model class, like so::
  146 
+You get a :class:`~django.db.models.query.QuerySet` by using your model's
  147 
+:class:`~django.db.models.Manager`. Each model has at least one
  148 
+:class:`~django.db.models.Manager`, and it's called ``objects`` by
  149 
+default. Access it directly via the model class, like so::
141 150
142 151 
     >>> Blog.objects
143 152 
     <django.db.models.manager.Manager object at ...>
 
@@ -153,64 +162,73 @@ directly via the model class, like so::
153 162 
     instances, to enforce a separation between "table-level" operations and
154 163 
     "record-level" operations.
155 164
156   
-The ``Manager`` is the main source of ``QuerySets`` for a model. It acts as a
157   
-"root" ``QuerySet`` that describes all objects in the model's database table.
158   
-For example, ``Blog.objects`` is the initial ``QuerySet`` that contains all
159   
-``Blog`` objects in the database.
  165 
+The :class:`~django.db.models.Manager` is the main source of ``QuerySets`` for
  166 
+a model. It acts as a "root" :class:`~django.db.models.query.QuerySet` that
  167 
+describes all objects in the model's database table.  For example,
  168 
+``Blog.objects`` is the initial :class:`~django.db.models.query.QuerySet` that
  169 
+contains all ``Blog`` objects in the database.
160 170
161 171 
 Retrieving all objects
162 172 
 ----------------------
163 173
164   
-The simplest way to retrieve objects from a table is to get all of them.
165   
-To do this, use the ``all()`` method on a ``Manager``::
  174 
+The simplest way to retrieve objects from a table is to get all of them.  To do
  175 
+this, use the :meth:`~django.db.models.query.QuerySet.all` method on a
  176 
+:class:`~django.db.models.Manager`::
166 177
167 178 
     >>> all_entries = Entry.objects.all()
168 179
169   
-The ``all()`` method returns a ``QuerySet`` of all the objects in the database.
  180 
+The :meth:`~django.db.models.query.QuerySet.all` method returns a
  181 
+:class:`~django.db.models.query.QuerySet` of all the objects in the database.
170 182
171   
-(If ``Entry.objects`` is a ``QuerySet``, why can't we just do ``Entry.objects``?
172   
-That's because ``Entry.objects``, the root ``QuerySet``, is a special case
173   
-that cannot be evaluated. The ``all()`` method returns a ``QuerySet`` that
174   
-*can* be evaluated.)
  183 
+(If ``Entry.objects`` is a :class:`~django.db.models.query.QuerySet`, why can't
  184 
+we just do ``Entry.objects``?  That's because ``Entry.objects``, the root
  185 
+:class:`~django.db.models.query.QuerySet`, is a special case that cannot be
  186 
+evaluated. The :meth:`~django.db.models.query.QuerySet.all` method returns a
  187 
+:class:`~django.db.models.query.QuerySet` that *can* be evaluated.)
175 188
176 189
177 190 
 Retrieving specific objects with filters
178 191 
 ----------------------------------------
179 192
180   
-The root ``QuerySet`` provided by the ``Manager`` describes all objects in the
181   
-database table. Usually, though, you'll need to select only a subset of the
182   
-complete set of objects.
  193 
+The root :class:`~django.db.models.query.QuerySet` provided by the
  194 
+:class:`~django.db.models.Manager` describes all objects in the database
  195 
+table. Usually, though, you'll need to select only a subset of the complete set
  196 
+of objects.
183 197
184   
-To create such a subset, you refine the initial ``QuerySet``, adding filter
185   
-conditions. The two most common ways to refine a ``QuerySet`` are:
  198 
+To create such a subset, you refine the initial
  199 
+:class:`~django.db.models.query.QuerySet`, adding filter conditions. The two
  200 
+most common ways to refine a :class:`~django.db.models.query.QuerySet` are:
186 201
187 202 
 ``filter(**kwargs)``
188   
-    Returns a new ``QuerySet`` containing objects that match the given
189   
-    lookup parameters.
  203 
+    Returns a new :class:`~django.db.models.query.QuerySet` containing objects
  204 
+    that match the given lookup parameters.
190 205
191 206 
 ``exclude(**kwargs)``
192   
-    Returns a new ``QuerySet`` containing objects that do *not* match the
193   
-    given lookup parameters.
  207 
+    Returns a new :class:`~django.db.models.query.QuerySet` containing objects
  208 
+    that do *not* match the given lookup parameters.
194 209
195 210 
 The lookup parameters (``**kwargs`` in the above function definitions) should
196 211 
 be in the format described in `Field lookups`_ below.
197 212
198   
-For example, to get a ``QuerySet`` of blog entries from the year 2006, use
199   
-``filter()`` like so::
  213 
+For example, to get a :class:`~django.db.models.query.QuerySet` of blog entries
  214 
+from the year 2006, use :meth:`~django.db.models.query.QuerySet.filter` like
  215 
+so::
200 216
201 217 
     Entry.objects.filter(pub_date__year=2006)
202 218
203   
-We don't have to add an ``all()`` -- ``Entry.objects.all().filter(...)``. That
204   
-would still work, but you only need ``all()`` when you want all objects from the
205   
-root ``QuerySet``.
  219 
+We don't have to add an :meth:`~django.db.models.query.QuerySet.all` --
  220 
+``Entry.objects.all().filter(...)``. That would still work, but you only need
  221 
+:meth:`~django.db.models.query.QuerySet.all` when you want all objects from the
  222 
+root :class:`~django.db.models.query.QuerySet`.
206 223
207 224 
 .. _chaining-filters:
208 225
209 226 
 Chaining filters
210 227 
 ~~~~~~~~~~~~~~~~
211 228
212   
-The result of refining a ``QuerySet`` is itself a ``QuerySet``, so it's
213   
-possible to chain refinements together. For example::
  229 
+The result of refining a :class:`~django.db.models.query.QuerySet` is itself a
  230 
+:class:`~django.db.models.query.QuerySet`, so it's possible to chain
  231 
+refinements together. For example::
214 232
215 233 
     >>> Entry.objects.filter(
216 234 
     ...     headline__startswith='What'
 
@@ -220,19 +238,22 @@ possible to chain refinements together. For example::
220 238 
     ...     pub_date__gte=datetime(2005, 1, 1)
221 239 
     ... )
222 240
223   
-This takes the initial ``QuerySet`` of all entries in the database, adds a
224   
-filter, then an exclusion, then another filter. The final result is a
225   
-``QuerySet`` containing all entries with a headline that starts with "What",
226   
-that were published between January 1, 2005, and the current day.
  241 
+This takes the initial :class:`~django.db.models.query.QuerySet` of all entries
  242 
+in the database, adds a filter, then an exclusion, then another filter. The
  243 
+final result is a :class:`~django.db.models.query.QuerySet` containing all
  244 
+entries with a headline that starts with "What", that were published between
  245 
+January 1, 2005, and the current day.
227 246
228 247 
 .. _filtered-querysets-are-unique:
229 248
230 249 
 Filtered QuerySets are unique
231 250 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
232 251
233   
-Each time you refine a ``QuerySet``, you get a brand-new ``QuerySet`` that is
234   
-in no way bound to the previous ``QuerySet``. Each refinement creates a
235   
-separate and distinct ``QuerySet`` that can be stored, used and reused.
  252 
+Each time you refine a :class:`~django.db.models.query.QuerySet`, you get a
  253 
+brand-new :class:`~django.db.models.query.QuerySet` that is in no way bound to
  254 
+the previous :class:`~django.db.models.query.QuerySet`. Each refinement creates
  255 
+a separate and distinct :class:`~django.db.models.query.QuerySet` that can be
  256 
+stored, used and reused.
236 257
237 258 
 Example::
238 259 
 
@@ -240,12 +261,13 @@ Example::
240 261 
     >> q2 = q1.exclude(pub_date__gte=datetime.now())
241 262 
     >> q3 = q1.filter(pub_date__gte=datetime.now())
242 263
243   
-These three ``QuerySets`` are separate. The first is a base ``QuerySet``
244   
-containing all entries that contain a headline starting with "What". The second
245   
-is a subset of the first, with an additional criteria that excludes records
246   
-whose ``pub_date`` is greater than now. The third is a subset of the first,
247   
-with an additional criteria that selects only the records whose ``pub_date`` is
248   
-greater than now. The initial ``QuerySet`` (``q1``) is unaffected by the
  264 
+These three ``QuerySets`` are separate. The first is a base
  265 
+:class:`~django.db.models.query.QuerySet` containing all entries that contain a
  266 
+headline starting with "What". The second is a subset of the first, with an
  267 
+additional criteria that excludes records whose ``pub_date`` is greater than
  268 
+now. The third is a subset of the first, with an additional criteria that
  269 
+selects only the records whose ``pub_date`` is greater than now. The initial
  270 
+:class:`~django.db.models.query.QuerySet` (``q1``) is unaffected by the
249 271 
 refinement process.
250 272
251 273 
 .. _querysets-are-lazy:
 
@@ -253,10 +275,11 @@ refinement process.
253 275 
 QuerySets are lazy
254 276 
 ~~~~~~~~~~~~~~~~~~
255 277
256   
-``QuerySets`` are lazy -- the act of creating a ``QuerySet`` doesn't involve any
257   
-database activity. You can stack filters together all day long, and Django won't
258   
-actually run the query until the ``QuerySet`` is *evaluated*. Take a look at
259   
-this example::
  278 
+``QuerySets`` are lazy -- the act of creating a
  279 
+:class:`~django.db.models.query.QuerySet` doesn't involve any database
  280 
+activity. You can stack filters together all day long, and Django won't
  281 
+actually run the query until the :class:`~django.db.models.query.QuerySet` is
  282 
+*evaluated*. Take a look at this example::
260 283
261 284 
     >>> q = Entry.objects.filter(headline__startswith="What")
262 285 
     >>> q = q.filter(pub_date__lte=datetime.now())
 
@@ -264,10 +287,12 @@ this example::
264 287 
     >>> print q
265 288
266 289 
 Though this looks like three database hits, in fact it hits the database only
267   
-once, at the last line (``print q``). In general, the results of a ``QuerySet``
268   
-aren't fetched from the database until you "ask" for them. When you do, the
269   
-``QuerySet`` is *evaluated* by accessing the database. For more details on
270   
-exactly when evaluation takes place, see :ref:`when-querysets-are-evaluated`.
  290 
+once, at the last line (``print q``). In general, the results of a
  291 
+:class:`~django.db.models.query.QuerySet` aren't fetched from the database
  292 
+until you "ask" for them. When you do, the
  293 
+:class:`~django.db.models.query.QuerySet` is *evaluated* by accessing the
  294 
+database. For more details on exactly when evaluation takes place, see
  295 
+:ref:`when-querysets-are-evaluated`.
271 296
272 297
273 298 
 .. _retrieving-single-object-with-get:
 
@@ -275,46 +300,56 @@ exactly when evaluation takes place, see :ref:`when-querysets-are-evaluated`.
275 300 
 Retrieving a single object with get
276 301 
 -----------------------------------
277 302
278   
-``.filter()`` will always give you a ``QuerySet``, even if only a single
279   
-object matches the query - in this case, it will be a ``QuerySet`` containing
280   
-a single element.
  303 
+:meth:`~django.db.models.query.QuerySet.filter` will always give you a
  304 
+:class:`~django.db.models.query.QuerySet`, even if only a single object matches
  305 
+the query - in this case, it will be a
  306 
+:class:`~django.db.models.query.QuerySet` containing a single element.
281 307
282   
-If you know there is only one object that matches your query, you can use
283   
-the ``get()`` method on a `Manager` which returns the object directly::
  308 
+If you know there is only one object that matches your query, you can use the
  309 
+:meth:`~django.db.models.query.QuerySet.get` method on a `Manager` which
  310 
+returns the object directly::
284 311
285 312 
     >>> one_entry = Entry.objects.get(pk=1)
286 313
287   
-You can use any query expression with ``get()``, just like with ``filter()`` -
288   
-again, see `Field lookups`_ below.
  314 
+You can use any query expression with
  315 
+:meth:`~django.db.models.query.QuerySet.get`, just like with
  316 
+:meth:`~django.db.models.query.QuerySet.filter` - again, see `Field lookups`_
  317 
+below.
289 318
290   
-Note that there is a difference between using ``.get()``, and using
291   
-``.filter()`` with a slice of ``[0]``. If there are no results that match the
292   
-query, ``.get()`` will raise a ``DoesNotExist`` exception. This exception is an
293   
-attribute of the model class that the query is being performed on - so in the
294   
-code above, if there is no ``Entry`` object with a primary key of 1, Django will
295   
-raise ``Entry.DoesNotExist``.
  319 
+Note that there is a difference between using
  320 
+:meth:`~django.db.models.query.QuerySet.get`, and using
  321 
+:meth:`~django.db.models.query.QuerySet.filter` with a slice of ``[0]``. If
  322 
+there are no results that match the query,
  323 
+:meth:`~django.db.models.query.QuerySet.get` will raise a ``DoesNotExist``
  324 
+exception. This exception is an attribute of the model class that the query is
  325 
+being performed on - so in the code above, if there is no ``Entry`` object with
  326 
+a primary key of 1, Django will raise ``Entry.DoesNotExist``.
296 327
297   
-Similarly, Django will complain if more than one item matches the ``get()``
298   
-query. In this case, it will raise ``MultipleObjectsReturned``, which again is
299   
-an attribute of the model class itself.
  328 
+Similarly, Django will complain if more than one item matches the
  329 
+:meth:`~django.db.models.query.QuerySet.get` query. In this case, it will raise
  330 
+``MultipleObjectsReturned``, which again is an attribute of the model class
  331 
+itself.
300 332
301 333
302 334 
 Other QuerySet methods
303 335 
 ----------------------
304 336
305   
-Most of the time you'll use ``all()``, ``get()``, ``filter()`` and ``exclude()``
306   
-when you need to look up objects from the database. However, that's far from all
307   
-there is; see the :ref:`QuerySet API Reference <queryset-api>` for a complete
308   
-list of all the various ``QuerySet`` methods.
  337 
+Most of the time you'll use :meth:`~django.db.models.query.QuerySet.all`,
  338 
+:meth:`~django.db.models.query.QuerySet.get`,
  339 
+:meth:`~django.db.models.query.QuerySet.filter` and
  340 
+:meth:`~django.db.models.query.QuerySet.exclude` when you need to look up
  341 
+objects from the database. However, that's far from all there is; see the
  342 
+:ref:`QuerySet API Reference <queryset-api>` for a complete list of all the
  343 
+various :class:`~django.db.models.query.QuerySet` methods.
309 344
310 345 
 .. _limiting-querysets:
311 346
312 347 
 Limiting QuerySets
313 348 
 ------------------
314 349
315   
-Use a subset of Python's array-slicing syntax to limit your ``QuerySet`` to a
316   
-certain number of results. This is the equivalent of SQL's ``LIMIT`` and
317   
-``OFFSET`` clauses.
  350 
+Use a subset of Python's array-slicing syntax to limit your
  351 
+:class:`~django.db.models.query.QuerySet` to a certain number of results. This
  352 
+is the equivalent of SQL's ``LIMIT`` and ``OFFSET`` clauses.
318 353
319 354 
 For example, this returns the first 5 objects (``LIMIT 5``)::
320 355 
 
@@ -326,10 +361,11 @@ This returns the sixth through tenth objects (``OFFSET 5 LIMIT 5``)::
326 361
327 362 
 Negative indexing (i.e. ``Entry.objects.all()[-1]``) is not supported.
328 363
329   
-Generally, slicing a ``QuerySet`` returns a new ``QuerySet`` -- it doesn't
330   
-evaluate the query. An exception is if you use the "step" parameter of Python
331   
-slice syntax. For example, this would actually execute the query in order to
332   
-return a list of every *second* object of the first 10::
  364 
+Generally, slicing a :class:`~django.db.models.query.QuerySet` returns a new
  365 
+:class:`~django.db.models.query.QuerySet` -- it doesn't evaluate the query. An
  366 
+exception is if you use the "step" parameter of Python slice syntax. For
  367 
+example, this would actually execute the query in order to return a list of
  368 
+every *second* object of the first 10::
333 369
334 370 
     >>> Entry.objects.all()[:10:2]
335 371 
 
@@ -354,8 +390,10 @@ Field lookups
354 390 
 -------------
355 391
356 392 
 Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're
357   
-specified as keyword arguments to the ``QuerySet`` methods ``filter()``,
358   
-``exclude()`` and ``get()``.
  393 
+specified as keyword arguments to the :class:`~django.db.models.query.QuerySet`
  394 
+methods :meth:`~django.db.models.query.QuerySet.filter`,
  395 
+:meth:`~django.db.models.query.QuerySet.exclude` and
  396 
+:meth:`~django.db.models.query.QuerySet.get`.
359 397
360 398 
 Basic lookups keyword arguments take the form ``field__lookuptype=value``.
361 399 
 (That's a double-underscore). For example::
 
@@ -377,7 +415,7 @@ translates (roughly) into the following SQL::
377 415 
 .. versionchanged:: 1.4
378 416 
     The field specified in a lookup has to be the name of a model field.
379 417 
     There's one exception though, in case of a
380   
-    :class:`~django.db.models.fields.ForeignKey` you can specify the field
  418 
+    :class:`~django.db.models.ForeignKey` you can specify the field
381 419 
     name suffixed with ``_id``. In this case, the value parameter is expected
382 420 
     to contain the raw value of the foreign model's primary key. For example::
383 421 
 
@@ -387,8 +425,9 @@ If you pass an invalid keyword argument, a lookup function will raise
387 425 
 ``TypeError``.
388 426
389 427 
 The database API supports about two dozen lookup types; a complete reference
390   
-can be found in the :ref:`field lookup reference <field-lookups>`. To give you a taste of what's available, here's some of the more common lookups
391   
-you'll probably use:
  428 
+can be found in the :ref:`field lookup reference <field-lookups>`. To give you
  429 
+a taste of what's available, here's some of the more common lookups you'll
  430 
+probably use:
392 431
393 432 
 :lookup:`exact`
394 433 
     An "exact" match. For example::
 
@@ -479,7 +518,7 @@ All this means is that no error will be raised. For example, in this filter::
479 518 
 associated with an entry, it would be treated as if there was also no ``name``
480 519 
 attached, rather than raising an error because of the missing ``author``.
481 520 
 Usually this is exactly what you want to have happen. The only case where it
482   
-might be confusing is if you are using ``isnull``. Thus::
  521 
+might be confusing is if you are using :lookup:`isnull`. Thus::
483 522
484 523 
     Blog.objects.filter(entry__authors__name__isnull=True)
485 524 
 
@@ -493,28 +532,32 @@ those latter objects, you could write::
493 532 
 Spanning multi-valued relationships
494 533 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
495 534
496   
-When you are filtering an object based on a ``ManyToManyField`` or a reverse
497   
-``ForeignKey``, there are two different sorts of filter you may be
498   
-interested in. Consider the ``Blog``/``Entry`` relationship (``Blog`` to
499   
-``Entry`` is a one-to-many relation). We might be interested in finding blogs
500   
-that have an entry which has both *"Lennon"* in the headline and was published
501   
-in 2008. Or we might want to find blogs that have an entry with *"Lennon"* in
502   
-the headline as well as an entry that was published in 2008. Since there are
503   
-multiple entries associated with a single ``Blog``, both of these queries are
504   
-possible and make sense in some situations.
505   
-
506   
-The same type of situation arises with a ``ManyToManyField``. For example, if
507   
-an ``Entry`` has a ``ManyToManyField`` called ``tags``, we might want to find
508   
-entries linked to tags called *"music"* and *"bands"* or we might want an
  535 
+When you are filtering an object based on a
  536 
+:class:`~django.db.models.ManyToManyField` or a reverse
  537 
+:class:`~django.db.models.ForeignKey`, there are two different sorts of filter
  538 
+you may be interested in. Consider the ``Blog``/``Entry`` relationship
  539 
+(``Blog`` to ``Entry`` is a one-to-many relation). We might be interested in
  540 
+finding blogs that have an entry which has both *"Lennon"* in the headline and
  541 
+was published in 2008. Or we might want to find blogs that have an entry with
  542 
+*"Lennon"* in the headline as well as an entry that was published
  543 
+in 2008. Since there are multiple entries associated with a single ``Blog``,
  544 
+both of these queries are possible and make sense in some situations.
  545 
+
  546 
+The same type of situation arises with a
  547 
+:class:`~django.db.models.ManyToManyField`. For example, if an ``Entry`` has a
  548 
+:class:`~django.db.models.ManyToManyField` called ``tags``, we might want to
  549 
+find entries linked to tags called *"music"* and *"bands"* or we might want an
509 550 
 entry that contains a tag with a name of *"music"* and a status of *"public"*.
510 551
511 552 
 To handle both of these situations, Django has a consistent way of processing
512   
-``filter()`` and ``exclude()`` calls. Everything inside a single ``filter()``
513   
-call is applied simultaneously to filter out items matching all those
514   
-requirements. Successive ``filter()`` calls further restrict the set of
515   
-objects, but for multi-valued relations, they apply to any object linked to
  553 
+:meth:`~django.db.models.query.QuerySet.filter` and
  554 
+:meth:`~django.db.models.query.QuerySet.exclude` calls.  Everything inside a
  555 
+single :meth:`~django.db.models.query.QuerySet.filter` call is applied
  556 
+simultaneously to filter out items matching all those requirements. Successive
  557 
+:meth:`~django.db.models.query.QuerySet.filter` calls further restrict the set
  558 
+of objects, but for multi-valued relations, they apply to any object linked to
516 559 
 the primary model, not necessarily those objects that were selected by an
517   
-earlier ``filter()`` call.
  560 
+earlier :meth:`~django.db.models.query.QuerySet.filter` call.
518 561
519 562 
 That may sound a bit confusing, so hopefully an example will clarify. To
520 563 
 select all blogs that contain entries with both *"Lennon"* in the headline
 
@@ -537,11 +580,14 @@ entry. The entries select by the second filter may or may not be the same as
537 580 
 the entries in the first filter. We are filtering the ``Blog`` items with each
538 581 
 filter statement, not the ``Entry`` items.
539 582
540   
-All of this behavior also applies to ``exclude()``: all the conditions in a
541   
-single ``exclude()`` statement apply to a single instance (if those conditions
542   
-are talking about the same multi-valued relation). Conditions in subsequent
543   
-``filter()`` or ``exclude()`` calls that refer to the same relation may end up
544   
-filtering on different linked objects.
  583 
+All of this behavior also applies to
  584 
+:meth:`~django.db.models.query.QuerySet.exclude`: all the conditions in a
  585 
+single :meth:`~django.db.models.query.QuerySet.exclude` statement apply to a
  586 
+single instance (if those conditions are talking about the same multi-valued
  587 
+relation). Conditions in subsequent
  588 
+:meth:`~django.db.models.query.QuerySet.filter` or
  589 
+:meth:`~django.db.models.query.QuerySet.exclude` calls that refer to the same
  590 
+relation may end up filtering on different linked objects.
545 591
546 592 
 .. _query-expressions:
547 593 
 
@@ -552,10 +598,10 @@ In the examples given so far, we have constructed filters that compare
552 598 
 the value of a model field with a constant. But what if you want to compare
553 599 
 the value of a model field with another field on the same model?
554 600
555   
-Django provides the ``F()`` object to allow such comparisons. Instances
556   
-of ``F()`` act as a reference to a model field within a query. These
557   
-references can then be used in query filters to compare the values of two
558   
-different fields on the same model instance.
  601 
+Django provides the :ref:`F() expressions <query-expressions>` to allow such
  602 
+comparisons. Instances of ``F()`` act as a reference to a model field within a
  603 
+query. These references can then be used in query filters to compare the values
  604 
+of two different fields on the same model instance.
559 605
560 606 
 For example, to find a list of all blog entries that have had more comments
561 607 
 than pingbacks, we construct an ``F()`` object to reference the pingback count,
 
@@ -587,9 +633,9 @@ issue the query::
587 633
588 634 
 .. versionadded:: 1.3
589 635
590   
-For date and date/time fields, you can add or subtract a ``datetime.timedelta``
591   
-object.  The following would return all entries that were modified more than 3 days
592   
-after they were published::
  636 
+For date and date/time fields, you can add or subtract a
  637 
+:class:`~datetime.timedelta` object.  The following would return all entries
  638 
+that were modified more than 3 days after they were published::
593 639
594 640 
     >>> from datetime import timedelta
595 641 
     >>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))
 
@@ -654,19 +700,23 @@ for you transparently.
654 700 
 Caching and QuerySets
655 701 
 ---------------------
656 702
657   
-Each ``QuerySet`` contains a cache, to minimize database access. It's important
658   
-to understand how it works, in order to write the most efficient code.
  703 
+Each :class:`~django.db.models.query.QuerySet` contains a cache, to minimize
  704 
+database access. It's important to understand how it works, in order to write
  705 
+the most efficient code.
659 706
660   
-In a newly created ``QuerySet``, the cache is empty. The first time a
661   
-``QuerySet`` is evaluated -- and, hence, a database query happens -- Django
662   
-saves the query results in the ``QuerySet``'s cache and returns the results
  707 
+In a newly created :class:`~django.db.models.query.QuerySet`, the cache is
  708 
+empty. The first time a :class:`~django.db.models.query.QuerySet` is evaluated
  709 
+-- and, hence, a database query happens -- Django saves the query results in
  710 
+the :class:`~django.db.models.query.QuerySet`\'s cache and returns the results
663 711 
 that have been explicitly requested (e.g., the next element, if the
664   
-``QuerySet`` is being iterated over). Subsequent evaluations of the
665   
-``QuerySet`` reuse the cached results.
  712 
+:class:`~django.db.models.query.QuerySet` is being iterated over). Subsequent
  713 
+evaluations of the :class:`~django.db.models.query.QuerySet` reuse the cached
  714 
+results.
666 715
667 716 
 Keep this caching behavior in mind, because it may bite you if you don't use
668   
-your ``QuerySet``\s correctly. For example, the following will create two
669   
-``QuerySet``\s, evaluate them, and throw them away::
  717 
+your :class:`~django.db.models.query.QuerySet`\s correctly. For example, the
  718 
+following will create two :class:`~django.db.models.query.QuerySet`\s, evaluate
  719 
+them, and throw them away::
670 720
671 721 
     >>> print [e.headline for e in Entry.objects.all()]
672 722 
     >>> print [e.pub_date for e in Entry.objects.all()]
 
@@ -676,7 +726,8 @@ your database load. Also, there's a possibility the two lists may not include
676 726 
 the same database records, because an ``Entry`` may have been added or deleted
677 727 
 in the split second between the two requests.
678 728
679   
-To avoid this problem, simply save the ``QuerySet`` and reuse it::
  729 
+To avoid this problem, simply save the
  730 
+:class:`~django.db.models.query.QuerySet` and reuse it::
680 731
681 732 
     >>> queryset = Entry.objects.all()
682 733 
     >>> print [p.headline for p in queryset] # Evaluate the query set.
 
@@ -687,13 +738,15 @@ To avoid this problem, simply save the ``QuerySet`` and reuse it::
687 738 
 Complex lookups with Q objects
688 739 
 ==============================
689 740
690   
-Keyword argument queries -- in ``filter()``, etc. -- are "AND"ed together. If
691   
-you need to execute more complex queries (for example, queries with ``OR``
692   
-statements), you can use ``Q`` objects.
  741 
+Keyword argument queries -- in :meth:`~django.db.models.query.QuerySet.filter`,
  742 
+etc. -- are "AND"ed together. If you need to execute more complex queries (for
  743 
+example, queries with ``OR`` statements), you can use ``Q`` objects.
693 744
694   
-A ``Q`` object (``django.db.models.Q``) is an object used to encapsulate a
695   
-collection of keyword arguments. These keyword arguments are specified as in
696   
-"Field lookups" above.
  745 
+.. comment: Link to Q does not work, since this documentation does not exist yet.
  746 
+
  747 
+A :class:`~django.db.models.Q` object (``django.db.models.Q``) is an object
  748 
+used to encapsulate a collection of keyword arguments. These keyword arguments
  749 
+are specified as in "Field lookups" above.
697 750
698 751 
 For example, this ``Q`` object encapsulates a single ``LIKE`` query::
699 752 
 
@@ -719,11 +772,13 @@ that combine both a normal query and a negated (``NOT``) query::
719 772
720 773 
     Q(question__startswith='Who') | ~Q(pub_date__year=2005)
721 774
722   
-Each lookup function that takes keyword-arguments (e.g. ``filter()``,
723   
-``exclude()``, ``get()``) can also be passed one or more ``Q`` objects as
724   
-positional (not-named) arguments. If you provide multiple ``Q`` object
725   
-arguments to a lookup function, the arguments will be "AND"ed together. For
726   
-example::
  775 
+Each lookup function that takes keyword-arguments
  776 
+(e.g. :meth:`~django.db.models.query.QuerySet.filter`,
  777 
+:meth:`~django.db.models.query.QuerySet.exclude`,
  778 
+:meth:`~django.db.models.query.QuerySet.get`) can also be passed one or more
  779 
+``Q`` objects as positional (not-named) arguments. If you provide multiple
  780 
+``Q`` object arguments to a lookup function, the arguments will be "AND"ed
  781 
+together. For example::
727 782
728 783 
     Poll.objects.get(
729 784 
         Q(question__startswith='Who'),
 
@@ -784,27 +839,31 @@ primary key field is called ``name``, these two statements are equivalent::
784 839 
 Deleting objects
785 840 
 ================
786 841
787   
-The delete method, conveniently, is named ``delete()``. This method immediately
788   
-deletes the object and has no return value. Example::
  842 
+The delete method, conveniently, is named
  843 
+:meth:`~django.db.models.Model.delete`. This method immediately deletes the
  844 
+object and has no return value. Example::
789 845
790 846 
     e.delete()
791 847
792   
-You can also delete objects in bulk. Every ``QuerySet`` has a ``delete()``
793   
-method, which deletes all members of that ``QuerySet``.
  848 
+You can also delete objects in bulk. Every
  849 
+:class:`~django.db.models.query.QuerySet` has a
  850 
+:meth:`~django.db.models.query.QuerySet.delete` method, which deletes all
  851 
+members of that :class:`~django.db.models.query.QuerySet`.
794 852
795 853 
 For example, this deletes all ``Entry`` objects with a ``pub_date`` year of
796 854 
 2005::
797 855
798 856 
     Entry.objects.filter(pub_date__year=2005).delete()
799 857
800   
-Keep in mind that this will, whenever possible, be executed purely in
801   
-SQL, and so the ``delete()`` methods of individual object instances
802   
-will not necessarily be called during the process. If you've provided
803   
-a custom ``delete()`` method on a model class and want to ensure that
804   
-it is called, you will need to "manually" delete instances of that
805   
-model (e.g., by iterating over a ``QuerySet`` and calling ``delete()``
806   
-on each object individually) rather than using the bulk ``delete()``
807   
-method of a ``QuerySet``.
  858 
+Keep in mind that this will, whenever possible, be executed purely in SQL, and
  859 
+so the ``delete()`` methods of individual object instances will not necessarily
  860 
+be called during the process. If you've provided a custom ``delete()`` method
  861 
+on a model class and want to ensure that it is called, you will need to
  862 
+"manually" delete instances of that model (e.g., by iterating over a
  863 
+:class:`~django.db.models.query.QuerySet` and calling ``delete()`` on each
  864 
+object individually) rather than using the bulk
  865 
+:meth:`~django.db.models.query.QuerySet.delete` method of a
  866 
+:class:`~django.db.models.query.QuerySet`.
808 867
809 868 
 When Django deletes an object, by default it emulates the behavior of the SQL
810 869 
 constraint ``ON DELETE CASCADE`` -- in other words, any objects which had
 
@@ -820,11 +879,12 @@ it. For example::
820 879 
     :attr:`~django.db.models.ForeignKey.on_delete` argument to the
821 880 
     :class:`~django.db.models.ForeignKey`.
822 881
823   
-Note that ``delete()`` is the only ``QuerySet`` method that is not exposed on a
824   
-``Manager`` itself. This is a safety mechanism to prevent you from accidentally
825   
-requesting ``Entry.objects.delete()``, and deleting *all* the entries. If you
826   
-*do* want to delete all the objects, then you have to explicitly request a
827   
-complete query set::
  882 
+Note that :meth:`~django.db.models.query.QuerySet.delete` is the only
  883 
+:class:`~django.db.models.query.QuerySet` method that is not exposed on a
  884 
+:class:`~django.db.models.Manager` itself. This is a safety mechanism to
  885 
+prevent you from accidentally requesting ``Entry.objects.delete()``, and
  886 
+deleting *all* the entries. If you *do* want to delete all the objects, then
  887 
+you have to explicitly request a complete query set::
828 888
829 889 
     Entry.objects.all().delete()
830 890 
 
@@ -874,15 +934,16 @@ Updating multiple objects at once
874 934 
 =================================
875 935
876 936 
 Sometimes you want to set a field to a particular value for all the objects in
877   
-a ``QuerySet``. You can do this with the ``update()`` method. For example::
  937 
+a :class:`~django.db.models.query.QuerySet`. You can do this with the
  938 
+:meth:`~django.db.models.query.QuerySet.update` method. For example::
878 939
879 940 
     # Update all the headlines with pub_date in 2007.
880 941 
     Entry.objects.filter(pub_date__year=2007).update(headline='Everything is the same')
881 942
882   
-You can only set non-relation fields and ``ForeignKey`` fields using this
883   
-method. To update a non-relation field, provide the new value as a constant.
884   
-To update ``ForeignKey`` fields, set the new value to be the new model
885   
-instance you want to point to. For example::
  943 
+You can only set non-relation fields and :class:`~django.db.models.ForeignKey`
  944 
+fields using this method. To update a non-relation field, provide the new value
  945 
+as a constant.  To update :class:`~django.db.models.ForeignKey` fields, set the
  946 
+new value to be the new model instance you want to point to. For example::
886 947
887 948 
     >>> b = Blog.objects.get(pk=1)
888 949 
 
@@ -890,10 +951,11 @@ instance you want to point to. For example::
890 951 
     >>> Entry.objects.all().update(blog=b)
891 952
892 953 
 The ``update()`` method is applied instantly and returns the number of rows
893   
-affected by the query. The only restriction on the ``QuerySet`` that is
894   
-updated is that it can only access one database table, the model's main
895   
-table. You can filter based on related fields, but you can only update columns
896   
-in the model's main table. Example::
  954 
+affected by the query. The only restriction on the
  955 
+:class:`~django.db.models.query.QuerySet` that is updated is that it can only
  956 
+access one database table, the model's main table. You can filter based on
  957 
+related fields, but you can only update columns in the model's main
  958 
+table. Example::
897 959
898 960 
     >>> b = Blog.objects.get(pk=1)
899 961 
 
@@ -902,11 +964,13 @@ in the model's main table. Example::
902 964
903 965 
 Be aware that the ``update()`` method is converted directly to an SQL
904 966 
 statement. It is a bulk operation for direct updates. It doesn't run any
905   
-``save()`` methods on your models, or emit the ``pre_save`` or ``post_save``
906   
-signals (which are a consequence of calling ``save()``). If you want to save
907   
-every item in a ``QuerySet`` and make sure that the ``save()`` method is
908   
-called on each instance, you don't need any special function to handle that.
909   
-Just loop over them and call ``save()``::
  967 
+:meth:`~django.db.models.Model.save` methods on your models, or emit the
  968 
+``pre_save`` or ``post_save`` signals (which are a consequence of calling
  969 
+:meth:`~django.db.models.Model.save`). If you want to save every item in a
  970 
+:class:`~django.db.models.query.QuerySet` and make sure that the
  971 
+:meth:`~django.db.models.Model.save` method is called on each instance, you
  972 
+don't need any special function to handle that.  Just loop over them and call
  973 
+:meth:`~django.db.models.Model.save`::
910 974
911 975 
     for item in my_queryset:
912 976 
         item.save()
 
@@ -931,8 +995,10 @@ a join with an ``F()`` object, a ``FieldError`` will be raised::
931 995 
 Related objects
932 996 
 ===============
933 997
934   
-When you define a relationship in a model (i.e., a ``ForeignKey``,
935   
-``OneToOneField``, or ``ManyToManyField``), instances of that model will have
  998 
+When you define a relationship in a model (i.e., a
  999 
+:class:`~django.db.models.ForeignKey`,
  1000 
+:class:`~django.db.models.OneToOneField`, or
  1001 
+:class:`~django.db.models.ManyToManyField`), instances of that model will have
936 1002 
 a convenient API to access the related object(s).
937 1003
938 1004 
 Using the models at the top of this page, for example, an ``Entry`` object ``e``
 
@@ -958,8 +1024,9 @@ One-to-many relationships
958 1024 
 Forward
959 1025 
 ~~~~~~~
960 1026
961   
-If a model has a ``ForeignKey``, instances of that model will have access to
962   
-the related (foreign) object via a simple attribute of the model.
  1027 
+If a model has a :class:`~django.db.models.ForeignKey`, instances of that model
  1028 
+will have access to the related (foreign) object via a simple attribute of the
  1029 
+model.
963 1030
964 1031 
 Example::
965 1032 
 
@@ -967,14 +1034,14 @@ Example::
967 1034 
     >>> e.blog # Returns the related Blog object.
968 1035
969 1036 
 You can get and set via a foreign-key attribute. As you may expect, changes to
970   
-the foreign key aren't saved to the database until you call ``save()``.
971   
-Example::
  1037 
+the foreign key aren't saved to the database until you call
  1038 
+:meth:`~django.db.models.Model.save`.  Example::
972 1039
973 1040 
     >>> e = Entry.objects.get(id=2)
974 1041 
     >>> e.blog = some_blog
975 1042 
     >>> e.save()
976 1043
977   
-If a ``ForeignKey`` field has ``null=True`` set (i.e., it allows ``NULL``
  1044 
+If a :class:`~django.db.models.ForeignKey` field has ``null=True`` set (i.e., it allows ``NULL``
978 1045 
 values), you can assign ``None`` to it. Example::
979 1046
980 1047 
     >>> e = Entry.objects.get(id=2)
 
@@ -989,8 +1056,9 @@ object instance are cached. Example::
989 1056 
     >>> print e.blog  # Hits the database to retrieve the associated Blog.
990 1057 
     >>> print e.blog  # Doesn't hit the database; uses cached version.
991 1058
992   
-Note that the ``select_related()`` ``QuerySet`` method recursively prepopulates
993   
-the cache of all one-to-many relationships ahead of time. Example::
  1059 
+Note that the :meth:`~django.db.models.query.QuerySet.select_related`
  1060 
+:class:`~django.db.models.query.QuerySet` method recursively prepopulates the
  1061 
+cache of all one-to-many relationships ahead of time. Example::
994 1062
995 1063 
     >>> e = Entry.objects.select_related().get(id=2)
996 1064 
     >>> print e.blog  # Doesn't hit the database; uses cached version.
 
@@ -1001,12 +1069,13 @@ the cache of all one-to-many relationships ahead of time. Example::
1001 1069 
 Following relationships "backward"
1002 1070 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1003 1071
1004   
-If a model has a ``ForeignKey``, instances of the foreign-key model will have
1005   
-access to a ``Manager`` that returns all instances of the first model. By
1006   
-default, this ``Manager`` is named ``FOO_set``, where ``FOO`` is the source
1007   
-model name, lowercased. This ``Manager`` returns ``QuerySets``, which can be
1008   
-filtered and manipulated as described in the "Retrieving objects" section
1009   
-above.
  1072 
+If a model has a :class:`~django.db.models.ForeignKey`, instances of the
  1073 
+foreign-key model will have access to a :class:`~django.db.models.Manager` that
  1074 
+returns all instances of the first model. By default, this
  1075 
+:class:`~django.db.models.Manager` is named ``FOO_set``, where ``FOO`` is the
  1076 
+source model name, lowercased. This :class:`~django.db.models.Manager` returns
  1077 
+``QuerySets``, which can be filtered and manipulated as described in the
  1078 
+"Retrieving objects" section above.
1010 1079
1011 1080 
 Example::
1012 1081 
 
@@ -1029,18 +1098,20 @@ above example code would look like this::
1029 1098 
     >>> b.entries.filter(headline__contains='Lennon')
1030 1099 
     >>> b.entries.count()
1031 1100
1032   
-You cannot access a reverse ``ForeignKey`` ``Manager`` from the class; it must
1033   
-be accessed from an instance::
  1101 
+You cannot access a reverse :class:`~django.db.models.ForeignKey`
  1102 
+:class:`~django.db.models.Manager` from the class; it must be accessed from an
  1103 
+instance::
1034 1104
1035 1105 
     >>> Blog.entry_set
1036 1106 
     Traceback:
1037 1107 
         ...
1038 1108 
     AttributeError: "Manager must be accessed via instance".
1039 1109
1040   
-In addition to the ``QuerySet`` methods defined in "Retrieving objects" above,
1041   
-the ``ForeignKey`` ``Manager`` has additional methods used to handle the set of
1042   
-related objects. A synopsis of each is below, and complete details can be found
1043   
-in the :doc:`related objects reference </ref/models/relations>`.
  1110 
+In addition to the :class:`~django.db.models.query.QuerySet` methods defined in
  1111 
+"Retrieving objects" above, the :class:`~django.db.models.ForeignKey`
  1112 
+:class:`~django.db.models.Manager` has additional methods used to handle the
  1113 
+set of related objects. A synopsis of each is below, and complete details can
  1114 
+be found in the :doc:`related objects reference </ref/models/relations>`.
1044 1115
1045 1116 
 ``add(obj1, obj2, ...)``
1046 1117 
     Adds the specified model objects to the related object set.
 
@@ -1084,9 +1155,9 @@ Both ends of a many-to-many relationship get automatic API access to the other
1084 1155 
 end. The API works just as a "backward" one-to-many relationship, above.
1085 1156
1086 1157 
 The only difference is in the attribute naming: The model that defines the
1087   
-``ManyToManyField`` uses the attribute name of that field itself, whereas the
1088   
-"reverse" model uses the lowercased model name of the original model, plus
1089   
-``'_set'`` (just like reverse one-to-many relationships).
  1158 
+:class:`~django.db.models.ManyToManyField` uses the attribute name of that
  1159 
+field itself, whereas the "reverse" model uses the lowercased model name of the
  1160 
+original model, plus ``'_set'`` (just like reverse one-to-many relationships).
1090 1161
1091 1162 
 An example makes this easier to understand::
1092 1163 
 
@@ -1098,10 +1169,11 @@ An example makes this easier to understand::
1098 1169 
     a = Author.objects.get(id=5)
1099 1170 
     a.entry_set.all() # Returns all Entry objects for this Author.
1100 1171
1101   
-Like ``ForeignKey``, ``ManyToManyField`` can specify ``related_name``. In the
1102   
-above example, if the ``ManyToManyField`` in ``Entry`` had specified
1103   
-``related_name='entries'``, then each ``Author`` instance would have an
1104   
-``entries`` attribute instead of ``entry_set``.
  1172 
+Like :class:`~django.db.models.ForeignKey`,
  1173 
+:class:`~django.db.models.ManyToManyField` can specify ``related_name``. In the
  1174 
+above example, if the :class:`~django.db.models.ManyToManyField` in ``Entry``
  1175 
+had specified ``related_name='entries'``, then each ``Author`` instance would
  1176 
+have an ``entries`` attribute instead of ``entry_set``.
1105 1177
1106 1178 
 One-to-one relationships
1107 1179 
 ------------------------
 
@@ -1147,10 +1219,11 @@ relationship on one end.
1147 1219 
 But how is this possible, given that a model class doesn't know which other
1148 1220 
 model classes are related to it until those other model classes are loaded?
1149 1221
1150   
-The answer lies in the :setting:`INSTALLED_APPS` setting. The first time any model is
1151   
-loaded, Django iterates over every model in :setting:`INSTALLED_APPS` and creates the
1152   
-backward relationships in memory as needed. Essentially, one of the functions
1153   
-of :setting:`INSTALLED_APPS` is to tell Django the entire model domain.
  1222 
+The answer lies in the :setting:`INSTALLED_APPS` setting. The first time any
  1223 
+model is loaded, Django iterates over every model in :setting:`INSTALLED_APPS`
  1224 
+and creates the backward relationships in memory as needed. Essentially, one of
  1225 
+the functions of :setting:`INSTALLED_APPS` is to tell Django the entire model
  1226 
+domain.
1154 1227
1155 1228 
 Queries over related objects
1156 1229 
 ----------------------------

0 notes on commit 7b624c6

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