Fixed #19756 - Corrected a ManyToMany example and added some links and markup.

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()

    >>> 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):

    >>> 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()

    >>> 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>]

    >>> 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>]

    >>> 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

    [<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>]

    >>> 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()

    >>> 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()

    >>> a5.publications.all()

    [<Publication: Science News>]

Removing publication from an article::

Removing ``Publication`` from an ``Article``::

    >>> a4.publications.remove(p2)

    >>> p2.article_set.all()

    >>> 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()

    >>> 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()

    [<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()