Index: tests/modeltests/fixtures/models.py =================================================================== --- tests/modeltests/fixtures/models.py (revision 7309) +++ tests/modeltests/fixtures/models.py (working copy) @@ -1,11 +1,10 @@ """ 37. Fixtures. -Fixtures are a way of loading data into the database in bulk. Fixure data -can be stored in any serializable format (including JSON and XML). Fixtures -are identified by name, and are stored in either a directory named 'fixtures' -in the application directory, on in one of the directories named in the -FIXTURE_DIRS setting. +For an explanation of what fixtures are, please look at the +`fixtures documentation`_. + +.. _Fixtures documentation: ../../fixtures/ """ from django.db import models Index: AUTHORS =================================================================== --- AUTHORS (revision 7309) +++ AUTHORS (working copy) @@ -289,7 +289,7 @@ Philippe Raoult Massimiliano Ravelli Brian Ray - remco@diji.biz + Remco Wendt David Reynolds rhettg@gmail.com ricardojbarrios@gmail.com Index: docs/model-api.txt =================================================================== --- docs/model-api.txt (revision 7309) +++ docs/model-api.txt (working copy) @@ -2073,9 +2073,18 @@ #... ) -Providing initial SQL data -========================== +Providing initial data +====================== +Django provides two ways for automatically loading data into the database just +after the CREATE TABLE statements. This is useful if you want to populate your +database with default records. You can provide Django with initial data by +providing custom SQL that does inserts into the appropriate tables and/or make +use of Django's fixture framework. + +Providing initial data using SQL +-------------------------------- + Django provides a hook for passing the database arbitrary SQL that's executed just after the CREATE TABLE statements. Use this hook, for example, if you want to populate default records, or create SQL functions, automatically. @@ -2104,10 +2113,10 @@ time your custom data files are executed, all the database tables already will have been created. -.. _`manage.py documentation`: ../django-admin/#sqlcustom-appname-appname +.. _manage.py documentation: ../django-admin/#sqlcustom-appname-appname Database-backend-specific SQL data ----------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There's also a hook for backend-specific SQL data. For example, you can have separate initial-data files for PostgreSQL and MySQL. For each app, Django @@ -2121,3 +2130,13 @@ ``sql/person.postgresql.sql`` and you're installing the app on PostgreSQL, Django will execute the contents of ``sql/person.postgresql.sql`` first, then ``sql/person.sql``. + +Providing initial data using fixtures +------------------------------------- + +An elegant way of providing initial data for your project is using Django's +fixture framework. Have a look at the +`using fixtures for loading initial data`_ +section in the fixtures documentation. + +.. _using fixtures for loading initial data: ../fixtures/#using-fixtures-for-loading-initial-data Index: docs/fixtures.txt =================================================================== --- docs/fixtures.txt (revision 0) +++ docs/fixtures.txt (revision 0) @@ -0,0 +1,219 @@ +=========================== +Django's fixtures framework +=========================== + +The fixtures framework provides an easy way to save and load snapshots of your +data. A *fixture* is a collection of one or more files with a unique name that +contain the serialized contents of the database. These files can be +distributed over multiple directories, in multiple applications. + +A very nice way of using fixtures is Django's testserver. Basically you can +first populate your applications with test data, save the data of all your +applications to a fixture and then tell the testserver to use this data +when you launch the testserver. Allowing you to change data while +testing, knowing that a restart of the testserver resets all changes. See the +`testserver documentation`_ for more information. + +.. note:: + If you've ever run ``manage.py syncdb``, you've already used a fixture + without even knowing it! When you call ``syncdb`` in the database for + the first time, Django installs a fixture called ``initial_data``. + This gives you a way of populating a new database with any initial data, + such as a default set of categories. + + Fixtures with other names can always be installed manually using the + ``manage.py loaddata`` command. + +.. _testserver documentation: ../django-admin/#testserver-fixture-fixture + +Loading fixtures +================ + +The ``django-admin.py loaddata `` command searches for +and loads the contents of the named fixture into the database. + +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. + +For example if you have a project called ``myproject`` which contains two +applications: ``myproject.polls`` and ``myproject.animals``. The layout of +your project directory including the fixtures could look something like this:: + + myproject/__init__.py + myproject/settings.py + myproject/urls.py + myproject/manage.py + myproject/animals/__init__.py + myproject/animals/models.py + myproject/animals/views.py + myproject/animals/fixtures/mydata.json + myproject/polls/__init__.py + myproject/polls/models.py + myproject/polls/views.py + myproject/polls/fixtures/mydata.xml + +To load the fixture called ``mydata`` into the database, populating both +``myproject.animals`` and ``myproject.polls``, you would issue the following +command:: + + django-admin.py loaddata mydata + +This will load both the json and xml file. 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``, in this cases only the +fixture file in ``myproject/animals/fixtures/`` would be loaded. The fixture +extension must correspond to the registered name of a `serializer`_ (e.g., +``json`` or ``xml``). + +If two fixtures with the same name but different fixture types are discovered +in the same directory (for example, having both ``mydata.json`` and +``mydata.xml`` in ``myproject/polls/fixtures/``), 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 ``/fixtures/foo/bar/mydata.json`` for each installed +application, ``/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. + +The ``dumpdata`` command can be used to generate input for ``loaddata``. + +.. _serializer: ../serialization/#serialization-formats + +--verbosity +~~~~~~~~~~~ + +Use ``--verbosity`` to specify the amount of notification and debug information +that ``django-admin.py`` should print to the console. + + * ``0`` means no input. + * ``1`` means normal input (default). + * ``2`` means verbose input. + +Example usage:: + + django-admin.py loaddata --verbosity=2 + +--traceback +~~~~~~~~~~~ + +Use ``--traceback`` to specify that ``django-admin.py`` should print a +traceback to the console when an exception occurs during the loading of a +fixture. + +.. 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. + +Using fixtures for loading initial data +--------------------------------------- + +Django's ``django-admin syncdb`` command uses the fixture framework on every +run to check for a fixture named ``initial_data``. When this fixture exists, +it is automatically `loaded`_. This allows you to define data you want to be +available within your project's database, on every fresh start. Look at +`saving`_ fixtures to see how you can actually save project data to the +``initial_data`` fixture. + +.. _loaded: ./#loading-fixtures +.. _saving: ./#saving-fixtures + +Using fixtures in automated tests +--------------------------------- + +The fixtures framework opens up an interesting possibility for use in unit +tests. In short, when you want to use test data for use during unit tests you +can use the ``django-admin.py dumpdata`` command to save part or all of your +project's current data and refer to this named fixture from within your unit +test. For details on how to do this, please look at the `fixture loading`_ +section of the ``testing Django applications`` documentation. + +.. _fixture loading: ../testing/#fixture-loading + +Saving fixtures +=============== + +The ``django-admin.py dumpdata `` command serializes the +data of the selected apps, currently in the database, and dumps it to the +console. + +You are responsible for deciding upon the right place of saving your fixture +data. Look at the `loading fixtures`_ documentation on the locations Django +uses to search for fixture data. + +For example using the project called ``myproject`` from the example above. You +could save data you have just inserted into ``myproject.polls`` as a named +fixture called mynewdata by issuing the following command:: + + django-admin.py dumpdata polls > polls/fixtures/mynewdata.json + +If no application name is provided, all installed applications will be dumped. + +The output of ``dumpdata`` can be used as input for ``loaddata``. + +.. admonition:: Dumpdata and custom managers + + Note that ``dumpdata`` uses the default manager on the model for selecting + the records to dump. If you're using a `custom manager`_ as the default + manager and it filters some of the available records, not all of the objects + will be dumped. + +.. _dumpdata command: ../django-admin/#dumpdata-appname-appname +.. _loading fixtures: ./#loading-fixtures +.. _custom manager: ../model-api/#custom-managers + +--format +~~~~~~~~ + +By default, ``dumpdata`` will format its output in JSON, but you can use the +``--format`` option to specify another format. Currently supported formats are +listed in `Serialization formats`_. + +Example usage:: + + django-admin.py dumpdata --format=xml + +.. _Serialization formats: ../serialization/#serialization-formats + +--indent +~~~~~~~~ + +By default, ``dumpdata`` will output all data on a single line. This isn't easy +for humans to read, so you can use the ``--indent`` option to pretty-print the +output with a number of indentation spaces. + +Example usage:: + + django-admin.py dumpdata --indent=4 + +--traceback +~~~~~~~~~~~ + +Use ``--traceback`` to specify that ``django-admin.py`` should print a +traceback to the console when an exception occurs during the dumping of a +fixture. Index: docs/testing.txt =================================================================== --- docs/testing.txt (revision 7309) +++ docs/testing.txt (working copy) @@ -743,26 +743,10 @@ A test case for a database-backed Web site 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's custom ``TestCase`` class provides a way of loading **fixtures**. +Django's custom ``TestCase`` class provides a way of loading **fixtures**. To +understand what fixtures are about, have a look at the +`fixtures documentation`_. -A fixture is a collection of data that Django knows how to import into a -database. For example, if your site has user accounts, you might set up a -fixture of fake user accounts in order to populate your database during tests. - -The most straightforward way of creating a fixture is to use the -``manage.py dumpdata`` command. This assumes you already have some data in -your database. See the `dumpdata documentation`_ for more details. - -.. note:: - If you've ever run ``manage.py syncdb``, you've already used a fixture - without even knowing it! When you call ``syncdb`` in the database for - the first time, Django installs a fixture called ``initial_data``. - This gives you a way of populating a new database with any initial data, - such as a default set of categories. - - Fixtures with other names can always be installed manually using the - ``manage.py loaddata`` command. - Once you've created a fixture and placed it somewhere in your Django project, you can use it in your unit tests by specifying a ``fixtures`` class attribute on your ``django.test.TestCase`` subclass:: @@ -786,16 +770,16 @@ directly after ``syncdb`` was called. * Then, all the named fixtures are installed. In this example, Django will - install any JSON fixture named ``mammals``, followed by any fixture named - ``birds``. See the `loaddata documentation`_ for more details on defining - and installing fixtures. + install any JSON fixture named ``mammals``, followed by any fixture + named ``birds``. See the `loading fixtures`_ section in the fixtures + documentation, for more details on defining and installing fixtures. 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 by the order of test execution. -.. _dumpdata documentation: ../django-admin/#dumpdata-appname-appname -.. _loaddata documentation: ../django-admin/#loaddata-fixture-fixture +.. _fixtures documentation: ../fixtures/ +.. _loading fixtures: ../fixtures/#loading-fixtures Emptying the test outbox ~~~~~~~~~~~~~~~~~~~~~~~~ Index: docs/django-admin.txt =================================================================== --- docs/django-admin.txt (revision 7309) +++ docs/django-admin.txt (working copy) @@ -68,7 +68,7 @@ Examples of output:: - 0.95 + 0.95 0.96 0.97-pre-SVN-6069 @@ -126,43 +126,13 @@ ------------------------------ Outputs to standard output all data in the database associated with the named -application(s). +application(s). Please look at the fixtures documentation for an explanation on +`saving fixtures`_. -If no application name is provided, all installed applications will be dumped. - The output of ``dumpdata`` can be used as input for ``loaddata``. -Note that ``dumpdata`` uses the default manager on the model for selecting the -records to dump. If you're using a `custom manager`_ as the default manager -and it filters some of the available records, not all of the objects will be -dumped. +.. _saving fixtures: ../fixtures/#saving-fixtures -.. _custom manager: ../model-api/#custom-managers - ---format -~~~~~~~~ - -By default, ``dumpdata`` will format its output in JSON, but you can use the -``--format`` option to specify another format. Currently supported formats are -listed in `Serialization formats`_. - -Example usage:: - - django-admin.py dumpdata --format=xml - -.. _Serialization formats: ../serialization/#serialization-formats - ---indent -~~~~~~~~ - -By default, ``dumpdata`` will output all data on a single line. This isn't easy -for humans to read, so you can use the ``--indent`` option to pretty-print the -output with a number of indentation spaces. - -Example usage:: - - django-admin.py dumpdata --indent=4 - flush ----- @@ -244,83 +214,13 @@ ------------------------------ Searches for and loads the contents of the named fixture into the database. +Please look at the fixtures documentation for an explanation on +`loading fixtures`_. -A *fixture* is a collection of files that contain the serialized contents of -the database. Each fixture has a unique name, and the files that comprise the -fixture can be distributed over multiple directories, in multiple applications. +The output of ``dumpdata`` can be used as input for ``loaddata``. -Django will search in three locations for fixtures: +.. _loading fixtures: ../fixtures/#loading-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 ``/fixtures/foo/bar/mydata.json`` for each installed -application, ``/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. - -The ``dumpdata`` command can be used to generate input for ``loaddata``. - -.. 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. - ---verbosity -~~~~~~~~~~~ - -Use ``--verbosity`` to specify the amount of notification and debug information -that ``django-admin.py`` should print to the console. - - * ``0`` means no input. - * ``1`` means normal input (default). - * ``2`` means verbose input. - -Example usage:: - - django-admin.py loaddata --verbosity=2 - reset --------------------------- @@ -606,7 +506,8 @@ **New in Django development version** Runs a Django development server (as in ``runserver``) using data from the -given fixture(s). +given fixture(s). For an explanation on what fixtures are, please look at the +`fixtures documentation`_. For example, this command:: @@ -616,7 +517,6 @@ 1. Create a test database, as described in `testing Django applications`_. 2. Populate the test database with fixture data from the given fixtures. - (For more on fixtures, see the documentation for ``loaddata`` above.) 3. Runs the Django development server (as in ``runserver``), pointed at this newly created test database instead of your production database. @@ -639,6 +539,7 @@ templates. .. _unit tests: ../testing/ +.. _fixtures documentation: ../fixtures/ --addrport [port number or ipaddr:port] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~