From ed72ca3aba4dce3cb824602b3d22cc6a1db7d320 Mon Sep 17 00:00:00 2001
From: Carl Meyer <carl@dirtcircle.com>
Date: Thu, 2 Jul 2009 14:13:42 -0400
Subject: [PATCH] docs

--HG--
extra : convert_revision : carl%40dirtcircle.com-20090702181342-2w81id5wu333dfsa
---
 README.txt | 25 +++++++++++++++++++++++++
 TODO.txt   |  2 ++
 2 files changed, 27 insertions(+)

diff --git a/README.txt b/README.txt
index 76264cd..4ad0d5a 100644
--- a/README.txt
+++ b/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.
diff --git a/TODO.txt b/TODO.txt
index 9378f11..abe2db7 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -1,3 +1,5 @@
 TODO list for django-model-utils
 ================================
 
+* Custom QuerySet subclass to pair with InheritanceCastModel for more
+  efficient querying.