newforms-admin: Merged to [4749]

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@4750 bcc190cf-cafb-0310-a4f2-bffc1f526a37

11 files changed, 470 insertions, 23 deletions

diff --git a/docs/contributing.txt b/docs/contributing.txt
index 6b2b64f672..1d2b635b76 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -195,7 +195,7 @@ The second part of this workflow involves a set of flags the describe what the
 ticket has or needs in order to be "ready for checkin":
 
     "Has patch"
-        The means the ticket has an associated patch_. These will be
+        This means the ticket has an associated patch_. These will be
         reviewed to see if the patch is "good".
 
     "Needs documentation"
@@ -212,6 +212,33 @@ ticket has or needs in order to be "ready for checkin":
         ready for checkin. This could mean the patch no longer applies
         cleanly, or that the code doesn't live up to our standards.
 
+A ticket can be resolved in a number of ways:
+
+    "fixed"
+        Used by one of the core developers once a patch has been rolled into
+        Django and the issue is fixed.
+
+    "invalid"
+        Used if the ticket is found to be incorrect or a user error.
+
+    "wontfix"
+        Used when a core developer decides that this request is not
+        appropriate for consideration in Django. This is usually chosen after
+        discussion in the ``django-developers`` mailing list, and you should
+        feel free to join in when it's something you care about.
+
+    "duplicate"
+        Used when another ticket covers the same issue. By closing duplicate
+        tickets, we keep all the discussion in one place, which helps everyone.
+
+    "worksforme"
+        Used when the triage team is unable to replicate the original bug.
+
+If you believe that the ticket was closed in error -- because you're
+still having the issue, or it's popped up somewhere else, or the triagers have
+-- made a mistake, please reopen the ticket and tell us why. Please do not
+reopen tickets that have been marked as "wontfix" by core developers.
+
 .. _required details: `Reporting bugs`_
 .. _good patch: `Patch style`_
 .. _patch: `Submitting patches`_
@@ -276,9 +303,11 @@ Please follow these coding standards when writing code for inclusion in Django:
           def my_view(req, foo):
               # ...
 
-    * Please don't put your name in the code. While we appreciate all
-      contributions to Django, our policy is not to publish individual
-      developer names in code -- for instance, at the top of Python modules.
+    * Please don't put your name in the code you contribute. Our policy is to
+      keep contributors' names in the ``AUTHORS`` file distributed with Django
+      -- not scattered throughout the codebase itself. Feel free to include a
+      change to the ``AUTHORS`` file in your patch if you make more than a
+      single trivial change.
 
 Committing code
 ===============
@@ -498,12 +527,12 @@ sure all other lines are commented::
     #   http://code.djangoproject.com/svn/django/trunk/
     #
     /path/to/trunk
-    
+
     # <branch> is a svn checkout of:
     #   http://code.djangoproject.com/svn/django/branches/<branch>/
     #
     #/path/to/<branch>
-    
+
     # On windows a path may look like this:
     # C:/path/to/<branch>
 
diff --git a/docs/databases.txt b/docs/databases.txt
new file mode 100644
index 0000000000..3545b58d47
--- /dev/null
+++ b/docs/databases.txt
@@ -0,0 +1,162 @@
+===============================
+Notes about supported databases
+===============================
+
+Django attempts to support as many features as possible on all database
+backends. However, not all database backends are alike, and we've had to make
+design decisions on which features to support and which assumptions we can make
+safely.
+
+This file describes some of the features that might be relevant to Django
+usage. Of course, it is not intended as a replacement for server-specific
+documentation or reference manuals.
+
+MySQL notes
+===========
+
+Django expects the database to support transactions, referential integrity,
+and Unicode support (UTF-8 encoding). Fortunately, MySQL_ has all these
+features as available as far back as 3.23. While it may be possible to use
+3.23 or 4.0, you'll probably have less trouble if you use 4.1 or 5.0.
+
+MySQL 4.1
+---------
+
+`MySQL 4.1`_ has greatly improved support for character sets. It is possible to
+set different default character sets on the database, table, and column.
+Previous versions have only a server-wide character set setting. It's also the
+first version where the character set can be changed on the fly. 4.1 also has
+support for views, but Django currently doesn't use views.
+
+MySQL 5.0
+---------
+
+`MySQL 5.0`_ adds the ``information_schema`` database, which contains detailed
+data on all database schema. Django's ``inspectdb`` feature uses this
+``information_schema`` if it's available. 5.0 also has support for stored
+procedures, but Django currently doesn't use stored procedures.
+
+.. _MySQL: http://www.mysql.com/
+.. _MySQL 4.1: http://dev.mysql.com/doc/refman/4.1/en/index.html
+.. _MySQL 5.0: http://dev.mysql.com/doc/refman/5.0/en/index.html
+
+Storage engines
+---------------
+
+MySQL has several `storage engines`_ (previously called table types). You can
+change the default storage engine in the server configuration.
+
+The default engine is MyISAM_. The main drawback of MyISAM is that it doesn't
+currently support transactions or foreign keys. On the plus side, it's
+currently the only engine that supports full-text indexing and searching.
+
+The InnoDB_ engine is fully transactional and supports foreign key references.
+
+The BDB_ engine, like InnoDB, is also fully transactional and supports foreign
+key references. However, its use seems to be deprecated.
+
+`Other storage engines`_, including SolidDB_ and Falcon_, are on the horizon.
+For now, InnoDB is probably your best choice.
+
+.. _storage engines: http://dev.mysql.com/doc/refman/5.0/en/storage-engines.html
+.. _MyISAM: http://dev.mysql.com/doc/refman/5.0/en/myisam-storage-engine.html
+.. _BDB: http://dev.mysql.com/doc/refman/5.0/en/bdb-storage-engine.html
+.. _InnoDB: http://dev.mysql.com/doc/refman/5.0/en/innodb.html
+.. _Other storage engines: http://dev.mysql.com/doc/refman/5.1/en/storage-engines-other.html
+.. _SolidDB: http://forge.mysql.com/projects/view.php?id=139
+.. _Falcon: http://dev.mysql.com/doc/falcon/en/index.html
+
+MySQLdb
+-------
+
+`MySQLdb`_ is the Python interface to MySQL. 1.2.1 is the first version that
+has support for MySQL 4.1 and newer. If you are trying to use an older version
+of MySQL, then 1.2.0 *might* work for you.
+
+.. _MySQLdb: http://sourceforge.net/projects/mysql-python
+
+Creating your database
+----------------------
+
+You can `create your database`_ using the command-line tools and this SQL::
+
+  CREATE DATABASE <dbname> CHARACTER SET utf8;
+
+This ensures all tables and columns will use UTF-8 by default.
+
+.. _create your database: http://dev.mysql.com/doc/refman/5.0/en/create-database.html
+
+Connecting to the database
+--------------------------
+
+Refer to the `settings documentation`_.
+
+Connection settings are used in this order:
+
+ 1. ``DATABASE_OPTIONS``
+ 2. ``DATABASE_NAME``, ``DATABASE_USER``, ``DATABASE_PASSWORD``, ``DATABASE_HOST``,
+    ``DATABASE_PORT``
+ 3. MySQL option files.
+
+In other words, if you set the name of the database in ``DATABASE_OPTIONS``,
+this will take precedence over ``DATABASE_NAME``, which would override
+anything in a `MySQL option file`_.
+
+Here's a sample configuration which uses a MySQL option file::
+
+  # settings.py
+  DATABASE_ENGINE = "mysql"
+  DATABASE_OPTIONS = {
+      'read_default_file': '/path/to/my.cnf',
+      }
+
+  # my.cnf
+  [client]
+  database = DATABASE_NAME
+  user = DATABASE_USER
+  passwd = DATABASE_PASSWORD
+  default-character-set = utf8
+
+Several other MySQLdb connection options may be useful, such as ``ssl``,
+``use_unicode``, ``init_command``, and ``sql_mode``. Consult the
+`MySQLdb documentation`_ for more details.
+
+.. _settings documentation: http://www.djangoproject.com/documentation/settings/#database-engine
+.. _MySQL option file: http://dev.mysql.com/doc/refman/5.0/en/option-files.html
+.. _MySQLdb documentation: http://mysql-python.sourceforge.net/
+
+Creating your tables
+--------------------
+
+When Django generates the schema, it doesn't specify a storage engine, so
+tables will be created with whatever default storage engine your database
+server is configured for. The easiest solution is to set your database server's
+default storage engine to the desired engine.
+
+If you're using a hosting service and can't change your server's default
+storage engine, you have a couple of options.
+
+    * After the tables are created, execute an ``ALTER TABLE`` statement to
+      convert a table to a new storage engine (such as InnoDB)::
+
+          ALTER TABLE <tablename> ENGINE=INNODB;
+
+      This can be tedious if you have a lot of tables.
+
+    * Another option is to use the ``init_command`` option for MySQLdb prior to
+      creating your tables::
+
+          DATABASE_OPTIONS = {
+              # ...
+             "init_command": "SET storage_engine=INNODB",
+              # ...
+          }
+
+      This sets the default storage engine upon connecting to the database.
+      After your tables have been created, you should remove this option.
+
+    * Another method for changing the storage engine is described in
+      AlterModelOnSyncDB_.
+
+.. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB
+
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 20a319740e..64db3def96 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -6,7 +6,7 @@ Once you've created your `data models`_, Django automatically gives you a
 database-abstraction API that lets you create, retrieve, update and delete
 objects. This document explains that API.
 
-.. _`data models`: http://www.djangoproject.com/documentation/model_api/
+.. _`data models`: ../model_api/
 
 Throughout this reference, we'll refer to the following models, which comprise
 a weblog application::
@@ -85,7 +85,7 @@ There's no way to tell what the value of an ID will be before you call
 unless you explicitly specify ``primary_key=True`` on a field. See the
 `AutoField documentation`_.)
 
-.. _AutoField documentation: http://www.djangoproject.com/documentation/model_api/#autofield
+.. _AutoField documentation: ../model_api/#autofield
 
 Explicitly specifying auto-primary-key values
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1801,4 +1801,4 @@ interface to your database. You can access your database via other tools,
 programming languages or database frameworks; there's nothing Django-specific
 about your database.
 
-.. _Executing custom SQL: http://www.djangoproject.com/documentation/model_api/#executing-custom-sql
+.. _Executing custom SQL: ../model_api/#executing-custom-sql
diff --git a/docs/distributions.txt b/docs/distributions.txt
index a77d3a1959..63206c535e 100644
--- a/docs/distributions.txt
+++ b/docs/distributions.txt
@@ -57,7 +57,7 @@ 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``.
+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
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index 368062468d..ef1d73cdbd 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,78 @@ 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 included 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.
@@ -250,15 +347,12 @@ sqlclear [appname appname ...]
 
 Prints the DROP TABLE SQL statements for the given appnames.
 
-sqlindexes [appname appname ...]
-----------------------------------------
+sqlcustom [appname appname ...]
+-------------------------------
 
-Prints the CREATE INDEX SQL statements for the given appnames.
-
-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
@@ -269,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 ...]
 --------------------------------------
 
@@ -313,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
 ----
 
@@ -362,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/fastcgi.txt b/docs/fastcgi.txt
index 1efeaf09cf..5ecaac8666 100644
--- a/docs/fastcgi.txt
+++ b/docs/fastcgi.txt
@@ -304,3 +304,14 @@ If you have access to a command shell on a Unix system, you can accomplish this
 easily by using the ``touch`` command::
 
     touch mysite.fcgi
+
+Serving admin media files
+=========================
+
+Regardless of the server and configuration you eventually decide to use, you will
+also need to give some thought to how to serve the admin media files. The
+advice given in the modpython_ documentation is also applicable in the setups
+detailed above.
+
+.. _modpython: ../modpython/#serving-the-admin-files
+
diff --git a/docs/forms.txt b/docs/forms.txt
index 8c40eeb997..f76f6d27ef 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -417,6 +417,27 @@ Here's a simple function that might drive the above form::
         form = forms.FormWrapper(manipulator, new_data, errors)
         return render_to_response('contact_form.html', {'form': form})
 
+Implementing ``flatten_data`` for custom manipulators
+------------------------------------------------------
+
+It is possible (although rarely needed) to replace the default automatically
+created manipulators on a model with your own custom manipulators. If you do
+this and you are intending to use those models in generic views, you should
+also define a ``flatten_data`` method in any ``ChangeManipulator`` replacement.
+This should act like the default ``flatten_data`` and return a dictionary
+mapping field names to their values, like so::
+
+    def flatten_data(self):
+        obj = self.original_object
+        return dict(
+            from = obj.from,
+            subject = obj.subject,
+            ...
+        )
+
+In this way, your new change manipulator will act exactly like the default
+version.
+
 ``FileField`` and ``ImageField`` special cases
 ==============================================
 
diff --git a/docs/i18n.txt b/docs/i18n.txt
index d7f5db6861..4a05e53ddf 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -282,6 +282,17 @@ How to create language files
 Once you've tagged your strings for later translation, you need to write (or
 obtain) the language translations themselves. Here's how that works.
 
+.. admonition:: Locale restrictions
+
+    Django does not support localizing your application into a locale for
+    which Django itself has not been translated. In this case, it will ignore
+    your translation files. If you were to try this and Django supported it,
+    you would inevitably see a mixture of translated strings (from your
+    application) and English strings (from Django itself). If you want to
+    support a locale for your application that is not already part of
+    Django, you'll need to make at least a minimal translation of the Django
+    core.
+
 Message files
 -------------
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 1e7f69903d..26686b02fe 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1216,6 +1216,10 @@ screen via ``<script src="">`` tags. This can be used to tweak a given type of
 admin page in JavaScript or to provide "quick links" to fill in default values
 for certain fields.
 
+If you use relative URLs -- URLs that don't start with ``http://`` or ``/`` --
+then the admin site will automatically prefix these links with
+``settings.ADMIN_MEDIA_PREFIX``.
+
 ``list_display``
 ----------------
 
diff --git a/docs/settings.txt b/docs/settings.txt
index 873b70a5e2..b41281ee49 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -162,10 +162,13 @@ a model object and return its URL. This is a way of overriding
 ``get_absolute_url()`` methods on a per-installation basis. Example::
 
     ABSOLUTE_URL_OVERRIDES = {
-        'blogs.Weblog': lambda o: "/blogs/%s/" % o.slug,
-        'news.Story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
+        'blogs.weblog': lambda o: "/blogs/%s/" % o.slug,
+        'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
     }
 
+Note that the model name used in this setting should be all lower-case, regardless
+of the case of the actual model class name.
+
 ADMIN_FOR
 ---------
 
@@ -422,6 +425,19 @@ 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
 ------------------
 
@@ -653,6 +669,17 @@ link). This is only used if ``CommonMiddleware`` is installed (see the
 `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
 ------------
 
diff --git a/docs/testing.txt b/docs/testing.txt
index 57e50f483d..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
 =============