/README.html
HTML | 411 lines | 353 code | 58 blank | 0 comment | 0 complexity | 7c8912b120166c068ab818def4e42cf6 MD5 | raw file
1<?xml version="1.0" encoding="utf-8" ?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 4<head> 5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 6<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> 7<title></title> 8<style type="text/css"> 9 10h1, h2, h3, h4, 11#table-of-contents 12{ 13 color: #47c; 14} 15h1 { padding-top: 15px; } 16h2 { padding-top: 10px; } 17h3 { padding-top: 7px; } 18 19a:hover { border-bottom: 1px solid #0066cc; } 20a {color: #0066cc; text-decoration: none;} 21 22li { 23 padding-top: 5px; 24 padding-bottom: 5px; 25} 26 27tt { 28 color: #080; 29 } 30 31blockquote tt { 32 color: #000 33} 34 35.first { 36 margin-top: 0 } 37 38.last { 39 margin-bottom: 0 } 40 41/* 42a.toc-backref { 43 text-decoration: none ; 44 color: black } 45*/ 46 47dd { 48 margin-bottom: 0.5em } 49 50div.abstract { 51 margin: 2em 5em } 52 53div.abstract p.topic-title { 54 font-weight: bold ; 55 text-align: center } 56 57div.attention, div.caution, div.danger, div.error, div.hint, 58div.important, div.note, div.tip, div.warning { 59 margin: 2em ; 60 border: medium outset ; 61 padding: 1em } 62 63div.attention p.admonition-title, div.caution p.admonition-title, 64div.danger p.admonition-title, div.error p.admonition-title, 65div.warning p.admonition-title { 66 color: red ; 67 font-weight: bold ; 68 font-family: sans-serif } 69 70div.hint p.admonition-title, div.important p.admonition-title, 71div.note p.admonition-title, div.tip p.admonition-title { 72 font-weight: bold ; 73 font-family: sans-serif } 74 75div.dedication { 76 margin: 2em 5em ; 77 text-align: center ; 78 font-style: italic } 79 80div.dedication p.topic-title { 81 font-weight: bold ; 82 font-style: normal } 83 84div.figure { 85 margin-left: 2em } 86 87div.footer, div.header { 88 font-size: smaller } 89 90div.system-messages { 91 margin: 5em } 92 93div.system-messages h1 { 94 color: red } 95 96div.system-message { 97 border: medium outset ; 98 padding: 1em } 99 100div.system-message p.system-message-title { 101 color: red ; 102 font-weight: bold } 103 104div.topic { 105 margin: 2em } 106 107h1.title { 108 text-align: center } 109 110h2.subtitle { 111 text-align: center } 112 113hr { 114 width: 75% } 115 116ol.simple, ul.simple { 117 margin-bottom: 1em } 118 119ol.arabic { 120 list-style: decimal } 121 122ol.loweralpha { 123 list-style: lower-alpha } 124 125ol.upperalpha { 126 list-style: upper-alpha } 127 128ol.lowerroman { 129 list-style: lower-roman } 130 131ol.upperroman { 132 list-style: upper-roman } 133 134p.caption { 135 font-style: italic } 136 137p.credits { 138 font-style: italic ; 139 font-size: smaller } 140 141p.label { 142 white-space: nowrap } 143 144p.topic-title { 145 font-weight: bold } 146 147pre.address { 148 margin-bottom: 0 ; 149 margin-top: 0 ; 150 font-family: serif ; 151 font-size: 100% } 152 153pre.line-block { 154 font-family: serif ; 155 font-size: 100% } 156 157pre.literal-block, pre.doctest-block { 158 margin-left: 2em ; 159 margin-right: 2em ; 160 background-color: #eeeeee } 161 162span.classifier { 163 font-family: sans-serif ; 164 font-style: oblique } 165 166span.classifier-delimiter { 167 font-family: sans-serif ; 168 font-weight: bold } 169 170span.interpreted { 171 font-family: sans-serif } 172 173span.option-argument { 174 font-style: italic } 175 176span.pre { 177 white-space: pre } 178 179span.problematic { 180 color: red } 181 182table { 183 margin-top: 0.5em ; 184 margin-bottom: 0.5em } 185 186table.citation { 187 border-left: solid thin gray ; 188 padding-left: 0.5ex } 189 190table.docinfo { 191 margin: 2em 4em } 192 193table.footnote { 194 border-left: solid thin black ; 195 padding-left: 0.5ex } 196 197td, th { 198 padding-left: 0.5em ; 199 padding-right: 0.5em ; 200 vertical-align: top } 201 202th.docinfo-name, th.field-name { 203 font-weight: bold ; 204 text-align: left ; 205 white-space: nowrap } 206 207h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { 208 font-size: 100% } 209 210tt, pre.literal-block, pre.doctest-block { 211 font-size: 115%; 212 line-height: 150% } 213 214ul.auto-toc { 215 list-style-type: none } 216 217</style> 218</head> 219<body> 220<div class="document"> 221 222 223<div class="section" id="polymorphic-models-for-django"> 224<h1>Polymorphic Models for Django</h1> 225<div class="section" id="quick-start-docs-contributing"> 226<h2>Quick Start, Docs, Contributing</h2> 227<ul class="simple"> 228<li><a class="reference external" href="#good-for">What is django_polymorphic good for?</a></li> 229<li><a class="reference external" href="http://bserve.webhop.org/django_polymorphic/DOCS.html#quickstart">Quickstart</a>, or the complete <a class="reference external" href="http://bserve.webhop.org/django_polymorphic/DOCS.html">Installation and Usage Docs</a></li> 230<li><a class="reference external" href="http://groups.google.de/group/django-polymorphic/topics">Release Notes, News and Discussion</a> (Google Group) or <a class="reference external" href="http://bserve.webhop.org/django_polymorphic/CHANGES.html">Changelog</a></li> 231<li>Download from <a class="reference external" href="http://github.com/bconstantin/django_polymorphic">GitHub</a> or <a class="reference external" href="http://bitbucket.org/bconstantin/django_polymorphic">Bitbucket</a>, or as <a class="reference external" href="http://github.com/bconstantin/django_polymorphic/tarball/master">TGZ</a> or <a class="reference external" href="http://github.com/bconstantin/django_polymorphic/zipball/master">ZIP</a></li> 232<li>Improve django_polymorphic, report issues, discuss, patch or fork (<a class="reference external" href="http://github.com/bconstantin/django_polymorphic">GitHub</a>, <a class="reference external" href="http://bitbucket.org/bconstantin/django_polymorphic">Bitbucket</a>, <a class="reference external" href="http://groups.google.de/group/django-polymorphic/topics">Group</a>, <a class="reference external" href="http://github.com/bconstantin/django_polymorphic/tree/master/setup.py">Mail</a>)</li> 233</ul> 234</div> 235<div class="section" id="id1"> 236<span id="good-for"></span><h2>What is django_polymorphic good for?</h2> 237<p>Let's assume the models <tt class="docutils literal">ArtProject</tt> and <tt class="docutils literal">ResearchProject</tt> are derived 238from the model <tt class="docutils literal">Project</tt>, and let's store one of each into the database:</p> 239<pre class="doctest-block"> 240>>> Project.objects.create(topic="Department Party") 241>>> ArtProject.objects.create(topic="Painting with Tim", artist="T. Turner") 242>>> ResearchProject.objects.create(topic="Swallow Aerodynamics", supervisor="Dr. Winter") 243</pre> 244<p>If we want to retrieve all our projects, we do:</p> 245<pre class="doctest-block"> 246>>> Project.objects.all() 247</pre> 248<p>Using django_polymorphic, we simply get what we stored:</p> 249<pre class="literal-block"> 250[ <Project: id 1, topic "Department Party">, 251 <ArtProject: id 2, topic "Painting with Tim", artist "T. Turner">, 252 <ResearchProject: id 3, topic "Swallow Aerodynamics", supervisor "Dr. Winter"> ] 253</pre> 254<p>Using vanilla Django, we get incomplete objects, which is probably not what we wanted:</p> 255<pre class="literal-block"> 256[ <Project: id 1, topic "Department Party">, 257 <Project: id 2, topic "Painting with Tim">, 258 <Project: id 3, topic "Swallow Aerodynamics"> ] 259</pre> 260<p>It's very similar for ForeignKeys, ManyToManyFields or OneToOneFields.</p> 261<p>In general, the effect of django_polymorphic is twofold:</p> 262<p>On one hand it makes sure that model inheritance just works as you 263expect, by simply ensuring that you always get back exactly the same 264objects from the database you stored there - regardless how you access 265them, making model inheritance much more "pythonic". 266This can save you a lot of unpleasant workarounds that tend to 267make your code messy, error-prone, and slow.</p> 268<p>On the other hand, together with some small API additions to the Django 269ORM, django_polymorphic enables a much more expressive and intuitive 270programming style and also very advanced object oriented designs 271that are not possible with vanilla Django.</p> 272<p>Fortunately, most of the heavy duty machinery that is needed for this 273functionality is already present in the original Django database layer. 274Django_polymorphic adds a rather thin layer above that in order 275to make real OO fully automatic and very easy to use.</p> 276<p>There is a catch however, which applies to concrete model inheritance 277in general: Current DBM systems like PostgreSQL or MySQL are not very 278good at processing the required sql queries and can be rather slow in 279many cases. Concrete benchmarks are forthcoming (please see 280discussion forum).</p> 281<p>For more information, please look at <a class="reference external" href="http://bserve.webhop.org/django_polymorphic/DOCS.html#quickstart">Quickstart</a> or at the complete 282<a class="reference external" href="http://bserve.webhop.org/django_polymorphic/DOCS.html">Installation and Usage Docs</a> and also see the <a class="reference external" href="http://bserve.webhop.org/django_polymorphic/DOCS.html#restrictions">restrictions and caveats</a>.</p> 283</div> 284<div class="section" id="this-is-a-v1-0-beta-testing-release"> 285<h2>This is a V1.0 Beta/Testing Release</h2> 286<p>The release contains a considerable amount of changes in some of the more 287critical parts of the software. It's intended for testing and development 288environments and not for production environments. For these, it's best to 289wait a few weeks for the proper V1.0 release, to allow some time for any 290potential problems to turn up (if they exist).</p> 291<p>If you encounter any problems or have suggestions regarding the API or the 292changes in this beta, please post them in the <a class="reference external" href="http://groups.google.de/group/django-polymorphic/topics">discussion group</a> 293or open an issue on <a class="reference external" href="http://github.com/bconstantin/django_polymorphic">GitHub</a> or <a class="reference external" href="http://bitbucket.org/bconstantin/django_polymorphic">BitBucket</a> (or send me an email).</p> 294</div> 295</div> 296<div class="section" id="license"> 297<h1>License</h1> 298<p>Django_polymorphic uses the same license as Django (BSD-like).</p> 299</div> 300<div class="section" id="api-changes-additions"> 301<h1>API Changes & Additions</h1> 302<div class="section" id="november-11-2010-v1-0-api-changes"> 303<h2>November 11 2010, V1.0 API Changes</h2> 304<div class="section" id="extra-queryset-method"> 305<h3>extra() queryset method</h3> 306<p><tt class="docutils literal">.extra()</tt> has been re-implemented. Now it's polymorphic by 307default and works (nearly) without restrictions (please see docs). This is a (very) 308incompatible API change regarding previous versions of django_polymorphic. 309Support for the <tt class="docutils literal">polymorphic</tt> keyword parameter has been removed. 310You can get back the non-polymorphic behaviour by using 311<tt class="docutils literal"><span class="pre">ModelA.objects.non_polymorphic().extra()</span></tt>.</p> 312</div> 313<div class="section" id="no-pretty-printing-of-querysets-by-default"> 314<h3>No Pretty-Printing of Querysets by default</h3> 315<p>In order to improve compatibility with vanilla Django, printing quersets 316(__repr__ and __unicode__) does not use django_polymorphic's pretty printing 317by default anymore. To get the old behaviour when printing querysets, 318you need to replace your model definition:</p> 319<pre class="doctest-block"> 320>>> class Project(PolymorphicModel): 321</pre> 322<p>by:</p> 323<pre class="doctest-block"> 324>>> class Project(PolymorphicModel, ShowFieldType): 325</pre> 326<p>The mixin classes for pretty output have been renamed:</p> 327<blockquote> 328<tt class="docutils literal">ShowFieldTypes, ShowFields, ShowFieldsAndTypes</tt></blockquote> 329<p>are now:</p> 330<blockquote> 331<tt class="docutils literal">ShowFieldType, ShowFieldContent and ShowFieldTypeAndContent</tt></blockquote> 332<p>(the old ones still exist for compatibility)</p> 333</div> 334<div class="section" id="pretty-printing-output-format-changed"> 335<h3>Pretty-Printing Output Format Changed</h3> 336<p><tt class="docutils literal">ShowFieldContent</tt> and <tt class="docutils literal">ShowFieldTypeAndContent</tt> now 337use a slightly different output format. If this causes too much trouble for 338your test cases, you can get the old behaviour back (mostly) by adding 339<tt class="docutils literal">polymorphic_showfield_old_format = True</tt> to your model definitions. 340<tt class="docutils literal"><span class="pre">ShowField...</span></tt> now also produces more informative output for custom 341primary keys.</p> 342</div> 343<div class="section" id="polymorphic-dumpdata"> 344<h3>polymorphic_dumpdata</h3> 345<p>The <tt class="docutils literal">polymorphic_dumpdata</tt> management command is not needed anymore 346and has been disabled, as the regular Django dumpdata command now automatically 347works correctly with polymorphic models (for all supported versions of Django).</p> 348</div> 349<div class="section" id="running-the-test-suite-with-django-1-3"> 350<h3>Running the Test suite with Django 1.3</h3> 351<p>Django 1.3 requires <tt class="docutils literal">python manage.py test polymorphic</tt> instead of 352just <tt class="docutils literal">python manage.py test</tt>.</p> 353</div> 354</div> 355<div class="section" id="november-01-2010-v1-0-api-additions"> 356<h2>November 01 2010, V1.0 API Additions</h2> 357<ul> 358<li><p class="first"><tt class="docutils literal">.non_polymorphic()</tt> queryset member function added. This is preferable to 359using <tt class="docutils literal"><span class="pre">.base_objects...</span></tt>, as it just makes the resulting queryset non-polymorphic 360and does not change anything else in the behaviour of the manager used (while 361<tt class="docutils literal">.base_objects</tt> is just a different manager).</p> 362</li> 363<li><p class="first"><tt class="docutils literal">.get_real_instances()</tt> has been elevated to an official part of the API. 364It allows you to turn a queryset or list of base objects into a list of the real instances. 365This is useful if e.g. you use <tt class="docutils literal"><span class="pre">ModelA.objects.non_polymorphic().extra(...)</span></tt> and then want to 366transform the result to its polymorphic equivalent:</p> 367<pre class="doctest-block"> 368>>> qs = ModelA.objects.all().non_polymorphic() 369>>> real_objects = qs.get_real_instances() 370</pre> 371<p>is equivalent to:</p> 372<pre class="doctest-block"> 373>>> real_objects = ModelA.objects.all() 374</pre> 375<p>Instead of <tt class="docutils literal">qs.get_real_instances()</tt>, <tt class="docutils literal">ModelA.objects.get_real_instances(qs)</tt> may be used 376as well. In the latter case, <tt class="docutils literal">qs</tt> may be any list of objects of type ModelA.</p> 377</li> 378<li><p class="first"><tt class="docutils literal">translate_polymorphic_Q_object</tt> (see DOCS)</p> 379</li> 380</ul> 381</div> 382<div class="section" id="february-22-2010-installation-note"> 383<h2>February 22 2010, Installation Note</h2> 384<p>The django_polymorphic source code has been restructured 385and as a result needs to be installed like a normal Django App 386- either via copying the "polymorphic" directory into your 387Django project or by running setup.py. Adding 'polymorphic' 388to INSTALLED_APPS in settings.py is still optional, however.</p> 389<p>The file <cite>polymorphic.py</cite> cannot be used as a standalone 390extension module anymore (as is has been split into a number 391of smaller files).</p> 392<p>Importing works slightly different now: All relevant symbols are 393imported directly from 'polymorphic' instead from 394'polymorphic.models':</p> 395<pre class="literal-block"> 396# new way 397from polymorphic import PolymorphicModel, ... 398 399# old way, doesn't work anymore 400from polymorphic.models import PolymorphicModel, ... 401</pre> 402</div> 403<div class="section" id="january-26-2010-database-schema-change"> 404<h2>January 26 2010: Database Schema Change</h2> 405<p>The update from January 26 changed the database schema (more info in the <a class="reference external" href="http://github.com/bconstantin/django_polymorphic/commit/c2b420aea06637966a208329ef7ec853889fa4c7">commit-log</a>). 406Sorry for any inconvenience. But this should be the final DB schema now.</p> 407</div> 408</div> 409</div> 410</body> 411</html>