Changes between Initial Version and Version 1 of RemovingTheMagic

Timestamp:

Dec 6, 2005, 10:18:29 PM (18 years ago)

Author:

Adrian Holovaty

Comment:

Created page.

RemovingTheMagic

@@ +1 @@
+= Removing the magic =
+
+This document proposes a new, cleaner and less magical Django database API.
+
+== Model definition ==
+
+Difference: Import is from {{{django.db.models}}} instead of {{{django.core.meta}}}. This is easier to remember. {{{models}}} may not be the best name for it.
+
+{{{
+#!python
+from django.db import models
+
+class Person(models.Model):
+    first_name = models.CharField(maxlength=30)
+
+    last_name = models.CharField(maxlength=30)
+}}}
+
+Properties are allowed.
+
+{{{
+#!python
+from django.db import models
+
+class Person(models.Model):
+    first_name = models.CharField(maxlength=30)
+    last_name = models.CharField(maxlength=30)
+
+def _get_full_name(self):
+    return "%s %s" % (self.first_name, self.last_name)
+full_name = property(_get_full_name)
+}}}
+
+== Database connection ==
+
+Old:
+{{{
+#!python
+from django.core.db import db
+cursor = db.cursor()
+}}}
+
+New:
+{{{
+#!python
+from django.db import connection
+cursor = connection.cursor()
+}}}
+
+This is easier to remember, clearer and more consistent.
+
+== API usage: Object creation ==
+
+Import the model class directly from the module in which it was defined. No more {{{django.models.*}}} magic.
+
+{{{
+#!python
+from myproject.people.models import Person
+p = Person(first_name='John', last_name='Smith')
+p.save()
+}}}
+
+== API usage: Table-level functions ==
+
+All "table-level" functions -- ways of retrieving records tablewide rather than performing instance-specific tasks -- are accessed via a model instance's {{{objects}}} attribute. They aren't direct methods of a model object because we want to keep the "table-wide" and "row-specific" namespaces separate.
+
+{{{
+#!python
+from myproject.people.models import Person
+p_list = Person.objects.get_list()
+p = Person.objects.get_object()
+}}}
+
+This doesn't work from an instance.
+
+{{{
+#!python
+p = Person.objects.get_object(pk=1)
+p.objects.get_list() # Will raise an exception.
+}}}
+
+If a model already has an {{{objects}}} attribute, the field-accessor attribute is renamed to {{{objects_}}}.
+
+{{{
+#!python
+class Person(models.Model):
+    first_name = models.CharField(maxlength=30)
+    last_name = models.CharField(maxlength=30)
+    objects = models.TextField()
+
+p = Person(first_name='Mary', last_name='Jones', objects_='Hello there.')
+p.save()
+p.objects_ == 'Hello there.'
+}}}
+
+== API usage: Overridding model methods (and pre- and post-save hooks) ==
+
+Proper subclassing of methods will now work, so you can subclass the automatic {{{save()}}} and {{{delete()}}} methods. This removes the need for the {{{_pre_save()}}} and {{{_post_save()}}} hooks. Example:
+
+{{{
+#!python
+class Person(models.Model):
+    first_name = models.CharField(maxlength=30)
+    last_name = models.CharField(maxlength=30)
+
+def save(self):
+    self.do_something()
+    super(Person, self).save(self) # Call the "real" save() method.
+    self.do_something_else()
+}}}
+
+You can even skip saving (as requested in #1014).
+
+{{{
+#!python
+class Person(models.Model):
+    first_name = models.CharField(maxlength=30)
+    last_name = models.CharField(maxlength=30)
+
+def save(self):
+    if datetime.date.today() > datetime.date(2005, 1, 1):
+        super(Person, self).save(self) # Call the "real" save() method.
+    else:
+        # Don't save.
+        pass
+}}}
+
+== API usage: Overridding table-level functions ==
+
+You can also override any table-level functions, such as {{{get_list()}}} or {{{get_object()}}}. Do this by creating a custom {{{models.Manager}}} subclass and passing it to your model.
+
+{{{
+#!python
+from django.db import models
+class PersonManager(models.Manager):
+    def get_list(self, **kwargs):
+        # Changes get_list() to hard-code a limit=10.
+        kwargs['limit'] = 10
+        return super(PersonManager, self).get_list(self, **kwargs) # Call the "real" get_list() method.
+
+class Person(models.Model):
+    first_name = models.CharField(maxlength=30)
+    last_name = models.CharField(maxlength=30)
+    class META:
+        manager = PersonManager()
+}}}
+
+== API usage: Specifying lookups ==
+
+Old:
+{{{
+#!python
+people.get_list(first_name__exact='Adrian')
+}}}
+
+New:
+{{{
+#!python
+Person.objects.get_list(Person.q.first_name == 'Adrian')
+}}}
+
+The old syntax will still be supported and documented, indefinitely. The new syntax will be implemented as a thin wrapper around the old syntax. See patch on #851 for implementation.
+
+== Other "module"-level members: Automatic manipulators and ObjectDoesNotExist exception ==
+
+{{{
+#!python
+Person.get_add_manipulator()
+Person.get_change_manipulator()
+Person.DoesNotExist
+}}}