Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.5.x] Fixed #19756 - Corrected a ManyToMany example and added some …

…links and markup.

Backport of 43efefa from master
  • Loading branch information...
commit a81363d85accfe09fe6885b255355dfb108e25af 1 parent 5ba7682
Tim Graham timgraham authored
Showing with 27 additions and 20 deletions.
  1. +27 −20 docs/topics/db/examples/many_to_many.txt
47 docs/topics/db/examples/many_to_many.txt
View
@@ -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()
[<Publication: The Python Journal>]
>>> a2.publications.all()
[<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
-Publication objects have access to their related Article objects::
+``Publication`` objects have access to their related ``Article`` objects::
>>> p2.article_set.all()
[<Article: NASA uses Python>]
@@ -102,7 +103,8 @@ Publication objects have access to their related Article objects::
>>> Publication.objects.get(id=4).article_set.all()
[<Article: NASA uses Python>]
-Many-to-many relationships can be queried using :ref:`lookups across relationships <lookups-that-span-relationships>`::
+Many-to-many relationships can be queried using :ref:`lookups across
+relationships <lookups-that-span-relationships>`::
>>> Article.objects.filter(publications__id__exact=1)
[<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
@@ -119,7 +121,8 @@ Many-to-many relationships can be queried using :ref:`lookups across relationshi
>>> Article.objects.filter(publications__title__startswith="Science").distinct()
[<Article: NASA uses Python>]
-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::
[<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
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)
[<Publication: The Python Journal>]
@@ -163,7 +166,7 @@ involved is a little complex)::
>>> Article.objects.exclude(publications=p2)
[<Article: Django lets you build Web apps easily>]
-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()
[<Publication: Science News>]
-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()
[<Article: Oxygen-free diet works wonders>]
-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::
[<Article: Django lets you build Web apps easily>]
>>> 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()
[<Article: NASA uses Python>]
-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()
Please sign in to comment.
Something went wrong with that request. Please try again.