========================== The contenttypes framework ========================== .. module:: django.contrib.contenttypes :synopsis: Provides generic interface to installed models. Django includes a :mod:`~django.contrib.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. Overview ======== At the heart of the contenttypes application is the :class:`~django.contrib.contenttypes.models.ContentType` model, which lives at ``django.contrib.contenttypes.models.ContentType``. Instances of :class:`~django.contrib.contenttypes.models.ContentType` represent and store information about the models installed in your project, and new instances of :class:`~django.contrib.contenttypes.models.ContentType` are automatically created whenever new models are installed. Instances of :class:`~django.contrib.contenttypes.models.ContentType` have methods for returning the model classes they represent and for querying objects from those models. :class:`~django.contrib.contenttypes.models.ContentType` also has a :ref:`custom manager ` that adds methods for working with :class:`~django.contrib.contenttypes.models.ContentType` and for obtaining instances of :class:`~django.contrib.contenttypes.models.ContentType` for a particular model. Relations between your models and :class:`~django.contrib.contenttypes.models.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. Installing the contenttypes framework ===================================== 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 :mod:`authentication framework ` uses it to tie user permissions to specific models. * Django's comments system (:mod:`django.contrib.comments`) uses it to "attach" comments to any installed model. .. currentmodule:: django.contrib.contenttypes.models The ``ContentType`` model ========================= .. class:: ContentType Each instance of :class:`~django.contrib.contenttypes.models.ContentType` has three fields which, taken together, uniquely describe an installed model: .. attribute:: app_label The name of the application the model is part of. This is taken from the :attr:`app_label` attribute of the model, and includes only the *last* part of the application's Python import path; "django.contrib.contenttypes", for example, becomes an :attr:`app_label` of "contenttypes". .. attribute:: model The name of the model class. .. attribute:: name The human-readable name of the model. This is taken from the :attr:`verbose_name ` attribute of the model. Let's look at an example to see how this works. If you already have the :mod:`~django.contrib.contenttypes` application installed, and then add :mod:`the sites application ` to your :setting:`INSTALLED_APPS` setting and run ``manage.py syncdb`` to install it, the model :class:`django.contrib.sites.models.Site` will be installed into your database. Along with it a new instance of :class:`~django.contrib.contenttypes.models.ContentType` will be created with the following values: * :attr:`~django.contrib.contenttypes.models.ContentType.app_label` will be set to ``'sites'`` (the last part of the Python path "django.contrib.sites"). * :attr:`~django.contrib.contenttypes.models.ContentType.model` will be set to ``'site'``. * :attr:`~django.contrib.contenttypes.models.ContentType.name` will be set to ``'site'``. .. _the verbose_name attribute: ../model-api/#verbose_name Methods on ``ContentType`` instances ==================================== Each :class:`~django.contrib.contenttypes.models.ContentType` instance has methods that allow you to get from a :class:`~django.contrib.contenttypes.models.ContentType` instance to the model it represents, or to retrieve objects from that model: .. method:: ContentType.get_object_for_this_type(**kwargs) Takes a set of valid :ref:`lookup arguments ` for the model the :class:`~django.contrib.contenttypes.models.ContentType` represents, and does :meth:`a get() lookup ` on that model, returning the corresponding object. .. method:: ContentType.model_class() Returns the model class represented by this :class:`~django.contrib.contenttypes.models.ContentType` instance. For example, we could look up the :class:`~django.contrib.contenttypes.models.ContentType` for the :class:`~django.contrib.auth.models.User` model:: >>> from django.contrib.contenttypes.models import ContentType >>> user_type = ContentType.objects.get(app_label="auth", model="user") >>> user_type And then use it to query for a particular :class:`~django.contrib.auth.models.User`, or to get access to the ``User`` model class:: >>> user_type.model_class() >>> user_type.get_object_for_this_type(username='Guido') Together, :meth:`~django.contrib.contenttypes.models.ContentType.get_object_for_this_type` and :meth:`~django.contrib.contenttypes.models.ContentType.model_class` enable two extremely important use cases: 1. 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 :class:`~django.contrib.contenttypes.models.ContentType` lookup at runtime, and then work with the model class or retrieve objects from it. 2. You can relate another model to :class:`~django.contrib.contenttypes.models.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, :class:`the permissions system ` in Django's authentication framework uses a :class:`~django.contrib.auth.models.Permission` model with a foreign key to :class:`~django.contrib.contenttypes.models.ContentType`; this lets :class:`~django.contrib.auth.models.Permission` represent concepts like "can add blog entry" or "can delete news story". The ``ContentTypeManager`` -------------------------- .. class:: ContentTypeManager :class:`~django.contrib.contenttypes.models.ContentType` also has a custom manager, :class:`~django.contrib.contenttypes.models.ContentTypeManager`, which adds the following methods: .. method:: clear_cache() Clears an internal cache used by :class:`~django.contrib.contenttypes.models.ContentType` to keep track of models for which it has created :class:`~django.contrib.contenttypes.models.ContentType` instances. You probably won't ever need to call this method yourself; Django will call it automatically when it's needed. .. method:: get_for_id(id) Lookup a :class:`~django.contrib.contenttypes.models.ContentType` by ID. Since this method uses the same shared cache as :meth:`~django.contrib.contenttypes.models.ContentTypeManager.get_for_model`, it's preferred to use this method over the usual ``ContentType.objects.get(pk=id)`` .. method:: get_for_model(model[, for_concrete_model=True]) Takes either a model class or an instance of a model, and returns the :class:`~django.contrib.contenttypes.models.ContentType` instance representing that model. .. method:: get_for_models(*models[, for_concrete_models=True]) Takes a variadic number of model classes, and returns a dictionary mapping the model classes to the :class:`~django.contrib.contenttypes.models.ContentType` instances representing them. .. method:: get_by_natural_key(app_label, model) Returns the :class:`~django.contrib.contenttypes.models.ContentType` instance uniquely identified by the given application label and model name. The primary purpose of this method is to allow :class:`~django.contrib.contenttypes.models.ContentType` objects to be referenced via a :ref:`natural key` during deserialization. The :meth:`~ContentTypeManager.get_for_model()` method is especially useful when you know you need to work with a :class:`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 .. module:: django.contrib.contenttypes.generic .. _generic-relations: .. versionadded:: 1.5 Prior to Django 1.5, :meth:`~django.contrib.contenttypes.models.ContentTypeManager.get_for_model` and :meth:`~django.contrib.contenttypes.models.ContentTypeManager.get_for_models` always returned the :class:`~django.contrib.contenttypes.models.ContentType` associated with the concrete model of the specified one(s). That means there was no way to retrieve the :class:`~django.contrib.contenttypes.models.ContentType` of a proxy model using those methods. As of Django 1.5 you can now pass a boolean flag – ``for_concrete_model`` and ``for_concrete_models`` respectively – to specify wether or not you want to retrieve the :class:`~django.contrib.contenttypes.models.ContentType` for the concrete or direct model. Generic relations ================= Adding a foreign key from one of your own models to :class:`~django.contrib.contenttypes.models.ContentType` allows your model to effectively tie itself to another model class, as in the example of the :class:`~django.contrib.auth.models.Permission` model above. But it's possible to go one step further and use :class:`~django.contrib.contenttypes.models.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 :class:`~django.db.models.ForeignKey` can only "point to" one other model, which means that if the ``TaggedItem`` model used a :class:`~django.db.models.ForeignKey` it would have to choose one and only one model to store tags for. The contenttypes application provides a special field type (``GenericForeignKey``) which works around this and allows the relationship to be with any model: .. class:: GenericForeignKey There are three parts to setting up a :class:`~django.contrib.contenttypes.generic.GenericForeignKey`: 1. Give your model a :class:`~django.db.models.ForeignKey` to :class:`~django.contrib.contenttypes.models.ContentType`. The usual name for this field is "content_type". 2. 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 :class:`~django.db.models.PositiveIntegerField`. The usual name for this field is "object_id". 3. Give your model a :class:`~django.contrib.contenttypes.generic.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 :class:`~django.contrib.contenttypes.generic.GenericForeignKey` will look for. .. admonition:: 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 :meth:`~django.db.models.Field.get_db_prep_value` method. For example, if you want to allow generic relations to models with either :class:`~django.db.models.IntegerField` or :class:`~django.db.models.CharField` primary key fields, you can use :class:`~django.db.models.CharField` for the "object_id" field on your model since integers can be coerced to strings by :meth:`~django.db.models.Field.get_db_prep_value`. For maximum flexibility you can use a :class:`~django.db.models.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. .. admonition:: Serializing references to ``ContentType`` objects If you're serializing data (for example, when generating :class:`~django.test.TestCase.fixtures`) from a model that implements generic relations, you should probably be using a natural key to uniquely identify related :class:`~django.contrib.contenttypes.models.ContentType` objects. See :ref:`natural keys` and :djadminopt:`dumpdata --natural <--natural>` for more information. This will enable an API similar to the one used for a normal :class:`~django.db.models.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 Due to the way :class:`~django.contrib.contenttypes.generic.GenericForeignKey` is implemented, you cannot use such fields directly with filters (``filter()`` and ``exclude()``, for example) via the database API. Because a :class:`~django.contrib.contenttypes.generic.GenericForeignKey` isn't a normal field object, these examples will *not* work:: # This will fail >>> TaggedItem.objects.filter(content_object=guido) # This will also fail >>> TaggedItem.objects.get(content_object=guido) Likewise, :class:`~django.contrib.contenttypes.generic.GenericForeignKey`\s does not appear in :class:`~django.forms.ModelForm`\s. Reverse generic relations ------------------------- .. class:: GenericRelation 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='https://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() [, ] Just as :class:`~django.contrib.contenttypes.generic.GenericForeignKey` accepts the names of the content-type and object-ID fields as arguments, so too does :class:`~django.contrib.contenttypes.generic.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 :class:`.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 :class:`.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='https://www.djangoproject.com/') >>> bookmark_type = ContentType.objects.get_for_model(b) >>> TaggedItem.objects.filter(content_type__pk=bookmark_type.id, ... object_id=b.id) [, ] Note that if the model in a :class:`~django.contrib.contenttypes.generic.GenericRelation` uses a non-default value for ``ct_field`` or ``fk_field`` in its :class:`~django.contrib.contenttypes.generic.GenericForeignKey` (e.g. the :mod:`django.contrib.comments` app uses ``ct_field="object_pk"``), you'll need to set ``content_type_field`` and/or ``object_id_field`` in the :class:`~django.contrib.contenttypes.generic.GenericRelation` to match the ``ct_field`` and ``fk_field``, respectively, in the :class:`~django.contrib.contenttypes.generic.GenericForeignKey`:: comments = generic.GenericRelation(Comment, object_id_field="object_pk") Note also, that if you delete an object that has a :class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects which have a :class:`~django.contrib.contenttypes.generic.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 :class:`~django.db.models.ForeignKey`, :class:`~django.contrib.contenttypes.generic.GenericForeignKey` does not accept an :attr:`~django.db.models.ForeignKey.on_delete` argument to customize this behavior; if desired, you can avoid the cascade-deletion simply by not using :class:`~django.contrib.contenttypes.generic.GenericRelation`, and alternate behavior can be provided via the :data:`~django.db.models.signals.pre_delete` signal. Generic relations and aggregation --------------------------------- :doc:`Django's database aggregation API ` doesn't work with a :class:`~django.contrib.contenttypes.generic.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 :meth:`~django.db.models.query.QuerySet.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. Generic relations in forms and admin ------------------------------------ The :mod:`django.contrib.contenttypes.generic` module provides: * ``BaseGenericInlineFormSet`` * :class:`~django.contrib.contenttypes.generic.GenericTabularInline` and :class:`~django.contrib.contenttypes.generic.GenericStackedInline` (subclasses of :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`) * A formset factory, :func:`generic_inlineformset_factory`, for use with :class:`GenericForeignKey` These classes and functions enable the use of generic relations in forms and the admin. See the :doc:`model formset ` and :ref:`admin ` documentation for more information. .. class:: GenericInlineModelAdmin The :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin` class inherits all properties from an :class:`~django.contrib.admin.InlineModelAdmin` class. However, it adds a couple of its own for working with the generic relation: .. attribute:: ct_field The name of the :class:`~django.contrib.contenttypes.models.ContentType` foreign key field on the model. Defaults to ``content_type``. .. attribute:: ct_fk_field The name of the integer field that represents the ID of the related object. Defaults to ``object_id``. .. class:: GenericTabularInline .. class:: GenericStackedInline Subclasses of :class:`GenericInlineModelAdmin` with stacked and tabular layouts, respectively. .. function:: generic_inlineformset_factory(model, form=ModelForm, formset=BaseGenericInlineFormSet, ct_field="content_type", fk_field="object_id", fields=None, exclude=None, extra=3, can_order=False, can_delete=True, max_num=None, formfield_callback=None) Returns a ``GenericInlineFormSet`` using :func:`~django.forms.models.modelformset_factory`. You must provide ``ct_field`` and ``fk_field`` if they are different from the defaults, ``content_type`` and ``object_id`` respectively. Other parameters are similar to those documented in :func:`~django.forms.models.modelformset_factory` and :func:`~django.forms.models.inlineformset_factory`.