queryset-refactor: Merged to [6155]

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

docs/generic_views.txt

@@ -688,9 +688,8 @@ A page representing a list of objects.
     * ``paginate_by``: An integer specifying how many objects should be
       displayed per page. If this is given, the view will paginate objects with
       ``paginate_by`` objects per page. The view will expect either a ``page``
-      query string parameter (via ``GET``) containing a 1-based page
-      number, or a ``page`` variable specified in the URLconf. See
-      "Notes on pagination" below.
+      query string parameter (via ``GET``) or a ``page`` variable specified in
+      the URLconf. See "Notes on pagination" below.
 
     * ``template_name``: The full name of a template to use in rendering the
       page. This lets you override the default template name (see below).
@@ -765,6 +764,9 @@ If the results are paginated, the context will contain these extra variables:
     * ``hits``: The total number of objects across *all* pages, not just this
       page.
 
+    * ``page_range``: A list of the page numbers that are available. This
+      is 1-based.
+
 Notes on pagination
 ~~~~~~~~~~~~~~~~~~~
 
@@ -777,12 +779,25 @@ specify the page number in the URL in one of two ways:
         (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))
 
     * Pass the page number via the ``page`` query-string parameter. For
-      example, a URL would look like this:
+      example, a URL would look like this::
 
         /objects/?page=3
 
-In both cases, ``page`` is 1-based, not 0-based, so the first page would be
-represented as page ``1``.
+    * To loop over all the available page numbers, use the ``page_range`` 
+      variable. You can iterate over the list provided by ``page_range`` 
+      to create a link to every page of results.
+
+These values and lists are is 1-based, not 0-based, so the first page would be
+represented as page ``1``. As a special case, you are also permitted to use 
+``last`` as a value for ``page``::
+
+    /objects/?page=last
+
+This allows you to access the final page of results without first having to 
+determine how many pages there are.
+
+Note that ``page`` *must* be either a valid page number or the value ``last``;
+any other value for ``page`` will result in a 404 error.
 
 ``django.views.generic.list_detail.object_detail``
 --------------------------------------------------

docs/newforms.txt

@@ -554,6 +554,29 @@ method you're using::
     <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p>
     <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
 
+Customizing the error list format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, forms use ``django.newforms.util.ErrorList`` to format validation
+errors. If you'd like to use an alternate class for displaying errors, you can
+pass that in at construction time::
+
+    >>> from django.newforms.util import ErrorList
+    >>> class DivErrorList(ErrorList):
+    ...     def __unicode__(self):
+    ...         return self.as_divs()
+    ...     def as_divs(self):
+    ...         if not self: return u''
+    ...         return u'<div class="errorlist">%s</div>' % ''.join([u'<div class="error">%s</div>' % e for e in self])
+    >>> f = ContactForm(data, auto_id=False, error_class=DivErrorList)
+    >>> f.as_p()
+    <div class="errorlist"><div class="error">This field is required.</div></div>
+    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
+    <p>Message: <input type="text" name="message" value="Hi there" /></p>
+    <div class="errorlist"><div class="error">Enter a valid e-mail address.</div></div>
+    <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p>
+    <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
+
 More granular output
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -1893,6 +1916,17 @@ Note that your callback needs to handle *all* possible model field types, not
 just the ones that you want to behave differently to the default. That's why
 this example has an ``else`` clause that implements the default behavior.
 
+.. warning::
+    The field that is passed into the ``formfield_callback`` function in
+    ``form_for_model()`` and ``form_for_instance`` is the field instance from
+    your model's class. You **must not** alter that object at all; treat it
+    as read-only!
+
+    If you make any alterations to that object, it will affect any future
+    users of the model class, because you will have changed the field object
+    used to construct the class. This is almost certainly what you don't want
+    to have happen.
+
 Finding the model associated with a form
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/request_response.txt

@@ -183,6 +183,9 @@ subclass of dictionary. Exceptions are outlined here:
 
     * ``__getitem__(key)`` -- Returns the value for the given key. If the key
       has more than one value, ``__getitem__()`` returns the last value.
+      Raises ``django.utils.datastructure.MultiValueDictKeyError`` if the key
+      does not exist (fortunately, this is a subclass of Python's standard
+      ``KeyError``, so you can stick to catching ``KeyError``).
 
     * ``__setitem__(key, value)`` -- Sets the given key to ``[value]``
       (a Python list whose single element is ``value``). Note that this, as

docs/sites.txt

@@ -316,6 +316,9 @@ Here's how Django uses the sites framework:
     * The shortcut view (``django.views.defaults.shortcut``) uses the domain of
       the current ``Site`` object when calculating an object's URL.
 
+    * In the admin framework, the ''view on site'' link uses the current
+      ``Site`` to work out the domain for the site that it will redirect to.
+
 .. _redirects framework: ../redirects/
 .. _flatpages framework: ../flatpages/
 .. _syndication framework: ../syndication_feeds/

docs/templates.txt

@@ -366,25 +366,36 @@ Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
 cycle
 ~~~~~
 
-Cycle among the given strings each time this tag is encountered.
+**Changed in Django development version**
+Cycle among the given strings or variables each time this tag is encountered.
 
-Within a loop, cycles among the given strings each time through the loop::
+Within a loop, cycles among the given strings/variables each time through the
+loop::
 
     {% for o in some_list %}
-        <tr class="{% cycle row1,row2 %}">
+        <tr class="{% cycle 'row1' 'row2' rowvar %}">
             ...
         </tr>
     {% endfor %}
-
+ 
 Outside of a loop, give the values a unique name the first time you call it,
 then use that name each successive time through::
 
-        <tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr>
+        <tr class="{% cycle 'row1' 'row2' rowvar as rowcolors %}">...</tr>
         <tr class="{% cycle rowcolors %}">...</tr>
         <tr class="{% cycle rowcolors %}">...</tr>
 
-You can use any number of values, separated by commas. Make sure not to put
-spaces between the values -- only commas.
+You can use any number of values, separated by spaces. Values enclosed in 
+single (') or double quotes (") are treated as string literals, while values 
+without quotes are assumed to refer to context variables. 
+
+You can also separate values with commas::
+
+    {% cycle row1,row2,row3 %}
+    
+In this syntax, each value will be interpreted as literal text. The 
+comma-based syntax exists for backwards-compatibility, and should not be 
+used for new projects.
 
 debug
 ~~~~~

docs/templates_python.txt

@@ -642,7 +642,23 @@ your function. Example::
         "Converts a string into all lowercase"
         return value.lower()
 
-When you've written your filter definition, you need to register it with
+Template filters which expect strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're writing a template filter which only expects a string as the first
+argument, you should use the included decorator ``stringfilter``. This will
+convert an object to it's string value before being passed to your function::
+
+    from django.template.defaultfilters import stringfilter
+
+    @stringfilter
+    def lower(value):
+        return value.lower()
+
+Registering a custom filters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you've written your filter definition, you need to register it with
 your ``Library`` instance, to make it available to Django's template language::
 
     register.filter('cut', cut)
@@ -658,28 +674,18 @@ If you're using Python 2.4 or above, you can use ``register.filter()`` as a
 decorator instead::
 
     @register.filter(name='cut')
+    @stringfilter
     def cut(value, arg):
         return value.replace(arg, '')
 
     @register.filter
+    @stringfilter
     def lower(value):
         return value.lower()
 
 If you leave off the ``name`` argument, as in the second example above, Django
 will use the function's name as the filter name.
 
-Template filters which expect strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you are writing a template filter which only expects a string as the first
-argument, you should use the included decorator ``stringfilter`` which will convert
-an object to it's string value before being passed to your function::
-
-    from django.template.defaultfilters import stringfilter
-
-    @stringfilter
-    def lower(value):
-        return value.lower()
-
 Writing custom template tags
 ----------------------------
 

docs/testing.txt

@@ -569,8 +569,8 @@ Testing responses
 
 The ``get()`` and ``post()`` methods both return a ``Response`` object. This
 ``Response`` object is *not* the same as the ``HttpResponse`` object returned
-Django views; this object is simpler and has some additional data useful for
-tests.
+Django views; the test response object has some additional data useful for
+test code to verify.
 
 Specifically, a ``Response`` object has the following attributes:
 
@@ -582,7 +582,7 @@ Specifically, a ``Response`` object has the following attributes:
 
     ``content``      The body of the response, as a string. This is the final
                      page content as rendered by the view, or any error
-                     message (such as the URL for a 302 redirect).
+                     message.
 
     ``context``      The template ``Context`` instance that was used to render
                      the template that produced the response content.
@@ -591,6 +591,8 @@ Specifically, a ``Response`` object has the following attributes:
                      ``context`` will be a list of ``Context``
                      objects, in the order in which they were rendered.
 
+    ``headers``      The HTTP headers of the response. This is a dictionary.
+
     ``request``      The request data that stimulated the response.
 
     ``status_code``  The HTTP status of the response, as an integer. See