Ticket #5096: fixtures-documentation.diff

File fixtures-documentation.diff, 20.7 KB (added by Remco Wendt, 17 years ago)

First concept of fixtures documentation

  • tests/modeltests/fixtures/models.py

     
    11"""
    2237. Fixtures.
    33
    4 Fixtures are a way of loading data into the database in bulk. Fixure data
    5 can be stored in any serializable format (including JSON and XML). Fixtures
    6 are identified by name, and are stored in either a directory named 'fixtures'
    7 in the application directory, on in one of the directories named in the
    8 FIXTURE_DIRS setting.
     4For an explanation of what fixtures are, please look at the
     5`fixtures documentation`_.
     6
     7.. _Fixtures documentation: ../../fixtures/
    98"""
    109
    1110from django.db import models
  • AUTHORS

     
    289289    Philippe Raoult <philippe.raoult@n2nsoft.com>
    290290    Massimiliano Ravelli <massimiliano.ravelli@gmail.com>
    291291    Brian Ray <http://brianray.chipy.org/>
    292     remco@diji.biz
     292    Remco Wendt <remco@diji.biz>
    293293    David Reynolds <david@reynoldsfamily.org.uk>
    294294    rhettg@gmail.com
    295295    ricardojbarrios@gmail.com
  • docs/model-api.txt

     
    20732073        #...
    20742074    )
    20752075
    2076 Providing initial SQL data
    2077 ==========================
     2076Providing initial data
     2077======================
    20782078
     2079Django provides two ways for automatically loading data into the database just
     2080after the CREATE TABLE statements. This is useful if you want to populate your
     2081database with default records. You can provide Django with initial data by
     2082providing custom SQL that does inserts into the appropriate tables and/or make
     2083use of Django's fixture framework.
     2084
     2085Providing initial data using SQL
     2086--------------------------------
     2087
    20792088Django provides a hook for passing the database arbitrary SQL that's executed
    20802089just after the CREATE TABLE statements. Use this hook, for example, if you want
    20812090to populate default records, or create SQL functions, automatically.
     
    21042113time your custom data files are executed, all the database tables already will
    21052114have been created.
    21062115
    2107 .. _`manage.py documentation`: ../django-admin/#sqlcustom-appname-appname
     2116.. _manage.py documentation: ../django-admin/#sqlcustom-appname-appname
    21082117
    21092118Database-backend-specific SQL data
    2110 ----------------------------------
     2119~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    21112120
    21122121There's also a hook for backend-specific SQL data. For example, you can have
    21132122separate initial-data files for PostgreSQL and MySQL. For each app, Django
     
    21212130``sql/person.postgresql.sql`` and you're installing the app on PostgreSQL,
    21222131Django will execute the contents of ``sql/person.postgresql.sql`` first, then
    21232132``sql/person.sql``.
     2133
     2134Providing initial data using fixtures
     2135-------------------------------------
     2136
     2137An elegant way of providing initial data for your project is using Django's
     2138fixture framework. Have a look at the
     2139`using fixtures for loading initial data`_
     2140section in the fixtures documentation.
     2141
     2142.. _using fixtures for loading initial data: ../fixtures/#using-fixtures-for-loading-initial-data
  • docs/fixtures.txt

     
     1===========================
     2Django's fixtures framework
     3===========================
     4
     5The fixtures framework provides an easy way to save and load snapshots of your
     6data. A *fixture* is a collection of one or more files with a unique name that
     7contain the serialized contents of the database. These files can be
     8distributed over multiple directories, in multiple applications.
     9
     10A very nice way of using fixtures is Django's testserver. Basically you can
     11first populate your applications with test data, save the data of all your
     12applications to a fixture and then tell the testserver to use this data
     13when you launch the testserver. Allowing you to change data while
     14testing, knowing that a restart of the testserver resets all changes. See the
     15`testserver documentation`_ for more information.
     16
     17.. note::
     18    If you've ever run ``manage.py syncdb``, you've already used a fixture
     19    without even knowing it! When you call ``syncdb`` in the database for
     20    the first time, Django installs a fixture called ``initial_data``.
     21    This gives you a way of populating a new database with any initial data,
     22    such as a default set of categories.
     23
     24    Fixtures with other names can always be installed manually using the
     25    ``manage.py loaddata`` command.
     26
     27.. _testserver documentation: ../django-admin/#testserver-fixture-fixture
     28
     29Loading fixtures
     30================
     31
     32The ``django-admin.py loaddata <fixture fixture ...>`` command searches for
     33and loads the contents of the named fixture into the database.
     34
     35Django will search in three locations for fixtures:
     36
     37   1. In the ``fixtures`` directory of every installed application
     38   2. In any directory named in the ``FIXTURE_DIRS`` setting
     39   3. In the literal path named by the fixture
     40
     41Django will load any and all fixtures it finds in these locations that match
     42the provided fixture names.
     43
     44For example if you have a project called ``myproject`` which contains two
     45applications: ``myproject.polls`` and ``myproject.animals``. The layout of
     46your project directory including the fixtures could look something like this::
     47
     48    myproject/__init__.py
     49    myproject/settings.py
     50    myproject/urls.py
     51    myproject/manage.py
     52    myproject/animals/__init__.py
     53    myproject/animals/models.py
     54    myproject/animals/views.py
     55    myproject/animals/fixtures/mydata.json
     56    myproject/polls/__init__.py
     57    myproject/polls/models.py
     58    myproject/polls/views.py
     59    myproject/polls/fixtures/mydata.xml
     60
     61To load the fixture called ``mydata`` into the database, populating both
     62``myproject.animals`` and ``myproject.polls``, you would issue the following
     63command::
     64
     65    django-admin.py loaddata mydata
     66
     67This will load both the json and xml file. If the named fixture has a file
     68extension, only fixtures of that type will be loaded. For example::
     69
     70    django-admin.py loaddata mydata.json
     71
     72would only load JSON fixtures called ``mydata``, in this cases only the
     73fixture file in ``myproject/animals/fixtures/`` would be loaded. The fixture
     74extension must correspond to the registered name of a `serializer`_ (e.g.,
     75``json`` or ``xml``).
     76
     77If two fixtures with the same name but different fixture types are discovered
     78in the same directory (for example, having both ``mydata.json`` and
     79``mydata.xml`` in ``myproject/polls/fixtures/``), fixture installation will be
     80aborted, and any data installed in the call to ``loaddata`` will be removed
     81from the database.
     82
     83The fixtures that are named can include directory components. These
     84directories will be included in the search path. For example::
     85
     86    django-admin.py loaddata foo/bar/mydata.json
     87
     88would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
     89application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
     90``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
     91
     92Note that the order in which fixture files are processed is undefined. However,
     93all fixture data is installed as a single transaction, so data in
     94one fixture can reference data in another fixture. If the database backend
     95supports row-level constraints, these constraints will be checked at the
     96end of the transaction.
     97
     98The ``dumpdata`` command can be used to generate input for ``loaddata``.
     99
     100.. _serializer: ../serialization/#serialization-formats
     101
     102--verbosity
     103~~~~~~~~~~~
     104
     105Use ``--verbosity`` to specify the amount of notification and debug information
     106that ``django-admin.py`` should print to the console.
     107
     108    * ``0`` means no input.
     109    * ``1`` means normal input (default).
     110    * ``2`` means verbose input.
     111
     112Example usage::
     113
     114    django-admin.py loaddata --verbosity=2
     115
     116--traceback
     117~~~~~~~~~~~
     118
     119Use ``--traceback`` to specify that ``django-admin.py`` should print a
     120traceback to the console when an exception occurs during the loading of a
     121fixture.
     122
     123.. admonition:: MySQL and Fixtures
     124
     125    Unfortunately, MySQL isn't capable of completely supporting all the
     126    features of Django fixtures. If you use MyISAM tables, MySQL doesn't
     127    support transactions or constraints, so you won't get a rollback if
     128    multiple transaction files are found, or validation of fixture data.
     129    If you use InnoDB tables, you won't be able to have any forward
     130    references in your data files - MySQL doesn't provide a mechanism to
     131    defer checking of row constraints until a transaction is committed.
     132
     133Using fixtures for loading initial data
     134---------------------------------------
     135
     136Django's ``django-admin syncdb`` command uses the fixture framework on every
     137run to check for a fixture named ``initial_data``. When this fixture exists,
     138it is automatically `loaded`_. This allows you to define data you want to be
     139available within your project's database, on every fresh start. Look at
     140`saving`_ fixtures to see how you can actually save project data to the
     141``initial_data`` fixture.
     142
     143.. _loaded: ./#loading-fixtures
     144.. _saving: ./#saving-fixtures
     145
     146Using fixtures in automated tests
     147---------------------------------
     148
     149The fixtures framework opens up an interesting possibility for use in unit
     150tests. In short, when you want to use test data for use during unit tests you
     151can use the ``django-admin.py dumpdata`` command to save part or all of your
     152project's current data and refer to this named fixture from within your unit
     153test. For details on how to do this, please look at the `fixture loading`_
     154section of the ``testing Django applications`` documentation.
     155
     156.. _fixture loading: ../testing/#fixture-loading
     157
     158Saving fixtures
     159===============
     160
     161The ``django-admin.py dumpdata <appname appname ...>`` command serializes the
     162data of the selected apps, currently in the database, and dumps it to the
     163console.
     164
     165You are responsible for deciding upon the right place of saving your fixture
     166data. Look at the `loading fixtures`_ documentation on the locations Django
     167uses to search for fixture data.
     168
     169For example using the project called ``myproject`` from the example above. You
     170could save data you have just inserted into ``myproject.polls`` as a named
     171fixture called mynewdata by issuing the following command::
     172
     173    django-admin.py dumpdata polls > polls/fixtures/mynewdata.json
     174
     175If no application name is provided, all installed applications will be dumped.
     176
     177The output of ``dumpdata`` can be used as input for ``loaddata``.
     178
     179.. admonition:: Dumpdata and custom managers
     180
     181    Note that ``dumpdata`` uses the default manager on the model for selecting
     182    the records to dump. If you're using a `custom manager`_ as the default
     183    manager and it filters some of the available records, not all of the objects
     184    will be dumped.
     185
     186.. _dumpdata command: ../django-admin/#dumpdata-appname-appname
     187.. _loading fixtures: ./#loading-fixtures
     188.. _custom manager: ../model-api/#custom-managers
     189
     190--format
     191~~~~~~~~
     192
     193By default, ``dumpdata`` will format its output in JSON, but you can use the
     194``--format`` option to specify another format. Currently supported formats are
     195listed in `Serialization formats`_.
     196
     197Example usage::
     198
     199    django-admin.py dumpdata --format=xml
     200
     201.. _Serialization formats: ../serialization/#serialization-formats
     202
     203--indent
     204~~~~~~~~
     205
     206By default, ``dumpdata`` will output all data on a single line. This isn't easy
     207for humans to read, so you can use the ``--indent`` option to pretty-print the
     208output with a number of indentation spaces.
     209
     210Example usage::
     211
     212    django-admin.py dumpdata --indent=4
     213
     214--traceback
     215~~~~~~~~~~~
     216
     217Use ``--traceback`` to specify that ``django-admin.py`` should print a
     218traceback to the console when an exception occurs during the dumping of a
     219fixture.
  • docs/testing.txt

     
    743743
    744744A test case for a database-backed Web site isn't much use if there isn't any
    745745data in the database. To make it easy to put test data into the database,
    746 Django's custom ``TestCase`` class provides a way of loading **fixtures**.
     746Django's custom ``TestCase`` class provides a way of loading **fixtures**. To
     747understand what fixtures are about, have a look at the
     748`fixtures documentation`_.
    747749
    748 A fixture is a collection of data that Django knows how to import into a
    749 database. For example, if your site has user accounts, you might set up a
    750 fixture of fake user accounts in order to populate your database during tests.
    751 
    752 The most straightforward way of creating a fixture is to use the
    753 ``manage.py dumpdata`` command. This assumes you already have some data in
    754 your database. See the `dumpdata documentation`_ for more details.
    755 
    756 .. note::
    757     If you've ever run ``manage.py syncdb``, you've already used a fixture
    758     without even knowing it! When you call ``syncdb`` in the database for
    759     the first time, Django installs a fixture called ``initial_data``.
    760     This gives you a way of populating a new database with any initial data,
    761     such as a default set of categories.
    762 
    763     Fixtures with other names can always be installed manually using the
    764     ``manage.py loaddata`` command.
    765 
    766750Once you've created a fixture and placed it somewhere in your Django project,
    767751you can use it in your unit tests by specifying a ``fixtures`` class attribute
    768752on your ``django.test.TestCase`` subclass::
     
    786770      directly after ``syncdb`` was called.
    787771
    788772    * Then, all the named fixtures are installed. In this example, Django will
    789       install any JSON fixture named ``mammals``, followed by any fixture named
    790       ``birds``. See the `loaddata documentation`_ for more details on defining
    791       and installing fixtures.
     773      install any JSON fixture named ``mammals``, followed by any fixture
     774      named ``birds``. See the `loading fixtures`_ section in the fixtures
     775      documentation, for more details on defining and installing fixtures.
    792776
    793777This flush/load procedure is repeated for each test in the test case, so you
    794778can be certain that the outcome of a test will not be affected by
    795779another test, or by the order of test execution.
    796780
    797 .. _dumpdata documentation: ../django-admin/#dumpdata-appname-appname
    798 .. _loaddata documentation: ../django-admin/#loaddata-fixture-fixture
     781.. _fixtures documentation: ../fixtures/
     782.. _loading fixtures: ../fixtures/#loading-fixtures
    799783
    800784Emptying the test outbox
    801785~~~~~~~~~~~~~~~~~~~~~~~~
  • docs/django-admin.txt

     
    6868
    6969Examples of output::
    7070
    71         0.95
     71    0.95
    7272    0.96
    7373    0.97-pre-SVN-6069
    7474
     
    126126------------------------------
    127127
    128128Outputs to standard output all data in the database associated with the named
    129 application(s).
     129application(s). Please look at the fixtures documentation for an explanation on
     130`saving fixtures`_.
    130131
    131 If no application name is provided, all installed applications will be dumped.
    132 
    133132The output of ``dumpdata`` can be used as input for ``loaddata``.
    134133
    135 Note that ``dumpdata`` uses the default manager on the model for selecting the
    136 records to dump. If you're using a `custom manager`_ as the default manager
    137 and it filters some of the available records, not all of the objects will be
    138 dumped.
     134.. _saving fixtures: ../fixtures/#saving-fixtures
    139135
    140 .. _custom manager: ../model-api/#custom-managers
    141 
    142 --format
    143 ~~~~~~~~
    144 
    145 By default, ``dumpdata`` will format its output in JSON, but you can use the
    146 ``--format`` option to specify another format. Currently supported formats are
    147 listed in `Serialization formats`_.
    148 
    149 Example usage::
    150 
    151     django-admin.py dumpdata --format=xml
    152 
    153 .. _Serialization formats: ../serialization/#serialization-formats
    154 
    155 --indent
    156 ~~~~~~~~
    157 
    158 By default, ``dumpdata`` will output all data on a single line. This isn't easy
    159 for humans to read, so you can use the ``--indent`` option to pretty-print the
    160 output with a number of indentation spaces.
    161 
    162 Example usage::
    163 
    164     django-admin.py dumpdata --indent=4
    165 
    166136flush
    167137-----
    168138
     
    244214------------------------------
    245215
    246216Searches for and loads the contents of the named fixture into the database.
     217Please look at the fixtures documentation for an explanation on
     218`loading fixtures`_.
    247219
    248 A *fixture* is a collection of files that contain the serialized contents of
    249 the database. Each fixture has a unique name, and the files that comprise the
    250 fixture can be distributed over multiple directories, in multiple applications.
     220The output of ``dumpdata`` can be used as input for ``loaddata``.
    251221
    252 Django will search in three locations for fixtures:
     222.. _loading fixtures: ../fixtures/#loading-fixtures
    253223
    254    1. In the ``fixtures`` directory of every installed application
    255    2. In any directory named in the ``FIXTURE_DIRS`` setting
    256    3. In the literal path named by the fixture
    257 
    258 Django will load any and all fixtures it finds in these locations that match
    259 the provided fixture names.
    260 
    261 If the named fixture has a file extension, only fixtures of that type
    262 will be loaded. For example::
    263 
    264     django-admin.py loaddata mydata.json
    265 
    266 would only load JSON fixtures called ``mydata``. The fixture extension
    267 must correspond to the registered name of a serializer (e.g., ``json`` or
    268 ``xml``).
    269 
    270 If you omit the extension, Django will search all available fixture types
    271 for a matching fixture. For example::
    272 
    273     django-admin.py loaddata mydata
    274 
    275 would look for any fixture of any fixture type called ``mydata``. If a fixture
    276 directory contained ``mydata.json``, that fixture would be loaded
    277 as a JSON fixture. However, if two fixtures with the same name but different
    278 fixture type are discovered (for example, if ``mydata.json`` and
    279 ``mydata.xml`` were found in the same fixture directory), fixture
    280 installation will be aborted, and any data installed in the call to
    281 ``loaddata`` will be removed from the database.
    282 
    283 The fixtures that are named can include directory components. These
    284 directories will be included in the search path. For example::
    285 
    286     django-admin.py loaddata foo/bar/mydata.json
    287 
    288 would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
    289 application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
    290 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
    291 
    292 Note that the order in which fixture files are processed is undefined. However,
    293 all fixture data is installed as a single transaction, so data in
    294 one fixture can reference data in another fixture. If the database backend
    295 supports row-level constraints, these constraints will be checked at the
    296 end of the transaction.
    297 
    298 The ``dumpdata`` command can be used to generate input for ``loaddata``.
    299 
    300 .. admonition:: MySQL and Fixtures
    301 
    302     Unfortunately, MySQL isn't capable of completely supporting all the
    303     features of Django fixtures. If you use MyISAM tables, MySQL doesn't
    304     support transactions or constraints, so you won't get a rollback if
    305     multiple transaction files are found, or validation of fixture data.
    306     If you use InnoDB tables, you won't be able to have any forward
    307     references in your data files - MySQL doesn't provide a mechanism to
    308     defer checking of row constraints until a transaction is committed.
    309 
    310 --verbosity
    311 ~~~~~~~~~~~
    312 
    313 Use ``--verbosity`` to specify the amount of notification and debug information
    314 that ``django-admin.py`` should print to the console.
    315 
    316         * ``0`` means no input.
    317         * ``1`` means normal input (default).
    318         * ``2`` means verbose input.
    319 
    320 Example usage::
    321 
    322     django-admin.py loaddata --verbosity=2
    323 
    324224reset <appname appname ...>
    325225---------------------------
    326226
     
    606506**New in Django development version**
    607507
    608508Runs a Django development server (as in ``runserver``) using data from the
    609 given fixture(s).
     509given fixture(s). For an explanation on what fixtures are, please look at the
     510`fixtures documentation`_.
    610511
    611512For example, this command::
    612513
     
    616517
    617518    1. Create a test database, as described in `testing Django applications`_.
    618519    2. Populate the test database with fixture data from the given fixtures.
    619        (For more on fixtures, see the documentation for ``loaddata`` above.)
    620520    3. Runs the Django development server (as in ``runserver``), pointed at
    621521       this newly created test database instead of your production database.
    622522
     
    639539templates.
    640540
    641541.. _unit tests: ../testing/
     542.. _fixtures documentation: ../fixtures/
    642543
    643544--addrport [port number or ipaddr:port]
    644545~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Back to Top