mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-05-30 10:46:29 +00:00
Code Issues 32 Releases Wiki Activity

Slight fixes to related fields reference to avoid conflicting target names

Browse Source 
with the queryset docs.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13272 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jacob Kaplan-Moss 2010-05-17 16:32:37 +00:00
parent acd8dcd5b0
commit 47e3cc74d9
1 changed files with 69 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/ref/models/relations.txt
View File

@ -6,7 +6,10 @@ Related objects reference
.. currentmodule:: django.db.models.fields.related .. currentmodule:: django.db.models.fields.related
This document describes extra methods available on managers when used in a one-to-many or many-to-many related context. This happens in two cases: .. class:: RelatedManager
A "related manager" is a on managers used in a one-to-many or many-to-many
related context. This happens in two cases:
* The "other side" of a ``ForeignKey`` relation. That is:: * The "other side" of a ``ForeignKey`` relation. That is::
@ -30,7 +33,9 @@ This document describes extra methods available on managers when used in a one-t
In this example, the methods below will be available both on In this example, the methods below will be available both on
``topping.pizza_set`` and on ``pizza.toppings``. ``topping.pizza_set`` and on ``pizza.toppings``.
.. method:: add(obj1, [obj2, ...]) These related managers have some extra methods:
.. method:: add(obj1, [obj2, ...])
Adds the specified model objects to the related object set. Adds the specified model objects to the related object set.
@ -40,7 +45,7 @@ This document describes extra methods available on managers when used in a one-t
>>> e = Entry.objects.get(id=234) >>> e = Entry.objects.get(id=234)
>>> b.entry_set.add(e) # Associates Entry e with Blog b. >>> b.entry_set.add(e) # Associates Entry e with Blog b.
.. method:: create(**kwargs) .. method:: create(**kwargs)
Creates a new object, saves it and puts it in the related object set. Creates a new object, saves it and puts it in the related object set.
Returns the newly created object:: Returns the newly created object::
@ -65,12 +70,12 @@ This document describes extra methods available on managers when used in a one-t
.... ) .... )
>>> e.save(force_insert=True) >>> e.save(force_insert=True)
Note that there's no need to specify the keyword argument of the model that Note that there's no need to specify the keyword argument of the model
defines the relationship. In the above example, we don't pass the parameter that defines the relationship. In the above example, we don't pass the
``blog`` to ``create()``. Django figures out that the new ``Entry`` object's parameter ``blog`` to ``create()``. Django figures out that the new
``blog`` field should be set to ``b``. ``Entry`` object's ``blog`` field should be set to ``b``.
.. method:: remove(obj1, [obj2, ...]) .. method:: remove(obj1, [obj2, ...])
Removes the specified model objects from the related object set:: Removes the specified model objects from the related object set::
@ -79,20 +84,22 @@ This document describes extra methods available on managers when used in a one-t
>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
In order to prevent database inconsistency, this method only exists on In order to prevent database inconsistency, this method only exists on
``ForeignKey`` objects where ``null=True``. If the related field can't be ``ForeignKey`` objects where ``null=True``. If the related field can't
set to ``None`` (``NULL``), then an object can't be removed from a relation be set to ``None`` (``NULL``), then an object can't be removed from a
without being added to another. In the above example, removing ``e`` from relation without being added to another. In the above example, removing
``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because the ``e`` from ``b.entry_set()`` is equivalent to doing ``e.blog = None``,
``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid. and because the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this
is invalid.
.. method:: clear() .. method:: clear()
Removes all objects from the related object set:: Removes all objects from the related object set::
>>> b = Blog.objects.get(id=1) >>> b = Blog.objects.get(id=1)
>>> b.entry_set.clear() >>> b.entry_set.clear()
Note this doesn't delete the related objects -- it just disassociates them. Note this doesn't delete the related objects -- it just disassociates
them.
Just like ``remove()``, ``clear()`` is only available on ``ForeignKey``\s Just like ``remove()``, ``clear()`` is only available on
where ``null=True``. ``ForeignKey``\s where ``null=True``.