[multi-db] Merged trunk to 3950. Some tests still failing.

git-svn-id: http://code.djangoproject.com/svn/django/branches/multiple-db-support@4155 bcc190cf-cafb-0310-a4f2-bffc1f526a37

14 files changed, 131 insertions, 43 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 0d1f049601..2f0c8b0589 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -876,15 +876,18 @@ The database API supports the following lookup types:
 exact
 ~~~~~
 
-Exact match.
+Exact match. If the value provided for comparison is ``None``, it will 
+be interpreted as an SQL ``NULL`` (See isnull_ for more details).  
 
-Example::
+Examples::
 
     Entry.objects.get(id__exact=14)
+    Entry.objects.get(id__exact=None)
 
-SQL equivalent::
+SQL equivalents::
 
     SELECT ... WHERE id = 14;
+    SELECT ... WHERE id = NULL;
 
 iexact
 ~~~~~~
@@ -1103,8 +1106,8 @@ such as January 3, July 3, etc.
 isnull
 ~~~~~~
 
-``NULL`` or ``IS NOT NULL`` match. Takes either ``True`` or ``False``, which
-correspond to ``IS NULL`` and ``IS NOT NULL``, respectively.
+Takes either ``True`` or ``False``, which correspond to SQL queries of 
+``IS NULL`` and ``IS NOT NULL``, respectively.
 
 Example::
 
@@ -1114,6 +1117,14 @@ SQL equivalent::
 
     SELECT ... WHERE pub_date IS NULL;
 
+.. admonition:: ``__isnull=True`` vs ``__exact=None``
+
+    There is an important difference between ``__isnull=True`` and 
+    ``__exact=None``. ``__exact=None`` will *always* return an empty result
+    set, because SQL requires that no value is equal to ``NULL``. 
+    ``__isnull`` determines if the field is currently holding the value 
+    of ``NULL`` without performing a comparison.
+
 search
 ~~~~~~
 
diff --git a/docs/faq.txt b/docs/faq.txt
index c7f92d3580..eaccc6be43 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -227,9 +227,7 @@ When will you release Django 1.0?
 
 Short answer: When we're comfortable with Django's APIs, have added all
 features that we feel are necessary to earn a "1.0" status, and are ready to
-begin maintaining backwards compatibility. This should happen in a couple of
-months or so, although it's entirely possible that it could happen earlier.
-That translates into summer 2006.
+begin maintaining backwards compatibility. 
 
 The merging of Django's `magic-removal branch`_ went a long way toward Django
 1.0.
diff --git a/docs/forms.txt b/docs/forms.txt
index 767225cfd4..4a4ba37289 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -211,7 +211,7 @@ Below is the finished view::
     def create_place(request):
         manipulator = Place.AddManipulator()
 
-        if request.POST:
+        if request.method == 'POST':
             # If data was POSTed, we're trying to create a new Place.
             new_data = request.POST.copy()
 
@@ -309,7 +309,7 @@ about editing an existing one? It's shockingly similar to creating a new one::
         # Grab the Place object in question for future use.
         place = manipulator.original_object
 
-        if request.POST:
+        if request.method == 'POST':
             new_data = request.POST.copy()
             errors = manipulator.get_validation_errors(new_data)
             if not errors:
@@ -391,7 +391,7 @@ Here's a simple function that might drive the above form::
 
     def contact_form(request):
         manipulator = ContactManipulator()
-        if request.POST:
+        if request.method == 'POST':
             new_data = request.POST.copy()
             errors = manipulator.get_validation_errors(new_data)
             if not errors:
@@ -579,7 +579,7 @@ fails. If no message is passed in, a default message is used.
 ``ValidateIfOtherFieldEquals``
     Takes three parameters: ``other_field``, ``other_value`` and
     ``validator_list``, in that order. If ``other_field`` has a value of
-    ``other_vaue``, then the validators in ``validator_list`` are all run
+    ``other_value``, then the validators in ``validator_list`` are all run
     against the current field.
 
 ``RequiredIfOtherFieldNotGiven``
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index fdab97de27..f0c3f738f3 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -92,6 +92,13 @@ which is a dictionary of the parameters captured in the URL.
 
     * ``template``: The full name of a template to use.
 
+**Optional arguments:**
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+      
 **Example:**
 
 Given the following URL patterns::
@@ -171,7 +178,7 @@ a date in the *future* are not included unless you set ``allow_future`` to
       template. By default, it's ``django.template.loader``.
 
     * ``extra_context``: A dictionary of values to add to the template
-      context. By default, this is an empty dictionary.
+      context. By default, this is an empty dictionary. If a value in the
       dictionary is callable, the generic view will call it
       just before rendering the template.
 
@@ -184,7 +191,7 @@ a date in the *future* are not included unless you set ``allow_future`` to
       the view's template. See the `RequestContext docs`_.
 
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
-      to the value of the ``DEFAULT_MIME_TYPE`` setting.
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
@@ -270,7 +277,7 @@ to ``True``.
       this is ``False``.
 
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
-      to the value of the ``DEFAULT_MIME_TYPE`` setting.
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
@@ -357,7 +364,7 @@ date in the *future* are not displayed unless you set ``allow_future`` to
        determining the variable's name.
 
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
-      to the value of the ``DEFAULT_MIME_TYPE`` setting.
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
@@ -438,7 +445,7 @@ in the *future* are not displayed unless you set ``allow_future`` to ``True``.
        determining the variable's name.
 
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
-      to the value of the ``DEFAULT_MIME_TYPE`` setting.
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
@@ -523,7 +530,7 @@ you set ``allow_future`` to ``True``.
        determining the variable's name.
 
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
-      to the value of the ``DEFAULT_MIME_TYPE`` setting.
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
@@ -633,7 +640,7 @@ future, the view will throw a 404 error by default, unless you set
        to use in the template context. By default, this is ``'object'``.
 
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
-      to the value of the ``DEFAULT_MIME_TYPE`` setting.
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
@@ -707,7 +714,7 @@ A page representing a list of objects.
        determining the variable's name.
 
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
-      to the value of the ``DEFAULT_MIME_TYPE`` setting.
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 
 **Template name:**
 
@@ -819,7 +826,7 @@ A page representing an individual object.
        to use in the template context. By default, this is ``'object'``.
 
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
-      to the value of the ``DEFAULT_MIME_TYPE`` setting.
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
 
 **Template name:**
 
diff --git a/docs/install.txt b/docs/install.txt
index fb1bd73122..ff8e1a8318 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -84,9 +84,12 @@ Installing the official version
 
 Note that the last command will automatically download and install setuptools_
 if you don't already have it installed. This requires a working Internet
+connection and may cause problems on Python 2.5. If you run into problems,
+try using our development version by following the instructions below. The
+development version no longer uses setuptools nor requires an Internet
 connection.
 
-This will install Django in your Python installation's ``site-packages``
+The command will install Django in your Python installation's ``site-packages``
 directory.
 
 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
@@ -94,19 +97,34 @@ directory.
 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. ``svn co http://code.djangoproject.com/svn/django/trunk/ django_src``
-3. Symlink ``django_src/django`` so that ``django`` is within your Python
-   ``site-packages`` directory:
+2. Check out the Django code into your Python ``site-packages`` directory.
+   On Linux / Mac OSX / Unix, do this::
 
-   ``ln -s `pwd`/django_src/django /usr/lib/python2.3/site-packages/django``
+       svn co http://code.djangoproject.com/svn/django/trunk/ django_src
+       ln -s `pwd`/django_src/django /usr/lib/python2.3/site-packages/django
 
    (In the above line, change ``python2.3`` to match your current Python version.)
 
-You don't have to run ``python setup.py install``.
+   On Windows, do this::
+
+       svn co http://code.djangoproject.com/svn/django/trunk/django c:\Python24\lib\site-packages\django
+
+4. 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``
+   (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 3 and 4 for you.
 
-When you want to update your code, just run the command ``svn update`` from
-within the ``django_src`` directory.
+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.
 
 .. _`download page`: http://www.djangoproject.com/download/
 .. _Subversion: http://subversion.tigris.org/
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 5524c76654..1aa8c811f4 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -188,7 +188,8 @@ JavaScript shortcuts.
 ~~~~~~~~~~~~~~
 
 A ``CharField`` that checks that the value is a valid e-mail address.
-This doesn't accept ``maxlength``.
+This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to
+75.
 
 ``FileField``
 ~~~~~~~~~~~~~
diff --git a/docs/modpython.txt b/docs/modpython.txt
index b88874d3d3..5177abf728 100644
--- a/docs/modpython.txt
+++ b/docs/modpython.txt
@@ -43,6 +43,11 @@ This tells Apache: "Use mod_python for any URL at or under '/mysite/', using the
 Django mod_python handler." It passes the value of ``DJANGO_SETTINGS_MODULE``
 so mod_python knows which settings to use.
 
+Note that we're using the ``<Location>`` directive, not the ``<Directory>``
+directive. The latter is used for pointing at places on your filesystem,
+whereas ``<Location>`` points at places in the URL structure of a Web site.
+``<Directory>`` would be meaningless here.
+
 Also, if you've manually altered your ``PYTHONPATH`` to put your Django project
 on it, you'll need to tell mod_python::
 
diff --git a/docs/request_response.txt b/docs/request_response.txt
index 1f3b9d5804..006ac6b648 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -341,9 +341,9 @@ hard-coded strings. If you use this technique, follow these guidelines:
 Methods
 -------
 
-``__init__(content='', mimetype=DEFAULT_MIME_TYPE)``
+``__init__(content='', mimetype=DEFAULT_CONTENT_TYPE)``
     Instantiates an ``HttpResponse`` object with the given page content (a
-    string) and MIME type. The ``DEFAULT_MIME_TYPE`` is ``'text/html'``.
+    string) and MIME type. The ``DEFAULT_CONTENT_TYPE`` is ``'text/html'``.
 
     ``content`` can be an iterator or a string. If it's an iterator, it should
     return strings, and those strings will be joined together to form the
diff --git a/docs/settings.txt b/docs/settings.txt
index 3f6e9b0e79..2253faf5ff 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -528,7 +528,7 @@ any code that uses ``LANGUAGES`` at runtime.
 MANAGERS
 --------
 
-Default: ``ADMINS`` (Whatever ``ADMINS`` is set to)
+Default: ``()`` (Empty tuple)
 
 A tuple in the same format as ``ADMINS`` that specifies who should get
 broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``.
diff --git a/docs/templates.txt b/docs/templates.txt
index b263a64aec..92d4b53660 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -109,6 +109,21 @@ Some tags require beginning and ending tags (i.e.
 below describes all the built-in tags. You can create your own tags, if you
 know how to write Python code.
 
+Comments
+========
+
+**New in Django development version**
+
+To comment-out part of a template, use the comment syntax: ``{# #}``.
+
+For example, this template would render as ``'hello'``::
+
+    {# greeting #}hello
+
+A comment can contain any template code, invalid or not. For example::
+
+    {# {% if foo %}bar{% else %} #}
+
 Template inheritance
 ====================
 
@@ -785,8 +800,12 @@ The argument tells which template bit to output:
     ``closevariable``   ``}}``
     ``openbrace``       ``{``
     ``closebrace``      ``}``
+    ``opencomment``     ``{#``
+    ``closecomment``    ``#}``
     ==================  =======
 
+Note: ``opencomment`` and ``closecomment`` are new in the Django development version.
+
 widthratio
 ~~~~~~~~~~
 
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 8129b209c7..ae2582d7b8 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -212,6 +212,21 @@ template tags. If an invalid variable is provided to one of these template
 tags, the variable will be interpreted as ``None``. Filters are always
 applied to invalid variables within these template tags.
 
+.. admonition:: For debug purposes only!
+
+    While ``TEMPLATE_STRING_IF_INVALID`` can be a useful debugging tool, 
+    it is a bad idea to turn it on as a 'development default'. 
+    
+    Many templates, including those in the Admin site, rely upon the 
+    silence of the template system when a non-existent variable is 
+    encountered. If you assign a value other than ``''`` to
+    ``TEMPLATE_STRING_IF_INVALID``, you will experience rendering 
+    problems with these templates and sites.
+    
+    Generally, ``TEMPLATE_STRING_IF_INVALID`` should only be enabled 
+    in order to debug a specific template problem, then cleared 
+    once debugging is complete.
+        
 Playing with Context objects
 ----------------------------
 
@@ -296,6 +311,20 @@ optional, third positional argument, ``processors``. In this example, the
             'foo': 'bar',
         }, [ip_address_processor])
 
+Note::
+    If you're using Django's ``render_to_response()`` shortcut to populate a
+    template with the contents of a dictionary, your template will be passed a
+    ``Context`` instance by default (not a ``RequestContext``). To use a
+    ``RequestContext`` in your template rendering, pass an optional third
+    argument to ``render_to_response()``: a ``RequestContext``
+    instance. Your code might look like this::
+
+        def some_view(request):
+            # ...
+            return render_to_response('my_template'html',
+                                      my_data_dictionary,
+                                      context_instance=RequestContext(request))
+
 Here's what each of the default processors does:
 
 .. _HttpRequest object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects
@@ -1063,7 +1092,7 @@ Configuring the template system in standalone mode
 .. note::
 
     This section is only of interest to people trying to use the template
-    system as an output component in another application. If you are using the
+    system as an output component in another application. If you're using the
     template system as part of a Django application, nothing here applies to
     you.
 
@@ -1080,7 +1109,7 @@ described in the `settings file`_ documentation. Simply import the appropriate
 pieces of the templating system and then, *before* you call any of the
 templating functions, call ``django.conf.settings.configure()`` with any
 settings you wish to specify. You might want to consider setting at least
-``TEMPLATE_DIRS`` (if you are going to use template loaders),
+``TEMPLATE_DIRS`` (if you're going to use template loaders),
 ``DEFAULT_CHARSET`` (although the default of ``utf-8`` is probably fine) and
 ``TEMPLATE_DEBUG``. All available settings are described in the
 `settings documentation`_, and any setting starting with *TEMPLATE_*
diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt
index bc1717e67c..f6d4045fa3 100644
--- a/docs/tutorial02.txt
+++ b/docs/tutorial02.txt
@@ -377,16 +377,16 @@ By default, ``TEMPLATE_DIRS`` is empty. So, let's add a line to it, to tell
 Django where our templates live::
 
     TEMPLATE_DIRS = (
-        "/home/mytemplates", # Change this to your own directory.
+        "/home/my_username/mytemplates", # Change this to your own directory.
     )
 
 Now copy the template ``admin/base_site.html`` from within the default Django
 admin template directory (``django/contrib/admin/templates``) into an ``admin``
 subdirectory of whichever directory you're using in ``TEMPLATE_DIRS``. For
-example, if your ``TEMPLATE_DIRS`` includes ``"/home/mytemplates"``, as above,
-then copy ``django/contrib/admin/templates/admin/base_site.html`` to
-``/home/mytemplates/admin/base_site.html``. Don't forget that ``admin``
-subdirectory.
+example, if your ``TEMPLATE_DIRS`` includes ``"/home/my_username/mytemplates"``,
+as above, then copy ``django/contrib/admin/templates/admin/base_site.html`` to
+``/home/my_username/mytemplates/admin/base_site.html``. Don't forget that
+``admin`` subdirectory.
 
 Then, just edit the file and replace the generic Django text with your own
 site's name and URL as you see fit.
diff --git a/docs/tutorial03.txt b/docs/tutorial03.txt
index b4f1d303dc..c4c1b4c546 100644
--- a/docs/tutorial03.txt
+++ b/docs/tutorial03.txt
@@ -257,7 +257,7 @@ provides a shortcut. Here's the full ``index()`` view, rewritten::
     from mysite.polls.models import Poll
 
     def index(request):
-        latest_poll_list = Poll.objects.all().order_by('-pub_date')
+        latest_poll_list = Poll.objects.all().order_by('-pub_date')[:5]
         return render_to_response('polls/index.html', {'latest_poll_list': latest_poll_list})
 
 Note that we no longer need to import ``loader``, ``Context`` or
diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt
index c5e2ea3cea..49ed649cff 100644
--- a/docs/tutorial04.txt
+++ b/docs/tutorial04.txt
@@ -192,13 +192,13 @@ objects" and "display a detail page for a particular type of object."
       ``object_id`` for the generic views.
 
 By default, the ``object_detail`` generic view uses a template called
-``<app name>/<module name>_detail.html``. In our case, it'll use the template
+``<app name>/<model name>_detail.html``. In our case, it'll use the template
 ``"polls/poll_detail.html"``. Thus, rename your ``polls/detail.html`` template to
 ``polls/poll_detail.html``, and change the ``render_to_response()`` line in
 ``vote()``.
 
 Similarly, the ``object_list`` generic view uses a template called
-``<app name>/<module name>_list.html``. Thus, rename ``polls/index.html`` to
+``<app name>/<model name>_list.html``. Thus, rename ``polls/index.html`` to
 ``polls/poll_list.html``.
 
 Because we have more than one entry in the URLconf that uses ``object_detail``