Changes between Version 15 and Version 16 of QuerysetRefactorBranch

Timestamp:

Apr 26, 2008, 11:06:03 PM (16 years ago)

Author:

Malcolm Tredinnick

Comment:

Split backwards-incompat changes into "things you care about" and "other"

QuerysetRefactorBranch

@@ -37 +37 @@
 A few backwards incompatible changes are created by the changes in this branch. Most people won't be affected by many of these, and porting code is reasonably straightforward.
 
- * The {{{Options.get_order_sql()}}} method is now gone in {{{django.db.models.options}}}. There appears to be no use for this method any longer.
- * {{{Q}}} objects have changed internally. This is only relevant if you have created custom Q-like objects. You would have created a {{{get_sql()}}} method that returned a data structure that was inserted into the query. In the new code, you create a {{{add_to_query()}}} method that accepts one argument -- the {{{django.db.models.sql.query.Query}}} instance for the current query. Your Q-like object can then add to the various attributes of this class (`select`, `where`, etc) to have whatever effect it likes on the result. Note that the {{{add_to_query()}}} method is called when the object is added to the {{{Query}}} object and more changes may be made before it is turned into SQL and executed against the database.
+=== Most visible ===
  * The {{{OneToOneField}}} class has finally been updated, as the documentation has indicated would be happening for a long while. There are few externally visible changes, with one exception: a {{{OneToOneField}}} is no longer automatically the primary key for a model that includes it. It still accepts the {{{primary_key}}} attribute, however, so you should add {{{primary_key=True}}} to the declaration of any existing {{{OneToOneField}}} instances in your code to preserve backwards compatibility.
  * If you pass a bad field name into a filter or {{{order_by()}}}, Django now raises {{{FieldError}}} (from {{{django.core.exceptions}}}), rather than Python's built in {{{TypeError}}}. Also, the list of legal field names is now sorted alphabetically for easier searching. This should have no effect on most production code, however some test suites may need to be updated to accommodate the changed traceback output.
+ * There is a slight difference between these two filter statements
+   {{{
+#!python
+qs.objects.filter(f1).filter(f2)
+qs.objects.filter(f1, f2)
+   }}}
+   This difference only applies when `f1` and `f2` are referencing the same multi-valued relationship (a `ManyToManyField` or reverse `ForeignKey`). The first version allows filtering against different items from the relationship (things that match `f1` on one object in the related table as well as `f2` on another object in the related table), whereas the second version's filters will be applied to the same item. See the database API documentation section called "Lookups that span relationships" for details. 
  * It is possible to use extra select fields -- those included via {{{extra(select=...)}}} -- for ordering the results. Previously, those fields could be specified to the {{{order_by()}}} method. Due to increased error checking, that is no longer practical. Instead, pass those extra columns to the {{{order_by}}} argument of the {{{extra()}}} method:
    {{{
@@ -49 +55 @@
    }}}
    This only applies to ordering by items in an `extra(select={...})` dictionary. Normal ordering is still done with the `order_by()` method to querysets, there have been no changes there. So this change will affect relatively few people.
+
+=== Other ===
+
+ * The {{{Options.get_order_sql()}}} method is now gone in {{{django.db.models.options}}}. There appears to be no use for this method any longer.
+ * {{{Q}}} objects have changed internally. This is only relevant if you have created custom Q-like objects. You would have created a {{{get_sql()}}} method that returned a data structure that was inserted into the query. In the new code, you create a {{{add_to_query()}}} method that accepts two arguments -- the {{{django.db.models.sql.query.Query}}} instance for the current query and a set of aliases used in the current `filter()` call. Your Q-like object can then add to the various attributes of this class (`select`, `where`, etc) to have whatever effect it likes on the result. Note that the {{{add_to_query()}}} method is called when the object is added to the {{{Query}}} object and more changes may be made before it is turned into SQL and executed against the database.
  * Still on {{{extra(select=...)}}}... if you want to substitute parameters into these extra selection columns, use the {{{select_params}}} argument to {{{extra()}}}. The {{{params}}} argument is only applied to the extra where conditions.
  * {{{select_related(False)}}} is no longer possible. Don't worry. You didn't know this existed, so you won't miss it. It was never part of the official API.
- * There is a slight difference between these two filter statements
-   {{{
-#!python
-qs.objects.filter(f1).filter(f2)
-qs.objects.filter(f1, f2)
-   }}}
-   This difference only applies when `f1` and `f2` are referencing the same multi-valued relationship (a `ManyToManyField` or reverse `ForeignKey`). The first version allows filtering against different items from the relationship (things that match `f1` on one object in the related table as well as `f2` on another object in the related table), whereas the second version's filters will be applied to the same item. See the database API documentation section called "Lookups that span relationships" for details. 
 
 == Things to Note ==