queryset-refactor: Merged changed from trunk up to [6463].

git-svn-id: http://code.djangoproject.com/svn/django/branches/queryset-refactor@6466 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/templates_python.txt

@@ -316,7 +316,7 @@ optional, third positional argument, ``processors``. In this example, the
         }, [ip_address_processor])
         return t.render(c)
 
-Note::
+.. note::
     If you're using Django's ``render_to_response()`` shortcut to populate a
     template with the contents of a dictionary, your template will be passed a
     ``Context`` instance by default (not a ``RequestContext``). To use a
@@ -928,10 +928,36 @@ current context, available in the ``render`` method::
 ``resolve_variable`` will try to resolve ``blog_entry.date_updated`` and then
 format it accordingly.
 
-.. note::
-    The ``resolve_variable()`` function will throw a ``VariableDoesNotExist``
-    exception if it cannot resolve the string passed to it in the current
-    context of the page.
+.. admonition:: New in development version:
+
+    Variable resolution has changed in the development version of Django.
+    ``template.resolve_variable()`` is still available, but has been deprecated
+    in favor of a new ``template.Variable`` class. Using this class will usually
+    be more efficient than calling ``template.resolve_variable``
+    
+    To use the ``Variable`` class, simply instantiate it with the name of the
+    variable to be resolved, and then call ``variable.resolve(context)``. So,
+    in the development version, the above example would be more correctly
+    written as:
+    
+    .. parsed-literal::
+    
+        class FormatTimeNode(template.Node):
+            def __init__(self, date_to_be_formatted, format_string):
+                self.date_to_be_formatted = **Variable(date_to_be_formatted)**
+                self.format_string = format_string
+        
+            def render(self, context):
+                try:
+                    actual_date = **self.date_to_be_formatted.resolve(context)**
+                    return actual_date.strftime(self.format_string)
+                except template.VariableDoesNotExist:
+                    return ''
+    
+    Changes are highlighted in bold.
+
+Variable resolution will throw a ``VariableDoesNotExist`` exception if it cannot
+resolve the string passed to it in the current context of the page.
 
 Shortcut for simple tags
 ~~~~~~~~~~~~~~~~~~~~~~~~