Ticket #17605: 17605-1.diff

File 17605-1.diff, 3.1 KB (added by Claude Paroz, 13 years ago)

Adding ManyToManyField examples

  • docs/topics/db/models.txt

    diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
    index 65b2d59..21264bb 100644
    a b For example, if a ``Pizza`` has multiple ``Topping`` objects -- that is, a  
    346346-- here's how you'd represent that::
    347347
    348348    class Topping(models.Model):
    349         # ...
     349        name = models.CharField(max_length=128)
    350350
    351351    class Pizza(models.Model):
    352         # ...
     352        name = models.CharField(max_length=128)
    353353        toppings = models.ManyToManyField(Topping)
    354354
    355355As with :class:`~django.db.models.ForeignKey`, you can also create
    because it's more natural to think about a pizza having toppings than a  
    374374topping being on multiple pizzas. The way it's set up above, the ``Pizza`` admin
    375375form would let users select the toppings.
    376376
     377Here are some examples of :class:`~django.db.models.ManyToManyField` uses::
     378
     379    >>> mozzarella = Topping.objects.create(name="Mozzarella")
     380    >>> tomato = Topping.objects.create(name="Tomato")
     381    >>> salami = Topping.objects.create(name="Salami")
     382    >>> diavola = Pizza.objects.create(name="Diavola")
     383
     384    >>> diavola.toppings = [tomato, mozzarella]
     385    >>> diavola.toppings.add(salami)
     386    >>> diavola.toppings.all()
     387    [<Topping: Tomato>, <Topping: Mozzarella>, <Topping: Salami>]
     388    >>> margherita = Pizza.objects.create(name="Margherita")
     389    # Add is also possible with primary key values
     390    >>> margherita.toppings = [tomato.id, mozzarella.id]
     391    >>> mozzarella.pizza_set.all()
     392    [<Pizza: Diavola>, <Pizza: Margherita>]
     393
     394    # Queries (from both ends of the relation)
     395    >>> Pizza.objects.filter(toppings__name="Tomato")
     396    [<Pizza: Diavola>, <Pizza: Margherita>]
     397    >>> Pizza.objects.filter(toppings__in=[tomato, mozzarella])
     398    [<Pizza: Diavola>, <Pizza: Margherita>, <Pizza: Diavola>, <Pizza: Margherita>]
     399    >>> Pizza.objects.filter(toppings__in=[tomato, mozzarella]).distinct()
     400    [<Pizza: Diavola>, <Pizza: Margherita>]
     401    >>> Topping.objects.filter(pizza=margherita)
     402    [<Topping: Mozzarella>, <Topping: Tomato>]
     403    >>> Pizza.objects.exclude(toppings=salami)
     404    [<Pizza: Margherita>]
     405
     406    # Removing
     407    >>> margherita.toppings.remove(mozzarella)
     408    >>> margherita.toppings.all()
     409    [<Topping: Tomato>]
     410    >>> salami.pizza_set.clear()
     411    >>> diavola.toppings.all()
     412    [<Topping: Tomato>, <Topping: Mozzarella>]
     413    # Assigning an empty list is equivalent to clear()
     414    >>> diavola.toppings = []
     415    >>> diavola.toppings.all()
     416    []
     417
    377418.. seealso::
    378419
    379     See the `Many-to-many relationship model example`_ for a full example.
     420    See the `Many-to-many relationship model tests`_ for extensive examples.
    380421
    381 .. _Many-to-many relationship model example: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/many_to_many/models.py
     422.. _Many-to-many relationship model tests: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/many_to_many/tests.py
    382423
    383424:class:`~django.db.models.ManyToManyField` fields also accept a number of extra
    384425arguments which are explained in :ref:`the model field reference
Back to Top