Файлы-образцы

Что такое файл-образец?

Файл-образец — это набор файлов, содержащих сериализованное содержимое базы данных. Каждый файл-образец имеет уникальное имя, а файлы, составляющие файл-образец, могут быть распределены по нескольким каталогам и приложениям.

Как создать файл-образец?

Файлы-образцы могут быть сгенерированы с помощью manage.py dumpdata. Также возможно создание пользовательских файлов-образцов, используя инструменты сериализации документации по сериализации или даже вручную.

Для чего использовать файлы-образцы?

Файлы-образцы могут использоваться для предварительной загрузки базы данных данными для тестов или для предоставления некоторых начальных данных.

Где Django ищет файлы-образцы?

Django будет искать файлы-образцы в трёх местах:

1. В каталоге fixtures каждого установленного приложения
2. В любом каталоге, указанном в настройке FIXTURE_DIRS
3. В указанном пути к файлу-образцу

Django загрузит все найденные в этих местах файлы-образцы, соответствующие указанным именам.

Если у имени файла-образца есть расширение, будут загружены только файлы-образцы с таким типом. Например:

django-admin loaddata mydata.json

будет загружать только файлы-образцы JSON, называемые mydata. Расширение файла-образца должно соответствовать зарегистрированному имени сериализатора (например, json или xml).

Если вы опустите расширение, Django будет искать все доступные типы файлов-образцов для совпадения по имени. Например:

django-admin loaddata mydata

будет искать любой файл-образец любого типа, называемый mydata. Если в каталоге с файлами-образцами содержался mydata.json, этот файл-образец будет загружен как файл-образец JSON.

Имена файлов-образцов могут включать компоненты каталога. Эти каталоги будут включены в путь поиска. Например:

django-admin loaddata foo/bar/mydata.json

будет искать <app_label>/fixtures/foo/bar/mydata.json для каждого установленного приложения, <dirname>/foo/bar/mydata.json для каждого каталога в FIXTURE_DIRS, и прямой путь foo/bar/mydata.json.

Как файлы-образцы сохраняются в базе данных?

При обработке файлов-образцов данные сохраняются в базе данных как есть. Определяемые моделью методы save() не вызываются, и любые сигналы pre_save или post_save будут вызваны со значениями raw=True, так как экземпляр содержит только атрибуты, локальные для модели. Например, вы можете отключить обработчики, которые обращаются к связанным полям, отсутствующим во время загрузки файла-образца и в противном случае вызывающим исключение:

from django.db.models.signals import post_save
from .models import MyModel


def my_handler(**kwargs):
    # disable the handler during fixture loading
    if kwargs["raw"]:
        return
    ...


post_save.connect(my_handler, sender=MyModel)

Вы также можете написать декоратор для инкапсуляции этой логики:

from functools import wraps


def disable_for_loaddata(signal_handler):
    """
    Decorator that turns off signal handlers when loading fixture data.
    """

    @wraps(signal_handler)
    def wrapper(*args, **kwargs):
        if kwargs["raw"]:
            return
        signal_handler(*args, **kwargs)

    return wrapper


@disable_for_loaddata
def my_handler(**kwargs):
    ...

Просто имейте в виду, что эта логика будет отключать сигналы всякий раз, когда файлы-образцы десериализуются, а не только во время loaddata.

Обратите внимание, что порядок обработки файлов-образцов не определён. Однако все данные файла-образца устанавливаются как единая транзакция, поэтому данные одного файла-образца могут ссылаться на данные другого файла-образца. Если движок базы данных поддерживает ограничения уровня строки, эти ограничения будут проверены в конце транзакции.

Сжатые файлы-образцы

Файлы-образцы могут быть сжаты в формате zip, gz, bz2, lzma, или xz. Например:

django-admin loaddata mydata.json

будет искать любой из mydata.json, mydata.json.zip, mydata.json.gz, mydata.json.bz2, mydata.json.lzma, или mydata.json.xz. Используется первый файл внутри сжатого архива.

Обратите внимание, что если обнаружатся два файла-образца с одинаковым именем, но разными типами (например, если mydata.json и mydata.xml.gz были найдены в одном каталоге файлов-образцов), установка файла-образца будет прервана, и все данные, установленные в вызове loaddata, будут удалены из базы данных.

Файлы-образцы для конкретной базы данных

Если вы работаете с многобазовой настройкой, у вас могут быть данные файла-образца, которые вы хотите загрузить только в одну базу данных, а не в другую. В этом случае вы можете добавить идентификатор базы данных в имена ваших файлов-образцов.

Например, если в настройке DATABASES определена база данных users, назовите файл-образец mydata.users.json или mydata.users.json.gz, и файл-образец будет загружен только тогда, когда вы укажете, что хотите загрузить данные в базу данных users.