Ticket #6095: 6095-trunk-withdocs.rc3.diff

django/db/models/options.py

@@ -10 +10 @@
-from django.db.models.fields.related import ManyToManyRel
-from django.db.models.fields import AutoField, FieldDoesNotExist
-from django.db.models.fields.proxy import OrderWrt
-
+get_model, 
-from django.db.models import Manager
-from django.utils.translation import activate, deactivate_all, get_language, string_concat
-from django.utils.encoding import force_unicode, smart_str
@@ -402 +402 @@
-            follow = self.get_follow()
-        return [f for f in self.get_all_related_objects() if follow.get(f.name, None)]
-
+    def get_related_object(self, from_model, self_ref=False):
+        "Gets the RelatedObject which links from from_model to this model."
+        for related_object in self.get_all_related_objects():
+            if related_object.model == from_model:
+                if self_ref:
+                    self_ref = False
+                else:
+                    return related_object
+        return None
+
-    def get_data_holders(self, follow=None):
-        if follow == None:
-            follow = self.get_follow()

django/db/models/fields/related.py

@@ -340 +340 @@
-            manager.clear()
-        manager.add(*value)
-
-
+, through=False
-    """Creates a manager that subclasses 'superclass' (which is a Manager)
-    and adds behavior for many-to-many related objects."""
-    class ManyRelatedManager(superclass):
@@ -354 +354 @@
-            self.join_table = join_table
-            self.source_col_name = source_col_name
-            self.target_col_name = target_col_name
+            self.through = through
-            self._pk_val = self.instance._get_pk_val()
-            if self._pk_val is None:
-                raise ValueError("%r instance needs to have a primary key value before a many-to-many relationship can be used." % instance.__class__.__name__)
@@ -386 +387 @@
-        clear.alters_data = True
-
-        def create(self, **kwargs):
+            # This check needs to be done here, since we can't later remove this
+            # from the method lookup table, as we do with add and remove.
+            if through is not None:
+                raise AttributeError, "'ManyRelatedManager' object has no attribute 'create'"
-            new_obj = self.model(**kwargs)
-            new_obj.save()
-            self.add(new_obj)
@@ -453 +458 @@
-                [self._pk_val])
-            transaction.commit_unless_managed()
-
+    # If it's an intermediary model, detach the add and remove methods from this 
+    # ManyRelatedManager.  Create cannot be detached this way due to an 
+    # inherited method in the dynamic method lookup table that gets in the way.
+    if through is not None:
+        del ManyRelatedManager.add
+        del ManyRelatedManager.remove
+
-    return ManyRelatedManager
-
-class ManyRelatedObjectsDescriptor(object):
@@ -473 +485 @@
-        # model's default manager.
-        rel_model = self.related.model
-        superclass = rel_model._default_manager.__class__
-
+, self.related.field.rel.through
-
-        qn = connection.ops.quote_name
-        manager = RelatedManager(
@@ -492 +504 @@
-        if instance is None:
-            raise AttributeError, "Manager must be accessed via instance"
-
+        through = getattr(self.related.field.rel, 'through', None)
+        if through is not None:
+            raise AttributeError, "Cannot set values on a ManyToManyField which specifies an intermediary model.  Use %s's Manager instead." % through
+
-        manager = self.__get__(instance)
-        manager.clear()
-        manager.add(*value)
@@ -514 +530 @@
-        # model's default manager.
-        rel_model=self.field.rel.to
-        superclass = rel_model._default_manager.__class__
-
+, self.field.rel.through
-
-        qn = connection.ops.quote_name
-        manager = RelatedManager(
@@ -533 +549 @@
-        if instance is None:
-            raise AttributeError, "Manager must be accessed via instance"
-
+        through = getattr(self.field.rel, 'through', None)
+        if through is not None:
+            raise AttributeError, "Cannot set values on a ManyToManyField which specifies an intermediary model.  Use %s's Manager instead." % through
+
-        manager = self.__get__(instance)
-        manager.clear()
-        manager.add(*value)
@@ -586 +606 @@
-
-class ManyToManyRel(object):
-    def __init__(self, to, num_in_admin=0, related_name=None,
-
+, through=None
-        self.to = to
-        self.num_in_admin = num_in_admin
-        self.related_name = related_name
@@ -598 +618 @@
-        self.raw_id_admin = raw_id_admin
-        self.symmetrical = symmetrical
-        self.multiple = True
+        self.through = through
+        self.through_app_label = None
+        self._model_cache = None
-
-        assert not (self.raw_id_admin and self.filter_interface), "ManyToManyRels may not use both raw_id_admin and filter_interface"
-
+    def _get_through_model(self):
+        if self._model_cache:
+            return self._model_cache
+        if self.through and self.through_app_label:
+            self._model_cache = get_model(self.through_app_label, self.through)
+            return self._model_cache
+        return None
+    through_model = property(_get_through_model)
+
-class ForeignKey(RelatedField, Field):
-    empty_strings_allowed = False
-    def __init__(self, to, to_field=None, rel_class=ManyToOneRel, **kwargs):
@@ -746 +778 @@
-            filter_interface=kwargs.pop('filter_interface', None),
-            limit_choices_to=kwargs.pop('limit_choices_to', None),
-            raw_id_admin=kwargs.pop('raw_id_admin', False),
-
+
+
-        self.db_table = kwargs.pop('db_table', None)
+        if kwargs['rel'].through is not None:
+            self.creates_table = False
+            assert self.db_table is None, "Cannot specify a db_table if an intermediary model is used."
+        else:
+            self.creates_table = True
-        if kwargs["rel"].raw_id_admin:
-            kwargs.setdefault("validator_list", []).append(self.isValidIDList)
-        Field.__init__(self, **kwargs)
@@ -770 +808 @@
-
-    def _get_m2m_db_table(self, opts):
-        "Function that can be curried to provide the m2m table name for this relation"
-
+
+
+
-            return self.db_table
-        else:
-            return '%s_%s' % (opts.db_table, self.name)
-
-    def _get_m2m_column_name(self, related):
-        "Function that can be curried to provide the source column name for the m2m table"
+        if self.rel.through is not None:
+            field = related.model._meta.get_related_object(self.rel.through_model).field
+            return field.get_attname_column()[1]
-        # If this is an m2m relation to self, avoid the inevitable name clash
-
+el
-            return 'from_' + related.model._meta.object_name.lower() + '_id'
-        else:
-            return related.model._meta.object_name.lower() + '_id'
-
-    def _get_m2m_reverse_name(self, related):
-        "Function that can be curried to provide the related column name for the m2m table"
+        if self.rel.through is not None:
+            meta = related.parent_model._meta
+            if self.parent == self.rel.to:
+                related = meta.get_related_object(self.rel.through_model, self_ref = True)
+            else:
+                related = meta.get_related_object(self.rel.through_model)
+            return related.field.get_attname_column()[1]
-        # If this is an m2m relation to self, avoid the inevitable name clash
-
+el
-            return 'to_' + related.parent_model._meta.object_name.lower() + '_id'
-        else:
-            return related.parent_model._meta.object_name.lower() + '_id'
@@ -832 +882 @@
-
-        # Set up the accessor for the m2m table name for the relation
-        self.m2m_db_table = curry(self._get_m2m_db_table, cls._meta)
+        
+        # Get a reference to the parent model
+        self.parent = cls
+        
+        # Populate some necessary rel arguments so that cross-app relations
+        # work correctly.
+        if isinstance(self.rel.through, basestring):
+            try:
+                self.rel.through_app_label, self.rel.through = self.rel.through.split('.')
+            except ValueError:
+                self.rel.through_app_label = cls._meta.app_label
-
-        if isinstance(self.rel.to, basestring):
-            target = self.rel.to

django/core/management/validation.py

@@ -104 +104 @@
-                        if r.get_accessor_name() == rel_query_name:
-                            e.add(opts, "Reverse query name for field '%s' clashes with related field '%s.%s'. Add a related_name argument to the definition for '%s'." % (f.name, rel_opts.object_name, r.get_accessor_name(), f.name))
-
+        seen_intermediary_signatures = [] 
-        for i, f in enumerate(opts.local_many_to_many):
-            # Check to see if the related m2m field will clash with any
-            # existing fields, m2m fields, m2m related objects or related
@@ -114 +115 @@
-                # so skip the next section
-                if isinstance(f.rel.to, (str, unicode)):
-                    continue
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-            rel_opts = f.rel.to._meta
-            rel_name = RelatedObject(f.rel.to, cls, f).get_accessor_name()
-            rel_query_name = f.related_query_name()

django/core/management/sql.py

@@ -353 +353 @@
-    qn = connection.ops.quote_name
-    inline_references = connection.features.inline_fk_references
-    for f in opts.local_many_to_many:
-not isinstance(f.rel, generic.GenericRel)
+f.creates_table
-            tablespace = f.db_tablespace or opts.db_tablespace
-            if tablespace and connection.features.supports_tablespaces: 
-                tablespace_sql = ' ' + connection.ops.tablespace_sql(tablespace, inline=True)

django/contrib/contenttypes/generic.py

@@ -104 +104 @@
-                            limit_choices_to=kwargs.pop('limit_choices_to', None),
-                            symmetrical=kwargs.pop('symmetrical', True))
-
+        # By its very nature, a GenericRelation doesn't create a table.
+        self.creates_table = False
+
-        # Override content-type/object-id field names on the related class
-        self.object_id_field_name = kwargs.pop("object_id_field", "object_id")
-        self.content_type_field_name = kwargs.pop("content_type_field", "content_type")

tests/modeltests/invalid_models/models.py

@@ -111 +111 @@
-class MissingRelations(models.Model):
-    rel1 = models.ForeignKey("Rel1")
-    rel2 = models.ManyToManyField("Rel2")
+    
+class MissingManualM2MModel(models.Model):
+    name = models.CharField(max_length=5)
+    missing_m2m = models.ManyToManyField(Model, through="MissingM2MModel")
+    
+class Person(models.Model):
+    name = models.CharField(max_length=5)
-
+class Group(models.Model):
+    name = models.CharField(max_length=5)
+    primary = models.ManyToManyField(Person, through="Membership", related_name="primary")
+    secondary = models.ManyToManyField(Person, through="Membership", related_name="secondary")
+
+class GroupTwo(models.Model):
+    name = models.CharField(max_length=5)
+    primary = models.ManyToManyField(Person, through="Membership")
+    secondary = models.ManyToManyField(Group, through="MembershipMissingFK")
+
+class Membership(models.Model):
+    person = models.ForeignKey(Person)
+    group = models.ForeignKey(Group)
+    not_default_or_null = models.CharField(max_length=5)
+
+class MembershipMissingFK(models.Model):
+    person = models.ForeignKey(Person)
+
+class PersonSelfRefM2M(models.Model):
+    name = models.CharField(max_length=5)
+    friends = models.ManyToManyField('self', through="Relationship")
+
+class Relationship(models.Model):
+    first = models.ForeignKey(PersonSelfRefM2M, related_name="rel_from_set")
+    second = models.ForeignKey(PersonSelfRefM2M, related_name="rel_to_set")
+    date_added = models.DateTimeField()
+
-model_errors = """invalid_models.fielderrors: "charfield": CharFields require a "max_length" attribute.
-invalid_models.fielderrors: "decimalfield": DecimalFields require a "decimal_places" attribute.
-invalid_models.fielderrors: "decimalfield": DecimalFields require a "max_digits" attribute.
@@ -197 +231 @@
-invalid_models.selfclashm2m: Reverse query name for m2m field 'm2m_4' clashes with field 'SelfClashM2M.selfclashm2m'. Add a related_name argument to the definition for 'm2m_4'.
-invalid_models.missingrelations: 'rel2' has m2m relation with model Rel2, which has not been installed
-invalid_models.missingrelations: 'rel1' has relation with model Rel1, which has not been installed
+invalid_models.group: Group has two manually-defined m2m relations through model Membership, which is not possible.  Please consider using an extra field on your intermediary model instead.
+invalid_models.missingmanualm2mmodel: missing_m2m has a manually-defined m2m relation through model MissingM2MModel, which does not exist.
+invalid_models.grouptwo: primary has a manually-defined m2m relation through model Membership, which does not have foreign keys to Person and GroupTwo
+invalid_models.grouptwo: secondary has a manually-defined m2m relation through model MembershipMissingFK, which does not have foreign keys to Group and GroupTwo
-"""

tests/modeltests/m2m_through/models.py

@@ +1 @@
+from django.db import models
+from datetime import datetime
+
+# M2M described on one of the models
+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')
+    custom_members = models.ManyToManyField(Person, through='CustomMembership', related_name="custom")
+    nodefaultsnonulls = models.ManyToManyField(Person, through='TestNoDefaultsOrNulls', related_name="testnodefaultsnonulls")
+    
+    def __unicode__(self):
+        return self.name
+
+class Membership(models.Model):
+    person = models.ForeignKey(Person)
+    group = models.ForeignKey(Group)
+    date_joined = models.DateTimeField(default=datetime.now)
+    invite_reason = models.CharField(max_length=64, null=True)
+    
+    def __unicode__(self):
+        return "%s is a member of %s" % (self.person.name, self.group.name)
+
+class CustomMembership(models.Model):
+    person = models.ForeignKey(Person, db_column="custom_person_column", related_name="custom_person_related_name")
+    group = models.ForeignKey(Group)
+    weird_fk = models.ForeignKey(Membership, null=True)
+    date_joined = models.DateTimeField(default=datetime.now)
+    
+    def __unicode__(self):
+        return "%s is a member of %s" % (self.person.name, self.group.name)
+    
+    class Meta:
+        db_table = "test_table"
+
+class TestNoDefaultsOrNulls(models.Model):
+    person = models.ForeignKey(Person)
+    group = models.ForeignKey(Group)
+    nodefaultnonull = models.CharField(max_length=5)
+
+class PersonSelfRefM2M(models.Model):
+    name = models.CharField(max_length=5)
+    friends = models.ManyToManyField('self', through="Friendship")
+    
+    def __unicode__(self):
+        return self.name
+
+class Friendship(models.Model):
+    first = models.ForeignKey(PersonSelfRefM2M, related_name="rel_from_set")
+    second = models.ForeignKey(PersonSelfRefM2M, related_name="rel_to_set")
+    date_friended = models.DateTimeField()
+
+__test__ = {'API_TESTS':"""
+>>> from datetime import datetime
+
+### Creation and Saving Tests ###
+
+>>> bob = Person.objects.create(name = 'Bob')
+>>> jim = Person.objects.create(name = 'Jim')
+>>> jane = Person.objects.create(name = 'Jane')
+>>> rock = Group.objects.create(name = 'Rock')
+>>> roll = Group.objects.create(name = 'Roll')
+
+# We start out by making sure that the Group 'rock' has no members.
+>>> rock.members.all()
+[]
+
+# To make Jim a member of Group Rock, simply create a Membership object.
+>>> m1 = Membership.objects.create(person = jim, group = rock)
+
+# We can do the same for Jane and Rock.
+>>> m2 = Membership.objects.create(person = jane, group = rock)
+
+# Let's check to make sure that it worked.  Jane and Jim should be members of Rock.
+>>> rock.members.all()
+[<Person: Jim>, <Person: Jane>]
+
+# Now we can add a bunch more Membership objects to test with.
+>>> m3 = Membership.objects.create(person = bob, group = roll)
+>>> m4 = Membership.objects.create(person = jim, group = roll)
+>>> m5 = Membership.objects.create(person = jane, group = roll)
+
+# We can get Jim's Group membership as with any ForeignKey.
+>>> jim.group_set.all()
+[<Group: Rock>, <Group: Roll>]
+
+# Querying the intermediary model works like normal.  
+# In this case we get Jane's membership to Rock.
+>>> m = Membership.objects.get(person = jane, group = rock)
+>>> m
+<Membership: Jane is a member of Rock>
+
+# Now we set some date_joined dates for further testing.
+>>> m2.invite_reason = "She was just awesome."
+>>> m2.date_joined = datetime(2006, 1, 1)
+>>> m2.save()
+
+>>> m5.date_joined = datetime(2004, 1, 1)
+>>> m5.save()
+
+>>> m3.date_joined = datetime(2004, 1, 1)
+>>> m3.save()
+
+# It's not only get that works.  Filter works like normal as well.
+>>> Membership.objects.filter(person = jim)
+[<Membership: Jim is a member of Rock>, <Membership: Jim is a member of Roll>]
+
+
+### Forward Descriptors Tests ###
+
+# Due to complications with adding via an intermediary model, the add method is
+# not provided.
+>>> rock.members.add(bob)
+Traceback (most recent call last):
+...
+AttributeError: 'ManyRelatedManager' object has no attribute 'add'
+
+>>> rock.members.create(name = 'Anne')
+Traceback (most recent call last):
+...
+AttributeError: 'ManyRelatedManager' object has no attribute 'create'
+
+# Remove has similar complications, and is not provided either.
+>>> rock.members.remove(jim)
+Traceback (most recent call last):
+...
+AttributeError: 'ManyRelatedManager' object has no attribute 'remove'
+
+# Here we back up the list of all members of Rock.
+>>> backup = list(rock.members.all())
+
+# ...and we verify that it has worked.
+>>> backup
+[<Person: Jim>, <Person: Jane>]
+
+# The clear function should still work.
+>>> rock.members.clear()
+
+# Now there will be no members of Rock.
+>>> rock.members.all()
+[]
+
+# Assignment should not work with models specifying a through model for many of
+# the same reasons as adding.
+>>> rock.members = backup
+Traceback (most recent call last):
+...
+AttributeError: Cannot set values on a ManyToManyField which specifies an intermediary model.  Use Membership's Manager instead.
+
+# Let's re-save those instances that we've cleared.
+>>> m1.save()
+>>> m2.save()
+
+# Verifying that those instances were re-saved successfully.
+>>> rock.members.all()
+[<Person: Jim>, <Person: Jane>]
+
+
+### Reverse Descriptors Tests ###
+
+# Due to complications with adding via an intermediary model, the add method is
+# not provided.
+>>> bob.group_set.add(rock)
+Traceback (most recent call last):
+...
+AttributeError: 'ManyRelatedManager' object has no attribute 'add'
+
+# Create is another method that should not work correctly, as it suffers from
+# the same problems as add.
+>>> bob.group_set.create(name = 'Funk')
+Traceback (most recent call last):
+...
+AttributeError: 'ManyRelatedManager' object has no attribute 'create'
+
+# Remove has similar complications, and is not provided either.
+>>> jim.group_set.remove(rock)
+Traceback (most recent call last):
+...
+AttributeError: 'ManyRelatedManager' object has no attribute 'remove'
+
+# Here we back up the list of all of Jim's groups.
+>>> backup = list(jim.group_set.all())
+>>> backup
+[<Group: Rock>, <Group: Roll>]
+
+# The clear function should still work.
+>>> jim.group_set.clear()
+
+# Now Jim will be in no groups.
+>>> jim.group_set.all()
+[]
+
+# Assignment should not work with models specifying a through model for many of
+# the same reasons as adding.
+>>> jim.group_set = backup
+Traceback (most recent call last):
+...
+AttributeError: Cannot set values on a ManyToManyField which specifies an intermediary model.  Use Membership's Manager instead.
+
+# Let's re-save those instances that we've cleared.
+>>> m1.save()
+>>> m4.save()
+
+# Verifying that those instances were re-saved successfully.
+>>> jim.group_set.all()
+[<Group: Rock>, <Group: Roll>]
+
+### Custom Tests ###
+
+# Let's see if we can query through our second relationship.
+>>> rock.custom_members.all()
+[]
+
+# We can query in the opposite direction as well.
+>>> bob.custom.all()
+[]
+
+# Let's create some membership objects in this custom relationship.
+>>> cm1 = CustomMembership.objects.create(person = bob, group = rock)
+>>> cm2 = CustomMembership.objects.create(person = jim, group = rock)
+
+# If we get the number of people in Rock, it should be both Bob and Jim.
+>>> rock.custom_members.all()
+[<Person: Bob>, <Person: Jim>]
+
+# Bob should only be in one custom group.
+>>> bob.custom.all()
+[<Group: Rock>]
+
+# Let's make sure our new descriptors don't conflict with the FK related_name.
+>>> bob.custom_person_related_name.all()
+[<CustomMembership: Bob is a member of Rock>]
+
+### SELF-REFERENTIAL TESTS ###
+
+# Let's first create a person who has no friends.
+>>> tony = PersonSelfRefM2M.objects.create(name="Tony")
+>>> tony.friends.all()
+[]
+
+# Now let's create another person for Tony to be friends with.
+>>> chris = PersonSelfRefM2M.objects.create(name="Chris")
+>>> f = Friendship.objects.create(first=tony, second=chris, 
+...     date_friended=datetime.now())
+
+# Tony should now show that Chris is his friend.
+>>> tony.friends.all()
+[<PersonSelfRefM2M: Chris>]
+
+# But we haven't established that Chris is Tony's Friend.
+>>> chris.friends.all()
+[]
+
+# So let's do that now.
+>>> f2 = Friendship.objects.create(first=chris, second=tony, 
+...     date_friended=datetime.now())
+
+# Having added Chris as a friend, let's make sure that his friend set reflects
+# that addition.
+>>> chris.friends.all()
+[<PersonSelfRefM2M: Tony>]
+
+# Chris gets mad and wants to get rid of all of his friends.
+>>> chris.friends.clear()
+
+# Now he should not have any more friends.
+>>> chris.friends.all()
+[]
+
+# Since this is a symmetrical relation, Tony's friend link is deleted as well.
+>>> tony.friends.all()
+[]
+
+
+
+### QUERY TESTS ###
+
+# We can query for the related model by using its attribute name (members, in 
+# this case).
+>>> Group.objects.filter(members__name='Bob')
+[<Group: Roll>]
+
+# To query through the intermediary model, we specify its model name.
+# In this case, membership.
+>>> Group.objects.filter(membership__invite_reason = "She was just awesome.")
+[<Group: Rock>]
+
+# If we want to query in the reverse direction by the related model, use its
+# model name (group, in this case).
+>>> Person.objects.filter(group__name="Rock")
+[<Person: Jim>, <Person: Jane>]
+
+# If the m2m field has specified a related_name, using that will work.
+>>> Person.objects.filter(custom__name="Rock")
+[<Person: Bob>, <Person: Jim>]
+
+# To query through the intermediary model in the reverse direction, we again
+# specify its model name (membership, in this case).
+>>> Person.objects.filter(membership__invite_reason = "She was just awesome.")
+[<Person: Jane>]
+
+# Let's see all of the groups that Jane joined after 1 Jan 2005:
+>>> Group.objects.filter(membership__date_joined__gt = datetime(2005, 1, 1), 
+... membership__person = jane)
+[<Group: Rock>]
+
+# Queries also work in the reverse direction: Now let's see all of the people 
+# that have joined Rock since 1 Jan 2005:
+>>> Person.objects.filter(membership__date_joined__gt = datetime(2005, 1, 1), 
+... membership__group = rock)
+[<Person: Jim>, <Person: Jane>]
+
+# Conceivably, queries through membership could return correct, but non-unique
+# querysets.  To demonstrate this, we query for all people who have joined a 
+# group after 2004:
+>>> Person.objects.filter(membership__date_joined__gt = datetime(2004, 1, 1))
+[<Person: Jim>, <Person: Jim>, <Person: Jane>]
+
+# Jim showed up twice, because he joined two groups ('Rock', and 'Roll'):
+>>> [(m.person.name, m.group.name) for m in 
+... Membership.objects.filter(date_joined__gt = datetime(2004, 1, 1))]
+[(u'Jim', u'Rock'), (u'Jane', u'Rock'), (u'Jim', u'Roll')]
+
+# QuerySet's distinct() method can correct this problem.
+>>> Person.objects.filter(membership__date_joined__gt = datetime(2004, 1, 1)).distinct()
+[<Person: Jim>, <Person: Jane>]
+"""}

AUTHORS

@@ -151 +151 @@
-    J. Pablo Fernandez <pupeno@pupeno.com>
-    Matthew Flanagan <http://wadofstuff.blogspot.com>
-    Eric Floehr <eric@intellovations.com>
+    Eric Florenzano <floguy@gmail.com>
-    Vincent Foley <vfoleybourgon@yahoo.ca>
-    Rudolph Froger <rfroger@estrate.nl>
-    Jorge Gajon <gajon@gajon.org>

docs/model-api.txt

@@ -991 +991 @@
-
-    =======================  ============================================================
-
+Extra fields 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 
+fields are required on the relationships between models.  For situations like 
+this, Django allows for the specification of an intermediary many-to-many model.
+To enable this functionality, simply 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)
+
+.. note::
+
+    The intermediary model must provide foreign keys to both of the models in
+    the relation.  This explicit declaration makes it clear how two models are 
+    related.  More importantly, perhaps, these foreign keys also provide access
+    to the intermediary model from either of the other models in the relation 
+    (as with any other foreign key).
+
+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 anything 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_through/models.py
+
-One-to-one relationships
-~~~~~~~~~~~~~~~~~~~~~~~~
-