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, cherrypicking objects from multiple derived classes
anywhere in the inheritance tree, using Q objects (with the
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)> ]
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
A ManyToManyField example:
# The model holding the relation may be any kind of model, polymorphic or not class RelatingModel(models.Model): many2many = models.ManyToManyField('ModelA') # ManyToMany relation to a polymorphic model >>> 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)> ]
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
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,
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¶
aggregate()work just as usual, with the addition that the
ModelX___fieldsyntax can be used for the keyword arguments (but not for the non-keyword arguments).
order_by()similarly supports the
ModelX___fieldsyntax 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
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
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_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.
only()work as expected. On Django 1.5+ they support the
ModelX___fieldsyntax, 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.showfields import PolymorphicModel, ShowFieldType class ModelA(ShowFieldType, PolymorphicModel): field1 = models.CharField(max_length=10)
You may also use
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 behaviour 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.
Restrictions & Caveats¶
- Database Performance regarding concrete Model inheritance in general. Please see the Performance Considerations.
- Queryset methods
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: http://code.djangoproject.com/ticket/10808. This problem is aggravated when trying to enhance models.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
- When using the
dumpdatamanagement command on polymorphic tables (or any table that has a reference to
ContentType), include the
--naturalflag in the arguments.