[soc2010/test-refactor] Merged back up to trunk

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

10 files changed, 178 insertions, 130 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 4d84dfafbc..1fbae3f060 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -474,17 +474,16 @@ change list page. By default, this is set to ``100``.
 
 .. attribute:: ModelAdmin.list_select_related
 
-Set ``list_select_related`` to tell Django to use ``select_related()`` in
-retrieving the list of objects on the admin change list page. This can save you
-a bunch of database queries.
+Set ``list_select_related`` to tell Django to use
+:meth:`~django.db.models.QuerySet.select_related` in retrieving the list of
+objects on the admin change list page. This can save you a bunch of database
+queries.
 
 The value should be either ``True`` or ``False``. Default is ``False``.
 
-Note that Django will use ``select_related()``, regardless of this setting,
-if one of the ``list_display`` fields is a ``ForeignKey``.
-
-For more on ``select_related()``, see
-:ref:`the select_related() docs <select-related>`.
+Note that Django will use :meth:`~django.db.models.QuerySet.select_related`,
+regardless of this setting, if one of the ``list_display`` fields is a
+``ForeignKey``.
 
 .. attribute:: ModelAdmin.inlines
 
@@ -595,11 +594,16 @@ This should be set to a list of field names that will be searched whenever
 somebody submits a search query in that text box.
 
 These fields should be some kind of text field, such as ``CharField`` or
-``TextField``. You can also perform a related lookup on a ``ForeignKey`` with
-the lookup API "follow" notation::
+``TextField``. You can also perform a related lookup on a ``ForeignKey`` or
+``ManyToManyField`` with the lookup API "follow" notation::
 
     search_fields = ['foreign_key__related_fieldname']
 
+For example, if you have a blog entry with an author, the following definition
+would enable search blog entries by the email address of the author::
+
+    search_fields = ['user__email']
+
 When somebody does a search in the admin search box, Django splits the search
 query into words and returns all objects that contain each of the words, case
 insensitive, where each word must be in at least one of ``search_fields``. For
@@ -865,11 +869,26 @@ return a subset of objects for this foreign key field based on the user::
         def formfield_for_foreignkey(self, db_field, request, **kwargs):
             if db_field.name == "car":
                 kwargs["queryset"] = Car.objects.filter(owner=request.user)
-                return db_field.formfield(**kwargs)
             return super(MyModelAdmin, self).formfield_for_foreignkey(db_field, request, **kwargs)
 
 This uses the ``HttpRequest`` instance to filter the ``Car`` foreign key field
-to only the cars owned by the ``User`` instance.
+to only display the cars owned by the ``User`` instance.
+
+.. method:: ModelAdmin.formfield_for_manytomany(self, db_field, request, **kwargs)
+
+.. versionadded:: 1.1
+
+Like the ``formfield_for_foreignkey`` method, the ``formfield_for_manytomany``
+method can be overridden to change the default formfield for a many to many
+field. For example, if an owner can own multiple cars and cars can belong
+to multiple owners -- a many to many relationship -- you could filter the
+``Car`` foreign key field to only display the cars owned by the ``User``::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        def formfield_for_manytomany(self, db_field, request, **kwargs):
+            if db_field.name == "cars":
+                kwargs["queryset"] = Car.objects.filter(owner=request.user)
+            return super(MyModelAdmin, self).formfield_for_manytomany(db_field, request, **kwargs)
 
 .. method:: ModelAdmin.queryset(self, request)
 
diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt
index 3085bf3ee9..da5d934d38 100644
--- a/docs/ref/contrib/contenttypes.txt
+++ b/docs/ref/contrib/contenttypes.txt
@@ -324,15 +324,19 @@ same types of lookups manually::
     ...                           object_id=b.id)
     [<TaggedItem: django>, <TaggedItem: python>]
 
-Note that if the model with a :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
-that you're referring to uses a non-default value for ``ct_field`` or ``fk_field``
-(e.g. the :mod:`django.contrib.comments` app uses ``ct_field="object_pk"``),
-you'll need to pass ``content_type_field`` and ``object_id_field`` to
-:class:`~django.contrib.contenttypes.generic.GenericRelation`.::
+Note that if the model in a
+:class:`~django.contrib.contenttypes.generic.GenericRelation` uses a
+non-default value for ``ct_field`` or ``fk_field`` in its
+:class:`~django.contrib.contenttypes.generic.GenericForeignKey` (e.g. the
+:mod:`django.contrib.comments` app uses ``ct_field="object_pk"``),
+you'll need to set ``content_type_field`` and/or ``object_id_field`` in
+the :class:`~django.contrib.contenttypes.generic.GenericRelation` to
+match the ``ct_field`` and ``fk_field``, respectively, in the
+:class:`~django.contrib.contenttypes.generic.GenericForeignKey`::
 
-	comments = generic.GenericRelation(Comment, content_type_field="content_type", object_id_field="object_pk")
+	comments = generic.GenericRelation(Comment, object_id_field="object_pk")
 
-Note that if you delete an object that has a
+Note also, that if you delete an object that has a
 :class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects
 which have a :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
 pointing at it will be deleted as well. In the example above, this means that
diff --git a/docs/ref/contrib/formtools/form-wizard.txt b/docs/ref/contrib/formtools/form-wizard.txt
index 5ef862ce3d..8dcebd1d6f 100644
--- a/docs/ref/contrib/formtools/form-wizard.txt
+++ b/docs/ref/contrib/formtools/form-wizard.txt
@@ -189,8 +189,10 @@ for the wizard to work properly.
 Hooking the wizard into a URLconf
 =================================
 
-Finally, give your new :class:`FormWizard` object a URL in ``urls.py``. The
-wizard takes a list of your :class:`~django.forms.Form` objects as arguments::
+Finally, we need to specify which forms to use in the wizard, and then
+deploy the new :class:`FormWizard` object a URL in ``urls.py``. The
+wizard takes a list of your :class:`~django.forms.Form` objects as
+arguments when you instantiate the Wizard::
 
     from django.conf.urls.defaults import *
     from mysite.testapp.forms import ContactForm1, ContactForm2, ContactWizard
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 542a71582d..83aa97240c 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -227,6 +227,11 @@ pretty-print the output with a number of indentation spaces.
 The :djadminopt:`--exclude` option may be provided to prevent specific
 applications from being dumped.
 
+.. versionadded:: 1.3
+
+The :djadminopt:`--exclude` option may also be provided to prevent specific
+models (specified as in the form of ``appname.ModelName``) from being dumped.
+
 .. versionadded:: 1.1
 
 In addition to specifying application names, you can provide a list of
@@ -957,6 +962,7 @@ that ``django-admin.py`` should print to the console.
     * ``0`` means no output.
     * ``1`` means normal output (default).
     * ``2`` means verbose output.
+    * ``3`` means *very* verbose output.
 
 Common options
 ==============
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index 1fc2bfa85d..e82fae7761 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -6,7 +6,7 @@ Widgets
 
 .. module:: django.forms.widgets
    :synopsis: Django's built-in form widgets.
-   
+
 .. currentmodule:: django.forms
 
 A widget is Django's representation of a HTML input element. The widget
@@ -29,7 +29,12 @@ commonly used groups of widgets:
     .. attribute:: PasswordInput.render_value
 
         Determines whether the widget will have a value filled in when the
-        form is re-displayed after a validation error (default is ``True``).
+        form is re-displayed after a validation error (default is ``False``).
+
+.. versionchanged:: 1.3
+    The default value for
+    :attr:`~PasswordInput.render_value` was
+    changed from ``True`` to ``False``
 
 .. class:: HiddenInput
 
@@ -50,7 +55,7 @@ commonly used groups of widgets:
     Date input as a simple text box: ``<input type='text' ...>``
 
     Takes one optional argument:
-    
+
     .. attribute:: DateInput.format
 
         The format in which this field's initial value will be displayed.
@@ -64,11 +69,11 @@ commonly used groups of widgets:
     Date/time input as a simple text box: ``<input type='text' ...>``
 
     Takes one optional argument:
-    
+
     .. attribute:: DateTimeInput.format
-    
+
         The format in which this field's initial value will be displayed.
-    
+
     If no ``format`` argument is provided, the default format is ``'%Y-%m-%d
     %H:%M:%S'``.
 
@@ -77,11 +82,11 @@ commonly used groups of widgets:
     Time input as a simple text box: ``<input type='text' ...>``
 
     Takes one optional argument:
-    
+
     .. attribute:: TimeInput.format
-    
+
         The format in which this field's initial value will be displayed.
-    
+
     If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``.
 
     .. versionchanged:: 1.1
@@ -98,15 +103,15 @@ commonly used groups of widgets:
     Takes one optional argument:
 
     .. attribute:: CheckboxInput.check_test
-     
-        A callable that takes the value of the CheckBoxInput 
+
+        A callable that takes the value of the CheckBoxInput
         and returns ``True`` if the checkbox should be checked for
-        that value. 
+        that value.
 
 .. class:: Select
 
     Select widget: ``<select><option ...>...</select>``
-    
+
     Requires that your field provides :attr:`~Field.choices`.
 
 .. class:: NullBooleanSelect
@@ -123,22 +128,22 @@ commonly used groups of widgets:
 .. class:: RadioSelect
 
     A list of radio buttons:
-    
+
     .. code-block:: html
-    
+
         <ul>
           <li><input type='radio' ...></li>
           ...
         </ul>
-        
+
     Requires that your field provides :attr:`~Field.choices`.
 
 .. class:: CheckboxSelectMultiple
 
     A list of checkboxes:
-    
+
     .. code-block:: html
-    
+
         <ul>
           <li><input type='checkbox' ...></li>
           ...
@@ -155,7 +160,7 @@ commonly used groups of widgets:
 
     Takes two optional arguments, ``date_format`` and ``time_format``, which
     work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.
-    
+
     .. versionchanged:: 1.1
        The ``date_format`` and ``time_format`` arguments were not supported in Django 1.0.
 
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 56ff6444e4..91d1415043 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -332,8 +332,6 @@ a model which defines a default ordering, or when using
 ordering was undefined prior to calling ``reverse()``, and will remain
 undefined afterward).
 
-.. _queryset-distinct:
-
 ``distinct()``
 ~~~~~~~~~~~~~~
 
@@ -367,9 +365,6 @@ query spans multiple tables, it's possible to get duplicate results when a
     ``values()`` together, be careful when ordering by fields not in the
     ``values()`` call.
 
-
-.. _queryset-values:
-
 ``values(*fields)``
 ~~~~~~~~~~~~~~~~~~~
 
@@ -679,8 +674,6 @@ related object.
 ``OneToOneFields`` will not be traversed in the reverse direction if you
 are performing a depth-based ``select_related``.
 
-.. _queryset-extra:
-
 ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -843,8 +836,6 @@ of the arguments is required, but you should use at least one of them.
 
         Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
 
-.. _queryset-defer:
-
 ``defer(*fields)``
 ~~~~~~~~~~~~~~~~~~
 
@@ -1143,8 +1134,6 @@ Example::
 
 If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.
 
-.. _queryset-iterator:
-
 ``iterator()``
 ~~~~~~~~~~~~~~
 
diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt
index 2c874a1a83..d111e4c127 100644
--- a/docs/ref/request-response.txt
+++ b/docs/ref/request-response.txt
@@ -498,11 +498,11 @@ Methods
 .. method:: HttpResponse.__delitem__(header)
 
     Deletes the header with the given name. Fails silently if the header
-    doesn't exist. Case-sensitive.
+    doesn't exist. Case-insensitive.
 
 .. method:: HttpResponse.__getitem__(header)
 
-    Returns the value for the given header name. Case-sensitive.
+    Returns the value for the given header name. Case-insensitive.
 
 .. method:: HttpResponse.has_header(header)
 
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 53fbfb2ffe..f3c5656a9a 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -152,18 +152,6 @@ Default: ``600``
 The default number of seconds to cache a page when the caching middleware or
 ``cache_page()`` decorator is used.
 
-.. setting:: CSRF_COOKIE_NAME
-
-CSRF_COOKIE_NAME
-----------------
-
-.. versionadded:: 1.2
-
-Default: ``'csrftoken'``
-
-The name of the cookie to use for the CSRF authentication token. This can be whatever you
-want.  See :ref:`ref-contrib-csrf`.
-
 .. setting:: CSRF_COOKIE_DOMAIN
 
 CSRF_COOKIE_DOMAIN
@@ -179,6 +167,18 @@ request forgery protection.  It should be set to a string such as
 ``".lawrence.com"`` to allow a POST request from a form on one subdomain to be
 accepted by accepted by a view served from another subdomain.
 
+.. setting:: CSRF_COOKIE_NAME
+
+CSRF_COOKIE_NAME
+----------------
+
+.. versionadded:: 1.2
+
+Default: ``'csrftoken'``
+
+The name of the cookie to use for the CSRF authentication token. This can be whatever you
+want.  See :ref:`ref-contrib-csrf`.
+
 .. setting:: CSRF_FAILURE_VIEW
 
 CSRF_FAILURE_VIEW
@@ -573,29 +573,29 @@ Default: ``'webmaster@localhost'``
 Default e-mail address to use for various automated correspondence from the
 site manager(s).
 
-.. setting:: DEFAULT_TABLESPACE
+.. setting:: DEFAULT_INDEX_TABLESPACE
 
-DEFAULT_TABLESPACE
-------------------
+DEFAULT_INDEX_TABLESPACE
+------------------------
 
 .. versionadded:: 1.0
 
 Default: ``''`` (Empty string)
 
-Default tablespace to use for models that don't specify one, if the
-backend supports it.
+Default tablespace to use for indexes on fields that don't specify
+one, if the backend supports it.
 
-.. setting:: DEFAULT_INDEX_TABLESPACE
+.. setting:: DEFAULT_TABLESPACE
 
-DEFAULT_INDEX_TABLESPACE
-------------------------
+DEFAULT_TABLESPACE
+------------------
 
 .. versionadded:: 1.0
 
 Default: ``''`` (Empty string)
 
-Default tablespace to use for indexes on fields that don't specify
-one, if the backend supports it.
+Default tablespace to use for models that don't specify one, if the
+backend supports it.
 
 .. setting:: DISALLOWED_USER_AGENTS
 
@@ -738,21 +738,6 @@ Default: ``2621440`` (i.e. 2.5 MB).
 The maximum size (in bytes) that an upload will be before it gets streamed to
 the file system. See :ref:`topics-files` for details.
 
-.. setting:: FILE_UPLOAD_TEMP_DIR
-
-FILE_UPLOAD_TEMP_DIR
---------------------
-
-.. versionadded:: 1.0
-
-Default: ``None``
-
-The directory to store data temporarily while uploading files. If ``None``,
-Django will use the standard temporary directory for the operating system. For
-example, this will default to '/tmp' on \*nix-style operating systems.
-
-See :ref:`topics-files` for details.
-
 .. setting:: FILE_UPLOAD_PERMISSIONS
 
 FILE_UPLOAD_PERMISSIONS
@@ -781,6 +766,21 @@ system's standard umask.
 
 .. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod
 
+.. setting:: FILE_UPLOAD_TEMP_DIR
+
+FILE_UPLOAD_TEMP_DIR
+--------------------
+
+.. versionadded:: 1.0
+
+Default: ``None``
+
+The directory to store data temporarily while uploading files. If ``None``,
+Django will use the standard temporary directory for the operating system. For
+example, this will default to '/tmp' on \*nix-style operating systems.
+
+See :ref:`topics-files` for details.
+
 .. setting:: FIRST_DAY_OF_WEEK
 
 FIRST_DAY_OF_WEEK
@@ -1227,27 +1227,6 @@ Default: ``'root@localhost'``
 The e-mail address that error messages come from, such as those sent to
 ``ADMINS`` and ``MANAGERS``.
 
-.. setting:: SESSION_ENGINE
-
-SESSION_ENGINE
---------------
-
-.. versionadded:: 1.0
-
-.. versionchanged:: 1.1
-   The ``cached_db`` backend was added
-
-Default: ``django.contrib.sessions.backends.db``
-
-Controls where Django stores session data. Valid values are:
-
-    * ``'django.contrib.sessions.backends.db'``
-    * ``'django.contrib.sessions.backends.file'``
-    * ``'django.contrib.sessions.backends.cache'``
-    * ``'django.contrib.sessions.backends.cached_db'``
-
-See :ref:`topics-http-sessions`.
-
 .. setting:: SESSION_COOKIE_AGE
 
 SESSION_COOKIE_AGE
@@ -1306,6 +1285,27 @@ Whether to use a secure cookie for the session cookie. If this is set to
 ensure that the cookie is only sent under an HTTPS connection.
 See the :ref:`topics-http-sessions`.
 
+.. setting:: SESSION_ENGINE
+
+SESSION_ENGINE
+--------------
+
+.. versionadded:: 1.0
+
+.. versionchanged:: 1.1
+   The ``cached_db`` backend was added
+
+Default: ``django.contrib.sessions.backends.db``
+
+Controls where Django stores session data. Valid values are:
+
+    * ``'django.contrib.sessions.backends.db'``
+    * ``'django.contrib.sessions.backends.file'``
+    * ``'django.contrib.sessions.backends.cache'``
+    * ``'django.contrib.sessions.backends.cached_db'``
+
+See :ref:`topics-http-sessions`.
+
 .. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE
 
 SESSION_EXPIRE_AT_BROWSER_CLOSE
@@ -1601,6 +1601,20 @@ A boolean that specifies whether to output the "Etag" header. This saves
 bandwidth but slows down performance. This is only used if ``CommonMiddleware``
 is installed (see :ref:`topics-http-middleware`).
 
+.. setting:: USE_I18N
+
+USE_I18N
+--------
+
+Default: ``True``
+
+A boolean that specifies whether Django's internationalization system should be
+enabled. This provides an easy way to turn it off, for performance. If this is
+set to ``False``, Django will make some optimizations so as not to load the
+internationalization machinery.
+
+See also ``USE_L10N``
+
 .. setting:: USE_L10N
 
 USE_L10N
@@ -1616,20 +1630,6 @@ format of the current locale.
 
 See also ``USE_I18N`` and ``LANGUAGE_CODE``
 
-.. setting:: USE_I18N
-
-USE_I18N
---------
-
-Default: ``True``
-
-A boolean that specifies whether Django's internationalization system should be
-enabled. This provides an easy way to turn it off, for performance. If this is
-set to ``False``, Django will make some optimizations so as not to load the
-internationalization machinery.
-
-See also ``USE_L10N``
-
 .. setting:: USE_THOUSAND_SEPARATOR
 
 USE_THOUSAND_SEPARATOR
diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt
index 12372dd0f1..a4dc0f705d 100644
--- a/docs/ref/signals.txt
+++ b/docs/ref/signals.txt
@@ -33,9 +33,9 @@ module system.
     If you override these methods on your model, you must call the parent class'
     methods for this signals to be sent.
 
-	Note also that Django stores signal handlers as weak references by default,
-	so if your handler is a local function, it may be garbage collected.  To
-	prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
+    Note also that Django stores signal handlers as weak references by default,
+    so if your handler is a local function, it may be garbage collected.  To
+    prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
 
 pre_init
 --------
@@ -113,6 +113,9 @@ Arguments sent with this signal:
     ``instance``
         The actual instance being saved.
 
+    ``using``
+        The database alias being used.
+
 post_save
 ---------
 
@@ -133,6 +136,9 @@ Arguments sent with this signal:
     ``created``
         A boolean; ``True`` if a new record was created.
 
+    ``using``
+        The database alias being used.
+
 pre_delete
 ----------
 
@@ -150,6 +156,9 @@ Arguments sent with this signal:
     ``instance``
         The actual instance being deleted.
 
+    ``using``
+        The database alias being used.
+
 post_delete
 -----------
 
@@ -170,6 +179,9 @@ Arguments sent with this signal:
         Note that the object will no longer be in the database, so be very
         careful what you do with this instance.
 
+    ``using``
+        The database alias being used.
+
 m2m_changed
 -----------
 
@@ -215,8 +227,8 @@ Arguments sent with this signal:
             Sent *after* the relation is cleared
 
     ``reverse``
-    	Indicates which side of the relation is updated (i.e., if it is the
-    	forward or reverse relation that is being modified).
+        Indicates which side of the relation is updated (i.e., if it is the
+        forward or reverse relation that is being modified).
 
     ``model``
         The class of the objects that are added to, removed from or cleared
@@ -228,6 +240,9 @@ Arguments sent with this signal:
 
         For the ``"clear"`` action, this is ``None``.
 
+    ``using``
+        The database alias being used.
+
 For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled
 like this:
 
@@ -266,6 +281,8 @@ the arguments sent to a :data:`m2m_changed` handler would be:
                     ``Pizza``)
 
     ``pk_set``      ``[t.id]`` (since only ``Topping t`` was added to the relation)
+
+    ``using``       ``"default"`` (since the default router sends writes here)
     ==============  ============================================================
 
 And if we would then do something like this:
@@ -293,6 +310,8 @@ the arguments sent to a :data:`m2m_changed` handler would be:
 
     ``pk_set``      ``[p.id]`` (since only ``Pizza p`` was removed from the
                     relation)
+
+    ``using``       ``"default"`` (since the default router sends writes here)
     ==============  ============================================================
 
 class_prepared
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 002aa3f416..0cf445cab7 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -1883,6 +1883,8 @@ For example::
 
 If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is ..."``.
 
+Newlines within the string will be removed.
+
 .. templatefilter:: truncatewords_html
 
 truncatewords_html
@@ -1902,6 +1904,8 @@ For example::
 If ``value`` is ``"<p>Joel is a slug</p>"``, the output will be
 ``"<p>Joel is ...</p>"``.
 
+Newlines in the HTML content will be preserved.
+
 .. templatefilter:: unordered_list
 
 unordered_list