Changes between Version 58 and Version 59 of RemovingTheMagic

Timestamp:

Feb 1, 2006, 12:28:54 PM (18 years ago)

Author:

Adrian Holovaty

Comment:

Moved DescriptorFields stuff to this page

RemovingTheMagic

@@ -17 +17 @@
  * The magic package {{{django.models}}} no longer exists. To use models, just import the model class from wherever it lives on the Python path. Similarly, the magic modules (such as {{{django.models.polls}}} in the tutorial) no longer exist; now, you interact directly with the model class.
  * All automatic pluralization is gone.
- * The lookup API is changing so that many methods will become attributes. For example, {{{choice.get_poll()}}} is now {{{choice.poll}}}.
+ * The database API has changed in several ways.
  * Various packages, such as the Django template system (previously in {{{django.core.template}}}), have been moved around to make importing less verbose and easier to remember.
 
@@ -164 +164 @@
 === Namespace simplification ===
 
-See NamespaceSimplification for details.
+{{{django.utils.httpwrappers}}} has moved to {{{django.http}}}.
+
+{{{django.core.exceptions.Http404}}} has moved to {{{django.http.Http404}}}.
+
+{{{django.core.template}}} has moved to {{{django.template}}}.
+
+{{{django.core.formfields}}} has moved to {{{django.forms}}}.
+
+{{{django.core.extensions}}} has moved to {{{django.shortcuts}}}.
+
+{{{django.core.extensions.DjangoContext}}} has been renamed to {{{RequestContext}}} and moved to {{{django.template.RequestContext}}}.
+
+You'll need to update {{{TEMPLATE_LOADERS}}} in your settings from:
+{{{
+#!python
+TEMPLATE_LOADERS = (
+    'django.core.template.loaders.filesystem.load_template_source',
+    'django.core.template.loaders.app_directories.load_template_source',
+#    'django.core.template.loaders.eggs.load_template_source',
+)
+}}}
+
+...to:
+
+{{{
+#!python
+TEMPLATE_LOADERS = (
+    'django.template.loaders.filesystem.load_template_source',
+    'django.template.loaders.app_directories.load_template_source',
+#    'django.template.loaders.eggs.load_template_source',
+)
+}}}
+
+The "auth" and "core" models have been split and moved to {{{django.contrib}}} as follows:
+
+    * {{{django.models.auth}}} has moved to {{{django.contrib.auth.models}}}.
+    * {{{django.models.core.sites}}} has moved to {{{django.contrib.sites.models}}}.
+    * {{{django.models.core.contenttypes}}} has moved to {{{django.contrib.contenttypes.models}}}.
+    * {{{django.models.core.packages}}} has moved to {{{django.contrib.contenttypes.models}}}. (Note that "packages" are going away before magic-removal is done.)
+
+Session middleware has moved from {{{django.middleware.sessions.SessionMiddleware}}} to {{{django.contrib.sessions.middleware.SessionMiddleware}}}. Make sure to update your {{{MIDDLEWARE_CLASSES}}} setting, if you're using sessions.
+
+Also, the {{{Session}}} model has moved from django/models/core.py to django/contrib/sessions/models.py. If you're accessing the {{{Session}}} model for some reason, note that location change.
 
 === Changes to model syntax ===
@@ -203 +245 @@
 }}}
 
+=== Database connection relocated/renamed ===
+
+For any code that uses the raw database connection, use {{{django.db.connection}}} instead of {{{django.core.db.db}}}.
+
+Old:
+{{{
+#!python
+from django.core.db import db
+cursor = db.cursor()
+}}}
+
+New:
+{{{
+#!python
+from django.db import connection
+cursor = connection.cursor()
+}}}
+
+Backend-specific functions, if you should need them, are available at {{{django.db.backend}}}.
+
+Old:
+{{{
+#!python
+from django.core import db
+db.quote_name('foo')
+}}}
+
+New:
+{{{
+#!python
+from django.db import backend
+backend.quote_name('foo')
+}}}
+
+Also, the various backend functionality has been split into three separate modules for each backend -- {{{base.py}}}, {{{creation.py}}} and {{{introspection.py}}}. This is purely for performance and memory savings, so that basic, everyday Django usage doesn't have to load the introspective functionality into memory.
+
 === Model methods no longer automatically have access to datetime and db modules ===
 
@@ -230 +308 @@
 }}}
 
-=== Access table-level DB API functions via model classes, not with magic modules ===
+=== Descriptor fields ===
 
 All "table-level" functions -- ways of retrieving records tablewide rather than performing instance-specific tasks -- are now accessed via a model class's {{{objects}}} attribute. They aren't direct methods of a model instance 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() # Raises AttributeError
+A model class's {{{objects}}} attribute is an instance of {{{django.db.models.manager.Manager}}}. A manager has the following methods, all of which return a {{{QuerySet}}} instance.
+
+    * {{{all()}}} -- Returns a {{{QuerySet}}} of all objects in the database. This is like the old {{{get_list()}}}. Takes no arguments.
+    * {{{filter(**kwargs)}}} -- Returns a {{{QuerySet}}}, filtered by the given keyword arguments. Lookup arguments are in the same style as previously, e.g. {{{pubdate__year=2005}}}, except you can leave off {{{__exact}}} as a convenience. For example, {{{name='John'}}} and {{{name__exact='John'}}} are equivalent.
+    * {{{order_by(*fieldnames)}}} -- Returns a {{{QuerySet}}}
+    * {{{count()}}} -- Returns the count of all objects in the database.
+    * {{{dates(field_name, kind)}}} -- Like the old {{{get_FIELD_list()}}} for date fields. For example, old-school {{{get_pubdate_list('year')}}} is now {{{dates('pubdate', 'year')}}}.
+    * {{{delete()}}} -- Deletes all objects.
+    * {{{distinct()}}} -- Returns a {{{QuerySet}}} with DISTINCT set.
+    * {{{extra(select=None, where=None, params=None, tables=None)}}} -- Sets the {{{select}}}, {{{where}}}, {{{params}}} and {{{tables}}} arguments, which are in the same format as before.
+    * {{{get(**kwargs)}}} -- Like the old {{{get_object()}}}. Returns an object or raises {{{DoesNotExist}}} on error.
+    * {{{in_bulk(id_list)}}} -- Like the old {{{get_in_bulk()}}}.
+    * {{{iterator()}}} -- Returns a generator that iterators over results.
+    * {{{select_related()}}} -- Returns a {{{QuerySet}}} with the "select related" option (which acts the same as before) set.
+    * {{{values(*fieldnames)}}} -- Like the old {{{get_values()}}}.
+
+Each {{{QuerySet}}} has the following methods, which return a clone of the query set with the appropriate changes made:
+
+    * {{{filter(**kwargs)}}}
+    * {{{order_by(*fieldnames)}}}
+    * {{{iterator()}}}
+    * {{{count()}}}
+    * {{{get(**kwargs)}}}
+    * {{{delete()}}}
+    * {{{filter(**kwargs)}}}
+    * {{{select_related()}}}
+    * {{{order_by(*fieldnames)}}}
+    * {{{distinct()}}}
+    * {{{extra(select=None, where=None, params=None, tables=None)}}}
+
+Here are some examples, which use the following models:
+
+{{{
+#!python
+class Reporter(models.Model):
+    fname = models.CharField(maxlength=30)
+    lname = models.CharField(maxlength=30)
+
+class Site(models.Model):
+    name = models.CharField(maxlength=20)
+
+class Article(models.Model):
+    headline = models.CharField(maxlength=50)
+    reporter = models.ForeignKey(Reporter)
+    pub_date = models.DateField()
+    sites = models.ManyToManyField(Site)
+}}}
+
+|| '''Old syntax'''                                        || '''New syntax'''                             ||
+|| {{{reporters.get_list()}}}                             || {{{Reporter.objects.all()}}}                       ||
+|| {{{reporters.get_list(fname__exact='John')}}}          || {{{Reporter.objects.filter(fname='John')}}}        ||
+|| {{{reporters.get_list(order_by=('-lname', 'fname'))}}} || {{{Reporter.objects.order_by('-lname', 'fname')}}} ||
+|| {{{reporters.get_list(fname__exact='John', order_by=('lname',))}}} || {{{Reporter.objects.filter(fname='John').order_by('lname')}}} ||
+|| {{{reporters.get_object(pk=3)}}}                       || {{{Reporter.objects.get(pk=3)}}}                   ||
+|| {{{reporters.get_object(fname__contains='John')}}}     || {{{Reporter.objects.get(fname__contains='John')}}} ||
+|| {{{reporters.get_list(distinct=True)}}}                || {{{Reporter.objects.distinct()}}} ||
+|| {{{reporters.get_values()}}}                           || {{{Reporter.objects.values()}}} ||
+|| {{{reporters.get_in_bulk([1, 2])}}}                    || {{{Reporter.objects.in_bulk([1, 2])}}} ||
+|| {{{reporters.get_in_bulk([1, 2], fname__exact='John')}}} || {{{Reporter.objects.filter(fname='John').in_bulk([1, 2])}}} ||
+|| '''Date lookup'''                                      ||                                              ||
+|| {{{articles.get_pub_date_list('year')}}}                     || {{{Article.objects.dates('pub_date', 'year')}}} ||
+|| '''Many-to-one related lookup'''                        ||                                              ||
+|| {{{article_obj.reporter_id}}}                                 || {{{article_obj.reporter.id}}} ||
+|| {{{article_obj.get_reporter()}}}                              || {{{article_obj.reporter}}}    ||
+|| {{{reporter_obj.get_article_list()}}}                         || {{{reporter_obj.article_set.all()}}} ||
+|| {{{reporter_obj.get_article_list(headline__exact='Hello')}}}  || {{{reporter_obj.article_set.filter(headline='Hello')}}} ||
+|| {{{reporter_obj.get_article_count()}}}                        || {{{reporter_obj.article_set.count()}}} ||
+|| {{{reporter_obj.add_article(headline='Foo')}}}                || {{{reporter_obj.article_set.add(headline='Foo')}}} ||
+|| (Alternate syntax)                                      || {{{reporter_obj.article_set.add(article_obj)}}} ||
+|| ("values" lookup, etc., not previously possible)        || {{{reporter_obj.article_set.values()}}} ||
+|| '''Many-to-many related lookup'''                       ||                         ||
+|| {{{article_obj.get_site_list()}}}                             || {{{article_obj.sites.all()}}} ||
+|| {{{article_obj.set_sites([s1.id, s2.id])}}}                   || {{{article_obj.sites.clear(); article_obj.sites.add(s1); article_obj.sites.add(s2)}}} ||
+|| {{{article_obj.set_sites([s1.id]) # deletion}}}               || {{{article_obj.sites.remove(s2)}}} ||
+|| {{{site_obj.get_reporter_list()}}}                            || {{{site_obj.reporter_set.all()}}} ||
+
+Note that related-object lookup uses the default manager of the related object, which means the API for accessing related objects is completely consistent with the API for accessing objects via a manager.
+
+Also note that managers can't be accessed from instances:
+
+{{{
+#!python
+p = Person.objects.get(pk=1)
+p.objects.all() # Raises AttributeError
 }}}
 
 === Override default manager name ("objects") ===
 
-If a model already has an {{{objects}}} attribute, you'll need to specify an alternate name for the magic {{{objects}}}.
+If a model already has an {{{objects}}} attribute, you'll need to specify an alternate name for the {{{objects}}} manager.
 
 {{{
@@ -264 +413 @@
 p.save()
 p.objects == 'Hello there.'
-Person.people.get_list()
+Person.people.all()
 }}}
 
@@ -280 +429 @@
     people = models.Manager()
     fun_people = SomeOtherManager()
+}}}
+
+If a manager needs to access its associated model class, it should use {{{self.model}}}. Example:
+
+{{{
+#!python
+class PersonManager(models.Manager):
+    def get_fun_person(self):
+        try:
+            return self.get(fun=True)
+        except self.model.DoesNotExist:
+            print "Doesn't exist."
 }}}
 
@@ -314 +475 @@
 }}}
 
-=== Database connection relocated/renamed ===
-
-For any code that uses the raw database connection, use {{{django.db.connection}}} instead of {{{django.core.db.db}}}.
-
-Old:
-{{{
-#!python
-from django.core.db import db
-cursor = db.cursor()
-}}}
-
-New:
-{{{
-#!python
-from django.db import connection
-cursor = connection.cursor()
-}}}
-
-Backend-specific functions, if you should need them, are available at {{{django.db.backend}}}.
-
-Old:
-{{{
-#!python
-from django.core import db
-db.quote_name('foo')
-}}}
-
-New:
-{{{
-#!python
-from django.db import backend
-backend.quote_name('foo')
-}}}
-
-Also, the various backend functionality has been split into three separate modules for each backend -- {{{base.py}}}, {{{creation.py}}} and {{{introspection.py}}}. This is purely for performance and memory savings, so that basic, everyday Django usage doesn't have to load the introspective functionality into memory.
-
 === Renamed !DoesNotExist exception ===
 
@@ -369 +494 @@
 from path.to.myapp.models import Person
 try:
-    Person.objects.get_object(pk=1)
+    Person.objects.get(pk=1)
 except Person.DoesNotExist:
     print "Not there"
@@ -395 +520 @@
 }}}
 
-=== Moved "auth" and "core" models to django.contrib ===
-
-See http://groups.google.com/group/django-developers/browse_thread/thread/276d071a74543448/7d4b1c40c2d53393
-
- * Old: {{{django.models.auth}}}
- * New: {{{django.contrib.auth.models}}}
-
- * Old: {{{django.models.core.sites}}}
- * New: {{{django.contrib.sites.models}}}
-
- * Old: {{{django.models.core.contenttypes}}}
- * New: {{{django.contrib.contenttypes.models}}}
-
- * Old: {{{django.models.core.packages}}}
- * New: {{{django.contrib.contenttypes.models}}} ("Packages" will most likely be removed in the future.)
-
-=== Moved Session model and middleware from core to django.contrib ===
-
-The location of the session middleware has changed.
-
- * Old: {{{django.middleware.sessions.SessionMiddleware}}}
- * New: {{{django.contrib.sessions.middleware.SessionMiddleware}}}
-
-Make sure to update your {{{MIDDLEWARE_CLASSES}}} setting, if you're using sessions.
-
-Also, the {{{Session}}} model has moved from django/models/core.py to django/contrib/sessions/models.py. If you're accessing the {{{Session}}} model for some reason, note that location change.
 
 === Changed the parameters you pass to generic views ===
@@ -441 +540 @@
 #!python
 from myproject.blog.models import Entry
-info_dict = {
-    'model': Entry
-}
+info_dict = {'model': Entry}
 }}}
 
@@ -459 +556 @@
 === Moved settings into an instance ===
 
-To make it easier to switch settings in situations where you would need multiple different settings - for example when trying to use multiple django projects within one server context or when using Django apps within a bigger WSGI scenario - the settings were moved out of a dedicated module {{{django.conf.settings}}} into an instance in the {{{django.conf}}} module. So now you need to import the {{{settings}}} object and reference settings as attributes of that instance.
-
-Wrappers around the Django machinery can make use of this by exchanging the settings instance with a proxy instance that delegates attribute access to a per-thread or per-location global.
+Settings have moved out of a dedicated module {{{django.conf.settings}}} into an instance in the {{{django.conf}}} module. So now you need to import the {{{settings}}} object and reference settings as attributes of that instance.
 
  * Old: {{{from django.conf.settings import LANGUAGE_CODE}}}
  * New: {{{from django.conf import settings}}}
 
+Wrappers around the Django machinery can make use of this by exchanging the settings instance with a proxy instance that delegates attribute access to a per-thread or per-location global.
+
 === Removed !SilentVariableFailure exception ===
 
@@ -471 +568 @@
 
 New behavior: Any exception that has a {{{silent_variable_failure}}} attribute fails silently in the template system. {{{django.core.template.SilentVariableFailure}}} no longer exists.
-
-
-
-
 
 == New functionality you can start using ==
@@ -495 +588 @@
 }}}
 
-=== You can override table-level functions ===
-
-You can 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 models.Manager.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)
-    objects = PersonManager()
-}}}
-
-If a manager needs to access its associated class, it should use {{{self.model}}}. Example:
-
-{{{
-#!python
-class PersonManager(models.Manager):
-    def get_fun_person(self):
-        try:
-            return self.get_object(fun__exact=True)
-        except self.model.DoesNotExist:
-            print "Doesn't exist."
-}}}
-
-
-
-
-
+=== You can override default QuerySets ===
+
+You can specify the default QuerySet (see "Descriptor fields" above) that a manager uses. For example:
+
+{{{
+#!python
+class PublishedBookManager(models.Manager):
+    def get_query_set(self):
+        return super(PublishedBookManager, self).get_query_set().filter(is_published=True)
+
+class Book(models.Model):
+    title = models.CharField(maxlength=50)
+    author = models.CharField(maxlength=30)
+    is_published = models.BooleanField()
+    published_objects = PublishedBookManager()
+}}}
 
 == Stuff that still needs to be done ==
 
-=== Automatic manipulators ===
-
-'''Status: Mostly done, with some quirks left'''
-
-Old:
-{{{
-#!python
-from django.models.myapp import people
-m1 = people.AddManipulator()
-m2 = people.ChangeManipulator(3)
-}}}
-
-New:
-{{{
-#!python
-from path.to.myapp.models import Person
-m1 = Person.AddManipulator()
-m2 = Person.ChangeManipulator(3)
-}}}
+=== Remove automatic manipulators, in favor of validation-aware models ===
+
+'''Status: Not done yet'''
 
 === Change subclassing syntax ===
@@ -558 +616 @@
 
 See ModelInheritance
-
-=== Database lookup API changes ===
-
-'''Status: Not done yet'''
-
-See DescriptorFields, rjwittams' proposal on the API changes.