Changeset 8136

Timestamp:

07/29/08 07:41:08 (2 months ago)

Author:

russellm

Message:

Fixed #6095 -- Added the ability to specify the model to use to manage a ManyToManyField?. Thanks to Eric Florenzano for his excellent work on this patch.

Files:

• django/trunk/AUTHORS (modified) (1 diff)
• django/trunk/django/contrib/admin/options.py (modified) (1 diff)
• django/trunk/django/contrib/contenttypes/generic.py (modified) (1 diff)
• django/trunk/django/core/management/sql.py (modified) (1 diff)
• django/trunk/django/core/management/validation.py (modified) (2 diffs)
• django/trunk/django/db/models/fields/related.py (modified) (20 diffs)
• django/trunk/docs/admin.txt (modified) (1 diff)
• django/trunk/docs/model-api.txt (modified) (3 diffs)
• django/trunk/tests/modeltests/invalid_models/models.py (modified) (2 diffs)
• django/trunk/tests/modeltests/m2m_through (added)
• django/trunk/tests/modeltests/m2m_through/__init__.py (added)
• django/trunk/tests/modeltests/m2m_through/models.py (added)
• django/trunk/tests/regressiontests/m2m_through_regress (added)
• django/trunk/tests/regressiontests/m2m_through_regress/__init__.py (added)
• django/trunk/tests/regressiontests/m2m_through_regress/models.py (added)

django/trunk/AUTHORS

@@ -155 +155 @@
-    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>

django/trunk/django/contrib/admin/options.py

@@ -162 +162 @@
-            else:
-                if isinstance(db_field, models.ManyToManyField):
-
+
+
+
+
-                        kwargs['widget'] = widgets.ManyToManyRawIdWidget(db_field.rel)
-                        kwargs['help_text'] = ''

django/trunk/django/contrib/contenttypes/generic.py

@@ -105 +105 @@
-                            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")

django/trunk/django/core/management/sql.py

@@ -354 +354 @@
-    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: 

django/trunk/django/core/management/validation.py

@@ -103 +103 @@
-                            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
@@ -113 +114 @@
-                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()

django/trunk/django/db/models/fields/related.py

@@ -24 +24 @@
-pending_lookups = {}
-
-
+, operation
-    """
-    Adds a lookup on ``cls`` when a related field is defined using a string,
@@ -46 +46 @@
-    lazy relationships -- then the relation won't be set up until the
-    class_prepared signal fires at the end of model initialization.
+    
+    operation is the work that must be performed once the relation can be resolved.
-    """
-    # Check for recursive relations
@@ -67 +69 @@
-    model = get_model(app_label, model_name, False)
-    if model:
-
-
+
-    else:
-        key = (app_label, model_name)
-
+, operation
-        pending_lookups.setdefault(key, []).append(value)
-
@@ -79 +80 @@
-    """
-    key = (sender._meta.app_label, sender.__name__)
-
-
-
+
+
-
-dispatcher.connect(do_pending_lookups, signal=signals.class_prepared)
@@ -109 +109 @@
-        other = self.rel.to
-        if isinstance(other, basestring):
-
+
+
+
+
-        else:
-            self.do_related_class(other, cls)
@@ -341 +344 @@
-        manager.add(*value)
-
-
+, through=False
-    """Creates a manager that subclasses 'superclass' (which is a Manager)
-    and adds behavior for many-to-many related objects."""
@@ -355 +358 @@
-            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:
@@ -362 +366 @@
-            return superclass.get_query_set(self).filter(**(self.core_filters))
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-        def clear(self):
@@ -387 +394 @@
-
-        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, "Cannot use create() on a ManyToManyField which specifies an intermediary model. Use %s's Manager instead." % through
-            new_obj = self.model(**kwargs)
-            new_obj.save()
@@ -474 +485 @@
-        rel_model = self.related.model
-        superclass = rel_model._default_manager.__class__
-
+, self.related.field.rel.through
-
-        qn = connection.ops.quote_name
@@ -493 +504 @@
-            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()
@@ -515 +530 @@
-        rel_model=self.field.rel.to
-        superclass = rel_model._default_manager.__class__
-
+, self.field.rel.through
-
-        qn = connection.ops.quote_name
@@ -533 +548 @@
-        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)
@@ -585 +604 @@
-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
@@ -595 +614 @@
-        self.symmetrical = symmetrical
-        self.multiple = True
+        self.through = through
-
-class ForeignKey(RelatedField, Field):
@@ -724 +744 @@
-            related_name=kwargs.pop('related_name', None),
-            limit_choices_to=kwargs.pop('limit_choices_to', None),
-
+
+
+
-        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
+
-        Field.__init__(self, **kwargs)
-
@@ -740 +768 @@
-    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:
@@ -747 +777 @@
-    def _get_m2m_column_name(self, related):
-        "Function that can be curried to provide the source column name for the m2m table"
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-    def _get_m2m_reverse_name(self, related):
-        "Function that can be curried to provide the related column name for the m2m table"
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-    def isValidIDList(self, field_data, all_data):
@@ -793 +857 @@
-
-    def contribute_to_class(self, cls, name):
-
+        
-        # Add the descriptor for the m2m relation
-        setattr(cls, self.name, ReverseManyRelatedObjectsDescriptor(self))
@@ -799 +863 @@
-        # Set up the accessor for the m2m table name for the relation
-        self.m2m_db_table = curry(self._get_m2m_db_table, cls._meta)
-
+
+
+
+
+
+
+
+
+
+
+
-        if isinstance(self.rel.to, basestring):
-            target = self.rel.to

django/trunk/docs/admin.txt

@@ -618 +618 @@
-        ]
-
+Working with Many-to-Many Intermediary Models
+----------------------------------------------
+
+By default, admin widgets for many-to-many relations will be displayed inline
+on whichever model contains the actual reference to the `ManyToManyField`.  
+However, when you specify an intermediary model using the ``through``
+argument to a ``ManyToManyField``, the admin will not display a widget by 
+default. This is because each instance of that intermediary model requires
+more information than could be displayed in a single widget, and the layout
+required for multiple widgets will vary depending on the intermediate model.
+
+However, we still want to be able to edit that information inline. Fortunately,
+this is easy to do with inline admin models. Suppose we have the following
+models::
+
+    class Person(models.Model):
+        name = models.CharField(max_length=128)
+    
+    class Group(models.Model):
+        name = models.CharField(max_length=128)
+        members = models.ManyToManyField(Person, through='Membership')
+
+    class Membership(models.Model):
+        person = models.ForeignKey(Person)
+        group = models.ForeignKey(Group)
+        date_joined = models.DateField()
+        invite_reason = models.CharField(max_length=64)
+
+The first step in displaying this intermediate model in the admin is to
+define an inline model for the Membership table::
+
+    class MembershipInline(admin.TabularInline):
+        model = Membership
+        extra = 1
+
+This simple example uses the defaults inline form for the Membership model,
+and shows 1 extra line. This could be customized using any of the options
+available to inline models.
+
+Now create admin views for the ``Person`` and ``Group`` models::
+
+    class PersonAdmin(admin.ModelAdmin):
+        inlines = (MembershipInline,)
+
+    class GroupAdmin(admin.ModelAdmin):
+        inlines = (MembershipInline,)
+
+Finally, register your ``Person`` and ``Group`` models with the admin site::
+    
+    admin.site.register(Person, PersonAdmin)
+    admin.site.register(Group, GroupAdmin)
+
+Now your admin site is set up to edit ``Membership`` objects inline from either
+the ``Person`` or the ``Group`` detail pages.
+
-``AdminSite`` objects
-=====================

django/trunk/docs/model-api.txt

@@ -656 +656 @@
-example::
-
-       
+    
-
-Alternatively you can use plain text and
@@ -945 +945 @@
-    =======================  ============================================================
-
+Extra fields on many-to-many relationships
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**New in Django development version** 
+
+When you're only dealing with simple many-to-many relationships such as
+mixing and matching pizzas and toppings, a standard ``ManyToManyField``
+is all you need. However, sometimes you may need to associate data with the
+relationship between two models. 
+
+For example, consider the case of an application tracking the musical groups
+which musicians belong to. There is a many-to-many relationship between a person
+and the groups of which they are a member, so you could use a ManyToManyField
+to represent this relationship. However, there is a lot of detail about the
+membership that you might want to collect, such as the date at which the person
+joined the group.
+
+For these situations, Django allows you to specify the model that will be used
+to govern the many-to-many relationship. You can then put extra fields on the
+intermediate model. The intermediate model is associated with the
+``ManyToManyField`` using the ``through`` argument to point to the model
+that will act as an intermediary. For our musician example, the code would look
+something like this::
+
+    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.DateField()
+        invite_reason = models.CharField(max_length=64)
+
+When you set up the intermediary model, you explicitly specify foreign 
+keys to the models that are involved in the ManyToMany relation. This
+explicit declaration defines how the two models are related.
+
+There are a few restrictions on the intermediate model:
+
+    * Your intermediate model must contain one - and *only* one - foreign key
+      on the target model (this would be ``Person`` in our example). If you
+      have more than one foreign key, a validation error will be raised.
+  
+    * Your intermediate model must contain one - and *only* one - foreign key 
+      on the source model (this would be ``Group`` in our example). If you
+      have more than one foreign key, a validation error will be raised.
+      
+    * If the many-to-many relation is a relation on itself, the relationship
+      must be non-symmetric.
+
+Now that you have set up your ``ManyToManyField`` to use your intermediary 
+model (Membership, in this case), you're ready to start creating some
+many-to-many relationships. You do this by creating instances of the
+intermediate model::
+    
+    >>> ringo = Person.objects.create(name="Ringo Starr")
+    >>> paul = Person.objects.create(name="Paul McCartney")
+    >>> beatles = Group.objects.create(name="The Beatles")
+    >>> m1 = Membership(person=ringo, group=beatles,
+    ...     date_joined=date(1962, 8, 16), 
+    ...     invite_reason= "Needed a new drummer.")
+    >>> m1.save()
+    >>> beatles.members.all()
+    [<Person: Ringo Starr>]
+    >>> ringo.group_set.all()
+    [<Group: The Beatles>]
+    >>> m2 = Membership.objects.create(person=paul, group=beatles,
+    ...     date_joined=date(1960, 8, 1), 
+    ...     invite_reason= "Wanted to form a band.")
+    >>> beatles.members.all()
+    [<Person: Ringo Starr>, <Person: Paul McCartney>]
+
+Unlike normal many-to-many fields, you *can't* use ``add``, ``create``,
+or assignment (i.e., ``beatles.members = [...]``) to create relationships::
+
+    # THIS WILL NOT WORK
+    >>> beatles.members.add(john)
+    # NEITHER WILL THIS
+    >>> beatles.members.create(name="George Harrison")
+    # AND NEITHER WILL THIS
+    >>> beatles.members = [john, paul, ringo, george]
+    
+Why? You can't just create a relationship between a Person and a Group - you
+need to specify all the detail for the relationship required by the
+Membership table. The simple ``add``, ``create`` and assignment calls
+don't provide a way to specify this extra detail. As a result, they are
+disabled for many-to-many relationships that use an intermediate model.
+The only way to create a many-to-many relationship with an intermediate table
+is to create instances of the intermediate model.
+
+The ``remove`` method is disabled for similar reasons. However, the
+``clear()`` method can be used to remove all many-to-many relationships
+for an instance::
+
+    # Beatles have broken up
+    >>> beatles.members.clear()
+
+Once you have established the many-to-many relationships by creating instances
+of your intermediate model, you can issue queries. Just as with normal 
+many-to-many relationships, you can query using the attributes of the 
+many-to-many-related model::
+
+    # Find all the groups with a member whose name starts with 'Paul'
+    >>> Groups.objects.filter(person__name__startswith='Paul')
+    [<Group: The Beatles>]
+
+As you are using an intermediate table, you can also query on the attributes 
+of the intermediate model::
+
+    # Find all the members of the Beatles that joined after 1 Jan 1961
+    >>> Person.objects.filter(
+    ...     group__name='The Beatles',
+    ...     membership__date_joined__gt=date(1961,1,1))
+    [<Person: Ringo Starr]
+    
-One-to-one relationships
-~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1146 +1271 @@
-with a single set of fields::
-
-       
+    
-
-``verbose_name``

django/trunk/tests/modeltests/invalid_models/models.py

@@ -111 +111 @@
-    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")
+    tertiary = models.ManyToManyField(Person, through="RelationshipDoubleFK", related_name="tertiary")
+
+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")
+    too_many_friends = models.ManyToManyField('self', through="RelationshipTripleFK")
+
+class PersonSelfRefM2MExplicit(models.Model):
+    name = models.CharField(max_length=5)
+    friends = models.ManyToManyField('self', through="ExplicitRelationship", symmetrical=True)
+
+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()
+
+class ExplicitRelationship(models.Model):
+    first = models.ForeignKey(PersonSelfRefM2MExplicit, related_name="rel_from_set")
+    second = models.ForeignKey(PersonSelfRefM2MExplicit, related_name="rel_to_set")
+    date_added = models.DateTimeField()
+
+class RelationshipTripleFK(models.Model):
+    first = models.ForeignKey(PersonSelfRefM2M, related_name="rel_from_set_2")
+    second = models.ForeignKey(PersonSelfRefM2M, related_name="rel_to_set_2")
+    third = models.ForeignKey(PersonSelfRefM2M, related_name="too_many_by_far")
+    date_added = models.DateTimeField()
+
+class RelationshipDoubleFK(models.Model):
+    first = models.ForeignKey(Person, related_name="first_related_name")
+    second = models.ForeignKey(Person, related_name="second_related_name")
+    third = models.ForeignKey(Group, related_name="rel_to_set")
+    date_added = models.DateTimeField()
-
-model_errors = """invalid_models.fielderrors: "charfield": CharFields require a "max_length" attribute.
@@ -196 +253 @@
-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.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
+invalid_models.missingmanualm2mmodel: 'missing_m2m' specifies an m2m relation through model MissingM2MModel, which has not been installed
+invalid_models.group: The model Group has two manually-defined m2m relations through the model Membership, which is not permitted. Please consider using an extra field on your intermediary model instead.
+invalid_models.group: Intermediary model RelationshipDoubleFK has more than one foreign key to Person, which is ambiguous and is not permitted.
+invalid_models.personselfrefm2m: Many-to-many fields with intermediate tables cannot be symmetrical.
+invalid_models.personselfrefm2m: Intermediary model RelationshipTripleFK has more than two foreign keys to PersonSelfRefM2M, which is ambiguous and is not permitted.
+invalid_models.personselfrefm2mexplicit: Many-to-many fields with intermediate tables cannot be symmetrical.
-"""