/README.rst

  1Polymorphic Models for Django
  2=============================
  3
  4
  5Quick Start, Docs, Contributing
  6-------------------------------
  7
  8* `What is django_polymorphic good for?`_
  9* `Quickstart`_, or the complete `Installation and Usage Docs`_
 10* `Release Notes, News and Discussion`_ (Google Group) or Changelog_
 11* Download from GitHub_ or Bitbucket_, or as TGZ_ or ZIP_
 12* Improve django_polymorphic, report issues, discuss, patch or fork (GitHub_, Bitbucket_, Group_, Mail_)
 13
 14.. _What is django_polymorphic good for?: #good-for
 15.. _release notes, news and discussion: http://groups.google.de/group/django-polymorphic/topics
 16.. _Group: http://groups.google.de/group/django-polymorphic/topics
 17.. _Mail: http://github.com/bconstantin/django_polymorphic/tree/master/setup.py
 18.. _Installation and Usage Docs: http://bserve.webhop.org/django_polymorphic/DOCS.html
 19.. _Quickstart: http://bserve.webhop.org/django_polymorphic/DOCS.html#quickstart
 20.. _GitHub: http://github.com/bconstantin/django_polymorphic
 21.. _Bitbucket: http://bitbucket.org/bconstantin/django_polymorphic
 22.. _TGZ: http://github.com/bconstantin/django_polymorphic/tarball/master
 23.. _ZIP: http://github.com/bconstantin/django_polymorphic/zipball/master
 24.. _Overview: http://bserve.webhop.org/django_polymorphic
 25.. _Changelog: http://bserve.webhop.org/django_polymorphic/CHANGES.html
 26
 27.. _good-for:
 28
 29What is django_polymorphic good for?
 30------------------------------------
 31
 32Let's assume the models ``ArtProject`` and ``ResearchProject`` are derived
 33from the model ``Project``, and let's store one of each into the database:
 34
 35>>> Project.objects.create(topic="Department Party")
 36>>> ArtProject.objects.create(topic="Painting with Tim", artist="T. Turner")
 37>>> ResearchProject.objects.create(topic="Swallow Aerodynamics", supervisor="Dr. Winter")
 38
 39If we want to retrieve all our projects, we do:
 40
 41>>> Project.objects.all()
 42
 43Using django_polymorphic, we simply get what we stored::
 44
 45    [ <Project:         id 1, topic "Department Party">,
 46      <ArtProject:      id 2, topic "Painting with Tim", artist "T. Turner">,
 47      <ResearchProject: id 3, topic "Swallow Aerodynamics", supervisor "Dr. Winter"> ]
 48
 49Using vanilla Django, we get incomplete objects, which is probably not what we wanted::
 50
 51    [ <Project: id 1, topic "Department Party">,
 52      <Project: id 2, topic "Painting with Tim">,
 53      <Project: id 3, topic "Swallow Aerodynamics"> ]
 54
 55It's very similar for ForeignKeys, ManyToManyFields or OneToOneFields.
 56
 57In general, the effect of django_polymorphic is twofold:
 58
 59On one hand it makes sure that model inheritance just works as you
 60expect, by simply ensuring that you always get back exactly the same
 61objects from the database you stored there - regardless how you access
 62them, making model inheritance much more "pythonic".
 63This can save you a lot of unpleasant workarounds that tend to
 64make your code messy, error-prone, and slow.
 65
 66On the other hand, together with some small API additions to the Django
 67ORM, django_polymorphic enables a much more expressive and intuitive
 68programming style and also very advanced object oriented designs
 69that are not possible with vanilla Django.
 70
 71Fortunately, most of the heavy duty machinery that is needed for this
 72functionality is already present in the original Django database layer.
 73Django_polymorphic adds a rather thin layer above that in order
 74to make real OO fully automatic and very easy to use.
 75
 76There is a catch however, which applies to concrete model inheritance
 77in general: Current DBM systems like PostgreSQL or MySQL are not very
 78good at processing the required sql queries and can be rather slow in
 79many cases. Concrete benchmarks are forthcoming (please see
 80discussion forum).
 81
 82For more information, please look at `Quickstart`_ or at the complete
 83`Installation and Usage Docs`_ and also see the `restrictions and caveats`_.
 84
 85.. _restrictions and caveats: http://bserve.webhop.org/django_polymorphic/DOCS.html#restrictions
 86
 87
 88This is a V1.0 Beta/Testing Release
 89-----------------------------------
 90
 91The release contains a considerable amount of changes in some of the more
 92critical parts of the software. It's intended for testing and development
 93environments and not for production environments. For these, it's best to
 94wait a few weeks for the proper V1.0 release, to allow some time for any
 95potential problems to turn up (if they exist).
 96
 97If you encounter any problems or have suggestions regarding the API or the
 98changes in this beta, please post them in the `discussion group`_
 99or open an issue on GitHub_ or BitBucket_ (or send me an email).
100
101.. _discussion group: http://groups.google.de/group/django-polymorphic/topics
102
103
104License
105=======
106
107Django_polymorphic uses the same license as Django (BSD-like).
108
109
110API Changes & Additions
111=======================
112
113
114November 11 2010, V1.0 API Changes
115-------------------------------------------------------------------
116
117extra() queryset method
118+++++++++++++++++++++++
119
120``.extra()`` has been re-implemented. Now it's polymorphic by
121default and works (nearly) without restrictions (please see docs). This is a (very)
122incompatible API change regarding previous versions of django_polymorphic.
123Support for the ``polymorphic`` keyword parameter has been removed.
124You can get back the non-polymorphic behaviour by using
125``ModelA.objects.non_polymorphic().extra()``.
126
127No Pretty-Printing of Querysets by default
128++++++++++++++++++++++++++++++++++++++++++
129
130In order to improve compatibility with vanilla Django, printing quersets
131(__repr__ and __unicode__) does not use django_polymorphic's pretty printing
132by default anymore. To get the old behaviour when printing querysets,
133you need to replace your model definition:
134
135>>> class Project(PolymorphicModel):
136
137by:
138
139>>> class Project(PolymorphicModel, ShowFieldType):
140
141The mixin classes for pretty output have been renamed:
142
143    ``ShowFieldTypes, ShowFields, ShowFieldsAndTypes``
144
145are now:
146
147    ``ShowFieldType, ShowFieldContent and ShowFieldTypeAndContent``
148
149(the old ones still exist for compatibility)
150
151Pretty-Printing Output Format Changed
152+++++++++++++++++++++++++++++++++++++
153
154``ShowFieldContent`` and ``ShowFieldTypeAndContent`` now
155use a slightly different output format. If this causes too much trouble for
156your test cases, you can get the old behaviour back (mostly) by adding
157``polymorphic_showfield_old_format = True`` to your model definitions.
158``ShowField...`` now also produces more informative output for custom
159primary keys.
160
161polymorphic_dumpdata
162++++++++++++++++++++
163
164The ``polymorphic_dumpdata`` management command is not needed anymore
165and has been disabled, as the regular Django dumpdata command now automatically
166works correctly with polymorphic models (for all supported versions of Django).
167
168Running the Test suite with Django 1.3
169++++++++++++++++++++++++++++++++++++++
170
171Django 1.3 requires ``python manage.py test polymorphic`` instead of
172just ``python manage.py test``.
173
174
175November 01 2010, V1.0 API Additions
176-------------------------------------------------------------------
177
178*   ``.non_polymorphic()`` queryset member function added. This is preferable to
179    using ``.base_objects...``, as it just makes the resulting queryset non-polymorphic
180    and does not change anything else in the behaviour of the manager used (while
181    ``.base_objects`` is just a different manager).
182
183*   ``.get_real_instances()`` has been elevated to an official part of the API.
184    It allows you to turn a queryset or list of base objects into a list of the real instances.
185    This is useful if e.g. you use ``ModelA.objects.non_polymorphic().extra(...)`` and then want to
186    transform the result to its polymorphic equivalent:
187
188    >>> qs = ModelA.objects.all().non_polymorphic()
189    >>> real_objects = qs.get_real_instances()
190
191    is equivalent to:
192
193    >>> real_objects = ModelA.objects.all()
194
195    Instead of ``qs.get_real_instances()``, ``ModelA.objects.get_real_instances(qs)`` may be used
196    as well. In the latter case, ``qs`` may be any list of objects of type ModelA.
197
198*   ``translate_polymorphic_Q_object``  (see DOCS)
199
200
201February 22 2010, Installation Note
202-------------------------------------------------------------------
203
204The django_polymorphic source code has been restructured
205and as a result needs to be installed like a normal Django App
206- either via copying the "polymorphic" directory into your
207Django project or by running setup.py. Adding 'polymorphic'
208to INSTALLED_APPS in settings.py is still optional, however.
209
210The file `polymorphic.py` cannot be used as a standalone
211extension module anymore (as is has been split into a number
212of smaller files).
213
214Importing works slightly different now: All relevant symbols are
215imported directly from 'polymorphic' instead from
216'polymorphic.models'::
217
218    # new way
219    from polymorphic import PolymorphicModel, ...
220
221    # old way, doesn't work anymore
222    from polymorphic.models import PolymorphicModel, ...
223
224
225January 26 2010: Database Schema Change
226-------------------------------------------------------------------
227
228The update from January 26 changed the database schema (more info in the commit-log_).
229Sorry for any inconvenience. But this should be the final DB schema now.
230
231.. _commit-log: http://github.com/bconstantin/django_polymorphic/commit/c2b420aea06637966a208329ef7ec853889fa4c7