Ticket #17605: 17605-1.diff

docs/topics/db/models.txt

@@ -346 +346 @@
 -- here's how you'd represent that::
 
     class Topping(models.Model):
-        # ...
+        name = models.CharField(max_length=128)
 
     class Pizza(models.Model):
-        # ...
+        name = models.CharField(max_length=128)
         toppings = models.ManyToManyField(Topping)
 
 As with :class:`~django.db.models.ForeignKey`, you can also create
@@ -374 +374 @@
 topping being on multiple pizzas. The way it's set up above, the ``Pizza`` admin
 form would let users select the toppings.
 
+Here are some examples of :class:`~django.db.models.ManyToManyField` uses::
+
+    >>> mozzarella = Topping.objects.create(name="Mozzarella")
+    >>> tomato = Topping.objects.create(name="Tomato")
+    >>> salami = Topping.objects.create(name="Salami")
+    >>> diavola = Pizza.objects.create(name="Diavola")
+
+    >>> diavola.toppings = [tomato, mozzarella]
+    >>> diavola.toppings.add(salami)
+    >>> diavola.toppings.all()
+    [<Topping: Tomato>, <Topping: Mozzarella>, <Topping: Salami>]
+    >>> margherita = Pizza.objects.create(name="Margherita")
+    # Add is also possible with primary key values
+    >>> margherita.toppings = [tomato.id, mozzarella.id]
+    >>> mozzarella.pizza_set.all()
+    [<Pizza: Diavola>, <Pizza: Margherita>]
+
+    # Queries (from both ends of the relation)
+    >>> Pizza.objects.filter(toppings__name="Tomato")
+    [<Pizza: Diavola>, <Pizza: Margherita>]
+    >>> Pizza.objects.filter(toppings__in=[tomato, mozzarella])
+    [<Pizza: Diavola>, <Pizza: Margherita>, <Pizza: Diavola>, <Pizza: Margherita>]
+    >>> Pizza.objects.filter(toppings__in=[tomato, mozzarella]).distinct()
+    [<Pizza: Diavola>, <Pizza: Margherita>]
+    >>> Topping.objects.filter(pizza=margherita)
+    [<Topping: Mozzarella>, <Topping: Tomato>]
+    >>> Pizza.objects.exclude(toppings=salami)
+    [<Pizza: Margherita>]
+
+    # Removing
+    >>> margherita.toppings.remove(mozzarella)
+    >>> margherita.toppings.all()
+    [<Topping: Tomato>]
+    >>> salami.pizza_set.clear()
+    >>> diavola.toppings.all()
+    [<Topping: Tomato>, <Topping: Mozzarella>]
+    # Assigning an empty list is equivalent to clear()
+    >>> diavola.toppings = []
+    >>> diavola.toppings.all()
+    []
+
 .. seealso::
 
-    See the `Many-to-many relationship model example`_ for a full example.
+    See the `Many-to-many relationship model tests`_ for extensive examples.
 
-.. _Many-to-many relationship model example: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/many_to_many/models.py
+.. _Many-to-many relationship model tests: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/many_to_many/tests.py
 
 :class:`~django.db.models.ManyToManyField` fields also accept a number of extra
 arguments which are explained in :ref:`the model field reference