Loading docs/ref/models/relations.txt +69 −62 Original line number Diff line number Diff line Loading @@ -6,7 +6,10 @@ Related objects reference .. 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:: Loading @@ -30,6 +33,8 @@ 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 ``topping.pizza_set`` and on ``pizza.toppings``. These related managers have some extra methods: .. method:: add(obj1, [obj2, ...]) Adds the specified model objects to the related object set. Loading Loading @@ -65,10 +70,10 @@ This document describes extra methods available on managers when used in a one-t .... ) >>> e.save(force_insert=True) Note that there's no need to specify the keyword argument of the model that defines the relationship. In the above example, we don't pass the parameter ``blog`` to ``create()``. Django figures out that the new ``Entry`` object's ``blog`` field should be set to ``b``. Note that there's no need to specify the keyword argument of the model that defines the relationship. In the above example, we don't pass the parameter ``blog`` to ``create()``. Django figures out that the new ``Entry`` object's ``blog`` field should be set to ``b``. .. method:: remove(obj1, [obj2, ...]) Loading @@ -79,11 +84,12 @@ 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. In order to prevent database inconsistency, this method only exists on ``ForeignKey`` objects where ``null=True``. If the related field can't be set to ``None`` (``NULL``), then an object can't be removed from a relation without being added to another. In the above example, removing ``e`` from ``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid. ``ForeignKey`` objects where ``null=True``. If the related field can't be set to ``None`` (``NULL``), then an object can't be removed from a relation without being added to another. In the above example, removing ``e`` from ``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid. .. method:: clear() Loading @@ -92,7 +98,8 @@ This document describes extra methods available on managers when used in a one-t >>> b = Blog.objects.get(id=1) >>> 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 where ``null=True``. Just like ``remove()``, ``clear()`` is only available on ``ForeignKey``\s where ``null=True``. Loading
docs/ref/models/relations.txt +69 −62 Original line number Diff line number Diff line Loading @@ -6,7 +6,10 @@ Related objects reference .. 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:: Loading @@ -30,6 +33,8 @@ 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 ``topping.pizza_set`` and on ``pizza.toppings``. These related managers have some extra methods: .. method:: add(obj1, [obj2, ...]) Adds the specified model objects to the related object set. Loading Loading @@ -65,10 +70,10 @@ This document describes extra methods available on managers when used in a one-t .... ) >>> e.save(force_insert=True) Note that there's no need to specify the keyword argument of the model that defines the relationship. In the above example, we don't pass the parameter ``blog`` to ``create()``. Django figures out that the new ``Entry`` object's ``blog`` field should be set to ``b``. Note that there's no need to specify the keyword argument of the model that defines the relationship. In the above example, we don't pass the parameter ``blog`` to ``create()``. Django figures out that the new ``Entry`` object's ``blog`` field should be set to ``b``. .. method:: remove(obj1, [obj2, ...]) Loading @@ -79,11 +84,12 @@ 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. In order to prevent database inconsistency, this method only exists on ``ForeignKey`` objects where ``null=True``. If the related field can't be set to ``None`` (``NULL``), then an object can't be removed from a relation without being added to another. In the above example, removing ``e`` from ``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid. ``ForeignKey`` objects where ``null=True``. If the related field can't be set to ``None`` (``NULL``), then an object can't be removed from a relation without being added to another. In the above example, removing ``e`` from ``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid. .. method:: clear() Loading @@ -92,7 +98,8 @@ This document describes extra methods available on managers when used in a one-t >>> b = Blog.objects.get(id=1) >>> 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 where ``null=True``. Just like ``remove()``, ``clear()`` is only available on ``ForeignKey``\s where ``null=True``.