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

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

14 files changed, 322 insertions, 33 deletions

diff --git a/docs/custom_model_fields.txt b/docs/custom_model_fields.txt
index 923b331a95..2b344921ef 100644
--- a/docs/custom_model_fields.txt
+++ b/docs/custom_model_fields.txt
@@ -401,8 +401,8 @@ For example::
         # ...
 
         def get_db_prep_save(self, value):
-            return ''.join([''.join(l) for l in (self.north,
-                    self.east, self.south, self.west)])
+            return ''.join([''.join(l) for l in (value.north,
+                    value.east, value.south, value.west)])
 
 ``pre_save(self, model_instance, add)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index 17187894c0..b7beb0b4be 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -751,6 +751,19 @@ In addition to ``extra_context``, the template's context will be:
 
 If the results are paginated, the context will contain these extra variables:
 
+    * **New in Django development version:** ``paginator``: An instance of
+      ``django.core.paginator.Paginator``.
+
+    * **New in Django development version:** ``page_obj``: An instance of
+      ``django.core.paginator.Page``.
+
+In older versions of Django, before ``paginator`` and ``page_obj`` were added
+to this template's context, the template included several other variables
+related to pagination. Note that you should *NOT* use these variables anymore;
+use ``paginator`` and ``page_obj`` instead, because they let you do everything
+these old variables let you do (and more!). But for legacy installations,
+here's a list of those old template variables:
+
     * ``results_per_page``: The number of objects per page. (Same as the
       ``paginate_by`` parameter.)
 
@@ -777,8 +790,8 @@ 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.
 
-    * **New in Django development version:** ``page_range``: A list of the 
-      page numbers that are available. This is 1-based.
+    * ``page_range``: A list of the page numbers that are available. This is
+      1-based.
 
 Notes on pagination
 ~~~~~~~~~~~~~~~~~~~
diff --git a/docs/install.txt b/docs/install.txt
index 542036e2af..341c4280e8 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -167,6 +167,20 @@ These commands will install Django in your Python installation's
 Installing the development version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. admonition:: Tracking Django development
+    
+    If you decide to use the latest development version of Django,
+    you'll want to pay close attention to `the development timeline`_,
+    and you'll want to keep an eye on `the list of
+    backwards-incompatible changes`_; this will help you stay on top
+    of any new features you might want to use, as well as any changes
+    you'll need to make to your code when updating your copy of Django
+    (for stable releases, any necessary changes are documented in the
+    release notes).
+
+.. _the development timeline: http://code.djangoproject.com/timeline
+.. _the list of backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
+
 If you'd like to be able to update your Django code occasionally with the
 latest bug fixes and improvements, follow these instructions:
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index e4d3805236..5502bd51eb 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -626,7 +626,8 @@ option is ignored.
 ``default``
 ~~~~~~~~~~~
 
-The default value for the field.
+The default value for the field. This can be a value or a callable object. If
+callable it will be called every time a new object is created.
 
 ``editable``
 ~~~~~~~~~~~~
@@ -1814,14 +1815,15 @@ For example::
 This example allows you to request ``Person.men.all()``, ``Person.women.all()``,
 and ``Person.people.all()``, yielding predictable results.
 
-If you use custom ``Manager`` objects, take note that the first ``Manager``
-Django encounters (in order by which they're defined in the model) has a
-special status. Django interprets the first ``Manager`` defined in a class as
-the "default" ``Manager``. Certain operations -- such as Django's admin site --
-use the default ``Manager`` to obtain lists of objects, so it's generally a
-good idea for the first ``Manager`` to be relatively unfiltered. In the last
-example, the ``people`` ``Manager`` is defined first -- so it's the default
-``Manager``.
+If you use custom ``Manager`` objects, take note that the first
+``Manager`` Django encounters (in the order in which they're defined
+in the model) has a special status. Django interprets this first
+``Manager`` defined in a class as the "default" ``Manager``, and
+several parts of Django (though not the admin application) will use
+that ``Manager`` exclusively for that model. As a result, it's often a
+good idea to be careful in your choice of default manager, in order to
+avoid a situation where overriding of ``get_query_set()`` results in
+an inability to retrieve objects you'd like to work with.
 
 Model methods
 =============
diff --git a/docs/modelforms.txt b/docs/modelforms.txt
index 47eaa9a769..05f9b1b3d4 100644
--- a/docs/modelforms.txt
+++ b/docs/modelforms.txt
@@ -231,6 +231,16 @@ For example::
     # Create and save the new author instance. There's no need to do anything else.
     >>> new_author = f.save()
 
+Other than the ``save()`` and ``save_m2m()`` methods, a ``ModelForm``
+works exactly the same way as any other ``newforms`` form. For
+example, the ``is_valid()`` method is used to check for validity, the
+``is_multipart()`` method is used to determine whether a form requires
+multipart file upload (and hence whether ``request.FILES`` must be
+passed to the form), etc.; see `the standard newforms documentation`_
+for more information.
+
+.. _the standard newforms documentation: ../newforms/
+
 Using a subset of fields on the form
 ------------------------------------
 
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 0b5559ab88..533ff75185 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -1333,13 +1333,14 @@ given length.
 
 An ``UploadedFile`` object has two attributes:
 
-    ======================  =====================================================
-    Argument                Description
-    ======================  =====================================================
+    ======================  ====================================================
+    Attribute               Description
+    ======================  ====================================================
     ``filename``            The name of the file, provided by the uploading
                             client.
+                            
     ``content``             The array of bytes comprising the file content.
-    ======================  =====================================================
+    ======================  ====================================================
 
 The string representation of an ``UploadedFile`` is the same as the filename
 attribute.
@@ -1349,6 +1350,38 @@ When you use a ``FileField`` on a form, you must also remember to
 
 .. _`bind the file data to the form`: `Binding uploaded files to a form`_
 
+``FilePathField``
+~~~~~~~~~~~~~~~~~
+
+**New in Django development version**
+
+    * Default widget: ``Select``
+    * Empty value: ``None``
+    * Normalizes to: A unicode object
+    * Validates that the selected choice exists in the list of choices.
+    * Error message keys: ``required``, ``invalid_choice``
+
+The field allows choosing from files inside a certain directory. It takes three
+extra arguments:
+
+    ==============  ==========  ===============================================
+    Argument        Required?   Description
+    ==============  ==========  ===============================================
+    ``path``        Yes         The absolute path to the directory whose 
+                                contents you want listed. This directory must 
+                                exist.
+                            
+    ``recursive``   No          If ``False`` (the default) only the direct
+                                contents of ``path`` will be offered as choices.
+                                If ``True``, the directory will be descended
+                                into recursively and all descendants will be
+                                listed as choices.
+                                
+    ``match``       No          A regular expression pattern; only files with
+                                names matching this expression will be allowed
+                                as choices.
+    ==============  ==========  ===============================================
+
 ``ImageField``
 ~~~~~~~~~~~~~~
 
@@ -1499,6 +1532,41 @@ the bottom of this document, for examples of their use.
 ``SplitDateTimeField``
 ~~~~~~~~~~~~~~~~~~~~~~
 
+Fields which handle relationships
+---------------------------------
+
+For representing relationships between models, two fields are
+provided which can derive their choices from a ``QuerySet``, and which
+place one or more model objects into the ``cleaned_data`` dictionary
+of forms in which they're used. Both of these fields have an
+additional required argument:
+
+``queryset``
+    A ``QuerySet`` of model objects from which the choices for the
+    field will be derived, and which will be used to validate the
+    user's selection.
+
+``ModelChoiceField``
+~~~~~~~~~~~~~~~~~~~~
+
+Allows the selection of a single model object, suitable for representing a
+foreign key. The method receives an object as an argument and must return a
+string to represent it.
+
+The labels for the choice field call the ``__unicode__`` method of the model to
+generate string representations. To provide custom labels, subclass ``ModelChoiceField`` and override ``label_for_model``::
+
+    class MyModelChoiceField(ModelChoiceField):
+        def label_from_instance(self, obj):
+            return "My Object #%i" % obj.id
+
+``ModelMultipleChoiceField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows the selection of one or more model objects, suitable for representing a
+many-to-many relation. As with ``ModelChoiceField``, you can use
+``label_from_instance`` to customize the object labels.
+
 Creating custom fields
 ----------------------
 
@@ -1569,9 +1637,9 @@ The three types of cleaning methods are:
 
 These methods are run in the order given above, one field at a time.  That is,
 for each field in the form (in the order they are declared in the form
-definition), the ``Field.clean()`` method (or it's override) is run, then
+definition), the ``Field.clean()`` method (or its override) is run, then
 ``clean_<fieldname>()``. Finally, once those two methods are run for every
-field, the ``Form.clean()`` method, or it's override, is executed.
+field, the ``Form.clean()`` method, or its override, is executed.
 
 As mentioned above, any of these methods can raise a ``ValidationError``. For
 any field, if the ``Field.clean()`` method raises a ``ValidationError``, any
@@ -1693,7 +1761,7 @@ For example, take the following simple form::
         comment = forms.CharField()
 
 This form will include three default TextInput widgets, with default rendering -
-no CSS class, no extra attributes. This means that the inputs boxes provided for
+no CSS class, no extra attributes. This means that the input boxes provided for
 each widget will be rendered exactly the same::
 
     >>> f = CommentForm(auto_id=False)
diff --git a/docs/pagination.txt b/docs/pagination.txt
new file mode 100644
index 0000000000..486c92264b
--- /dev/null
+++ b/docs/pagination.txt
@@ -0,0 +1,133 @@
+==========
+Pagination
+==========
+
+**New in Django development version**
+
+Django provides a few classes that help you manage paginated data -- that is,
+data that's split across several pages, with "Previous/Next" links. These
+classes live in the module ``django/core/paginator.py``.
+
+Example
+=======
+
+Give ``Paginator`` a list of objects, plus the number of items you'd like to
+have on each page, and it gives you methods for accessing the items for each
+page::
+
+    >>> from django.core.paginator import Paginator
+    >>> objects = ['john', 'paul', 'george', 'ringo']
+    >>> p = Paginator(objects, 2)
+
+    >>> p.count
+    4
+    >>> p.num_pages
+    2
+    >>> p.page_range
+    [1, 2]
+
+    >>> page1 = p.page(1)
+    >>> page1
+    <Page 1 of 2>
+    >>> page1.object_list
+    ['john', 'paul']
+
+    >>> page2 = p.page(2)
+    >>> page2.object_list
+    ['george', 'ringo']
+    >>> page2.has_next()
+    False
+    >>> page2.has_previous()
+    True
+    >>> page2.has_other_pages()
+    True
+    >>> page2.next_page_number()
+    3
+    >>> page2.previous_page_number()
+    1
+    >>> page2.start_index() # The 1-based index of the first item on this page
+    3
+    >>> page2.end_index() # The 1-based index of the last item on this page
+    4
+
+    >>> p.page(0)
+    Traceback (most recent call last):
+    ...
+    InvalidPage
+    >>> p.page(3)
+    Traceback (most recent call last):
+    ...
+    InvalidPage
+
+``Paginator`` objects
+=====================
+
+Methods
+-------
+
+``page(number)`` -- Returns a ``Page`` object with the given 1-based index.
+Raises ``InvalidPage`` if the given page number doesn't exist.
+
+Attributes
+----------
+
+``count`` -- The total number of objects, across all pages.
+
+``num_pages`` -- The total number of pages.
+
+``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
+
+``Page`` objects
+================
+
+Methods
+-------
+
+``has_next()`` -- Returns ``True`` if there's a next page.
+
+``has_previous()`` -- Returns ``True`` if there's a previous page.
+
+``has_other_pages()`` -- Returns ``True`` if there's a next *or* previous page.
+
+``next_page_number()`` -- Returns the next page number. Note that this is
+"dumb" and will return the next page number regardless of whether a subsequent
+page exists.
+
+``previous_page_number()`` -- Returns the previous page number. Note that this
+is "dumb" and will return the previous page number regardless of whether a
+previous page exists.
+
+``start_index()`` -- Returns the 1-based index of the first object on the page,
+relative to all of the objects in the paginator's list. For example, when
+paginating a list of 5 objects with 2 objects per page, the second page's
+``start_index()`` would return ``3``.
+
+``end_index()`` -- Returns the 1-based index of the last object on the page,
+relative to all of the objects in the paginator's list. For example, when
+paginating a list of 5 objects with 2 objects per page, the second page's
+``end_index()`` would return ``4``.
+
+Attributes
+----------
+
+``object_list`` -- The list of objects on this page.
+
+``number`` -- The 1-based page number for this page.
+
+``paginator`` -- The associated ``Paginator`` object.
+
+``QuerySetPaginator`` objects
+=============================
+
+Use ``QuerySetPaginator`` instead of ``Paginator`` if you're paginating across
+a ``QuerySet`` from Django's database API. This is slightly more efficient, and
+there are no API differences between the two classes.
+
+The legacy ``ObjectPaginator`` class
+====================================
+
+The ``Paginator`` and ``Page`` classes are new in the Django development
+version, as of revision 7306. In previous versions, Django provided an
+``ObjectPaginator`` class that offered similar functionality but wasn't as
+convenient. This class still exists, for backwards compatibility, but Django
+now issues a ``DeprecationWarning`` if you try to use it.
diff --git a/docs/request_response.txt b/docs/request_response.txt
index e50cfc5ea3..0e0f046a2d 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -141,6 +141,16 @@ All attributes except ``session`` should be considered read-only.
     The raw HTTP POST data. This is only useful for advanced processing. Use
     ``POST`` instead.
 
+``urlconf``
+    Not defined by Django itself, but will be read if other code
+    (e.g., a custom middleware class) sets it; when present, this will
+    be used as the root URLConf for the current request, overriding
+    the ``ROOT_URLCONF`` setting. See `How Django processes a
+    request`_ for details.
+
+.. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request
+
+
 Methods
 -------
 
@@ -189,6 +199,23 @@ Methods
    Returns ``True`` if the request is secure; that is, if it was made with
    HTTPS.
 
+``is_ajax()``
+   **New in Django development version**
+
+   Returns ``True`` if the request was made via an XMLHttpRequest by checking
+   the ``HTTP_X_REQUESTED_WITH`` header for the string *'XMLHttpRequest'*. The
+   following major Javascript libraries all send this header:
+
+   * jQuery
+   * Dojo
+   * MochiKit
+   * MooTools
+   * Prototype
+   * YUI
+
+   If you write your own XMLHttpRequest call (on the browser side), you will
+   have to set this header manually to use this method.
+
 QueryDict objects
 -----------------
 
diff --git a/docs/sessions.txt b/docs/sessions.txt
index 6355524d2e..d8bac5b8d4 100644
--- a/docs/sessions.txt
+++ b/docs/sessions.txt
@@ -48,10 +48,10 @@ Using file-based sessions
 To use file-based sessions, set the ``SESSION_ENGINE`` setting to
 ``"django.contrib.sessions.backends.file"``.
 
-You might also want to set the ``SESSION_FILE_PATH`` setting (which
-defaults to ``/tmp``) to control where Django stores session files. Be
-sure to check that your Web server has permissions to read and write to
-this location.
+You might also want to set the ``SESSION_FILE_PATH`` setting (which defaults
+to output from ``tempfile.gettempdir()``, most likely  ``/tmp``) to control
+where Django stores session files. Be sure to check that your Web server has
+permissions to read and write to this location.
 
 Using cache-based sessions
 --------------------------
diff --git a/docs/settings.txt b/docs/settings.txt
index 77e3c6692f..fb2e04f1ea 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -185,8 +185,11 @@ ADMIN_MEDIA_PREFIX
 
 Default: ``'/media/'``
 
-The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use
-a trailing slash.
+The URL prefix for admin media -- CSS, JavaScript and images used by
+the Django administrative interface. Make sure to use a trailing
+slash, and to have this be different from the ``MEDIA_URL`` setting
+(since the same URL cannot be mapped onto two different sets of
+files).
 
 ADMINS
 ------
@@ -754,7 +757,9 @@ ROOT_URLCONF
 Default: Not defined
 
 A string representing the full Python import path to your root URLconf. For example:
-``"mydjangoapps.urls"``. See `How Django processes a request`_.
+``"mydjangoapps.urls"``. Can be overridden on a per-request basis by
+setting the attribute ``urlconf`` on the incoming ``HttpRequest``
+object. See `How Django processes a request`_ for details.
 
 .. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request
 
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index ebd6af26f8..f86acfe54d 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -245,6 +245,13 @@ request to the URL ``/rss/beats/0613/``:
       subclass of ``ObjectDoesNotExist``. Raising ``ObjectDoesNotExist`` in
       ``get_object()`` tells Django to produce a 404 error for that request.
 
+      **New in Django development version:** The ``get_object()`` method also
+      has a chance to handle the ``/rss/beats/`` url.  In this case, ``bits``
+      will be an empty list. In our example, ``len(bits) != 1`` and an
+      ``ObjectDoesNotExist`` exception will be raised, so ``/rss/beats/`` will
+      generate a 404 page. But you can handle this case however you like.  For
+      example you could generate a combined feed for all beats.
+
     * To generate the feed's ``<title>``, ``<link>`` and ``<description>``,
       Django uses the ``title()``, ``link()`` and ``description()`` methods. In
       the previous example, they were simple string class attributes, but this
diff --git a/docs/templates.txt b/docs/templates.txt
index 3360b04178..ea9f3fb6b2 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -429,8 +429,9 @@ all block tags. For example::
     # base.html
 
     {% autoescape off %}
-    <h1>{% block title %}</h1>
+    <h1>{% block title %}{% endblock %}</h1>
     {% block content %}
+    {% endblock %}
     {% endautoescape %}
 
 
@@ -438,10 +439,11 @@ all block tags. For example::
 
     {% extends "base.html" %}
     {% block title %}This & that{% endblock %}
-    {% block content %}<b>Hello!</b>{% endblock %}
+    {% block content %}{{ greeting }}{% endblock %}
 
 Because auto-escaping is turned off in the base template, it will also be
-turned off in the child template, resulting in the following rendered HTML::
+turned off in the child template, resulting in the following rendered
+HTML when the ``greeting`` variable contains the string ``<b>Hello!</b>``::
 
     <h1>This & that</h1>
     <b>Hello!</b>
diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt
index bd16fa2924..473fba1ef8 100644
--- a/docs/tutorial04.txt
+++ b/docs/tutorial04.txt
@@ -37,6 +37,12 @@ A quick rundown:
       form will alter data server-side. Whenever you create a form that alters
       data server-side, use ``method="post"``. This tip isn't specific to
       Django; it's just good Web development practice.
+    
+    * ``forloop.counter`` indicates how many times the ``for`` tag has
+      gone through its loop; for more information, see `the
+      documentation for the "for" tag`_.
+
+.. _the documentation for the "for" tag: ../templates/#for
 
 Now, let's create a Django view that handles the submitted data and does
 something with it. Remember, in `Tutorial 3`_, we created a URLconf for the
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 789399de8d..053ee954a3 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -32,9 +32,11 @@ How Django processes a request
 When a user requests a page from your Django-powered site, this is the
 algorithm the system follows to determine which Python code to execute:
 
-    1. Django looks at the ``ROOT_URLCONF`` setting in your `settings file`_.
-       This should be a string representing the full Python import path to your
-       URLconf. For example: ``"mydjangoapps.urls"``.
+    1. Django determines the root URLConf module to use; ordinarily
+       this is the value of the ``ROOT_URLCONF`` setting in your
+       `settings file`_, but if the incoming ``HttpRequest`` object
+       has an attribute called ``urlconf``, its value will be used in
+       place of the ``ROOT_URLCONF`` setting.
     2. Django loads that Python module and looks for the variable
        ``urlpatterns``. This should be a Python list, in the format returned by
        the function ``django.conf.urls.defaults.patterns()``.