[soc2010/query-refactor] Merged up to trunk r13556, resolved merge conflictsarchive/soc2010/query-refactorsoc2010/query-refactor

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

12 files changed, 137 insertions, 27 deletions

diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt
index eae07ed717..480509961b 100644
--- a/docs/topics/auth.txt
+++ b/docs/topics/auth.txt
@@ -898,8 +898,9 @@ includes a few other useful built-in views located in
 
 .. function:: views.password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect])
 
-    Allows a user to reset their password, and sends them the new password
-    in an e-mail.
+    Allows a user to reset their password by generating a one-time use link
+    that can be used to reset the password, and sending that link to the
+    user's registered e-mail address.
 
     **Optional arguments:**
 
@@ -1005,8 +1006,8 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`:
 
 .. class:: PasswordResetForm
 
-    A form for resetting a user's password and e-mailing the new password to
-    them.
+    A form for generating and e-mailing a one-time use link to reset a
+    user's password.
 
 .. class:: SetPasswordForm
 
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 9dedbcf3b9..5e263aa543 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -136,6 +136,49 @@ settings file. You can't use a different database backend for your cache table.
 
 Database caching works best if you've got a fast, well-indexed database server.
 
+Database caching and multiple databases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you use database caching with multiple databases, you'll also need
+to set up routing instructions for your database cache table. For the
+purposes of routing, the database cache table appears as a model named
+``CacheEntry``, in an application named ``django_cache``. This model
+won't appear in the models cache, but the model details can be used
+for routing purposes.
+
+For example, the following router would direct all cache read
+operations to ``cache_slave``, and all write operations to
+``cache_master``. The cache table will only be synchronized onto
+``cache_master``::
+
+    class CacheRouter(object):
+        """A router to control all database cache operations"""
+
+        def db_for_read(self, model, **hints):
+            "All cache read operations go to the slave"
+            if model._meta.app_label in ('django_cache',):
+                return 'cache_slave'
+            return None
+
+        def db_for_write(self, model, **hints):
+            "All cache write operations go to master"
+            if model._meta.app_label in ('django_cache',):
+                return 'cache_master'
+            return None
+
+        def allow_syncdb(self, db, model):
+            "Only synchronize the cache model on master"
+            if model._meta.app_label in ('django_cache',):
+                return db == 'cache_master'
+            return None
+
+If you don't specify routing directions for the database cache model,
+the cache backend will use the ``default`` database.
+
+Of course, if you don't use the database cache backend, you don't need
+to worry about providing routing instructions for the database cache
+model.
+
 Filesystem caching
 ------------------
 
diff --git a/docs/topics/db/aggregation.txt b/docs/topics/db/aggregation.txt
index 087c1bf239..41580c94b6 100644
--- a/docs/topics/db/aggregation.txt
+++ b/docs/topics/db/aggregation.txt
@@ -353,7 +353,7 @@ without any harmful effects, since that is already playing a role in the
 query.
 
 This behavior is the same as that noted in the queryset documentation for
-:ref:`distinct() <queryset-distinct>` and the general rule is the same:
+:meth:`~django.db.models.QuerySet.distinct` and the general rule is the same:
 normally you won't want extra columns playing a part in the result, so clear
 out the ordering, or at least make sure it's restricted only to those fields
 you also select in a ``values()`` call.
diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt
index 123408b2bb..aa47e5dd15 100644
--- a/docs/topics/db/managers.txt
+++ b/docs/topics/db/managers.txt
@@ -170,7 +170,8 @@ and ``Person.people.all()``, yielding predictable results.
 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 the first ``Manager`` defined in a class as
-the "default" ``Manager``, and several parts of Django will use that ``Manager``
+the "default" ``Manager``, and several parts of Django
+(including :djadmin:`dumpdata`) will use that ``Manager``
 exclusively for that model. As a result, it's a good idea to be careful in
 your choice of default manager in order to avoid a situation where overriding
 ``get_query_set()`` results in an inability to retrieve objects you'd like to
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index 6d7a7a4374..78c578d61a 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -353,7 +353,7 @@ For example, if a ``Pizza`` has multiple ``Topping`` objects -- that is, a
 
 As with :class:`~django.db.models.ForeignKey`, you can also create
 :ref:`recursive relationships <recursive-relationships>` (an object with a
-many-to-one relationship to itself) and :ref:`relationships to models not yet
+many-to-many relationship to itself) and :ref:`relationships to models not yet
 defined <lazy-relationships>`; see :ref:`the model field reference
 <ref-manytomany>` for details.
 
diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt
index 5d74fc9ce9..bb40139f23 100644
--- a/docs/topics/db/optimization.txt
+++ b/docs/topics/db/optimization.txt
@@ -101,7 +101,7 @@ Use ``iterator()``
 
 When you have a lot of objects, the caching behaviour of the ``QuerySet`` can
 cause a large amount of memory to be used. In this case,
-:ref:`QuerySet.iterator() <queryset-iterator>` may help.
+:meth:`~django.db.models.QuerySet.iterator()` may help.
 
 Do database work in the database rather than in Python
 ======================================================
@@ -121,9 +121,9 @@ If these aren't enough to generate the SQL you need:
 Use ``QuerySet.extra()``
 ------------------------
 
-A less portable but more powerful method is :ref:`QuerySet.extra()
-<queryset-extra>`, which allows some SQL to be explicitly added to the query.
-If that still isn't powerful enough:
+A less portable but more powerful method is
+:meth:`~django.db.models.QuerySet.extra()`, which allows some SQL to be
+explicitly added to the query. If that still isn't powerful enough:
 
 Use raw SQL
 -----------
@@ -159,7 +159,7 @@ Use ``QuerySet.values()`` and ``values_list()``
 -----------------------------------------------
 
 When you just want a dict/list of values, and don't need ORM model objects, make
-appropriate usage of :ref:`QuerySet.values() <queryset-values>`.
+appropriate usage of :meth:`~django.db.models.QuerySet.values()`.
 These can be useful for replacing model objects in template code - as long as
 the dicts you supply have the same attributes as those used in the template, you
 are fine.
@@ -167,7 +167,8 @@ are fine.
 Use ``QuerySet.defer()`` and ``only()``
 ---------------------------------------
 
-Use :ref:`defer() and only() <queryset-defer>` if there are database columns you
+Use :meth:`~django.db.models.QuerySet.defer()` and
+:meth:`~django.db.models.QuerySet.only()` if there are database columns you
 know that you won't need (or won't need in most cases) to avoid loading
 them. Note that if you *do* use them, the ORM will have to go and get them in a
 separate query, making this a pessimization if you use it inappropriately.
diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt
index f55a164373..c3272da757 100644
--- a/docs/topics/db/sql.txt
+++ b/docs/topics/db/sql.txt
@@ -116,9 +116,9 @@ Fields may also be left out::
 
     >>> people = Person.objects.raw('SELECT id, first_name FROM myapp_person')
 
-The ``Person`` objects returned by this query will be :ref:`deferred
-<queryset-defer>` model instances. This means that the fields that are omitted
-from the query will be loaded on demand. For example::
+The ``Person`` objects returned by this query will be deferred model instances
+(see :meth:`~django.db.models.QuerySet.defer()`). This means that the fields
+that are omitted from the query will be loaded on demand. For example::
 
     >>> for p in Person.objects.raw('SELECT id, first_name FROM myapp_person'):
     ...     print p.first_name, # This will be retrieved by the original query
diff --git a/docs/topics/email.txt b/docs/topics/email.txt
index 74e153de61..8ea64dac1f 100644
--- a/docs/topics/email.txt
+++ b/docs/topics/email.txt
@@ -501,7 +501,7 @@ convenience that can be used during development.
 Defining a custom e-mail backend
 --------------------------------
 
-If you need to change how e-mails are send you can write your own e-mail
+If you need to change how e-mails are sent you can write your own e-mail
 backend. The ``EMAIL_BACKEND`` setting in your settings file is then the
 Python import path for your backend class.
 
diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index fd3edf5104..02cce34fbc 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -595,8 +595,8 @@ Alternatively, you can create a subclass that sets ``self.queryset`` in
 
     class BaseAuthorFormSet(BaseModelFormSet):
         def __init__(self, *args, **kwargs):
-            self.queryset = Author.objects.filter(name__startswith='O')
             super(BaseAuthorFormSet, self).__init__(*args, **kwargs)
+            self.queryset = Author.objects.filter(name__startswith='O')
 
 Then, pass your ``BaseAuthorFormSet`` class to the factory function::
 
diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
index 5a2980f9d2..d5746c52f2 100644
--- a/docs/topics/http/urls.txt
+++ b/docs/topics/http/urls.txt
@@ -827,17 +827,80 @@ namespaces into URLs on specific application instances, according to the
 resolve()
 ---------
 
-The :func:`django.core.urlresolvers.resolve` function can be used for resolving
-URL paths to the corresponding view functions. It has the following signature:
+The :func:`django.core.urlresolvers.resolve` function can be used for
+resolving URL paths to the corresponding view functions. It has the
+following signature:
 
 .. function:: resolve(path, urlconf=None)
 
-``path`` is the URL path you want to resolve. As with ``reverse()`` above, you
-don't need to worry about the ``urlconf`` parameter. The function returns the
-triple (view function, arguments, keyword arguments).
+``path`` is the URL path you want to resolve. As with
+:func:`~django.core.urlresolvers.reverse`, you don't need to
+worry about the ``urlconf`` parameter. The function returns a
+:class:`django.core.urlresolvers.ResolverMatch` object that allows you
+to access various meta-data about the resolved URL.
 
-For example, it can be used for testing if a view would raise a ``Http404``
-error before redirecting to it::
+.. class:: ResolverMatch()
+
+    .. attribute:: ResolverMatch.func
+
+        The view function that would be used to serve the URL
+
+    .. attribute:: ResolverMatch.args
+
+        The arguments that would be passed to the view function, as
+        parsed from the URL.
+
+    .. attribute:: ResolverMatch.kwargs
+
+        The keyword arguments that would be passed to the view
+        function, as parsed from the URL.
+
+    .. attribute:: ResolverMatch.url_name
+
+        The name of the URL pattern that matches the URL.
+
+    .. attribute:: ResolverMatch.app_name
+
+        The application namespace for the URL pattern that matches the
+        URL.
+
+    .. attribute:: ResolverMatch.namespace
+
+        The instance namespace for the URL pattern that matches the
+        URL.
+
+    .. attribute:: ResolverMatch.namespaces
+
+        The list of individual namespace components in the full
+        instance namespace for the URL pattern that matches the URL.
+        i.e., if the namespace is ``foo:bar``, then namespaces will be
+        ``[`foo`, `bar`]``.
+
+A :class:`~django.core.urlresolvers.ResolverMatch` object can then be
+interrogated to provide information about the URL pattern that matches
+a URL::
+
+    # Resolve a URL
+    match = resolve('/some/path/')
+    # Print the URL pattern that matches the URL
+    print match.url_name
+
+A :class:`~django.core.urlresolvers.ResolverMatch` object can also be
+assigned to a triple::
+
+    func, args, kwargs = resolve('/some/path/')
+
+.. versionchanged:: 1.3
+    Triple-assignment exists for backwards-compatibility. Prior to
+    Django 1.3, :func:`~django.core.urlresolvers.resolve` returned a
+    triple containing (view function, arguments, keyword arguments);
+    the :class:`~django.core.urlresolvers.ResolverMatch` object (as
+    well as the namespace and pattern information it provides) is not
+    available in earlier Django releases.
+
+One possible use of :func:`~django.core.urlresolvers.resolve` would be
+to testing if a view would raise a ``Http404`` error before
+redirecting to it::
 
     from urlparse import urlparse
     from django.core.urlresolvers import resolve
@@ -858,6 +921,7 @@ error before redirecting to it::
             return HttpResponseRedirect('/')
         return response
 
+
 permalink()
 -----------
 
diff --git a/docs/topics/i18n/internationalization.txt b/docs/topics/i18n/internationalization.txt
index 7ae8d18791..35e76c3d62 100644
--- a/docs/topics/i18n/internationalization.txt
+++ b/docs/topics/i18n/internationalization.txt
@@ -569,7 +569,7 @@ function supports both positional and named interpolation:
       object or associative array. For example::
 
         d = {
-            count: 10
+            count: 10,
             total: 50
         };
 
diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt
index c5155107f0..b99a3b925e 100644
--- a/docs/topics/serialization.txt
+++ b/docs/topics/serialization.txt
@@ -338,7 +338,7 @@ example, ``(first name, last name)``. Then, when you call
 ``serializers.serialize()``, you provide a ``use_natural_keys=True``
 argument::
 
-    >>> serializers.serialize([book1, book2], format='json', indent=2, use_natural_keys=True)
+    >>> serializers.serialize('json', [book1, book2], indent=2, use_natural_keys=True)
 
 When ``use_natural_keys=True`` is specified, Django will use the
 ``natural_key()`` method to serialize any reference to objects of the