[4.2.x] Fixed #15578 -- Stated the processing order of fixtures in the fixtures docs.

Also, added details about loading multiple fixtures and unified line wrapping
at 79 cols.

Co-Authored-By: Aniketh Babu <anikethbabu@gmail.com>
Co-Authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>
Co-Authored-By: Natalia Bidart <124304+nessita@users.noreply.github.com>

Backport of 334dc073b1 from main
This commit is contained in:
Leo Suarez 2023-10-19 15:30:41 -04:00 committed by Natalia
parent 0cd8b867a0
commit 43a3646070
1 changed files with 69 additions and 34 deletions

View File

@ -19,62 +19,104 @@ How to produce a fixture?
=========================
Fixtures can be generated by :djadmin:`manage.py dumpdata <dumpdata>`. It's
also possible to generate custom fixtures by directly using
:doc:`serialization documentation </topics/serialization>` tools or even by
handwriting them.
also possible to generate custom fixtures by directly using :doc:`serialization
tools </topics/serialization>` or even by handwriting them.
What to use a fixture for?
==========================
How to use a fixture?
=====================
Fixtures can be used to pre-populate database with data for
:ref:`tests <topics-testing-fixtures>` or to provide some :ref:`initial data
<initial-data-via-fixtures>`.
:ref:`tests <topics-testing-fixtures>`:
.. code-block:: python
class MyTestCase(TestCase):
fixtures = ["fixture-label"]
or to provide some :ref:`initial data <initial-data-via-fixtures>` using the
:djadmin:`loaddata` command:
.. code-block:: shell
django-admin loaddata <fixture label>
Where Django looks for fixtures?
================================
Django will search in three locations for fixtures:
Django will search in these locations for fixtures:
1. In the ``fixtures`` directory of every installed application
2. In any directory named in the :setting:`FIXTURE_DIRS` setting
2. In any directory listed in the :setting:`FIXTURE_DIRS` setting
3. In the literal path named by the fixture
Django will load any and all fixtures it finds in these locations that match
the provided fixture names.
If the named fixture has a file extension, only fixtures of that type
will be loaded. For example:
the provided fixture names. If the named fixture has a file extension, only
fixtures of that type will be loaded. For example:
.. code-block:: shell
django-admin loaddata mydata.json
would only load JSON fixtures called ``mydata``. The fixture extension
must correspond to the registered name of a
would only load JSON fixtures called ``mydata``. The fixture extension must
correspond to the registered name of a
:ref:`serializer <serialization-formats>` (e.g., ``json`` or ``xml``).
If you omit the extensions, Django will search all available fixture types
for a matching fixture. For example:
If you omit the extensions, Django will search all available fixture types for
a matching fixture. For example:
.. code-block:: shell
django-admin loaddata mydata
would look for any fixture of any fixture type called ``mydata``. If a fixture
directory contained ``mydata.json``, that fixture would be loaded
as a JSON fixture.
directory contained ``mydata.json``, that fixture would be loaded as a JSON
fixture.
The fixtures that are named can include directory components. These
directories will be included in the search path. For example:
The fixtures that are named can include directory components. These directories
will be included in the search path. For example:
.. code-block:: shell
django-admin loaddata foo/bar/mydata.json
would search ``<app_label>/fixtures/foo/bar/mydata.json`` for each installed
application, ``<dirname>/foo/bar/mydata.json`` for each directory in
application, ``<dirname>/foo/bar/mydata.json`` for each directory in
:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
Fixtures loading order
----------------------
Multiple fixtures can be specified in the same invocation. For example:
.. code-block:: shell
manage.py loaddata mammals birds insects
or in a test case class:
.. code-block:: python
class AnimalTestCase(TestCase):
fixtures = ["mammals", "birds", "insects"]
The order in which fixtures are loaded follows the order in which they are
listed, whether it's when using the management command or when listing them in
the test case class as shown above.
In these examples, all the fixtures named ``mammals`` from all applications (in
the order in which applications are defined in :setting:`INSTALLED_APPS`) will
be loaded first. Subsequently, all the ``birds`` fixtures will be loaded,
followed by all the ``insects`` fixtures.
Be aware that if the database backend supports row-level constraints, these
constraints will be checked at the end of the transaction. Any relationships
across fixtures may result in a load error if the database configuration does
not support deferred constraint checking (refer to the `MySQL`_ docs for an
example).
.. _MySQL: https://dev.mysql.com/doc/refman/en/constraint-foreign-key.html
How fixtures are saved to the database?
=======================================
@ -124,13 +166,7 @@ You could also write a decorator to encapsulate this logic::
...
Just be aware that this logic will disable the signals whenever fixtures are
deserialized, not just during ``loaddata``.
Note that the order in which fixture files are processed is undefined. However,
all fixture data is installed as a single transaction, so data in
one fixture can reference data in another fixture. If the database backend
supports row-level constraints, these constraints will be checked at the
end of the transaction.
deserialized, not just during :djadmin:`loaddata`.
Compressed fixtures
===================
@ -146,11 +182,10 @@ would look for any of ``mydata.json``, ``mydata.json.zip``, ``mydata.json.gz``,
``mydata.json.bz2``, ``mydata.json.lzma``, or ``mydata.json.xz``. The first
file contained within a compressed archive is used.
Note that if two fixtures with the same name but different
fixture type are discovered (for example, if ``mydata.json`` and
``mydata.xml.gz`` were found in the same fixture directory), fixture
installation will be aborted, and any data installed in the call to
``loaddata`` will be removed from the database.
Note that if two fixtures with the same name but different fixture type are
discovered (for example, if ``mydata.json`` and ``mydata.xml.gz`` were found in
the same fixture directory), fixture installation will be aborted, and any data
installed in the call to :djadmin:`loaddata` will be removed from the database.
.. admonition:: MySQL with MyISAM and fixtures