Ticket #5096: fixtures-documentation.diff
| File fixtures-documentation.diff, 20.7 KB (added by , 16 years ago) |
|---|
-
tests/modeltests/fixtures/models.py
1 1 """ 2 2 37. Fixtures. 3 3 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. 4 For an explanation of what fixtures are, please look at the 5 `fixtures documentation`_. 6 7 .. _Fixtures documentation: ../../fixtures/ 9 8 """ 10 9 11 10 from django.db import models -
AUTHORS
289 289 Philippe Raoult <philippe.raoult@n2nsoft.com> 290 290 Massimiliano Ravelli <massimiliano.ravelli@gmail.com> 291 291 Brian Ray <http://brianray.chipy.org/> 292 remco@diji.biz292 Remco Wendt <remco@diji.biz> 293 293 David Reynolds <david@reynoldsfamily.org.uk> 294 294 rhettg@gmail.com 295 295 ricardojbarrios@gmail.com -
docs/model-api.txt
2073 2073 #... 2074 2074 ) 2075 2075 2076 Providing initial SQLdata2077 ====================== ====2076 Providing initial data 2077 ====================== 2078 2078 2079 Django provides two ways for automatically loading data into the database just 2080 after the CREATE TABLE statements. This is useful if you want to populate your 2081 database with default records. You can provide Django with initial data by 2082 providing custom SQL that does inserts into the appropriate tables and/or make 2083 use of Django's fixture framework. 2084 2085 Providing initial data using SQL 2086 -------------------------------- 2087 2079 2088 Django provides a hook for passing the database arbitrary SQL that's executed 2080 2089 just after the CREATE TABLE statements. Use this hook, for example, if you want 2081 2090 to populate default records, or create SQL functions, automatically. … … 2104 2113 time your custom data files are executed, all the database tables already will 2105 2114 have been created. 2106 2115 2107 .. _ `manage.py documentation`: ../django-admin/#sqlcustom-appname-appname2116 .. _manage.py documentation: ../django-admin/#sqlcustom-appname-appname 2108 2117 2109 2118 Database-backend-specific SQL data 2110 ---------------------------------- 2119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2111 2120 2112 2121 There's also a hook for backend-specific SQL data. For example, you can have 2113 2122 separate initial-data files for PostgreSQL and MySQL. For each app, Django … … 2121 2130 ``sql/person.postgresql.sql`` and you're installing the app on PostgreSQL, 2122 2131 Django will execute the contents of ``sql/person.postgresql.sql`` first, then 2123 2132 ``sql/person.sql``. 2133 2134 Providing initial data using fixtures 2135 ------------------------------------- 2136 2137 An elegant way of providing initial data for your project is using Django's 2138 fixture framework. Have a look at the 2139 `using fixtures for loading initial data`_ 2140 section in the fixtures documentation. 2141 2142 .. _using fixtures for loading initial data: ../fixtures/#using-fixtures-for-loading-initial-data -
docs/fixtures.txt
1 =========================== 2 Django's fixtures framework 3 =========================== 4 5 The fixtures framework provides an easy way to save and load snapshots of your 6 data. A *fixture* is a collection of one or more files with a unique name that 7 contain the serialized contents of the database. These files can be 8 distributed over multiple directories, in multiple applications. 9 10 A very nice way of using fixtures is Django's testserver. Basically you can 11 first populate your applications with test data, save the data of all your 12 applications to a fixture and then tell the testserver to use this data 13 when you launch the testserver. Allowing you to change data while 14 testing, 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 29 Loading fixtures 30 ================ 31 32 The ``django-admin.py loaddata <fixture fixture ...>`` command searches for 33 and loads the contents of the named fixture into the database. 34 35 Django 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 41 Django will load any and all fixtures it finds in these locations that match 42 the provided fixture names. 43 44 For example if you have a project called ``myproject`` which contains two 45 applications: ``myproject.polls`` and ``myproject.animals``. The layout of 46 your 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 61 To load the fixture called ``mydata`` into the database, populating both 62 ``myproject.animals`` and ``myproject.polls``, you would issue the following 63 command:: 64 65 django-admin.py loaddata mydata 66 67 This will load both the json and xml file. If the named fixture has a file 68 extension, only fixtures of that type will be loaded. For example:: 69 70 django-admin.py loaddata mydata.json 71 72 would only load JSON fixtures called ``mydata``, in this cases only the 73 fixture file in ``myproject/animals/fixtures/`` would be loaded. The fixture 74 extension must correspond to the registered name of a `serializer`_ (e.g., 75 ``json`` or ``xml``). 76 77 If two fixtures with the same name but different fixture types are discovered 78 in the same directory (for example, having both ``mydata.json`` and 79 ``mydata.xml`` in ``myproject/polls/fixtures/``), fixture installation will be 80 aborted, and any data installed in the call to ``loaddata`` will be removed 81 from the database. 82 83 The fixtures that are named can include directory components. These 84 directories will be included in the search path. For example:: 85 86 django-admin.py loaddata foo/bar/mydata.json 87 88 would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed 89 application, ``<dirname>/foo/bar/mydata.json`` for each directory in 90 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``. 91 92 Note that the order in which fixture files are processed is undefined. However, 93 all fixture data is installed as a single transaction, so data in 94 one fixture can reference data in another fixture. If the database backend 95 supports row-level constraints, these constraints will be checked at the 96 end of the transaction. 97 98 The ``dumpdata`` command can be used to generate input for ``loaddata``. 99 100 .. _serializer: ../serialization/#serialization-formats 101 102 --verbosity 103 ~~~~~~~~~~~ 104 105 Use ``--verbosity`` to specify the amount of notification and debug information 106 that ``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 112 Example usage:: 113 114 django-admin.py loaddata --verbosity=2 115 116 --traceback 117 ~~~~~~~~~~~ 118 119 Use ``--traceback`` to specify that ``django-admin.py`` should print a 120 traceback to the console when an exception occurs during the loading of a 121 fixture. 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 133 Using fixtures for loading initial data 134 --------------------------------------- 135 136 Django's ``django-admin syncdb`` command uses the fixture framework on every 137 run to check for a fixture named ``initial_data``. When this fixture exists, 138 it is automatically `loaded`_. This allows you to define data you want to be 139 available 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 146 Using fixtures in automated tests 147 --------------------------------- 148 149 The fixtures framework opens up an interesting possibility for use in unit 150 tests. In short, when you want to use test data for use during unit tests you 151 can use the ``django-admin.py dumpdata`` command to save part or all of your 152 project's current data and refer to this named fixture from within your unit 153 test. For details on how to do this, please look at the `fixture loading`_ 154 section of the ``testing Django applications`` documentation. 155 156 .. _fixture loading: ../testing/#fixture-loading 157 158 Saving fixtures 159 =============== 160 161 The ``django-admin.py dumpdata <appname appname ...>`` command serializes the 162 data of the selected apps, currently in the database, and dumps it to the 163 console. 164 165 You are responsible for deciding upon the right place of saving your fixture 166 data. Look at the `loading fixtures`_ documentation on the locations Django 167 uses to search for fixture data. 168 169 For example using the project called ``myproject`` from the example above. You 170 could save data you have just inserted into ``myproject.polls`` as a named 171 fixture called mynewdata by issuing the following command:: 172 173 django-admin.py dumpdata polls > polls/fixtures/mynewdata.json 174 175 If no application name is provided, all installed applications will be dumped. 176 177 The 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 193 By default, ``dumpdata`` will format its output in JSON, but you can use the 194 ``--format`` option to specify another format. Currently supported formats are 195 listed in `Serialization formats`_. 196 197 Example usage:: 198 199 django-admin.py dumpdata --format=xml 200 201 .. _Serialization formats: ../serialization/#serialization-formats 202 203 --indent 204 ~~~~~~~~ 205 206 By default, ``dumpdata`` will output all data on a single line. This isn't easy 207 for humans to read, so you can use the ``--indent`` option to pretty-print the 208 output with a number of indentation spaces. 209 210 Example usage:: 211 212 django-admin.py dumpdata --indent=4 213 214 --traceback 215 ~~~~~~~~~~~ 216 217 Use ``--traceback`` to specify that ``django-admin.py`` should print a 218 traceback to the console when an exception occurs during the dumping of a 219 fixture. -
docs/testing.txt
743 743 744 744 A test case for a database-backed Web site isn't much use if there isn't any 745 745 data 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**. 746 Django's custom ``TestCase`` class provides a way of loading **fixtures**. To 747 understand what fixtures are about, have a look at the 748 `fixtures documentation`_. 747 749 748 A fixture is a collection of data that Django knows how to import into a749 database. For example, if your site has user accounts, you might set up a750 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 the753 ``manage.py dumpdata`` command. This assumes you already have some data in754 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 fixture758 without even knowing it! When you call ``syncdb`` in the database for759 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 the764 ``manage.py loaddata`` command.765 766 750 Once you've created a fixture and placed it somewhere in your Django project, 767 751 you can use it in your unit tests by specifying a ``fixtures`` class attribute 768 752 on your ``django.test.TestCase`` subclass:: … … 786 770 directly after ``syncdb`` was called. 787 771 788 772 * Then, all the named fixtures are installed. In this example, Django will 789 install any JSON fixture named ``mammals``, followed by any fixture named790 ``birds``. See the `loaddata documentation`_ for more details on defining791 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. 792 776 793 777 This flush/load procedure is repeated for each test in the test case, so you 794 778 can be certain that the outcome of a test will not be affected by 795 779 another test, or by the order of test execution. 796 780 797 .. _ dumpdata documentation: ../django-admin/#dumpdata-appname-appname798 .. _load data documentation: ../django-admin/#loaddata-fixture-fixture781 .. _fixtures documentation: ../fixtures/ 782 .. _loading fixtures: ../fixtures/#loading-fixtures 799 783 800 784 Emptying the test outbox 801 785 ~~~~~~~~~~~~~~~~~~~~~~~~ -
docs/django-admin.txt
68 68 69 69 Examples of output:: 70 70 71 71 0.95 72 72 0.96 73 73 0.97-pre-SVN-6069 74 74 … … 126 126 ------------------------------ 127 127 128 128 Outputs to standard output all data in the database associated with the named 129 application(s). 129 application(s). Please look at the fixtures documentation for an explanation on 130 `saving fixtures`_. 130 131 131 If no application name is provided, all installed applications will be dumped.132 133 132 The output of ``dumpdata`` can be used as input for ``loaddata``. 134 133 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 139 135 140 .. _custom manager: ../model-api/#custom-managers141 142 --format143 ~~~~~~~~144 145 By default, ``dumpdata`` will format its output in JSON, but you can use the146 ``--format`` option to specify another format. Currently supported formats are147 listed in `Serialization formats`_.148 149 Example usage::150 151 django-admin.py dumpdata --format=xml152 153 .. _Serialization formats: ../serialization/#serialization-formats154 155 --indent156 ~~~~~~~~157 158 By default, ``dumpdata`` will output all data on a single line. This isn't easy159 for humans to read, so you can use the ``--indent`` option to pretty-print the160 output with a number of indentation spaces.161 162 Example usage::163 164 django-admin.py dumpdata --indent=4165 166 136 flush 167 137 ----- 168 138 … … 244 214 ------------------------------ 245 215 246 216 Searches for and loads the contents of the named fixture into the database. 217 Please look at the fixtures documentation for an explanation on 218 `loading fixtures`_. 247 219 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. 220 The output of ``dumpdata`` can be used as input for ``loaddata``. 251 221 252 Django will search in three locations for fixtures: 222 .. _loading fixtures: ../fixtures/#loading-fixtures 253 223 254 1. In the ``fixtures`` directory of every installed application255 2. In any directory named in the ``FIXTURE_DIRS`` setting256 3. In the literal path named by the fixture257 258 Django will load any and all fixtures it finds in these locations that match259 the provided fixture names.260 261 If the named fixture has a file extension, only fixtures of that type262 will be loaded. For example::263 264 django-admin.py loaddata mydata.json265 266 would only load JSON fixtures called ``mydata``. The fixture extension267 must correspond to the registered name of a serializer (e.g., ``json`` or268 ``xml``).269 270 If you omit the extension, Django will search all available fixture types271 for a matching fixture. For example::272 273 django-admin.py loaddata mydata274 275 would look for any fixture of any fixture type called ``mydata``. If a fixture276 directory contained ``mydata.json``, that fixture would be loaded277 as a JSON fixture. However, if two fixtures with the same name but different278 fixture type are discovered (for example, if ``mydata.json`` and279 ``mydata.xml`` were found in the same fixture directory), fixture280 installation will be aborted, and any data installed in the call to281 ``loaddata`` will be removed from the database.282 283 The fixtures that are named can include directory components. These284 directories will be included in the search path. For example::285 286 django-admin.py loaddata foo/bar/mydata.json287 288 would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed289 application, ``<dirname>/foo/bar/mydata.json`` for each directory in290 ``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 in294 one fixture can reference data in another fixture. If the database backend295 supports row-level constraints, these constraints will be checked at the296 end of the transaction.297 298 The ``dumpdata`` command can be used to generate input for ``loaddata``.299 300 .. admonition:: MySQL and Fixtures301 302 Unfortunately, MySQL isn't capable of completely supporting all the303 features of Django fixtures. If you use MyISAM tables, MySQL doesn't304 support transactions or constraints, so you won't get a rollback if305 multiple transaction files are found, or validation of fixture data.306 If you use InnoDB tables, you won't be able to have any forward307 references in your data files - MySQL doesn't provide a mechanism to308 defer checking of row constraints until a transaction is committed.309 310 --verbosity311 ~~~~~~~~~~~312 313 Use ``--verbosity`` to specify the amount of notification and debug information314 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=2323 324 224 reset <appname appname ...> 325 225 --------------------------- 326 226 … … 606 506 **New in Django development version** 607 507 608 508 Runs a Django development server (as in ``runserver``) using data from the 609 given fixture(s). 509 given fixture(s). For an explanation on what fixtures are, please look at the 510 `fixtures documentation`_. 610 511 611 512 For example, this command:: 612 513 … … 616 517 617 518 1. Create a test database, as described in `testing Django applications`_. 618 519 2. Populate the test database with fixture data from the given fixtures. 619 (For more on fixtures, see the documentation for ``loaddata`` above.)620 520 3. Runs the Django development server (as in ``runserver``), pointed at 621 521 this newly created test database instead of your production database. 622 522 … … 639 539 templates. 640 540 641 541 .. _unit tests: ../testing/ 542 .. _fixtures documentation: ../fixtures/ 642 543 643 544 --addrport [port number or ipaddr:port] 644 545 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~