Code

Ticket #5096: fixtures-documentation.diff

File fixtures-documentation.diff, 20.7 KB (added by shanx, 6 years ago)

First concept of fixtures documentation

Line 
1Index: tests/modeltests/fixtures/models.py
2===================================================================
3--- tests/modeltests/fixtures/models.py (revision 7309)
4+++ tests/modeltests/fixtures/models.py (working copy)
5@@ -1,11 +1,10 @@
6 """
7 37. Fixtures.
8 
9-Fixtures are a way of loading data into the database in bulk. Fixure data
10-can be stored in any serializable format (including JSON and XML). Fixtures
11-are identified by name, and are stored in either a directory named 'fixtures'
12-in the application directory, on in one of the directories named in the
13-FIXTURE_DIRS setting.
14+For an explanation of what fixtures are, please look at the
15+`fixtures documentation`_.
16+
17+.. _Fixtures documentation: ../../fixtures/
18 """
19 
20 from django.db import models
21Index: AUTHORS
22===================================================================
23--- AUTHORS     (revision 7309)
24+++ AUTHORS     (working copy)
25@@ -289,7 +289,7 @@
26     Philippe Raoult <philippe.raoult@n2nsoft.com>
27     Massimiliano Ravelli <massimiliano.ravelli@gmail.com>
28     Brian Ray <http://brianray.chipy.org/>
29-    remco@diji.biz
30+    Remco Wendt <remco@diji.biz>
31     David Reynolds <david@reynoldsfamily.org.uk>
32     rhettg@gmail.com
33     ricardojbarrios@gmail.com
34Index: docs/model-api.txt
35===================================================================
36--- docs/model-api.txt  (revision 7309)
37+++ docs/model-api.txt  (working copy)
38@@ -2073,9 +2073,18 @@
39         #...
40     )
41 
42-Providing initial SQL data
43-==========================
44+Providing initial data
45+======================
46 
47+Django provides two ways for automatically loading data into the database just
48+after the CREATE TABLE statements. This is useful if you want to populate your
49+database with default records. You can provide Django with initial data by
50+providing custom SQL that does inserts into the appropriate tables and/or make
51+use of Django's fixture framework.
52+
53+Providing initial data using SQL
54+--------------------------------
55+
56 Django provides a hook for passing the database arbitrary SQL that's executed
57 just after the CREATE TABLE statements. Use this hook, for example, if you want
58 to populate default records, or create SQL functions, automatically.
59@@ -2104,10 +2113,10 @@
60 time your custom data files are executed, all the database tables already will
61 have been created.
62 
63-.. _`manage.py documentation`: ../django-admin/#sqlcustom-appname-appname
64+.. _manage.py documentation: ../django-admin/#sqlcustom-appname-appname
65 
66 Database-backend-specific SQL data
67-----------------------------------
68+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69 
70 There's also a hook for backend-specific SQL data. For example, you can have
71 separate initial-data files for PostgreSQL and MySQL. For each app, Django
72@@ -2121,3 +2130,13 @@
73 ``sql/person.postgresql.sql`` and you're installing the app on PostgreSQL,
74 Django will execute the contents of ``sql/person.postgresql.sql`` first, then
75 ``sql/person.sql``.
76+
77+Providing initial data using fixtures
78+-------------------------------------
79+
80+An elegant way of providing initial data for your project is using Django's
81+fixture framework. Have a look at the
82+`using fixtures for loading initial data`_
83+section in the fixtures documentation.
84+
85+.. _using fixtures for loading initial data: ../fixtures/#using-fixtures-for-loading-initial-data
86Index: docs/fixtures.txt
87===================================================================
88--- docs/fixtures.txt   (revision 0)
89+++ docs/fixtures.txt   (revision 0)
90@@ -0,0 +1,219 @@
91+===========================
92+Django's fixtures framework
93+===========================
94+
95+The fixtures framework provides an easy way to save and load snapshots of your
96+data. A *fixture* is a collection of one or more files with a unique name that
97+contain the serialized contents of the database. These files can be
98+distributed over multiple directories, in multiple applications.
99+
100+A very nice way of using fixtures is Django's testserver. Basically you can
101+first populate your applications with test data, save the data of all your
102+applications to a fixture and then tell the testserver to use this data
103+when you launch the testserver. Allowing you to change data while
104+testing, knowing that a restart of the testserver resets all changes. See the
105+`testserver documentation`_ for more information.
106+
107+.. note::
108+    If you've ever run ``manage.py syncdb``, you've already used a fixture
109+    without even knowing it! When you call ``syncdb`` in the database for
110+    the first time, Django installs a fixture called ``initial_data``.
111+    This gives you a way of populating a new database with any initial data,
112+    such as a default set of categories.
113+
114+    Fixtures with other names can always be installed manually using the
115+    ``manage.py loaddata`` command.
116+
117+.. _testserver documentation: ../django-admin/#testserver-fixture-fixture
118+
119+Loading fixtures
120+================
121+
122+The ``django-admin.py loaddata <fixture fixture ...>`` command searches for
123+and loads the contents of the named fixture into the database.
124+
125+Django will search in three locations for fixtures:
126+
127+   1. In the ``fixtures`` directory of every installed application
128+   2. In any directory named in the ``FIXTURE_DIRS`` setting
129+   3. In the literal path named by the fixture
130+
131+Django will load any and all fixtures it finds in these locations that match
132+the provided fixture names.
133+
134+For example if you have a project called ``myproject`` which contains two
135+applications: ``myproject.polls`` and ``myproject.animals``. The layout of
136+your project directory including the fixtures could look something like this::
137+
138+    myproject/__init__.py
139+    myproject/settings.py
140+    myproject/urls.py
141+    myproject/manage.py
142+    myproject/animals/__init__.py
143+    myproject/animals/models.py
144+    myproject/animals/views.py
145+    myproject/animals/fixtures/mydata.json
146+    myproject/polls/__init__.py
147+    myproject/polls/models.py
148+    myproject/polls/views.py
149+    myproject/polls/fixtures/mydata.xml       
150+
151+To load the fixture called ``mydata`` into the database, populating both
152+``myproject.animals`` and ``myproject.polls``, you would issue the following
153+command::
154+
155+    django-admin.py loaddata mydata
156+
157+This will load both the json and xml file. If the named fixture has a file
158+extension, only fixtures of that type will be loaded. For example::
159+
160+    django-admin.py loaddata mydata.json
161+
162+would only load JSON fixtures called ``mydata``, in this cases only the
163+fixture file in ``myproject/animals/fixtures/`` would be loaded. The fixture
164+extension must correspond to the registered name of a `serializer`_ (e.g.,
165+``json`` or ``xml``).
166+
167+If two fixtures with the same name but different fixture types are discovered
168+in the same directory (for example, having both ``mydata.json`` and
169+``mydata.xml`` in ``myproject/polls/fixtures/``), fixture installation will be
170+aborted, and any data installed in the call to ``loaddata`` will be removed
171+from the database.
172+
173+The fixtures that are named can include directory components. These
174+directories will be included in the search path. For example::
175+
176+    django-admin.py loaddata foo/bar/mydata.json
177+
178+would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
179+application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
180+``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
181+
182+Note that the order in which fixture files are processed is undefined. However,
183+all fixture data is installed as a single transaction, so data in
184+one fixture can reference data in another fixture. If the database backend
185+supports row-level constraints, these constraints will be checked at the
186+end of the transaction.
187+
188+The ``dumpdata`` command can be used to generate input for ``loaddata``.
189+
190+.. _serializer: ../serialization/#serialization-formats
191+
192+--verbosity
193+~~~~~~~~~~~
194+
195+Use ``--verbosity`` to specify the amount of notification and debug information
196+that ``django-admin.py`` should print to the console.
197+
198+    * ``0`` means no input.
199+    * ``1`` means normal input (default).
200+    * ``2`` means verbose input.
201+
202+Example usage::
203+
204+    django-admin.py loaddata --verbosity=2
205+
206+--traceback
207+~~~~~~~~~~~
208+
209+Use ``--traceback`` to specify that ``django-admin.py`` should print a
210+traceback to the console when an exception occurs during the loading of a
211+fixture.
212+
213+.. admonition:: MySQL and Fixtures
214+
215+    Unfortunately, MySQL isn't capable of completely supporting all the
216+    features of Django fixtures. If you use MyISAM tables, MySQL doesn't
217+    support transactions or constraints, so you won't get a rollback if
218+    multiple transaction files are found, or validation of fixture data.
219+    If you use InnoDB tables, you won't be able to have any forward
220+    references in your data files - MySQL doesn't provide a mechanism to
221+    defer checking of row constraints until a transaction is committed.
222+
223+Using fixtures for loading initial data
224+---------------------------------------
225+
226+Django's ``django-admin syncdb`` command uses the fixture framework on every
227+run to check for a fixture named ``initial_data``. When this fixture exists,
228+it is automatically `loaded`_. This allows you to define data you want to be
229+available within your project's database, on every fresh start. Look at
230+`saving`_ fixtures to see how you can actually save project data to the
231+``initial_data`` fixture.
232+
233+.. _loaded: ./#loading-fixtures
234+.. _saving: ./#saving-fixtures
235+
236+Using fixtures in automated tests
237+---------------------------------
238+
239+The fixtures framework opens up an interesting possibility for use in unit
240+tests. In short, when you want to use test data for use during unit tests you
241+can use the ``django-admin.py dumpdata`` command to save part or all of your
242+project's current data and refer to this named fixture from within your unit
243+test. For details on how to do this, please look at the `fixture loading`_
244+section of the ``testing Django applications`` documentation.
245+
246+.. _fixture loading: ../testing/#fixture-loading
247+
248+Saving fixtures
249+===============
250+
251+The ``django-admin.py dumpdata <appname appname ...>`` command serializes the
252+data of the selected apps, currently in the database, and dumps it to the
253+console.
254+
255+You are responsible for deciding upon the right place of saving your fixture
256+data. Look at the `loading fixtures`_ documentation on the locations Django
257+uses to search for fixture data.
258+
259+For example using the project called ``myproject`` from the example above. You
260+could save data you have just inserted into ``myproject.polls`` as a named
261+fixture called mynewdata by issuing the following command::
262+
263+    django-admin.py dumpdata polls > polls/fixtures/mynewdata.json
264+
265+If no application name is provided, all installed applications will be dumped.
266+
267+The output of ``dumpdata`` can be used as input for ``loaddata``.
268+
269+.. admonition:: Dumpdata and custom managers
270+
271+    Note that ``dumpdata`` uses the default manager on the model for selecting
272+    the records to dump. If you're using a `custom manager`_ as the default
273+    manager and it filters some of the available records, not all of the objects
274+    will be dumped.
275+
276+.. _dumpdata command: ../django-admin/#dumpdata-appname-appname
277+.. _loading fixtures: ./#loading-fixtures
278+.. _custom manager: ../model-api/#custom-managers
279+
280+--format
281+~~~~~~~~
282+
283+By default, ``dumpdata`` will format its output in JSON, but you can use the
284+``--format`` option to specify another format. Currently supported formats are
285+listed in `Serialization formats`_.
286+
287+Example usage::
288+
289+    django-admin.py dumpdata --format=xml
290+
291+.. _Serialization formats: ../serialization/#serialization-formats
292+
293+--indent
294+~~~~~~~~
295+
296+By default, ``dumpdata`` will output all data on a single line. This isn't easy
297+for humans to read, so you can use the ``--indent`` option to pretty-print the
298+output with a number of indentation spaces.
299+
300+Example usage::
301+
302+    django-admin.py dumpdata --indent=4
303+
304+--traceback
305+~~~~~~~~~~~
306+
307+Use ``--traceback`` to specify that ``django-admin.py`` should print a
308+traceback to the console when an exception occurs during the dumping of a
309+fixture.
310Index: docs/testing.txt
311===================================================================
312--- docs/testing.txt    (revision 7309)
313+++ docs/testing.txt    (working copy)
314@@ -743,26 +743,10 @@
315 
316 A test case for a database-backed Web site isn't much use if there isn't any
317 data in the database. To make it easy to put test data into the database,
318-Django's custom ``TestCase`` class provides a way of loading **fixtures**.
319+Django's custom ``TestCase`` class provides a way of loading **fixtures**. To
320+understand what fixtures are about, have a look at the
321+`fixtures documentation`_.
322 
323-A fixture is a collection of data that Django knows how to import into a
324-database. For example, if your site has user accounts, you might set up a
325-fixture of fake user accounts in order to populate your database during tests.
326-
327-The most straightforward way of creating a fixture is to use the
328-``manage.py dumpdata`` command. This assumes you already have some data in
329-your database. See the `dumpdata documentation`_ for more details.
330-
331-.. note::
332-    If you've ever run ``manage.py syncdb``, you've already used a fixture
333-    without even knowing it! When you call ``syncdb`` in the database for
334-    the first time, Django installs a fixture called ``initial_data``.
335-    This gives you a way of populating a new database with any initial data,
336-    such as a default set of categories.
337-
338-    Fixtures with other names can always be installed manually using the
339-    ``manage.py loaddata`` command.
340-
341 Once you've created a fixture and placed it somewhere in your Django project,
342 you can use it in your unit tests by specifying a ``fixtures`` class attribute
343 on your ``django.test.TestCase`` subclass::
344@@ -786,16 +770,16 @@
345       directly after ``syncdb`` was called.
346 
347     * Then, all the named fixtures are installed. In this example, Django will
348-      install any JSON fixture named ``mammals``, followed by any fixture named
349-      ``birds``. See the `loaddata documentation`_ for more details on defining
350-      and installing fixtures.
351+      install any JSON fixture named ``mammals``, followed by any fixture
352+      named ``birds``. See the `loading fixtures`_ section in the fixtures
353+      documentation, for more details on defining and installing fixtures.
354 
355 This flush/load procedure is repeated for each test in the test case, so you
356 can be certain that the outcome of a test will not be affected by
357 another test, or by the order of test execution.
358 
359-.. _dumpdata documentation: ../django-admin/#dumpdata-appname-appname
360-.. _loaddata documentation: ../django-admin/#loaddata-fixture-fixture
361+.. _fixtures documentation: ../fixtures/
362+.. _loading fixtures: ../fixtures/#loading-fixtures
363 
364 Emptying the test outbox
365 ~~~~~~~~~~~~~~~~~~~~~~~~
366Index: docs/django-admin.txt
367===================================================================
368--- docs/django-admin.txt       (revision 7309)
369+++ docs/django-admin.txt       (working copy)
370@@ -68,7 +68,7 @@
371 
372 Examples of output::
373 
374-       0.95
375+    0.95
376     0.96
377     0.97-pre-SVN-6069
378 
379@@ -126,43 +126,13 @@
380 ------------------------------
381 
382 Outputs to standard output all data in the database associated with the named
383-application(s).
384+application(s). Please look at the fixtures documentation for an explanation on
385+`saving fixtures`_.
386 
387-If no application name is provided, all installed applications will be dumped.
388-
389 The output of ``dumpdata`` can be used as input for ``loaddata``.
390 
391-Note that ``dumpdata`` uses the default manager on the model for selecting the
392-records to dump. If you're using a `custom manager`_ as the default manager
393-and it filters some of the available records, not all of the objects will be
394-dumped.
395+.. _saving fixtures: ../fixtures/#saving-fixtures
396 
397-.. _custom manager: ../model-api/#custom-managers
398-
399---format
400-~~~~~~~~
401-
402-By default, ``dumpdata`` will format its output in JSON, but you can use the
403-``--format`` option to specify another format. Currently supported formats are
404-listed in `Serialization formats`_.
405-
406-Example usage::
407-
408-    django-admin.py dumpdata --format=xml
409-
410-.. _Serialization formats: ../serialization/#serialization-formats
411-
412---indent
413-~~~~~~~~
414-
415-By default, ``dumpdata`` will output all data on a single line. This isn't easy
416-for humans to read, so you can use the ``--indent`` option to pretty-print the
417-output with a number of indentation spaces.
418-
419-Example usage::
420-
421-    django-admin.py dumpdata --indent=4
422-
423 flush
424 -----
425 
426@@ -244,83 +214,13 @@
427 ------------------------------
428 
429 Searches for and loads the contents of the named fixture into the database.
430+Please look at the fixtures documentation for an explanation on
431+`loading fixtures`_.
432 
433-A *fixture* is a collection of files that contain the serialized contents of
434-the database. Each fixture has a unique name, and the files that comprise the
435-fixture can be distributed over multiple directories, in multiple applications.
436+The output of ``dumpdata`` can be used as input for ``loaddata``.
437 
438-Django will search in three locations for fixtures:
439+.. _loading fixtures: ../fixtures/#loading-fixtures
440 
441-   1. In the ``fixtures`` directory of every installed application
442-   2. In any directory named in the ``FIXTURE_DIRS`` setting
443-   3. In the literal path named by the fixture
444-
445-Django will load any and all fixtures it finds in these locations that match
446-the provided fixture names.
447-
448-If the named fixture has a file extension, only fixtures of that type
449-will be loaded. For example::
450-
451-    django-admin.py loaddata mydata.json
452-
453-would only load JSON fixtures called ``mydata``. The fixture extension
454-must correspond to the registered name of a serializer (e.g., ``json`` or
455-``xml``).
456-
457-If you omit the extension, Django will search all available fixture types
458-for a matching fixture. For example::
459-
460-    django-admin.py loaddata mydata
461-
462-would look for any fixture of any fixture type called ``mydata``. If a fixture
463-directory contained ``mydata.json``, that fixture would be loaded
464-as a JSON fixture. However, if two fixtures with the same name but different
465-fixture type are discovered (for example, if ``mydata.json`` and
466-``mydata.xml`` were found in the same fixture directory), fixture
467-installation will be aborted, and any data installed in the call to
468-``loaddata`` will be removed from the database.
469-
470-The fixtures that are named can include directory components. These
471-directories will be included in the search path. For example::
472-
473-    django-admin.py loaddata foo/bar/mydata.json
474-
475-would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
476-application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
477-``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
478-
479-Note that the order in which fixture files are processed is undefined. However,
480-all fixture data is installed as a single transaction, so data in
481-one fixture can reference data in another fixture. If the database backend
482-supports row-level constraints, these constraints will be checked at the
483-end of the transaction.
484-
485-The ``dumpdata`` command can be used to generate input for ``loaddata``.
486-
487-.. admonition:: MySQL and Fixtures
488-
489-    Unfortunately, MySQL isn't capable of completely supporting all the
490-    features of Django fixtures. If you use MyISAM tables, MySQL doesn't
491-    support transactions or constraints, so you won't get a rollback if
492-    multiple transaction files are found, or validation of fixture data.
493-    If you use InnoDB tables, you won't be able to have any forward
494-    references in your data files - MySQL doesn't provide a mechanism to
495-    defer checking of row constraints until a transaction is committed.
496-
497---verbosity
498-~~~~~~~~~~~
499-
500-Use ``--verbosity`` to specify the amount of notification and debug information
501-that ``django-admin.py`` should print to the console.
502-
503-       * ``0`` means no input.
504-       * ``1`` means normal input (default).
505-       * ``2`` means verbose input.
506-
507-Example usage::
508-
509-    django-admin.py loaddata --verbosity=2
510-
511 reset <appname appname ...>
512 ---------------------------
513 
514@@ -606,7 +506,8 @@
515 **New in Django development version**
516 
517 Runs a Django development server (as in ``runserver``) using data from the
518-given fixture(s).
519+given fixture(s). For an explanation on what fixtures are, please look at the
520+`fixtures documentation`_.
521 
522 For example, this command::
523 
524@@ -616,7 +517,6 @@
525 
526     1. Create a test database, as described in `testing Django applications`_.
527     2. Populate the test database with fixture data from the given fixtures.
528-       (For more on fixtures, see the documentation for ``loaddata`` above.)
529     3. Runs the Django development server (as in ``runserver``), pointed at
530        this newly created test database instead of your production database.
531 
532@@ -639,6 +539,7 @@
533 templates.
534 
535 .. _unit tests: ../testing/
536+.. _fixtures documentation: ../fixtures/
537 
538 --addrport [port number or ipaddr:port]
539 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~