queryset-refactor: Merged to [6190]

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

9 files changed, 119 insertions, 32 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index f5da56ddf9..2a1f428ae7 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -799,6 +799,9 @@ of the arguments is required, but you should use at least one of them.
 
         Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
 
+    The combined number of placeholders in the list of strings for ``select``
+    or ``where`` should equal the number of values in the ``params`` list.
+
 QuerySet methods that do not return QuerySets
 ---------------------------------------------
 
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index 33c39b7e12..a00a49d8be 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -201,6 +201,10 @@ a date in the *future* are not included unless you set ``allow_future`` to
       specified in ``date_field`` is greater than the current date/time. By
       default, this is ``False``.
 
+    * **New in Django development version:** ``template_object_name``:
+      Designates the name of the template variable to use in the template
+      context. By default, this is ``'latest'``.
+
 **Template name:**
 
 If ``template_name`` isn't specified, this view will use the template
@@ -221,10 +225,16 @@ In addition to ``extra_context``, the template's context will be:
       years that have objects available according to ``queryset``. These are
       ordered in reverse. This is equivalent to
       ``queryset.dates(date_field, 'year')[::-1]``.
+
     * ``latest``: The ``num_latest`` objects in the system, ordered descending
       by ``date_field``. For example, if ``num_latest`` is ``10``, then
       ``latest`` will be a list of the latest 10 objects in ``queryset``.
 
+      **New in Django development version:** This variable's name depends on
+      the ``template_object_name`` parameter, which is ``'latest'`` by default.
+      If ``template_object_name`` is ``'foo'``, this variable's name will be
+      ``foo``.
+
 .. _RequestContext docs: ../templates_python/#subclassing-context-requestcontext
 
 ``django.views.generic.date_based.archive_year``
@@ -764,8 +774,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.
 
-    * ``page_range``: A list of the page numbers that are available. This
-      is 1-based.
+    * **New in Django development version:** ``page_range``: A list of the 
+    page numbers that are available. This is 1-based.
 
 Notes on pagination
 ~~~~~~~~~~~~~~~~~~~
@@ -788,7 +798,11 @@ specify the page number in the URL in one of two ways:
       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 
+represented as page ``1``. 
+
+**New in Django development version:** 
+
+As a special case, you are also permitted to use 
 ``last`` as a value for ``page``::
 
     /objects/?page=last
diff --git a/docs/install.txt b/docs/install.txt
index 082000149f..9300c7f0f8 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -127,16 +127,24 @@ Installing an official release
 
     1. Download the latest release from our `download page`_.
 
-    2. Untar the downloaded file (e.g. ``tar xzvf Django-NNN.tar.gz``).
+    2. Untar the downloaded file (e.g. ``tar xzvf Django-NNN.tar.gz``,
+       where ``NNN`` is the version number of the latest release).
+       If you're using Windows, you can download the command-line tool
+       bsdtar_ to do this, or you can use a GUI-based tool such as 7-zip_.
 
-    3. Change into the downloaded directory (e.g. ``cd Django-NNN``).
+    3. Change into the directory created in step 2 (e.g. ``cd Django-NNN``).
 
-    4. Run ``sudo python setup.py install``.
+    4. If you're using Linux, Mac OS X or some other flavor of Unix, enter
+       the command ``sudo python setup.py install`` at the shell prompt.
+       If you're using Windows, start up a command shell with administrator
+       privileges and run the command ``setup.py install``.
 
-The command will install Django in your Python installation's ``site-packages``
-directory.
+These commands will install Django in your Python installation's
+``site-packages`` directory.
 
 .. _distribution specific notes: ../distributions/
+.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
+.. _7-zip: http://www.7-zip.org/
 
 Installing the development version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -144,34 +152,55 @@ Installing the development version
 If you'd like to be able to update your Django code occasionally with the
 latest bug fixes and improvements, follow these instructions:
 
-1. Make sure you have Subversion_ installed.
-2. Check out the Django code into your Python ``site-packages`` directory.
+1. Make sure that you have Subversion_ installed, and that you can run its
+   commands from a shell. (Enter ``svn help`` at a shell prompt to test
+   this.)
 
-   On Linux / Mac OSX / Unix, do this::
+2. Check out Django's main development branch (the 'trunk') like so::
 
-       svn co http://code.djangoproject.com/svn/django/trunk/ django_src
-       ln -s `pwd`/django_src/django SITE-PACKAGES-DIR/django
+       svn co http://code.djangoproject.com/svn/django/trunk/ django-trunk
+
+3. Next, make sure that the Python interpreter can load Django's code. There
+   are various ways of accomplishing this.  One of the most convenient, on
+   Linux, Mac OSX or other Unix-like systems, is to use a symbolic link::
+
+       ln -s `pwd`/django-trunk/django SITE-PACKAGES-DIR/django
 
    (In the above line, change ``SITE-PACKAGES-DIR`` to match the location of
    your system's ``site-packages`` directory, as explained in the
    "Where are my ``site-packages`` stored?" section above.)
 
-   On Windows, do this::
+   Alternatively, you can define your ``PYTHONPATH`` environment variable
+   so that it includes the ``django`` subdirectory of ``django-trunk``.
+   This is perhaps the most convenient solution on Windows systems, which
+   don't support symbolic links. (Environment variables can be defined on
+   Windows systems `from the Control Panel`_.)
+
+   .. admonition:: What about Apache and mod_python?
+
+      If you take the approach of setting ``PYTHONPATH``, you'll need to
+      remember to do the same thing in your Apache configuration once you
+      deploy your production site. Do this by setting ``PythonPath`` in your
+      Apache configuration file.
+
+      More information about deployment is available, of course, in our
+      `How to use Django with mod_python`_ documentation.
 
-       svn co http://code.djangoproject.com/svn/django/trunk/django c:\Python24\lib\site-packages\django
+      .. _How to use Django with mod_python: ../modpython/
 
-3. Copy the file ``django_src/django/bin/django-admin.py`` to somewhere on your
-   system path, such as ``/usr/local/bin`` (Unix) or ``C:\Python24\Scripts``
+4. Copy the file ``django-trunk/django/bin/django-admin.py`` to somewhere on
+   your system path, such as ``/usr/local/bin`` (Unix) or ``C:\Python24\Scripts``
    (Windows). This step simply lets you type ``django-admin.py`` from within
    any directory, rather than having to qualify the command with the full path
    to the file.
 
-You *don't* have to run ``python setup.py install``, because that command
-takes care of steps 2 and 3 for you.
+You *don't* have to run ``python setup.py install``, because you've already
+carried out the equivalent actions in steps 3 and 4.
 
 When you want to update your copy of the Django source code, just run the
-command ``svn update`` from within the ``django`` directory. When you do this,
-Subversion will automatically download any changes.
+command ``svn update`` from within the ``django-trunk`` directory. When you do
+this, Subversion will automatically download any changes.
 
 .. _`download page`: http://www.djangoproject.com/download/
 .. _Subversion: http://subversion.tigris.org/
+.. _from the Control Panel: http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/sysdm_advancd_environmnt_addchange_variable.mspx
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 44488ae1d8..27207aab6f 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1550,8 +1550,8 @@ Finally, note that in order to use ``list_display_links``, you must define
 
 Set ``list_filter`` to activate filters in the right sidebar of the change list
 page of the admin. This should be a list of field names, and each specified
-field should be either a ``BooleanField``, ``DateField``, ``DateTimeField``
-or ``ForeignKey``.
+field should be either a ``BooleanField``, ``CharField``, ``DateField``, 
+``DateTimeField``, ``IntegerField`` or ``ForeignKey``. 
 
 This example, taken from the ``django.contrib.auth.models.User`` model, shows
 how both ``list_display`` and ``list_filter`` work::
diff --git a/docs/modpython.txt b/docs/modpython.txt
index cbed0ee8c3..4a8c169a51 100644
--- a/docs/modpython.txt
+++ b/docs/modpython.txt
@@ -83,7 +83,7 @@ need to write your ``PythonPath`` directive as::
 With this path, ``import weblog`` and ``import mysite.settings`` will both
 work. If you had ``import blogroll`` in your code somewhere and ``blogroll``
 lived under the ``weblog/`` directory, you would *also* need to add
-``/var/production/django-apps/weblog/`` to your ``PythonPath``. Remember: the
+``/usr/local/django-apps/weblog/`` to your ``PythonPath``. Remember: the
 **parent directories** of anything you import directly must be on the Python
 path.
 
diff --git a/docs/request_response.txt b/docs/request_response.txt
index 1eef41659a..bf914fb5ff 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -161,6 +161,18 @@ Methods
 
    Example: ``"/music/bands/the_beatles/?print=true"``
 
+``build_absolute_uri(location)``
+   **New in Django development version**
+
+   Returns the absolute URI form of ``location``. If no location is provided,
+   the location will be set to ``request.get_full_path()``.
+
+   If the location is already an absolute URI, it will not be altered.
+   Otherwise the absolute URI is built using the server variables available in
+   this request.
+
+   Example: ``"http://example.com/music/bands/the_beatles/?print=true"``
+
 ``is_secure()``
    Returns ``True`` if the request is secure; that is, if it was made with
    HTTPS.
@@ -184,8 +196,8 @@ 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``).
+      does not exist. (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
diff --git a/docs/sites.txt b/docs/sites.txt
index e7a8ecbfa6..5896afcf41 100644
--- a/docs/sites.txt
+++ b/docs/sites.txt
@@ -213,6 +213,31 @@ To do this, you can use the sites framework. A simple example::
     >>> 'http://%s%s' % (Site.objects.get_current().domain, obj.get_absolute_url())
     'http://example.com/mymodel/objects/3/'
 
+Caching the current ``Site`` object
+===================================
+
+**New in Django development version**
+
+As the current site is stored in the database, each call to
+``Site.objects.get_current()`` could result in a database query. But Django is a
+little cleverer than that: on the first request, the current site is cached, and
+any subsequent call returns the cached data instead of hitting the database.
+
+If for any reason you want to force a database query, you can tell Django to
+clear the cache using ``Site.objects.clear_cache()``::
+
+    # First call; current site fetched from database.
+    current_site = Site.objects.get_current()
+    # ...
+
+    # Second call; current site fetched from cache.
+    current_site = Site.objects.get_current()
+    # ...
+
+    # Force a database query for the third call.
+    Site.objects.clear_cache()
+    current_site = Site.objects.get_current()
+
 The ``CurrentSiteManager``
 ==========================
 
diff --git a/docs/templates.txt b/docs/templates.txt
index ff67579b87..0c8cc79311 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -1431,4 +1431,4 @@ Read the document `The Django template language: For Python programmers`_ if
 you're interested in learning the template system from a technical
 perspective -- how it works and how to extend it.
 
-.. _The Django template language: For Python programmers: ../templates_python/
+.. _The Django template language\: For Python programmers: ../templates_python/
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 150aa70fdf..3399639611 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -642,12 +642,12 @@ your function. Example::
         "Converts a string into all lowercase"
         return value.lower()
 
-Template filters which expect strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Template filters that 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::
+If you're writing a template filter that only expects a string as the first
+argument, you should use the decorator ``stringfilter``. This will
+convert an object to its string value before being passed to your function::
 
     from django.template.defaultfilters import stringfilter
 
@@ -655,6 +655,10 @@ convert an object to it's string value before being passed to your function::
     def lower(value):
         return value.lower()
 
+This way, you'll be able to pass, say, an integer to this filter, and it
+won't cause an ``AttributeError`` (because integers don't have ``lower()``
+methods).
+
 Registering a custom filters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~