Django

Code

Ticket #5096: fixtures-documentation.diff

File fixtures-documentation.diff, 20.7 kB (added by shanx, 4 months ago)

First concept of fixtures documentation

  • tests/modeltests/fixtures/models.py

    old new  
    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

    old new  
    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

    old new  
    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

    old new  
     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

    old new  
    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

    old new  
    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~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~