Ticket #6095: docs.3.diff

a/docs/model-api.txt

@@ -976 +976 @@
-
-    =======================  ============================================================
-
+Extra data on many-to-many relationships
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you're only dealing with mixing and matching pizzas and toppings, a standard 
+``ManyToManyField`` works great.  For many situations, however, some extra data
+is necessary about relationships between models.  For situations like this,
+Django allows for the specification of an intermediary many-to-many model.  To 
+use this functionality, specify a ``through`` keyword argument onto the 
+``ManyToManyField``.  This is best illustrated with an example::
+
+    class Person(models.Model):
+        # ...
+        name = models.CharField(max_length=128)
+        
+        def __unicode__(self):
+            return self.name
+    
+    class Group(models.Model):
+        # ...
+        name = models.CharField(max_length=128)
+        members = models.ManyToManyField(Person, through='Membership')
+        
+        def __unicode__(self):
+            return self.name
+    
+    class Membership(models.Model):
+        person = models.ForeignKey(Person)
+        group = models.ForeignKey(Group)
+        date_joined = models.DateTimeField()
+        invite_reason = models.CharField(max_length=64)
+
+Now that you have set up your ``ManyToManyField`` to use your intermediary 
+model (Membership, in this case), you're ready to use the convenience methods
+provided by that ``ManyToManyField``.  Here's an example of how you can query
+for and use these models::
+    
+    >>> ringo = Person.objects.create(name="Ringo Starr")
+    >>> paul = Person.objects.create(name="Paul McCartney")
+    >>> beatles = Group.objects.create(name="The Beatles")
+    >>> m1 = Membership.objects.create(person=ringo, group=beatles,
+    ...     date_joined=datetime(1962, 8, 16), 
+    ...     invite_reason= "Needed a new drummer.")
+    >>> beatles.members.all()
+    [<Person: Ringo Starr>]
+    >>> ringo.group_set.all()
+    [<Group: The Beatles>]
+    >>> m2 = Membership.objects.create(person=paul, group=beatles,
+    ...     date_joined=datetime(1960, 8, 1), 
+    ...     invite_reason= "Wanted to form a band.")
+    >>> beatles.members.all()
+    [<Person: Ringo Starr>, <Person: Paul McCartney>]
+
+As you can see, creating ``Membership`` objects automatically adds the 
+``Person`` objects to the ``beatles.members`` queryset.  This means that you 
+can do anyting that you would do on a normal queryset, like ``filter`` or 
+``exclude``.
+
+.. note::
+
+    As soon as an intermediary model is specified, the ``add`` and  
+    ``remove`` methods become unavailable on the descriptors added by the
+    ``ManyToManyField``.  For example, something like  
+    ``beatles.members.add(paul)`` will no longer work.
+
+For more examples and ideas on how to work with intermediary models,  
+`see the tests`_.
+
+.. _`see the tests`: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/m2m_manual/models.py
+
-One-to-one relationships
-~~~~~~~~~~~~~~~~~~~~~~~~
-