If you work with Django's model inheritance, django_polymorphic might save you from implementing unpleasant workarounds that make your code messy, error-prone, and slow. Model inheritance becomes much more "pythonic" and now just works as you as a Python programmer expect.
Let's assume the models ArtProject and ResearchProject are derived from the model Project, and let's store one of each into the database:
>>> Project.objects.create(topic="John's Gathering") >>> ArtProject.objects.create(topic="Sculpting with Tim", artist="T. Turner") >>> ResearchProject.objects.create(topic="Swallow Aerodynamics", supervisor="Dr. Winter")
If we want to retrieve all our projects, we do:
>>> Project.objects.all()
Using django_polymorphic, we simply get what we stored:
[ <Project: id 1, topic: "John's Gathering">, <ArtProject: id 2, topic: "Sculpting with Tim", artist: "T. Turner">, <ResearchProject: id 3, topic: "Swallow Aerodynamics", supervisor: "Dr. Winter"> ]
Using vanilla Django, we get incomplete objects, which is probably not what we wanted:
[ <Project: id 1, topic: "John's Gathering">, <Project: id 2, topic: "Sculpting with Tim">, <Project: id 3, topic: "Swallow Aerodynamics"> ]
It's very similar for ForeignKeys, ManyToManyFields or OneToOneFields.
In general, the effect of django_polymorphic is twofold:
On one hand it makes sure that model inheritance just works as you expect, by simply ensuring that you always get back exactly the same objects from the database you stored there - regardless how you access them. This can save you a lot of unpleasant workarounds.
On the other hand, together with only few small API additions to the Django ORM, django_polymorphic enables a much more expressive and intuitive programming style and also very advanced object oriented designs that are not possible with vanilla Django.
Fortunately, most of the heavy duty machinery that is needed for this functionality is already present in the original Django database layer. Django_polymorphic merely adds a rather thin layer above that, which is all that is required to make real OO fully automatic and very easy to use, with only minimal additions to Django's API.
For more information, please look at Quickstart or the complete Installation and Usage Docs. Please also see the restrictions and caveats.
This release is mostly a cleanup and maintenance release that also improves a number of minor things and fixes one (non-critical) bug.
Some pending API changes and corrections have been folded into this release in order to make the upcoming V1.0 API as stable as possible.
This release is also about getting feedback from you in case you don't approve of any of these changes or would like to get additional API fixes into V1.0.
The release contains a considerable amount of changes in some of the more critical parts of the software. It's intended for testing and development environments and not for production environments. For these, it's best to wait a few weeks for the proper V1.0 release, to allow some time for any potential problems to turn up (if they exist).
If you encounter any problems please post them in the discussion group or open an issue on GitHub or BitBucket (or send me an email).
Django_polymorphic uses the same license as Django (BSD-like).
The polymorphic_dumpdata management command is not needed anymore and has been removed, as the regular Django dumpdata command now automatically works correctly with polymorphic models (for all supported versions of Django).
In order to improve compatibility with vanilla Django, printing quersets does not use django_polymorphic's pretty printing by default anymore. To get the old behaviour when printing querysets, you need to replace your model definition:
>>> class Project(PolymorphicModel):
by:
>>> class Project(PolymorphicModel, ShowFieldType):
The mixin classes for pretty output have been renamed:
ShowFieldTypes, ShowFields, ShowFieldsAndTypes
are now:
ShowFieldType, ShowFieldContent and ShowFieldTypeAndContent
(the old ones still exist for compatibility)
Django 1.3 requires python manage.py test polymorphic instead of just python manage.py test.
The django_polymorphic source code has been restructured and as a result needs to be installed like a normal Django App - either via copying the "polymorphic" directory into your Django project or by running setup.py. Adding 'polymorphic' to INSTALLED_APPS in settings.py is still optional, however.
The file polymorphic.py cannot be used as a standalone extension module anymore (as is has been split into a number of smaller files).
Importing works slightly different now: All relevant symbols are imported directly from 'polymorphic' instead from 'polymorphic.models':
# new way from polymorphic import PolymorphicModel, ... # old way, doesn't work anymore from polymorphic.models import PolymorphicModel, ...