/README.rst

https://bitbucket.org/bconstantin/django_polymorphic/ · ReStructuredText · 231 lines · 159 code · 72 blank · 0 comment · 0 complexity · e65f019d1a55820feb4095d4fa78e8f9 MD5 · raw file

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