Django includes a contenttypes application that can track all of the models installed in your Django-powered project, providing a high-level, generic interface for working with your models.
At the heart of the contenttypes application is the ContentType model, which lives at django.contrib.contenttypes.models.ContentType. Instances of ContentType represent and store information about the models installed in your project, and new instances of ContentType are automatically created whenever new models are installed.
Instances of ContentType have methods for returning the model classes they represent and for querying objects from those models. ContentType also has a custom manager that adds methods for working with ContentType and for obtaining instances of ContentType for a particular model.
Relations between your models and ContentType can also be used to enable “generic” relationships between an instance of one of your models and instances of any model you have installed.
The contenttypes framework is included in the default :setting:`INSTALLED_APPS` list created by django-admin.py startproject, but if you’ve removed it or if you manually set up your :setting:`INSTALLED_APPS` list, you can enable it by adding 'django.contrib.contenttypes' to your :setting:`INSTALLED_APPS` setting.
It’s generally a good idea to have the contenttypes framework installed; several of Django’s other bundled applications require it:
- The admin application uses it to log the history of each object added or changed through the admin interface.
- Django’s authentication framework uses it to tie user permissions to specific models.
- Django’s comments system (django.contrib.comments) uses it to “attach” comments to any installed model.
Each instance of ContentType has three fields which, taken together, uniquely describe an installed model:
Let’s look at an example to see how this works. If you already have the contenttypes application installed, and then add the sites application to your :setting:`INSTALLED_APPS` setting and run manage.py syncdb to install it, the model django.contrib.sites.models.Site will be installed into your database. Along with it a new instance of ContentType will be created with the following values:
Each ContentType instance has methods that allow you to get from a ContentType instance to the model it represents, or to retrieve objects from that model:
For example, we could look up the ContentType for the User model:
>>> from django.contrib.contenttypes.models import ContentType
>>> user_type = ContentType.objects.get(app_label="auth", model="user")
>>> user_type
<ContentType: user>
And then use it to query for a particular User, or to get access to the User model class:
>>> user_type.model_class()
<class 'django.contrib.auth.models.User'>
>>> user_type.get_object_for_this_type(username='Guido')
<User: Guido>
Together, get_object_for_this_type() and model_class() enable two extremely important use cases:
- Using these methods, you can write high-level generic code that performs queries on any installed model -- instead of importing and using a single specific model class, you can pass an app_label and model into a ContentType lookup at runtime, and then work with the model class or retrieve objects from it.
- You can relate another model to ContentType as a way of tying instances of it to particular model classes, and use these methods to get access to those model classes.
Several of Django's bundled applications make use of the latter technique. For example, the permissions system in Django's authentication framework uses a Permission model with a foreign key to ContentType; this lets Permission represent concepts like "can add blog entry" or "can delete news story".
ContentType also has a custom manager, ContentTypeManager, which adds the following methods:
The get_for_model() method is especially useful when you know you need to work with a ContentType but don't want to go to the trouble of obtaining the model's metadata to perform a manual lookup:
>>> from django.contrib.auth.models import User
>>> user_type = ContentType.objects.get_for_model(User)
>>> user_type
<ContentType: user>
Adding a foreign key from one of your own models to ContentType allows your model to effectively tie itself to another model class, as in the example of the Permission model above. But it's possible to go one step further and use ContentType to enable truly generic (sometimes called "polymorphic") relationships between models.
A simple example is a tagging system, which might look like this:
from django.db import models
from django.contrib.contenttypes.models import ContentType
from django.contrib.contenttypes import generic
class TaggedItem(models.Model):
tag = models.SlugField()
content_type = models.ForeignKey(ContentType)
object_id = models.PositiveIntegerField()
content_object = generic.GenericForeignKey('content_type', 'object_id')
def __unicode__(self):
return self.tag
A normal ForeignKey can only "point to" one other model, which means that if the TaggedItem model used a ForeignKey it would have to choose one and only one model to store tags for. The contenttypes application provides a special field type which works around this and allows the relationship to be with any model:
There are three parts to setting up a GenericForeignKey:
- Give your model a ForeignKey to ContentType.
- Give your model a field that can store primary key values from the models you'll be relating to. For most models, this means a PositiveIntegerField. The usual name for this field is "object_id".
- Give your model a GenericForeignKey, and pass it the names of the two fields described above. If these fields are named "content_type" and "object_id", you can omit this -- those are the default field names GenericForeignKey will look for.
Primary key type compatibility
The "object_id" field doesn't have to be the same type as the primary key fields on the related models, but their primary key values must be coercible to the same type as the "object_id" field by its get_db_prep_value() method.
For example, if you want to allow generic relations to models with either IntegerField or CharField primary key fields, you can use CharField for the "object_id" field on your model since integers can be coerced to strings by get_db_prep_value().
For maximum flexibility you can use a TextField which doesn't have a maximum length defined, however this may incur significant performance penalties depending on your database backend.
There is no one-size-fits-all solution for which field type is best. You should evaluate the models you expect to be pointing to and determine which solution will be most effective for your use case.
This will enable an API similar to the one used for a normal ForeignKey; each TaggedItem will have a content_object field that returns the object it's related to, and you can also assign to that field or use it when creating a TaggedItem:
>>> from django.contrib.auth.models import User
>>> guido = User.objects.get(username='Guido')
>>> t = TaggedItem(content_object=guido, tag='bdfl')
>>> t.save()
>>> t.content_object
<User: Guido>
Due to the way GenericForeignKey is implemented, you cannot use such fields directly with filters (filter() and exclude(), for example) via the database API. Because a GenericForeignKey isn't a normal field objects, these examples will not work:
# This will fail
>>> TaggedItem.objects.filter(content_object=guido)
# This will also fail
>>> TaggedItem.objects.get(content_object=guido)
If you know which models you'll be using most often, you can also add a "reverse" generic relationship to enable an additional API. For example:
class Bookmark(models.Model):
url = models.URLField()
tags = generic.GenericRelation(TaggedItem)
Bookmark instances will each have a tags attribute, which can be used to retrieve their associated TaggedItems:
>>> b = Bookmark(url='http://www.djangoproject.com/')
>>> b.save()
>>> t1 = TaggedItem(content_object=b, tag='django')
>>> t1.save()
>>> t2 = TaggedItem(content_object=b, tag='python')
>>> t2.save()
>>> b.tags.all()
[<TaggedItem: django>, <TaggedItem: python>]
Just as GenericForeignKey accepts the names of the content-type and object-ID fields as arguments, so too does GenericRelation; if the model which has the generic foreign key is using non-default names for those fields, you must pass the names of the fields when setting up a GenericRelation to it. For example, if the TaggedItem model referred to above used fields named content_type_fk and object_primary_key to create its generic foreign key, then a GenericRelation back to it would need to be defined like so:
tags = generic.GenericRelation(TaggedItem,
content_type_field='content_type_fk',
object_id_field='object_primary_key')
Of course, if you don't add the reverse relationship, you can do the same types of lookups manually:
>>> b = Bookmark.objects.get(url='http://www.djangoproject.com/')
>>> bookmark_type = ContentType.objects.get_for_model(b)
>>> TaggedItem.objects.filter(content_type__pk=bookmark_type.id,
... object_id=b.id)
[<TaggedItem: django>, <TaggedItem: python>]
Note that if the model in a GenericRelation uses a non-default value for ct_field or fk_field in its GenericForeignKey (e.g. the django.contrib.comments app uses ct_field="object_pk"), you'll need to set content_type_field and/or object_id_field in the GenericRelation to match the ct_field and fk_field, respectively, in the GenericForeignKey:
comments = generic.GenericRelation(Comment, object_id_field="object_pk")
Note also, that if you delete an object that has a GenericRelation, any objects which have a GenericForeignKey pointing at it will be deleted as well. In the example above, this means that if a Bookmark object were deleted, any TaggedItem objects pointing at it would be deleted at the same time.
Unlike ForeignKey, GenericForeignKey does not accept an on_delete argument to customize this behavior; if desired, you can avoid the cascade-deletion simply by not using GenericRelation, and alternate behavior can be provided via the pre_delete signal.
Django's database aggregation API doesn't work with a GenericRelation. For example, you might be tempted to try something like:
Bookmark.objects.aggregate(Count('tags'))
This will not work correctly, however. The generic relation adds extra filters to the queryset to ensure the correct content type, but the aggregate() method doesn't take them into account. For now, if you need aggregates on generic relations, you'll need to calculate them without using the aggregation API.
The django.contrib.contenttypes.generic module provides GenericInlineFormSet, GenericTabularInline and GenericStackedInline (the last two are subclasses of GenericInlineModelAdmin). This enables the use of generic relations in forms and the admin. See the model formset and admin documentation for more information.
The GenericInlineModelAdmin class inherits all properties from an InlineModelAdmin class. However, it adds a couple of its own for working with the generic relation:
Mar 31, 2011