model-api documentation should note model inheritance should not be used
|Reported by:||calvins||Owned by:||nobody|
|Severity:||Keywords:||documentation model inheritance|
|Has patch:||no||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
I was told in the IRC channel that model inheritance is known to be broken at the moment and is not supposed to work.
The primary documentation page, Django | Model reference | Django Documentation, does not note that it should not be used.
In the "basics" bullet points of that page, the first point is: "Each model is a Python class that subclasses django.db.models.Model." That would be the logical point to put a boldface warning that you can't extend any model types that extend models.Model and friends. You might want to link to IRCFAQ How do I extend a model? and/or Model Inheritance.
It would be nice too if django gave a warning (perhaps only at verbosity=2) when the user does this and tries to use either loaddata or dumpdata (or any other db-related manage.py functions), since a user that knows the model-api reasonably well might not check the documentation until they've spent a long time trying to figure out why some of their objects don't get serialized at all using dumpdata. In my case, I had a trivial sub-type of a model that I had defined (literally "class Archived_Item(Item): pass"), and spent a long time trying to figure out why just 1 object was not serialized using dumpdata, which caused problems when loaddata is run (where I originally thought the problem was).