From 47e3cc74d9bcf7ff2ce58cca34fa6575118357af Mon Sep 17 00:00:00 2001 From: Jacob Kaplan-Moss <jacob@jacobian.org> Date: Mon, 17 May 2010 16:32:37 +0000 Subject: [PATCH] Slight fixes to related fields reference to avoid conflicting target names with the queryset docs. git-svn-id: http://code.djangoproject.com/svn/django/trunk@13272 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/relations.txt | 131 ++++++++++++++++++---------------- 1 file changed, 69 insertions(+), 62 deletions(-) diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index 798569cc68..f58cfe7301 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -6,93 +6,100 @@ 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 - * The "other side" of a ``ForeignKey`` relation. That is:: + A "related manager" is a on managers used in a one-to-many or many-to-many + related context. This happens in two cases: - class Reporter(models.Model): - ... + * The "other side" of a ``ForeignKey`` relation. That is:: - class Article(models.Model): - reporter = models.ForeignKey(Reporter) + class Reporter(models.Model): + ... - In the above example, the methods below will be available on - the manager ``reporter.article_set``. + class Article(models.Model): + reporter = models.ForeignKey(Reporter) - * Both sides of a ``ManyToManyField`` relation:: + In the above example, the methods below will be available on + the manager ``reporter.article_set``. - class Topping(models.Model): - ... + * Both sides of a ``ManyToManyField`` relation:: - class Pizza(models.Model): - toppings = models.ManyToManyField(Topping) + class Topping(models.Model): + ... - In this example, the methods below will be available both on - ``topping.pizza_set`` and on ``pizza.toppings``. + class Pizza(models.Model): + toppings = models.ManyToManyField(Topping) -.. method:: add(obj1, [obj2, ...]) + In this example, the methods below will be available both on + ``topping.pizza_set`` and on ``pizza.toppings``. - Adds the specified model objects to the related object set. + These related managers have some extra methods: - Example:: + .. method:: add(obj1, [obj2, ...]) - >>> b = Blog.objects.get(id=1) - >>> e = Entry.objects.get(id=234) - >>> b.entry_set.add(e) # Associates Entry e with Blog b. + Adds the specified model objects to the related object set. -.. method:: create(**kwargs) + Example:: - Creates a new object, saves it and puts it in the related object set. - Returns the newly created object:: + >>> b = Blog.objects.get(id=1) + >>> e = Entry.objects.get(id=234) + >>> b.entry_set.add(e) # Associates Entry e with Blog b. - >>> b = Blog.objects.get(id=1) - >>> e = b.entry_set.create( - ... headline='Hello', - ... body_text='Hi', - ... pub_date=datetime.date(2005, 1, 1) - ... ) + .. method:: create(**kwargs) - # No need to call e.save() at this point -- it's already been saved. + Creates a new object, saves it and puts it in the related object set. + Returns the newly created object:: - This is equivalent to (but much simpler than):: + >>> b = Blog.objects.get(id=1) + >>> e = b.entry_set.create( + ... headline='Hello', + ... body_text='Hi', + ... pub_date=datetime.date(2005, 1, 1) + ... ) - >>> b = Blog.objects.get(id=1) - >>> e = Entry( - .... blog=b, - .... headline='Hello', - .... body_text='Hi', - .... pub_date=datetime.date(2005, 1, 1) - .... ) - >>> e.save(force_insert=True) + # No need to call e.save() at this point -- it's already been saved. - 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``. + This is equivalent to (but much simpler than):: -.. method:: remove(obj1, [obj2, ...]) + >>> b = Blog.objects.get(id=1) + >>> e = Entry( + .... blog=b, + .... headline='Hello', + .... body_text='Hi', + .... pub_date=datetime.date(2005, 1, 1) + .... ) + >>> e.save(force_insert=True) - Removes the specified model objects from the related object set:: + 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``. - >>> b = Blog.objects.get(id=1) - >>> e = Entry.objects.get(id=234) - >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. + .. method:: remove(obj1, [obj2, ...]) - 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. + Removes the specified model objects from the related object set:: -.. method:: clear() + >>> b = Blog.objects.get(id=1) + >>> e = Entry.objects.get(id=234) + >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. - Removes all objects from the related object set:: + 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. - >>> b = Blog.objects.get(id=1) - >>> b.entry_set.clear() + .. method:: clear() - Note this doesn't delete the related objects -- it just disassociates them. + Removes all objects from the related object set:: - Just like ``remove()``, ``clear()`` is only available on ``ForeignKey``\s - where ``null=True``. + >>> b = Blog.objects.get(id=1) + >>> b.entry_set.clear() + + 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``.