docs

--HG--
extra : convert_revision : carl%40dirtcircle.com-20090702181342-2w81id5wu333dfsa

README.txt

@@ -4,3 +4,28 @@ django-model-utils
 
 Django model mixins and utilities.
 
+InheritanceCastModel
+====================
+
+This abstract base class can be inherited by the root (parent) model
+in a model-inheritance tree.  It allows each model in the tree to
+"know" what type it is (via an automatically-set foreign key to
+``ContentType``), allowing for automatic casting of a parent instance
+to its proper leaf (child) type.
+
+For instance, if you have a ``Place`` model with subclasses
+``Restaurant`` and ``Bar``, you may want to query all Places::
+
+    nearby_places = Place.objects.filter(location='here')
+
+But when you iterate over ``nearby_places``, you'll get only ``Place``
+instances back, even for objects that are "really" ``Restaurant`` or
+``Bar``.  If you have ``Place`` inherit from ``InheritanceCastModel``,
+you can just call the ``cast()`` method on each ``Place`` and it will
+return an instance of the proper subtype, ``Restaurant`` or ``Bar``.
+
+.. note:: 
+    This is inefficient for large querysets, as it results in n
+    queries to the subtype tables.  It would be possible to write a
+    QuerySet subclass that could reduce this to k queries, where there
+    are k subtypes in the inheritance tree.

TODO.txt

@@ -1,3 +1,5 @@
 TODO list for django-model-utils
 ================================
 
+* Custom QuerySet subclass to pair with InheritanceCastModel for more
+  efficient querying.