gis: Merged revisions 4564-4668 via svnmerge from

http://code.djangoproject.com/svn/django/trunk

git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@4669 bcc190cf-cafb-0310-a4f2-bffc1f526a37

15 files changed, 657 insertions, 45 deletions

diff --git a/docs/authentication.txt b/docs/authentication.txt
index ef30879ae0..aff336f67a 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -86,10 +86,10 @@ objects in the same way as any other `Django model`_::
     myuser.groups.add(group, group,...)
     myuser.groups.remove(group, group,...)
     myuser.groups.clear()
-    myuser.permissions = [permission_list]
-    myuser.permissions.add(permission, permission, ...)
-    myuser.permissions.remove(permission, permission, ...]
-    myuser.permissions.clear()
+    myuser.user_permissions = [permission_list]
+    myuser.user_permissions.add(permission, permission, ...)
+    myuser.user_permissions.remove(permission, permission, ...]
+    myuser.user_permissions.clear()
 
 In addition to those automatic API methods, ``User`` objects have the following
 custom methods:
@@ -317,6 +317,16 @@ This example shows how you might use both ``authenticate()`` and ``login()``::
         else:
             # Return an 'invalid login' error message.
 
+Manually checking a user's password
+-----------------------------------
+
+If you'd like to manually authenticate a user by comparing a
+plain-text password to the hashed password in the database, use the
+convenience function `django.contrib.auth.models.check_password`. It
+takes two arguments: the plain-text password to check, and the full
+value of a user's ``password`` field in the database to check against,
+and returns ``True`` if they match, ``False`` otherwise.
+
 How to log a user out
 ---------------------
 
@@ -388,7 +398,7 @@ To do this, add the following line to your URLconf::
 
     (r'^accounts/login/$', 'django.contrib.auth.views.login'),
 
-Here's what ``django.contrib.auth.views.login`` does::
+Here's what ``django.contrib.auth.views.login`` does:
 
     * If called via ``GET``, it displays a login form that POSTs to the same
       URL. More on this in a bit.
@@ -444,6 +454,147 @@ block::
 .. _forms documentation: ../forms/
 .. _site framework docs: ../sites/
 
+Other built-in views
+--------------------
+
+In addition to the `login` view, the authentication system includes a
+few other useful built-in views:
+
+``django.contrib.auth.views.logout``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Logs a user out.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to display after
+      logging the user out. This will default to
+      ``registration/logged_out.html`` if no argument is supplied.
+
+**Template context:**
+
+    * ``title``: The string "Logged out", localized.
+
+``django.contrib.auth.views.logout_then_login``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Logs a user out, then redirects to the login page.
+
+**Optional arguments:**
+
+    * ``login_url``: The URL of the login page to redirect to. This
+      will default to ``/accounts/login/`` if not supplied.
+
+``django.contrib.auth.views.password_change``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Allows a user to change their password.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use for
+      displaying the password change form. This will default to
+      ``registration/password_change_form.html`` if not supplied.
+
+**Template context:**
+
+    * ``form``: The password change form.
+
+``django.contrib.auth.views.password_change_done``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+The page shown after a user has changed their password.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use. This will
+      default to ``registration/password_change_done.html`` if not
+      supplied.
+
+``django.contrib.auth.views.password_reset``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Allows a user to reset their password, and sends them the new password
+in an email.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use for
+      displaying the password reset form. This will default to
+      ``registration/password_reset_form.html`` if not supplied.
+
+    * ``email_template_name``: The full name of a template to use for
+      generating the email with the new password. This will default to
+      ``registration/password_reset_email.html`` if not supplied.
+
+**Template context:**
+
+    * ``form``: The form for resetting the user's password.
+
+``django.contrib.auth.views.password_reset_done``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+The page shown after a user has reset their password.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use. This will
+      default to ``registration/password_reset_done.html`` if not
+      supplied.
+
+``django.contrib.auth.views.redirect_to_login``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Redirects to the login page, and then back to another URL after a
+successful login.
+
+**Required arguments:**
+
+    * ``next``: The URL to redirect to after a successful login.
+
+**Optional arguments:**
+
+    * ``login_url``: The URL of the login page to redirect to. This
+      will default to ``/accounts/login/`` if not supplied.
+
+Built-in manipulators
+---------------------
+
+If you don't want to use the built-in views, but want the convenience
+of not having to write manipulators for this functionality, the
+authentication system provides several built-in manipulators:
+
+    * ``django.contrib.auth.forms.AdminPasswordChangeForm``: A
+      manipulator used in the admin interface to change a user's
+      password.
+
+    * ``django.contrib.auth.forms.AuthenticationForm``: A manipulator
+      for logging a user in.
+
+    * ``django.contrib.auth.forms.PasswordChangeForm``: A manipulator
+      for allowing a user to change their password.
+
+    * ``django.contrib.auth.forms.PasswordResetForm``: A manipulator
+      for resetting a user's password and emailing the new password to
+      them.
+
+    * ``django.contrib.auth.forms.UserCreationForm``: A manipulator
+      for creating a new user.
+
 Limiting access to logged-in users that pass a test
 ---------------------------------------------------
 
@@ -813,13 +964,13 @@ The  ``authenticate`` method takes credentials as keyword arguments. Most of
 the time, it'll just look like this::
 
     class MyBackend:
-        def authenticate(username=None, password=None):
+        def authenticate(self, username=None, password=None):
             # Check the username/password and return a User.
 
 But it could also authenticate a token, like so::
 
     class MyBackend:
-        def authenticate(token=None):
+        def authenticate(self, token=None):
             # Check the token and return a User.
 
 Either way, ``authenticate`` should check the credentials it gets, and it
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 99bb30054b..20a319740e 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -596,6 +596,21 @@ related ``Person`` *and* the related ``City``::
 Note that ``select_related()`` does not follow foreign keys that have
 ``null=True``.
 
+Usually, using ``select_related()`` can vastly improve performance because your
+app can avoid many database calls. However, in situations with deeply nested
+sets of relationships ``select_related()`` can sometimes end up following "too
+many" relations, and can generate queries so large that they end up being slow.
+
+In these situations, you can use the ``depth`` argument to ``select_related()``
+to control how many "levels" of relations ``select_related()`` will actually
+follow::
+
+    b = Book.objects.select_related(depth=1).get(id=4)
+    p = b.author         # Doesn't hit the database.
+    c = p.hometown       # Requires a database call.
+
+The ``depth`` argument is new in the Django development version.
+    
 ``extra(select=None, where=None, params=None, tables=None)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1621,6 +1636,15 @@ For example, this deletes all ``Entry`` objects with a ``pub_date`` year of
 
     Entry.objects.filter(pub_date__year=2005).delete()
 
+When Django deletes an object, it emulates the behavior of the SQL
+constraint ``ON DELETE CASCADE`` -- in other words, any objects which
+had foreign keys pointing at the object to be deleted will be deleted
+along with it. For example::
+
+    b = Blog.objects.get(pk=1)
+    # This will delete the Blog and all of its Entry objects.
+    b.delete()
+
 Note that ``delete()`` is the only ``QuerySet`` method that is not exposed on a
 ``Manager`` itself. This is a safety mechanism to prevent you from accidentally
 requesting ``Entry.objects.delete()``, and deleting *all* the entries. If you
diff --git a/docs/distributions.txt b/docs/distributions.txt
new file mode 100644
index 0000000000..a77d3a1959
--- /dev/null
+++ b/docs/distributions.txt
@@ -0,0 +1,76 @@
+===================================
+Third-party distributions of Django
+===================================
+
+Several third-party distributors are now providing versions of Django integrated
+with their package-management systems. These can make installation and upgrading
+much easier for users of Django since the integration includes the ability to
+automatically install dependancies (like database adapters) that Django
+requires.
+
+Typically, these packages are based on the latest stable release of Django, so
+if you want to use the development version of Django you'll need to follow the
+instructions for `installing the development version`_ from our Subversion
+repository.
+
+.. _installing the development version: ../install/#installing-the-development-version
+
+Linux distributions
+===================
+
+Debian
+------
+
+A `packaged version of Django`_ is available for `Debian GNU/Linux`_, and can be
+installed from either the "testing" or the "unstable" repositories by typing
+``apt-get install python-django``.
+
+When you install this package, ``apt`` will recommend installing a database
+adapter; you should select and install the adapter for whichever database you
+plan to use with Django.
+
+.. _Debian GNU/Linux: http://www.debian.org/
+.. _packaged version of Django: http://packages.debian.org/testing/python/python-django
+
+Ubuntu
+------
+
+The Debian ``python-django`` package is also available for `Ubuntu Linux`_, in
+the "universe" repository for Ubuntu 7.04 ("Feisty Fawn"). The `current Ubuntu
+package`_ is also based on Django 0.95.1 and can be installed in the same
+fashion as for Debian.
+
+.. _Ubuntu Linux: http://www.ubuntu.com/
+.. _current Ubuntu package: http://packages.ubuntu.com/feisty/python/python-django
+
+Fedora
+------
+
+A Django package is available for `Fedora Linux`_, in the "Fedora Extras"
+repository. The `current Fedora package`_ is based on Django 0.95.1, and can be
+installed by typing ``yum install Django``.
+
+.. _Fedora Linux: http://fedora.redhat.com/
+.. _current Fedora package: http://fedoraproject.org/extras/6/i386/repodata/repoview/Django-0-0.95.1-1.fc6.html
+
+Gentoo
+------
+
+A Django build is available for `Gentoo Linux`_, and is based on Django 0.95.1.
+The `current Gentoo build`_ can be installed by typing ``emerge Django``.
+
+.. _Gentoo Linux: http://www.gentoo.org/
+.. _current Gentoo build: http://packages.gentoo.org/packages/?category=dev-python;name=django
+
+For distributors
+================
+
+If you'd like to package Django for distribution, we'd be happy to help out!
+Please join the `django-developers mailing list`_ and introduce yourself. 
+
+We also encourage all distributors to subscribe to the `django-announce mailing
+list`_, which is a (very) low-traffic list for announcing new releases of Django
+and important bugfixes.
+
+.. _django-developers mailing list: http://groups.google.com/group/django-developers/
+.. _django-announce mailing list: http://groups.google.com/group/django-announce/
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index cf15168030..371c44e010 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -97,6 +97,33 @@ example, the default settings don't define ``ROOT_URLCONF``, so
 Note that Django's default settings live in ``django/conf/global_settings.py``,
 if you're ever curious to see the full list of defaults.
 
+dumpdata [appname appname ...]
+------------------------------
+
+**New in Django development version**
+
+Output to standard output all data in the database associated with the named 
+application(s).
+
+By default, the database will be dumped in JSON format. If you want the output
+to be in another format, use the ``--format`` option (e.g., ``format=xml``). 
+You may specify any Django serialization backend (including any user specified 
+serialization backends named in the ``SERIALIZATION_MODULES`` setting).
+
+If no application name is provided, all installed applications will be dumped.
+
+The output of ``dumpdata`` can be used as input for ``loaddata``. 
+
+flush
+-----
+
+**New in Django development version**
+
+Return the database to the state it was in immediately after syncdb was 
+executed. This means that all data will be removed from the database, any 
+post-synchronization handlers will be re-executed, and the ``initial_data``
+fixture will be re-installed.
+
 inspectdb
 ---------
 
@@ -141,8 +168,92 @@ only works in PostgreSQL and with certain types of MySQL tables.
 install [appname appname ...]
 -----------------------------
 
+**Removed in Django development version**
+
 Executes the equivalent of ``sqlall`` for the given appnames.
 
+loaddata [fixture fixture ...]
+------------------------------
+
+**New in Django development version**
+
+Searches for and loads the contents of the named fixture into the database.
+
+A *Fixture* is a collection of files that contain the serialized contents of
+the database. Each fixture has a unique name; however, the files that
+comprise the fixture can be distributed over multiple directories, in
+multiple applications.
+
+Django will search in three locations for fixtures:
+
+   1. In the ``fixtures`` directory of every installed application
+   2. In any directory named in the ``FIXTURE_DIRS`` setting
+   3. In the literal path named by the fixture
+
+Django will load any and all fixtures it finds in these locations that match
+the provided fixture names. 
+
+If the named fixture has a file extension, only fixtures of that type 
+will be loaded. For example::
+
+    django-admin.py loaddata mydata.json
+    
+would only load JSON fixtures called ``mydata``. The fixture extension 
+must correspond to the registered name of a serializer (e.g., ``json`` or 
+``xml``).
+
+If you omit the extension, Django will search all available fixture types 
+for a matching fixture. For example::
+
+    django-admin.py loaddata mydata
+    
+would look for any fixture of any fixture type called ``mydata``. If a fixture
+directory contained ``mydata.json``, that fixture would be loaded
+as a JSON fixture. However, if two fixtures with the same name but different 
+fixture type are discovered (for example, if ``mydata.json`` and 
+``mydata.xml`` were found in the same fixture directory), fixture 
+installation will be aborted, and any data installed in the call to 
+``loaddata`` will be removed from the database.
+
+The fixtures that are named can include directory components. These 
+directories will be inluded in the search path. For example::
+
+    django-admin.py loaddata foo/bar/mydata.json
+ 
+would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed 
+application,  ``<dirname>/foo/bar/mydata.json`` for each directory in 
+``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
+
+Note that the order in which fixture files are processed is undefined. However,
+all fixture data is installed as a single transaction, so data in
+one fixture can reference data in another fixture. If the database backend
+supports row-level constraints, these constraints will be checked at the
+end of the transaction.
+
+.. admonition:: MySQL and Fixtures
+
+    Unfortunately, MySQL isn't capable of completely supporting all the 
+    features of Django fixtures. If you use MyISAM tables, MySQL doesn't
+    support transactions or constraints, so you won't get a rollback if 
+    multiple transaction files are found, or validation of fixture data. 
+    If you use InnoDB tables, you won't be able to have any forward 
+    references in your data files - MySQL doesn't provide a mechanism to 
+    defer checking of row constraints until a transaction is committed.    
+    
+reset [appname appname ...]
+---------------------------
+Executes the equivalent of ``sqlreset`` for the given appnames.
+
+runfcgi [options]
+-----------------
+Starts a set of FastCGI processes suitable for use with any web server
+which supports the FastCGI protocol. See the `FastCGI deployment
+documentation`_ for details. Requires the Python FastCGI module from
+`flup`_.
+
+.. _FastCGI deployment documentation: ../fastcgi/
+.. _flup: http://www.saddi.com/software/flup/
+
 runserver [optional port number, or ipaddr:port]
 ------------------------------------------------
 
@@ -236,15 +347,12 @@ sqlclear [appname appname ...]
 
 Prints the DROP TABLE SQL statements for the given appnames.
 
-sqlindexes [appname appname ...]
-----------------------------------------
-
-Prints the CREATE INDEX SQL statements for the given appnames.
+sqlcustom [appname appname ...]
+-------------------------------
 
-sqlinitialdata [appname appname ...]
---------------------------------------------
+**New in Django development version**
 
-Prints the initial INSERT SQL statements for the given appnames.
+Prints the custom SQL statements for the given appnames.
 
 For each model in each specified app, this command looks for the file
 ``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given appname and
@@ -255,11 +363,23 @@ command.
 
 Each of the SQL files, if given, is expected to contain valid SQL. The SQL
 files are piped directly into the database after all of the models'
-table-creation statements have been executed. Use this SQL hook to populate
-tables with any necessary initial records, SQL functions or test data.
+table-creation statements have been executed. Use this SQL hook to make any
+table modifications, or insert any SQL functions into the database.
 
 Note that the order in which the SQL files are processed is undefined.
 
+sqlindexes [appname appname ...]
+----------------------------------------
+
+Prints the CREATE INDEX SQL statements for the given appnames.
+
+sqlinitialdata [appname appname ...]
+--------------------------------------------
+
+**Removed in Django development version**
+
+This method has been renamed ``sqlcustom`` in the development version of Django. 
+
 sqlreset [appname appname ...]
 --------------------------------------
 
@@ -299,6 +419,10 @@ this command to install the default apps.
 If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
 give you the option of creating a superuser immediately.
 
+``syncdb`` will also search for and install any fixture named ``initial_data``. 
+See the documentation for ``loaddata`` for details on the specification of 
+fixture data files.
+
 test
 ----
 
@@ -348,12 +472,37 @@ setting the Python path for you.
 
 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
 
+--format
+--------
+
+**New in Django development version**
+
+Example usage::
+
+    django-admin.py dumpdata --format=xml
+
+Specifies the output format that will be used. The name provided must be the name
+of a registered serializer.
+
 --help
 ------
 
 Displays a help message that includes a terse list of all available actions and
 options.
 
+--indent
+--------
+
+**New in Django development version**
+
+Example usage::
+
+    django-admin.py dumpdata --indent=4
+
+Specifies the number of spaces that will be used for indentation when 
+pretty-printing output. By default, output will *not* be pretty-printed.
+Pretty-printing will only be enabled if the indent option is provided.
+
 --noinput
 ---------
 
diff --git a/docs/email.txt b/docs/email.txt
index 1edce88cef..1f4ce4ef42 100644
--- a/docs/email.txt
+++ b/docs/email.txt
@@ -34,8 +34,8 @@ The simplest way to send e-mail is using the function
 ``django.core.mail.send_mail()``. Here's its definition::
 
     send_mail(subject, message, from_email, recipient_list,
-        fail_silently=False, auth_user=EMAIL_HOST_USER,
-        auth_password=EMAIL_HOST_PASSWORD)
+        fail_silently=False, auth_user=None,
+        auth_password=None)
 
 The ``subject``, ``message``, ``from_email`` and ``recipient_list`` parameters
 are required.
@@ -65,7 +65,7 @@ send_mass_mail()
 Here's the definition::
 
     send_mass_mail(datatuple, fail_silently=False,
-        auth_user=EMAIL_HOST_USER, auth_password=EMAIL_HOST_PASSWORD):
+        auth_user=None, auth_password=None):
 
 ``datatuple`` is a tuple in which each element is in this format::
 
diff --git a/docs/forms.txt b/docs/forms.txt
index fc10e3f17a..8c40eeb997 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -608,6 +608,10 @@ fails. If no message is passed in, a default message is used.
     order). If the given field does (or does not have, in the latter case) the
     given value, then the current field being validated is required.
 
+    An optional ``other_label`` argument can be passed which, if given, is used
+    in error messages instead of the value. This allows more user friendly error
+    messages if the value itself is not descriptive enough.
+
     Note that because validators are called before any ``do_html2python()``
     functions, the value being compared against is a string. So
     ``RequiredIfOtherFieldEquals('choice', '1')`` is correct, whilst
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index 23f40acb24..a136c72a07 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -686,7 +686,7 @@ A page representing a list of objects.
     * ``paginate_by``: An integer specifying how many objects should be
       displayed per page. If this is given, the view will paginate objects with
       ``paginate_by`` objects per page. The view will expect either a ``page``
-      query string parameter (via ``GET``) containing a zero-indexed page
+      query string parameter (via ``GET``) containing a 1-based page
       number, or a ``page`` variable specified in the URLconf. See
       "Notes on pagination" below.
 
@@ -752,6 +752,12 @@ If the results are paginated, the context will contain these extra variables:
 
     * ``previous``: The previous page number, as an integer. This is 1-based.
 
+    * `last_on_page`: **New in Django development version** The number of the
+      last result on the current page. This is 1-based.
+
+    * `first_on_page`: **New in Django development version** The number of the
+      first result on the current page. This is 1-based.
+
     * ``pages``: The total number of pages, as an integer.
 
     * ``hits``: The total number of objects across *all* pages, not just this
diff --git a/docs/install.txt b/docs/install.txt
index 89a1415f5a..3eede02af0 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -51,16 +51,20 @@ make sure a database server is running. Django works with PostgreSQL_
 Additionally, you'll need to make sure your Python database bindings are
 installed.
 
-* If you're using PostgreSQL, you'll need the psycopg_ package (version 1.1 --
-  not version 1.0 or version 2, which is still in beta). If you're on Windows,
-  check out the unofficial `compiled Windows version`_.
-* If you're using MySQL, you'll need MySQLdb_.
+* If you're using PostgreSQL, you'll need the psycopg_ package (version 2 is
+  recommended with ``postgresql_psycopg2`` backend, version 1.1 works also with the
+  ``postgresql``` backend). 
+  
+  If you're on Windows, check out the unofficial `compiled Windows version`_.
+  
+* If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher.
+
 * If you're using SQLite, you'll need pysqlite_. Use version 2.0.3 or higher.
 
 .. _PostgreSQL: http://www.postgresql.org/
 .. _MySQL: http://www.mysql.com/
 .. _Django's ticket system: http://code.djangoproject.com/report/1
-.. _psycopg: http://initd.org/projects/psycopg1
+.. _psycopg: http://initd.org/tracker/psycopg
 .. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/
 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
 .. _SQLite: http://www.sqlite.org/
@@ -77,10 +81,18 @@ It's easy either way.
 Installing the official version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. Download Django-0.95.tar.gz from our `download page`_.
-2. ``tar xzvf Django-0.95.tar.gz``
-3. ``cd Django-0.95``
-4. ``sudo python setup.py install``
+    1. Check the `distribution specific notes`_ to see if your
+       platform/distribution provides official Django packages/installers.
+       Distribution-provided packages will typically allow for automatic
+       installation of dependancies and easy upgrade paths.
+
+    2. Download Django-0.95.tar.gz from our `download page`_.
+
+    3. ``tar xzvf Django-0.95.tar.gz``
+
+    4. ``cd Django-0.95``
+
+    5. ``sudo python setup.py install``
 
 Note that the last command will automatically download and install setuptools_
 if you don't already have it installed. This requires a working Internet
@@ -93,6 +105,7 @@ The command will install Django in your Python installation's ``site-packages``
 directory.
 
 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
+.. _distribution specific notes: ../distributions/
 
 Installing the development version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 0a10918d54..1e7f69903d 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -498,6 +498,12 @@ or outside your model class altogether::
     class Foo(models.Model):
         gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
 
+For each model field that has ``choices`` set, Django will add a method to
+retrieve the human-readable name for the field's current value. See
+`get_FOO_display`_ in the database API documentation.
+
+.. _get_FOO_display: ../db_api/#get-foo-display
+
 Finally, note that choices can be any iterable object -- not necessarily a
 list or tuple. This lets you construct choices dynamically. But if you find
 yourself hacking ``choices`` to be dynamic, you're probably better off using
@@ -1295,10 +1301,30 @@ A few special cases to note about ``list_display``:
 
           list_display = ('__str__', 'some_other_field')
 
-    * For any element of ``list_display`` that is not a field on the model, the
-      change list page will not allow ordering by that column. This is because
-      ordering is done at the database level, and Django has no way of knowing
-      how to order the result of a custom method at the SQL level.
+    * Usually, elements of ``list_display`` that aren't actual database fields
+      can't be used in sorting (because Django does all the sorting at the
+      database level).
+      
+      However, if an element of ``list_display`` represents a certain database
+      field, you can indicate this fact by setting the ``admin_order_field``
+      attribute of the item.
+      
+      For example::
+      
+        class Person(models.Model):
+            first_name = models.CharField(maxlength=50)
+            color_code = models.CharField(maxlength=6)
+
+            class Admin:
+                list_display = ('first_name', 'colored_first_name')
+
+            def colored_first_name(self):
+                return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
+            colored_first_name.allow_tags = True
+            colored_first_name.admin_order_field = 'first_name'
+    
+      The above will tell Django to order by the ``first_name`` field when
+      trying to sort by ``colored_first_name`` in the admin.
 
 ``list_display_links``
 ----------------------
diff --git a/docs/settings.txt b/docs/settings.txt
index b9e46a858c..b2ca11240a 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -197,6 +197,9 @@ of (Full name, e-mail address). Example::
 
     (('John', 'john@example.com'), ('Mary', 'mary@example.com'))
 
+Note that Django will e-mail *all* of these people whenever an error happens. See the
+section on `error reporting via e-mail`_ for more information.
+
 ALLOWED_INCLUDE_ROOTS
 ---------------------
 
@@ -236,10 +239,10 @@ The cache key prefix that the cache middleware should use. See the
 DATABASE_ENGINE
 ---------------
 
-Default: ``'postgresql'``
+Default: ``''`` (Empty string)
 
-Which database backend to use. Either ``'postgresql'``, ``'mysql'``,
-``'sqlite3'`` or ``'ado_mssql'``.
+Which database backend to use. Either ``'postgresql_psycopg2'``, 
+``'postgresql'``, ``'mysql'``, ``'sqlite3'`` or ``'ado_mssql'``.
 
 DATABASE_HOST
 -------------
@@ -328,6 +331,16 @@ Default: ``False``
 
 A boolean that turns on/off debug mode.
 
+If you define custom settings, django/views/debug.py has a ``HIDDEN_SETTINGS``
+regular expression which will hide from the DEBUG view anything that contins
+``'SECRET``, ``PASSWORD``, or ``PROFANITIES'``. This allows untrusted users to
+be able to give backtraces without seeing sensitive (or offensive) settings.
+
+Still, note that there are always going to be sections of your debug output that
+are inapporpriate for public consumption. File paths, configuration options, and
+the like all give attackers extra information about your server. Never deploy a
+site with ``DEBUG`` turned on.
+
 DEFAULT_CHARSET
 ---------------
 
@@ -409,12 +422,25 @@ Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins
 or ``django.core.mail.mail_managers``. You'll probably want to include the
 trailing space.
 
+FIXTURE_DIRS
+-------------
+
+**New in Django development version**
+
+Default: ``()`` (Empty tuple)
+
+List of locations of the fixture data files, in search order. Note that
+these paths should use Unix-style forward slashes, even on Windows. See 
+`Testing Django Applications`_.
+
+.. _Testing Django Applications: ../testing/
+
 IGNORABLE_404_ENDS
 ------------------
 
 Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')``
 
-See also ``IGNORABLE_404_STARTS``.
+See also ``IGNORABLE_404_STARTS`` and ``Error reporting via e-mail``.
 
 IGNORABLE_404_STARTS
 --------------------
@@ -422,7 +448,8 @@ IGNORABLE_404_STARTS
 Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')``
 
 A tuple of strings that specify beginnings of URLs that should be ignored by
-the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS`` and ``IGNORABLE_404_ENDS``.
+the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and
+the section on `error reporting via e-mail`_.
 
 INSTALLED_APPS
 --------------
@@ -636,8 +663,19 @@ Default: ``False``
 Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a
 Django-powered page that is 404ed with a non-empty referer (i.e., a broken
 link). This is only used if ``CommonMiddleware`` is installed (see the
-`middleware docs`_). See also ``IGNORABLE_404_STARTS`` and
-``IGNORABLE_404_ENDS``.
+`middleware docs`_). See also ``IGNORABLE_404_STARTS``,
+``IGNORABLE_404_ENDS`` and the section on `error reporting via e-mail`_
+
+SERIALIZATION_MODULES
+---------------------
+
+Default: Not defined.
+
+A dictionary of modules containing serializer definitions (provided as 
+strings), keyed by a string identifier for that serialization type. For 
+example, to define a YAML serializer, use::
+
+    SERIALIZATION_MODULES = { 'yaml' : 'path.to.yaml_serializer' }
 
 SERVER_EMAIL
 ------------
@@ -977,3 +1015,36 @@ Also, it's an error to call ``configure()`` more than once, or to call
 
 It boils down to this: Use exactly one of either ``configure()`` or
 ``DJANGO_SETTINGS_MODULE``. Not both, and not neither.
+
+Error reporting via e-mail
+==========================
+
+Server errors
+-------------
+
+When ``DEBUG`` is ``False``, Django will e-mail the users listed in the
+``ADMIN`` setting whenever your code raises an unhandled exception and results
+in an internal server error (HTTP status code 500). This gives the
+administrators immediate notification of any errors.
+
+To disable this behavior, just remove all entries from the ``ADMINS`` setting.
+
+404 errors
+----------
+
+When ``DEBUG`` is ``False`` and your ``MIDDLEWARE_CLASSES`` setting includes
+``CommonMiddleware``, Django will e-mail the users listed in the ``MANAGERS``
+setting whenever your code raises a 404 and the request has a referer.
+(It doesn't bother to e-mail for 404s that don't have a referer.)
+
+You can tell Django to stop reporting particular 404s by tweaking the
+``IGNORABLE_404_ENDS`` and ``IGNORABLE_404_STARTS`` settings. Both should be a
+tuple of strings. For example::
+
+    IGNORABLE_404_ENDS = ('.php', '.cgi')
+    IGNORABLE_404_STARTS = ('/phpmyadmin/')
+
+In this example, a 404 to any URL ending with ``.php`` or ``.cgi`` will *not*
+be reported. Neither will any URL starting with ``/phpmyadmin/``.
+
+To disable this behavior, just remove all entries from the ``MANAGERS`` setting.
diff --git a/docs/templates.txt b/docs/templates.txt
index 5a007c13ae..d53270ac16 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -645,6 +645,7 @@ Available format strings:
                       output, because this includes periods
                       to match Associated Press style.)
     A                 ``'AM'`` or ``'PM'``.                     ``'AM'``
+    b                 Month, textual, 3 letters, lowercase.     ``'jan'``
     B                 Not implemented.
     d                 Day of the month, 2 digits with           ``'01'`` to ``'31'``
                       leading zeros.
diff --git a/docs/testing.txt b/docs/testing.txt
index 33014723cd..f7fd402502 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -198,7 +198,6 @@ used as test conditions.
 .. _Twill: http://twill.idyll.org/
 .. _Selenium: http://www.openqa.org/selenium/
 
-
 Making requests
 ~~~~~~~~~~~~~~~
 
@@ -357,7 +356,55 @@ The following is a simple unit test using the Test Client::
 Fixtures
 --------
 
-Feature still to come...
+A test case for a database-backed website isn't much use if there isn't any
+data in the database. To make it easy to put test data into the database,
+Django provides a fixtures framework.
+
+A *Fixture* is a collection of files that contain the serialized contents of
+the database. Each fixture has a unique name; however, the files that
+comprise the fixture can be distributed over multiple directories, in
+multiple applications.
+
+.. note::
+    If you have synchronized a Django project, you have already experienced 
+    the use of one fixture -- the ``initial_data`` fixture. Every time you
+    synchronize the database, Django installs the ``initial_data`` fixture.
+    This provides a mechanism to populate a new database with any initial
+    data (such as a default set of categories). Fixtures with other names
+    can be installed manually using ``django-admin.py loaddata``. 
+    
+
+However, for the purposes of unit testing, each test must be able to 
+guarantee the contents of the database at the start of each and every
+test. To do this, Django provides a TestCase baseclass that can integrate
+with fixtures.
+
+Moving from a normal unittest TestCase to a Django TestCase is easy - just
+change the base class of your test, and define a list of fixtures
+to be used. For example, the test case from `Writing unittests`_ would 
+look like::
+
+    from django.test import TestCase
+    from myapp.models import Animal
+
+    class AnimalTestCase(TestCase):
+        fixtures = ['mammals.json', 'birds']
+        
+        def setUp(self):
+            # test definitions as before
+
+At the start of each test case, before ``setUp()`` is run, Django will
+flush the database, returning the database the state it was in directly 
+after ``syncdb`` was called. Then, all the named fixtures are installed. 
+In this example, any JSON fixture called ``mammals``, and any fixture
+named ``birds`` will be installed. See the documentation on 
+`loading fixtures`_ for more details on defining and installing fixtures.
+
+.. _`loading fixtures`: ../django_admin/#loaddata-fixture-fixture
+
+This flush/load procedure is repeated for each test in the test case, so you 
+can be certain that the outcome of a test will not be affected by 
+another test, or the order of test execution.
 
 Running tests
 =============
@@ -417,7 +464,10 @@ failed::
 
     FAILED (failures=1)
 
-When the tests have all been executed, the test database is destroyed.
+The return code for the script will indicate the number of tests that failed.
+
+Regardless of whether the tests pass or fail, the test database is destroyed when
+all the tests have been executed. 
 
 Using a different testing framework
 ===================================
@@ -428,7 +478,8 @@ it does provide a mechanism to allow you to invoke tests constructed for
 an alternative framework as if they were normal Django tests.
 
 When you run ``./manage.py test``, Django looks at the ``TEST_RUNNER``
-setting to determine what to do. By default, ``TEST_RUNNER`` points to ``django.test.simple.run_tests``. This method defines the default Django
+setting to determine what to do. By default, ``TEST_RUNNER`` points to 
+``django.test.simple.run_tests``. This method defines the default Django
 testing behavior. This behavior involves:
 
 #. Performing global pre-test setup
@@ -436,7 +487,7 @@ testing behavior. This behavior involves:
 #. Running ``syncdb`` to install models and initial data into the test database
 #. Looking for Unit Tests and Doctests in ``models.py`` and ``tests.py`` file for each installed application
 #. Running the Unit Tests and Doctests that are found
-#. Destroying the test database.
+#. Destroying the test database
 #. Performing global post-test teardown
 
 If you define your own test runner method and point ``TEST_RUNNER``
@@ -457,6 +508,8 @@ arguments:
     Verbosity determines the amount of notification and debug information that
     will be printed to the console; `0` is no output, `1` is normal output,
     and `2` is verbose output.
+    
+    This method should return the number of tests that failed.
 
 Testing utilities
 -----------------
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 1b241f728a..56c5fa769e 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -19,6 +19,15 @@ installed.
 
 .. _`Django installed`: ../install/
 
+.. admonition:: Where to get help:
+
+    If you're having trouble going through this tutorial, please post a message
+    to `django-users`_ or drop by `#django`_ on ``irc.freenode.net`` and we'll 
+    try to help.
+
+.. _django-users: http://groups.google.com/group/django-users 
+.. _#django: irc://irc.freenode.net/django
+
 Creating a project
 ==================
 
@@ -32,6 +41,13 @@ From the command line, ``cd`` into a directory where you'd like to store your
 code, then run the command ``django-admin.py startproject mysite``. This
 will create a ``mysite`` directory in your current directory.
 
+.. note::
+    
+    You'll need to avoid naming projects after built-in Python or Django
+    components. In particular, this means you should avoid using names like
+    ``django`` (which will conflict with Django itself) or ``site`` (which
+    conflicts with a built-in Python package).
+
 (``django-admin.py`` should be on your system path if you installed Django via
 ``python setup.py``. If it's not on your path, you can find it in
 ``site-packages/django/bin``, where ``site-packages`` is a directory within
diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt
index 7b19bdaeaf..b1c8c7d4fc 100644
--- a/docs/tutorial04.txt
+++ b/docs/tutorial04.txt
@@ -206,6 +206,21 @@ for the polls app, we manually specify a template name for the results view:
 ``template_name='polls/results.html'``. Otherwise, both views would use the same
 template. Note that we use ``dict()`` to return an altered dictionary in place.
 
+.. note:: ``all()`` is lazy
+
+    It might look a little frightening to see ``Poll.objects.all()`` being used
+    in a detail view which only needs one ``Poll`` object, but don't worry;
+    ``Poll.objects.all()`` is actually a special object called a ``QuerySet``,
+    which is "lazy" and doesn't hit your database until it absolutely has to. By
+    the time the database query happens, the ``object_detail`` generic view will
+    have narrowed its scope down to a single object, so the eventual query will
+    only select one row from the database. 
+    
+    If you'd like to know more about how that works, The Django database API
+    documentation `explains the lazy nature of QuerySet objects`_.
+
+.. _explains the lazy nature of QuerySet objects: ../db_api/#querysets-are-lazy
+
 In previous parts of the tutorial, the templates have been provided with a context
 that contains the ``poll`` and ``latest_poll_list`` context variables. However,
 the generic views provide the variables ``object`` and ``object_list`` as context.
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index da4be2c746..3f51ce4b91 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -390,6 +390,13 @@ to pass metadata and options to views.
 .. _generic views: ../generic_views/
 .. _syndication framework: ../syndication/
 
+.. admonition:: Dealing with conflicts
+
+    It's possible to have a URL pattern which captures named keyword arguments,
+    and also passes arguments with the same names in its dictionary of extra
+    arguments. When this happens, the arguments in the dictionary will be used
+    instead of the arguments captured in the URL.
+
 Passing extra options to ``include()``
 --------------------------------------