From 43efefae692729925c0f75c55e93bd1f33f42bfd Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Thu, 7 Feb 2013 06:12:25 -0500 Subject: [PATCH] Fixed #19756 - Corrected a ManyToMany example and added some links and markup. --- docs/topics/db/examples/many_to_many.txt | 47 ++++++++++++++---------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/docs/topics/db/examples/many_to_many.txt b/docs/topics/db/examples/many_to_many.txt index 5a24027894..2076427768 100644 --- a/docs/topics/db/examples/many_to_many.txt +++ b/docs/topics/db/examples/many_to_many.txt @@ -35,7 +35,7 @@ objects, and a ``Publication`` has multiple ``Article`` objects: What follows are examples of operations that can be performed using the Python API facilities. -Create a couple of Publications:: +Create a couple of ``Publications``:: >>> p1 = Publication(title='The Python Journal') >>> p1.save() @@ -44,11 +44,11 @@ Create a couple of Publications:: >>> p3 = Publication(title='Science Weekly') >>> p3.save() -Create an Article:: +Create an ``Article``:: >>> a1 = Article(headline='Django lets you build Web apps easily') -You can't associate it with a Publication until it's been saved:: +You can't associate it with a ``Publication`` until it's been saved:: >>> a1.publications.add(p1) Traceback (most recent call last): @@ -60,11 +60,11 @@ Save it! >>> a1.save() -Associate the Article with a Publication:: +Associate the ``Article`` with a ``Publication``:: >>> a1.publications.add(p1) -Create another Article, and set it to appear in both Publications:: +Create another ``Article``, and set it to appear in both ``Publications``:: >>> a2 = Article(headline='NASA uses Python') >>> a2.save() @@ -75,25 +75,26 @@ Adding a second time is OK:: >>> a2.publications.add(p3) -Adding an object of the wrong type raises TypeError:: +Adding an object of the wrong type raises :exc:`~exceptions.TypeError`:: >>> a2.publications.add(a1) Traceback (most recent call last): ... TypeError: 'Publication' instance expected -Add a Publication directly via publications.add by using keyword arguments:: +Create and add a ``Publication`` to an ``Article`` in one step using +:meth:`~django.db.models.fields.related.RelatedManager.create`:: >>> new_publication = a2.publications.create(title='Highlights for Children') -Article objects have access to their related Publication objects:: +``Article`` objects have access to their related ``Publication`` objects:: >>> a1.publications.all() [] >>> a2.publications.all() [, , , ] -Publication objects have access to their related Article objects:: +``Publication`` objects have access to their related ``Article`` objects:: >>> p2.article_set.all() [] @@ -102,7 +103,8 @@ Publication objects have access to their related Article objects:: >>> Publication.objects.get(id=4).article_set.all() [] -Many-to-many relationships can be queried using :ref:`lookups across relationships `:: +Many-to-many relationships can be queried using :ref:`lookups across +relationships `:: >>> Article.objects.filter(publications__id__exact=1) [, ] @@ -119,7 +121,8 @@ Many-to-many relationships can be queried using :ref:`lookups across relationshi >>> Article.objects.filter(publications__title__startswith="Science").distinct() [] -The count() function respects distinct() as well:: +The :meth:`~django.db.models.query.QuerySet.count` function respects +:meth:`~django.db.models.query.QuerySet.distinct` as well:: >>> Article.objects.filter(publications__title__startswith="Science").count() 2 @@ -133,7 +136,7 @@ The count() function respects distinct() as well:: [, ] Reverse m2m queries are supported (i.e., starting at the table that doesn't have -a ManyToManyField):: +a :class:`~django.db.models.ManyToManyField`):: >>> Publication.objects.filter(id__exact=1) [] @@ -163,7 +166,7 @@ involved is a little complex):: >>> Article.objects.exclude(publications=p2) [] -If we delete a Publication, its Articles won't be able to access it:: +If we delete a ``Publication``, its ``Articles`` won't be able to access it:: >>> p1.delete() >>> Publication.objects.all() @@ -172,7 +175,7 @@ If we delete a Publication, its Articles won't be able to access it:: >>> a1.publications.all() [] -If we delete an Article, its Publications won't be able to access it:: +If we delete an ``Article``, its ``Publications`` won't be able to access it:: >>> a2.delete() >>> Article.objects.all() @@ -199,7 +202,7 @@ Adding via the other end using keywords:: >>> a5.publications.all() [] -Removing publication from an article:: +Removing ``Publication`` from an ``Article``:: >>> a4.publications.remove(p2) >>> p2.article_set.all() @@ -242,7 +245,7 @@ And you can clear from the other end:: >>> p2.article_set.all() [] -Recreate the article and Publication we have deleted:: +Recreate the ``Article`` and ``Publication`` we have deleted:: >>> p1 = Publication(title='The Python Journal') >>> p1.save() @@ -250,7 +253,8 @@ Recreate the article and Publication we have deleted:: >>> a2.save() >>> a2.publications.add(p1, p2, p3) -Bulk delete some Publications - references to deleted publications should go:: +Bulk delete some ``Publications`` - references to deleted publications should +go:: >>> Publication.objects.filter(title__startswith='Science').delete() >>> Publication.objects.all() @@ -267,15 +271,18 @@ Bulk delete some articles - references to deleted objects should go:: [] >>> q.delete() -After the delete, the QuerySet cache needs to be cleared, and the referenced -objects should be gone:: +After the :meth:`~django.db.models.query.QuerySet.delete`, the +:class:`~django.db.models.query.QuerySet` cache needs to be cleared, and the +referenced objects should be gone:: >>> print(q) [] >>> p1.article_set.all() [] -An alternate to calling clear() is to assign the empty set:: +An alternate to calling +:meth:`~django.db.models.fields.related.RelatedManager.clear` is to assign the +empty set:: >>> p1.article_set = [] >>> p1.article_set.all()