Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Deprecated depth kwarg on select_related.

This is the start of a deprecation path for the depth kwarg on
select_related. Removing this will allow us to update select_related so
it chains properly and have an API similar to prefetch_related.

Thanks to Marc Tamlyn for spearheading and initial patch.

refs #16855
  • Loading branch information...
commit 965cc0b1ffa27574e5684a18f9400577e5b4598d 1 parent 7b57a72
Preston Holmes authored November 02, 2012
4  django/db/models/query.py
@@ -5,6 +5,7 @@
5 5
 import copy
6 6
 import itertools
7 7
 import sys
  8
+import warnings
8 9
 
9 10
 from django.core import exceptions
10 11
 from django.db import connections, router, transaction, IntegrityError
@@ -698,6 +699,9 @@ def select_related(self, *fields, **kwargs):
698 699
         If fields are specified, they must be ForeignKey fields and only those
699 700
         related objects are included in the selection.
700 701
         """
  702
+        if 'depth' in kwargs:
  703
+            warnings.warn('The "depth" keyword argument has been deprecated.\n'
  704
+                    'Use related field names instead.', PendingDeprecationWarning)
701 705
         depth = kwargs.pop('depth', 0)
702 706
         if kwargs:
703 707
             raise TypeError('Unexpected keyword arguments to select_related: %s'
3  docs/internals/deprecation.txt
@@ -298,6 +298,9 @@ these changes.
298 298
 
299 299
 * The ``daily_cleanup.py`` script will be removed.
300 300
 
  301
+* The ``depth`` keyword argument will be removed from
  302
+  :meth:`~django.db.models.query.QuerySet.select_related`.
  303
+
301 304
 2.0
302 305
 ---
303 306
 
30  docs/ref/models/querysets.txt
@@ -676,21 +676,12 @@ Note that, by default, ``select_related()`` does not follow foreign keys that
676 676
 have ``null=True``.
677 677
 
678 678
 Usually, using ``select_related()`` can vastly improve performance because your
679  
-app can avoid many database calls. However, in situations with deeply nested
680  
-sets of relationships ``select_related()`` can sometimes end up following "too
681  
-many" relations, and can generate queries so large that they end up being slow.
  679
+app can avoid many database calls. However, there are times you are only
  680
+interested in specific related models, or have deeply nested sets of
  681
+relationships, and in these cases ``select_related()`` can can be optimized by
  682
+explicitly passing the related field names you are interested in. Only
  683
+the specified relations will be followed.
682 684
 
683  
-In these situations, you can use the ``depth`` argument to ``select_related()``
684  
-to control how many "levels" of relations ``select_related()`` will actually
685  
-follow::
686  
-
687  
-    b = Book.objects.select_related(depth=1).get(id=4)
688  
-    p = b.author         # Doesn't hit the database.
689  
-    c = p.hometown       # Requires a database call.
690  
-
691  
-Sometimes you only want to access specific models that are related to your root
692  
-model, not all of the related models. In these cases, you can pass the related
693  
-field names to ``select_related()`` and it will only follow those relations.
694 685
 You can even do this for models that are more than one relation away by
695 686
 separating the field names with double underscores, just as for filters. For
696 687
 example, if you have this model::
@@ -730,6 +721,17 @@ You can also refer to the reverse direction of a
730 721
 is defined. Instead of specifying the field name, use the :attr:`related_name
731 722
 <django.db.models.ForeignKey.related_name>` for the field on the related object.
732 723
 
  724
+.. deprecated:: 1.5
  725
+    The ``depth`` parameter to ``select_related()`` has been deprecated. You
  726
+    should replace it with the use of the ``(*fields)`` listing specific
  727
+    related fields instead as documented above.
  728
+
  729
+A depth limit of relationships to follow can also be specified::
  730
+
  731
+    b = Book.objects.select_related(depth=1).get(id=4)
  732
+    p = b.author         # Doesn't hit the database.
  733
+    c = p.hometown       # Requires a database call.
  734
+
733 735
 A :class:`~django.db.models.OneToOneField` is not traversed in the reverse
734 736
 direction if you are performing a depth-based ``select_related()`` call.
735 737
 
7  docs/releases/1.5.txt
@@ -638,3 +638,10 @@ The :djadmin:`cleanup` management command has been deprecated and replaced by
638 638
 
639 639
 The undocumented ``daily_cleanup.py`` script has been deprecated. Use the
640 640
 :djadmin:`clearsessions` management command instead.
  641
+
  642
+``depth`` keyword argument in ``select_related``
  643
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  644
+
  645
+The ``depth`` keyword argument in
  646
+:meth:`~django.db.models.query.QuerySet.select_related` has been deprecated.
  647
+You should use field names instead.

0 notes on commit 965cc0b

Please sign in to comment.
Something went wrong with that request. Please try again.