Advanced Features

In the examples below, these models are being used:

from django.db import models
from polymorphic.models import PolymorphicModel

class ModelA(PolymorphicModel):
    field1 = models.CharField(max_length=10)

class ModelB(ModelA):
    field2 = models.CharField(max_length=10)

class ModelC(ModelB):
    field3 = models.CharField(max_length=10)

Filtering for classes (equivalent to python’s isinstance()):

>>> ModelA.objects.instance_of(ModelB)
[ <ModelB: id 2, field1 (CharField), field2 (CharField)>,
  <ModelC: id 3, field1 (CharField), field2 (CharField), field3 (CharField)> ]

In general, including or excluding parts of the inheritance tree:

ModelA.objects.instance_of(ModelB [, ModelC ...])
ModelA.objects.not_instance_of(ModelB [, ModelC ...])

You can also use this feature in Q-objects (with the same result as above):

>>> ModelA.objects.filter( Q(instance_of=ModelB) )

Polymorphic filtering (for fields in inherited classes)

For example, cherry-picking objects from multiple derived classes anywhere in the inheritance tree, using Q objects (with the syntax: exact model name + three _ + field name):

>>> ModelA.objects.filter(  Q(ModelB___field2 = 'B2') | Q(ModelC___field3 = 'C3')  )
[ <ModelB: id 2, field1 (CharField), field2 (CharField)>,
  <ModelC: id 3, field1 (CharField), field2 (CharField), field3 (CharField)> ]

Combining Querysets

Querysets could now be regarded as object containers that allow the aggregation of different object types, very similar to python lists - as long as the objects are accessed through the manager of a common base class:

>>> Base.objects.instance_of(ModelX) | Base.objects.instance_of(ModelY)

[ <ModelX: id 1, field_x (CharField)>,
  <ModelY: id 2, field_y (CharField)> ]

ManyToManyField, ForeignKey, OneToOneField

Relationship fields referring to polymorphic models work as expected: like polymorphic querysets they now always return the referred objects with the same type/class these were created and saved as.

E.g., if in your model you define:

field1 = OneToOneField(ModelA)

then field1 may now also refer to objects of type ModelB or ModelC.

A ManyToManyField example:

# The model holding the relation may be any kind of model, polymorphic or not
class RelatingModel(models.Model):

    # ManyToMany relation to a polymorphic model
    many2many = models.ManyToManyField('ModelA')

>>> o=RelatingModel.objects.create()
>>> o.many2many.add(ModelA.objects.get(id=1))
>>> o.many2many.add(ModelB.objects.get(id=2))
>>> o.many2many.add(ModelC.objects.get(id=3))

>>> o.many2many.all()
[ <ModelA: id 1, field1 (CharField)>,
  <ModelB: id 2, field1 (CharField), field2 (CharField)>,
  <ModelC: id 3, field1 (CharField), field2 (CharField), field3 (CharField)> ]

Copying Polymorphic objects

Copying polymorphic models is no different than copying regular multi-table models. You have two options:

  1. Use create() and provide all field values from the original instance except the primary key(s).

  2. Set the primary key attribute, and parent table pointers at all levels of inheritance to None and call save().

The Django documentation offers some discussion on copying, including the complexity around related fields and multi-table inheritance. django-polymorphic offers a utility function prepare_for_copy() that resets all necessary fields on a model instance to prepare it for copying:

from polymorphic.utils import prepare_for_copy

obj = ModelB.objects.first()
prepare_for_copy(obj)
obj.save()
# obj is now a copy of the original ModelB instance

Working with Fixtures

Polymorphic models work with Django’s dumpdata and loaddata commands just as regular models do. There are two important considerations:

  1. Polymorphic models are multi-table models and dumpdata serializes each table separately. django-polymorphic does it’s best to ensure non-polymorphic managers are used when creating fixtures but there may be edge cases where this fails. If you override dumpdata you must make sure any polymorphic managers encountered toggle polymorphism off. Other usual multi-table model caveats apply. If you serialize a subset of tables in the model inheritance you may generate corrupt data or “upcast” your models if child tables were omitted.

  2. Polymorphic models rely on the ContentType framework. When serializing and deserializing polymorphic models, the polymorphic_ctype field must be handled correctly. If there is any question about if the content type primary keys are or will be different between the source and target database you should use the --natural-foreign flag to serialize those relations by-value. Polymorphism introduces no special consideration here - any model using contenttypes, polymorphic or not, must handle this correctly.

Note

Prior documentation urged users to use both --natural-primary and --natural-foreign flags when dumping polymorphic models. This is not necessary and only needs to be done when the primary keys are not guaranteed to match or be available at the target database.

Loading Fixtures (loaddata)

Fixtures should be loadable as normal with loaddata. However, if there are problems with the polymorphic_ctype references, you may fix them using reset_polymorphic_ctype():

from polymorphic.utils import reset_polymorphic_ctype
from myapp.models import Animal, Dog, Cat

# Reset polymorphic_ctype for all models in the inheritance tree
reset_polymorphic_ctype(Animal, Dog, Cat)

Using Third Party Models (without modifying them)

Third party models can be used as polymorphic models without restrictions by subclassing them. E.g. using a third party model as the root of a polymorphic inheritance tree:

from thirdparty import ThirdPartyModel

class MyThirdPartyBaseModel(PolymorphicModel, ThirdPartyModel):
    pass    # or add fields

Or instead integrating the third party model anywhere into an existing polymorphic inheritance tree:

class MyBaseModel(SomePolymorphicModel):
    my_field = models.CharField(max_length=10)

class MyModelWithThirdParty(MyBaseModel, ThirdPartyModel):
    pass    # or add fields

Non-Polymorphic Queries

If you insert non_polymorphic() anywhere into the query chain, then django-polymorphic will simply leave out the final step of retrieving the real objects, and the manager/queryset will return objects of the type of the base class you used for the query, like vanilla Django would (ModelA in this example).

>>> qs=ModelA.objects.non_polymorphic().all()
>>> qs
[ <ModelA: id 1, field1 (CharField)>,
  <ModelA: id 2, field1 (CharField)>,
  <ModelA: id 3, field1 (CharField)> ]

There are no other changes in the behaviour of the queryset. For example, enhancements for filter() or instance_of() etc. still work as expected. If you do the final step yourself, you get the usual polymorphic result:

>>> ModelA.objects.get_real_instances(qs)
[ <ModelA: id 1, field1 (CharField)>,
  <ModelB: id 2, field1 (CharField), field2 (CharField)>,
  <ModelC: id 3, field1 (CharField), field2 (CharField), field3 (CharField)> ]

About Queryset Methods

  • annotate() and aggregate() work just as usual, with the addition that the ModelX___field syntax can be used for the keyword arguments (but not for the non-keyword arguments).

  • order_by() similarly supports the ModelX___field syntax for specifying ordering through a field in a submodel.

  • distinct() works as expected. It only regards the fields of the base class, but this should never make a difference.

  • select_related() works just as usual, but it can not (yet) be used to select relations in inherited models (like ModelA.objects.select_related('ModelC___fieldxy') )

  • extra() works as expected (it returns polymorphic results) but currently has one restriction: The resulting objects are required to have a unique primary key within the result set - otherwise an error is thrown (this case could be made to work, however it may be mostly unneeded).. The keyword-argument “polymorphic” is no longer supported. You can get back the old non-polymorphic behaviour by using ModelA.objects.non_polymorphic().extra(...).

  • get_real_instances() allows you to turn a queryset or list of base model objects efficiently into the real objects. For example, you could do base_objects_queryset=ModelA.extra(...).non_polymorphic() and then call real_objects=base_objects_queryset.get_real_instances(). Or alternatively real_objects=ModelA.objects.get_real_instances(base_objects_queryset_or_object_list)

  • values() & values_list() currently do not return polymorphic results. This may change in the future however. If you want to use these methods now, it’s best if you use Model.base_objects.values... as this is guaranteed to not change.

  • defer() and only() work as expected. On Django 1.5+ they support the ModelX___field syntax, but on Django 1.4 it is only possible to pass fields on the base model into these methods.

Using enhanced Q-objects in any Places

The queryset enhancements (e.g. instance_of()) only work as arguments to the member functions of a polymorphic queryset. Occasionally it may be useful to be able to use Q objects with these enhancements in other places. As Django doesn’t understand these enhanced Q objects, you need to transform them manually into normal Q objects before you can feed them to a Django queryset or function:

normal_q_object = ModelA.translate_polymorphic_Q_object( Q(instance_of=Model2B) )

This function cannot be used at model creation time however (in models.py), as it may need to access the ContentTypes database table.

Nicely Displaying Polymorphic Querysets

In order to get the output as seen in all examples here, you need to use the ShowFieldType class mixin:

from polymorphic.models import PolymorphicModel
from polymorphic.showfields import ShowFieldType

class ModelA(ShowFieldType, PolymorphicModel):
    field1 = models.CharField(max_length=10)

You may also use ShowFieldContent or ShowFieldTypeAndContent to display additional information when printing querysets (or converting them to text).

When showing field contents, they will be truncated to 20 characters. You can modify this behavior by setting a class variable in your model like this:

class ModelA(ShowFieldType, PolymorphicModel):
    polymorphic_showfield_max_field_width = 20
    ...

Similarly, pre-V1.0 output formatting can be re-estated by using polymorphic_showfield_old_format = True.

Create Children from Parents (Downcasting)

You can create an instance of a subclass from an existing instance of a superclass using the create_from_super() method of the subclass’s manager. For example:

super_instance = ModelA.objects.get(id=1)
sub_instance = ModelB.objects.create_from_super(super_instance, field2='value2')

The restriction is that super_instance must be an instance of the direct superclass of ModelB, and any required fields of ModelB must be provided as keyword arguments. If multiple levels of subclassing are involved, you must call this method multiple times to “promote” each level.

Delete Children, Leaving Parents (Upcasting)

The reverse operation of create_from_super() is to delete the subclass instance while keeping the superclass instance. This can be done using the keep_parents=True argument to delete(). django-polymorphic ensures that the polymorphic_ctype fields of the superclass instances are updated accordingly when doing this.

Restrictions & Caveats

  • Database Performance regarding concrete Model inheritance in general. Please see Performance Considerations.

  • Queryset methods values(), values_list(), and select_related() are not yet fully supported (see above). extra() has one restriction: the resulting objects are required to have a unique primary key within the result set.

  • Diamond shaped inheritance: There seems to be a general problem with diamond shaped multiple model inheritance with Django models (tested with V1.1 - V1.3). An example is here. This problem is aggravated when trying to enhance Model by subclassing it instead of modifying Django core (as we do here with PolymorphicModel).

  • The enhanced filter-definitions/Q-objects only work as arguments for the methods of the polymorphic querysets. Please see above for translate_polymorphic_Q_object.

  • When using the dumpdata management command on polymorphic tables (or any table that has a reference to ContentType), include the --natural-primary and --natural-foreign flags in the arguments.

  • If the polymorphic_ctype_id on the base table points to the wrong ContentType (this can happen if you delete child rows manually with raw SQL, DELETE FROM table), then polymorphic queries will elide the corresponding model objects:

    • BaseClass.objects.all() will exclude these rows (it filters for existing child types).

    • BaseClass.objects.non_polymorphic().all() will behave as normal - but polymorphic behavior for the affected rows will be undefined - for instance, get_real_instances() will raise an exception.

    Always use instance.delete() or QuerySet.delete() to ensure cascading deletion of the base row. If you must delete manually, ensure you also delete the corresponding row from the base table.