The contenttypes framework | Django documentation (original) (raw)

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.

Overview

At the heart of the contenttypes application is theContentType model, which lives atdjango.contrib.contenttypes.models.ContentType. Instances ofContentType represent and store information about the models installed in your project, and new instances ofContentType 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. ContentTypealso has a custom manager that adds methods for working with ContentType and for obtaining instances of ContentTypefor a particular model.

Relations between your models andContentType 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 defaultINSTALLED_APPS list created by django-admin startproject, but if you’ve removed it or if you manually set up yourINSTALLED_APPS list, you can enable it by adding'django.contrib.contenttypes' to your 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 ContentType model

class ContentType[source]

Each instance of ContentTypehas two fields which, taken together, uniquely describe an installed model:

app_label

The name of the application the model is part of. This is taken from the 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 anapp_label of contenttypes.

model

The name of the model class.

Additionally, the following property is available:

name[source]

The human-readable name of the content type. This is taken from theverbose_nameattribute of the model.

Let’s look at an example to see how this works. If you already have the contenttypes application installed, and then addthe sites application to yourINSTALLED_APPS setting and run manage.py migrate to install it, the model django.contrib.sites.models.Site will be installed into your database. Along with it a new instance ofContentType will be created with the following values:

Methods on ContentType instances

Each ContentType instance has methods that allow you to get from aContentType instance to the model it represents, or to retrieve objects from that model:

ContentType.get_object_for_this_type(using=None, **kwargs)[source]

Takes a set of valid lookup arguments for the model the ContentTyperepresents, and doesa get() lookupon that model, returning the corresponding object. The using argument can be used to specify a different database than the default one.

Changed in Django 5.1:

The using argument was added.

ContentType.model_class()[source]

Returns the model class represented by thisContentType instance.

For example, we could look up theContentType for theUser 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 particularUser, 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:

  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 andmodel into aContentType lookup at runtime, and then work with the model class or retrieve objects from it.
  2. You can relate another model toContentType 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 aPermission model with a foreign key to ContentType; this letsPermission represent concepts like “can add blog entry” or “can delete news story”.

The ContentTypeManager

class ContentTypeManager[source]

ContentType also has a custom manager, ContentTypeManager, which adds the following methods:

clear_cache()[source]

Clears an internal cache used byContentType to keep track of models for which it has createdContentType instances. You probably won’t ever need to call this method yourself; Django will call it automatically when it’s needed.

get_for_id(id)[source]

Lookup a ContentType by ID. Since this method uses the same shared cache asget_for_model(), it’s preferred to use this method over the usualContentType.objects.get(pk=id)

get_for_model(model, for_concrete_model=True)[source]

Takes either a model class or an instance of a model, and returns theContentType instance representing that model. for_concrete_model=False allows fetching the ContentType of a proxy model.

get_for_models(*models, for_concrete_models=True)[source]

Takes a variadic number of model classes, and returns a dictionary mapping the model classes to theContentType instances representing them. for_concrete_models=False allows fetching theContentType of proxy models.

get_by_natural_key(app_label, model)[source]

Returns the ContentTypeinstance uniquely identified by the given application label and model name. The primary purpose of this method is to allowContentType objects to be referenced via a natural keyduring deserialization.

The get_for_model() method is especially useful when you know you need to work with aContentType 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 ContentType.objects.get_for_model(User) <ContentType: user>

Generic relations

Adding a foreign key from one of your own models toContentType allows your model to effectively tie itself to another model class, as in the example of thePermission model above. But it’s possible to go one step further and useContentType to enable truly generic (sometimes called “polymorphic”) relationships between models.

For example, it could be used for a tagging system like so:

from django.contrib.contenttypes.fields import GenericForeignKey from django.contrib.contenttypes.models import ContentType from django.db import models

class TaggedItem(models.Model): tag = models.SlugField() content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE) object_id = models.PositiveBigIntegerField() content_object = GenericForeignKey("content_type", "object_id")

def __str__(self):
    return self.tag

class Meta:
    indexes = [
        models.Index(fields=["content_type", "object_id"]),
    ]

A normal ForeignKey can only “point to” one other model, which means that if the TaggedItem model used aForeignKey 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[source]

There are three parts to setting up aGenericForeignKey:

  1. Give your model a ForeignKeyto 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 aPositiveBigIntegerField. The usual name for this field is “object_id”.
  3. Give your model aGenericForeignKey, 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 namesGenericForeignKey will look for.

Unlike for the ForeignKey, a database index is_not_ automatically created on theGenericForeignKey, so it’s recommended that you useMeta.indexes to add your own multiple column index. This behavior may change in the future.

for_concrete_model

If False, the field will be able to reference proxy models. Default is True. This mirrors the for_concrete_model argument toget_for_model().

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 itsget_db_prep_value() method.

For example, if you want to allow generic relations to models with eitherIntegerField orCharField 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 aTextField 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.

Serializing references to ContentType objects

If you’re serializing data (for example, when generatingfixtures) from a model that implements generic relations, you should probably be using a natural key to uniquely identify related ContentTypeobjects. See natural keys anddumpdata --natural-foreign for more information.

This will enable an API similar to the one used for a normalForeignKey; 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>

If the related object is deleted, the content_type and object_id fields remain set to their original values and the GenericForeignKey returnsNone:

guido.delete() t.content_object # returns None

Due to the way GenericForeignKeyis implemented, you cannot use such fields directly with filters (filter()and exclude(), for example) via the database API. Because aGenericForeignKey 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, GenericForeignKeys does not appear in ModelForms.

Reverse generic relations

class GenericRelation[source]

related_query_name

The relation on the related object back to this object doesn’t exist by default. Setting related_query_name creates a relation from the related object back to this one. This allows querying and filtering from the related object.

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:

from django.contrib.contenttypes.fields import GenericRelation from django.db import models

class Bookmark(models.Model): url = models.URLField() tags = 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() <QuerySet [<TaggedItem: django>, <TaggedItem: python>]>

You can also use add(), create(), or set() to create relationships:

t3 = TaggedItem(tag="Web development") b.tags.add(t3, bulk=False) b.tags.create(tag="Web framework") <TaggedItem: Web framework> b.tags.all() <QuerySet [<TaggedItem: django>, <TaggedItem: python>, <TaggedItem: Web development>, <TaggedItem: Web framework>]> b.tags.set([t1, t3]) b.tags.all() <QuerySet [<TaggedItem: django>, <TaggedItem: Web development>]>

The remove() call will bulk delete the specified model objects:

b.tags.remove(t3) b.tags.all() <QuerySet [<TaggedItem: django>]> TaggedItem.objects.all() <QuerySet [<TaggedItem: django>]>

The clear() method can be used to bulk delete all related objects for an instance:

b.tags.clear() b.tags.all() <QuerySet []> TaggedItem.objects.all() <QuerySet []>

Defining GenericRelation withrelated_query_name set allows querying from the related object:

tags = GenericRelation(TaggedItem, related_query_name="bookmark")

This enables filtering, ordering, and other query operations on Bookmarkfrom TaggedItem:

Get all tags belonging to bookmarks containing django in the url

TaggedItem.objects.filter(bookmark__url__contains="django") <QuerySet [<TaggedItem: django>, <TaggedItem: python>]>

If you don’t add the related_query_name, you can do the same types of lookups manually:

bookmarks = Bookmark.objects.filter(url__contains="django") bookmark_type = ContentType.objects.get_for_model(Bookmark) TaggedItem.objects.filter(content_type__pk=bookmark_type.id, object_id__in=bookmarks) <QuerySet [<TaggedItem: django>, <TaggedItem: python>]>

Just as GenericForeignKeyaccepts the names of the content-type and object-ID fields as arguments, so too doesGenericRelation; 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 aGenericRelation to it. For example, if the TaggedItem model referred to above used fields named content_type_fk andobject_primary_key to create its generic foreign key, then aGenericRelation back to it would need to be defined like so:

tags = GenericRelation( TaggedItem, content_type_field="content_type_fk", object_id_field="object_primary_key", )

Note also, that if you delete an object that has aGenericRelation, any objects which have a GenericForeignKeypointing 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 by not usingGenericRelation, and alternate behavior can be provided via the pre_deletesignal.

Generic relations and aggregation

Django’s database aggregation API works with aGenericRelation. For example, you can find out how many tags all the bookmarks have:

Bookmark.objects.aggregate(Count("tags")) {'tags__count': 3}

Generic relation in forms

The django.contrib.contenttypes.forms module provides:

class BaseGenericInlineFormSet[source]

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, validate_max=False, for_concrete_model=True, min_num=None, validate_min=False, absolute_max=None, can_delete_extra=True)[source]

Returns a GenericInlineFormSet usingmodelformset_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 inmodelformset_factory() andinlineformset_factory().

The for_concrete_model argument corresponds to thefor_concrete_modelargument on GenericForeignKey.

Generic relations in admin

The django.contrib.contenttypes.admin module providesGenericTabularInline andGenericStackedInline (subclasses ofGenericInlineModelAdmin)

These classes and functions enable the use of generic relations in forms and the admin. See the model formset andadmin documentation for more information.

class GenericInlineModelAdmin[source]

The GenericInlineModelAdminclass inherits all properties from anInlineModelAdmin class. However, it adds a couple of its own for working with the generic relation:

ct_field

The name of theContentType foreign key field on the model. Defaults to content_type.

ct_fk_field

The name of the integer field that represents the ID of the related object. Defaults to object_id.

class GenericTabularInline[source]

class GenericStackedInline[source]

Subclasses of GenericInlineModelAdmin with stacked and tabular layouts, respectively.

GenericPrefetch()

class GenericPrefetch(lookup, querysets, to_attr=None)[source]

This lookup is similar to Prefetch() and it should only be used onGenericForeignKey. The querysets argument accepts a list of querysets, each for a different ContentType. This is useful for GenericForeignKeywith non-homogeneous set of results.

from django.contrib.contenttypes.prefetch import GenericPrefetch bookmark = Bookmark.objects.create(url="https://www.djangoproject.com/") animal = Animal.objects.create(name="lion", weight=100) TaggedItem.objects.create(tag="great", content_object=bookmark) TaggedItem.objects.create(tag="awesome", content_object=animal) prefetch = GenericPrefetch( ... "content_object", [Bookmark.objects.all(), Animal.objects.only("name")] ... ) TaggedItem.objects.prefetch_related(prefetch).all() <QuerySet [<TaggedItem: Great>, <TaggedItem: Awesome>]>