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

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

11 files changed, 90 insertions, 28 deletions

diff --git a/docs/authentication.txt b/docs/authentication.txt
index aee9c5224a..2c34c6663d 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -170,7 +170,7 @@ The ``User`` model has a custom manager that has the following helper functions:
 
       If no password is provided, ``set_unusable_password()`` will be called.
 
-      See _`Creating users` for example usage.
+      See `Creating users`_ for example usage.
 
     * ``make_random_password(length=10, allowed_chars='abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789')``
       Returns a random password with the given length and given string of
diff --git a/docs/cache.txt b/docs/cache.txt
index 4f177b8c07..6dfe2bf5ee 100644
--- a/docs/cache.txt
+++ b/docs/cache.txt
@@ -263,6 +263,18 @@ See the `middleware documentation`_ for more on middleware.
 
 .. _`middleware documentation`: ../middleware/
 
+**New in Django development version**
+
+If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in
+its ``Cache-Control`` header) then the page will be cached until the expiry
+time, rather than ``CACHE_MIDDLEWARE_SECONDS``. Using the decorators in
+``django.views.decorators.cache`` you can easily set a view's expiry time
+(using the ``cache_control`` decorator) or disable caching for a view (using
+the ``never_cache`` decorator). See the `using other headers`__ section for
+more on these decorators.
+
+__ `Controlling cache: Using other headers`_
+
 The per-view cache
 ==================
 
@@ -566,7 +578,7 @@ the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom
 precedence, and the header values will be merged correctly.)
 
 If you want to use headers to disable caching altogether,
-``django.views.decorators.never_cache`` is a view decorator that adds
+``django.views.decorators.cache.never_cache`` is a view decorator that adds
 headers to ensure the response won't be cached by browsers or other caches. Example::
 
     from django.views.decorators.cache import never_cache
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index e751a7b3d9..2977f9908f 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -184,9 +184,9 @@ is being executed as an unattended, automated script.
 Use ``--verbosity`` to specify the amount of notification and debug information
 that ``django-admin.py`` should print to the console.
 
-	* ``0`` means no input.
-	* ``1`` means normal input (default).
-	* ``2`` means verbose input.
+	* ``0`` means no output.
+	* ``1`` means normal output (default).
+	* ``2`` means verbose output.
 
 Example usage::
 
@@ -651,7 +651,7 @@ To run the test server on port 7000 with ``fixture1`` and ``fixture2``::
 that it doesn't matter whether the options come before or after the fixture
 arguments.)
 
-To run on 1.2.3.4:7000 with a `test` fixture::
+To run on 1.2.3.4:7000 with a ``test`` fixture::
 
     django-admin.py testserver --addrport 1.2.3.4:7000 test
 
diff --git a/docs/install.txt b/docs/install.txt
index 519bf2674c..08444d3a1a 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -187,10 +187,10 @@ latest bug fixes and improvements, follow these instructions:
    "Where are my ``site-packages`` stored?" section above.)
 
    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`_.)
+   so that it includes the ``django-trunk`` directory. 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?
 
@@ -204,11 +204,18 @@ latest bug fixes and improvements, follow these instructions:
 
       .. _How to use Django with mod_python: ../modpython/
 
-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.
+4. On Unix-like systems, create a symbolic link to the file
+   ``django-trunk/django/bin/django-admin.py`` in a directory on your system
+   path, such as ``/usr/local/bin``. For example::
+
+       ln -s `pwd`/django-trunk/django/bin/django-admin.py /usr/local/bin
+
+   This 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.
+
+   On Windows systems, the same result can be achieved by copying the file
+   ``django-trunk/django/bin/django-admin.py`` to somewhere on your system
+   path, for example ``C:\Python24\Scripts``.
 
 You *don't* have to run ``python setup.py install``, because you've already
 carried out the equivalent actions in steps 3 and 4.
diff --git a/docs/model-api.txt b/docs/model-api.txt
index ca84c84d09..f39b711e84 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -50,7 +50,7 @@ The above ``Person`` model would create a database table like this::
 Some technical notes:
 
     * The name of the table, ``myapp_person``, is automatically derived from
-      some model metadata but can be overridden. See _`Table names` below.
+      some model metadata but can be overridden. See `Table names`_ below.
     * An ``id`` field is added automatically, but this behavior can be
       overriden. See `Automatic primary key fields`_ below.
     * The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL
@@ -1664,7 +1664,7 @@ Adding extra Manager methods
 
 Adding extra ``Manager`` methods is the preferred way to add "table-level"
 functionality to your models. (For "row-level" functionality -- i.e., functions
-that act on a single instance of a model object -- use _`Model methods`, not
+that act on a single instance of a model object -- use `Model methods`_, not
 custom ``Manager`` methods.)
 
 A custom ``Manager`` method can return anything you want. It doesn't have to
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 593e9216d7..810982d788 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -753,6 +753,30 @@ For example::
     </ul>
     </form>
 
+Highlighting required fields in templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may wish to show a visitor which fields are required. Here is the above
+example modified to insert an asterix after the label of each required field::
+
+    <form method="post" action="">
+    <dl>
+    {% for field in form %}
+        <dt>{{ field.label_tag }}{{ field.label }}{% if field.field.required %}*{% endif %}</dt>
+        <dd>{{ field }}</dd>
+        {% if field.help_text %}<dd>{{ field.help_text }}</dd>{% endif %}
+        {% if field.errors %}<dd class="myerrors">{{ field.errors }}</dd>{% endif %}
+    {% endfor %}
+    </dl>
+    <input type="submit" />
+    </form>
+
+The ``{% if field.field.required %}*{% endif %}`` fragment is the relevant
+addition here. It adds the asterix only if the field is required. Note that we
+check ``field.field.required`` and not ``field.required``. In the template,
+``field`` is a ``newforms.forms.BoundField`` instance, which holds the actual
+``Field`` instance in its ``field`` attribute.
+
 Binding uploaded files to a form
 --------------------------------
 
@@ -1849,7 +1873,11 @@ In addition, each generated form field has attributes set as follows:
 
     * If the model field has ``choices`` set, then the form field's ``widget``
       will be set to ``Select``, with choices coming from the model field's
-      ``choices``.
+      ``choices``. The choices will normally include the blank choice which is
+      selected by default. If the field is required, this forces the user to
+      make a selection. The blank choice will not be included if the model
+      field has ``blank=False`` and an explicit ``default`` value (the
+      ``default`` value will be initially selected instead).
 
 Finally, note that you can override the form field used for a given model
 field. See "Overriding the default field types" below.
@@ -2095,10 +2123,14 @@ instance instead of a model class::
     # Instantiate the form.
     >>> f = AuthorForm()
 
-When a form created by ``form_for_instance()`` is created, the initial
-data values for the form fields are drawn from the instance. However,
-this data is not bound to the form. You will need to bind data to the
-form before the form can be saved.
+When a form created by ``form_for_instance()`` is created, the initial data
+values for the form fields are drawn from the instance. However, this data is
+not bound to the form. You will need to bind data to the form before the form
+can be saved.
+
+Unlike ``form_for_model()``, a choice field in form created by
+``form_for_instance()`` will not include the blank choice if the respective
+model field has ``blank=False``. The initial choice is drawn from the instance.
 
 When you call ``save()`` on a form created by ``form_for_instance()``,
 the database instance will be updated. As in ``form_for_model()``, ``save()``
diff --git a/docs/release_notes_0.96.txt b/docs/release_notes_0.96.txt
index 4227de8155..59931541e1 100644
--- a/docs/release_notes_0.96.txt
+++ b/docs/release_notes_0.96.txt
@@ -44,7 +44,7 @@ to this::
     DATABASE_ENGINE = "mysql_old"
 
 However, we strongly encourage MySQL users to upgrade to a more recent
-version of `MySQLdb` as soon as possible, The "mysql_old" backend is
+version of ``MySQLdb`` as soon as possible, The "mysql_old" backend is
 provided only to ease this transition, and is considered deprecated;
 aside from any necessary security fixes, it will not be actively
 maintained, and it will be removed in a future release of Django.
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index 30943591b8..2eb188a737 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -201,6 +201,8 @@ the feed.
 
 An example makes this clear. Here's the code for these beat-specific feeds::
 
+    from django.contrib.syndication import FeedDoesNotExist
+
     class BeatFeed(Feed):
         def get_object(self, bits):
             # In case of "/rss/beats/0613/foo/bar/baz/", or other such clutter,
@@ -213,6 +215,8 @@ An example makes this clear. Here's the code for these beat-specific feeds::
             return "Chicagocrime.org: Crimes for beat %s" % obj.beat
 
         def link(self, obj):
+            if not obj:
+                raise FeedDoesNotExist
             return obj.get_absolute_url()
 
         def description(self, obj):
@@ -246,11 +250,18 @@ request to the URL ``/rss/beats/0613/``:
       each of ``title``, ``link`` and ``description``, Django follows this
       algorithm:
 
-          * First, it tries to call a method, passing the ``obj`` argument, where
-            ``obj`` is the object returned by ``get_object()``.
+          * First, it tries to call a method, passing the ``obj`` argument,
+            where ``obj`` is the object returned by ``get_object()``.
           * Failing that, it tries to call a method with no arguments.
           * Failing that, it uses the class attribute.
 
+      Inside the ``link()`` method, we handle the possibility that ``obj``
+      might be ``None``, which can occur when the URL isn't fully specified. In
+      some cases, you might want to do something else in this case, which would
+      mean you'd need to check for ``obj`` existing in other methods as well
+      (the ``link()`` method is called very early in the feed generation
+      process, so is a good place to bail out early).
+
     * Finally, note that ``items()`` in this example also takes the ``obj``
       argument. The algorithm for ``items`` is the same as described in the
       previous step -- first, it tries ``items(obj)``, then ``items()``, then
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 5ac93f5a58..64b67a1333 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -1183,7 +1183,7 @@ on the object being edited -- so they're a perfect case for using a small
 template that is filled with details from the current object. (In the admin's
 case, this is the ``submit_row`` tag.)
 
-These sorts of tags are called `inclusion tags`.
+These sorts of tags are called "inclusion tags".
 
 Writing inclusion tags is probably best demonstrated by example. Let's write a
 tag that outputs a list of choices for a given ``Poll`` object, such as was
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 9e0c287346..b84ecd5f7e 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -47,7 +47,7 @@ will create a ``mysite`` directory in your current directory.
    denied" when you try to run ``django-admin.py startproject``. This
    is because, on Unix-based systems like OS X, a file must be marked
    as "executable" before it can be run as a program. To do this, open
-   Terminal.app and navigate (using the `cd` command) to the directory
+   Terminal.app and navigate (using the ``cd`` command) to the directory
    where ``django-admin.py`` is installed, then run the command
    ``chmod +x django-admin.py``.
 
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 76a4e1b5f0..6ed7043fd5 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -237,7 +237,7 @@ include
 -------
 
 A function that takes a full Python import path to another URLconf that should
-be "included" in this place. See _`Including other URLconfs` below.
+be "included" in this place. See `Including other URLconfs`_ below.
 
 Notes on capturing text in URLs
 ===============================