API Reference

This page documents the internal API of django-nested-seed. Most users won’t need to interact with these classes directly, as the management command provides the primary interface.

Management Command

from django.core.management import call_command

# Programmatically load seed data
call_command('nested_seed', 'data.yaml')
call_command('nested_seed', 'file1.yaml', 'file2.yaml')

Core Classes

The package is organized into several key modules:

Parser Module

Located in django_nested_seed.parser, this module handles YAML parsing and reference resolution.

Loader Module

Located in django_nested_seed.loader, this module handles database operations and object creation.

Graph Module

Located in django_nested_seed.graph, this module handles topological sorting of dependencies.

Internal API

Note

The internal API is subject to change. For stable usage, use the management command interface.

Example Programmatic Usage

If you need to load seed data programmatically in your code:

from django.core.management import call_command

def load_test_data():
    """Load test data for development environment."""
    call_command('nested_seed', 'fixtures/base.yaml')
    call_command('nested_seed', 'fixtures/test_users.yaml')

Django Integration

The package integrates with Django through:

  1. Management Command: nested_seed

  2. App Config: django_nested_seed.apps.DjangoNestedSeedConfig

Installation in Django

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'django_nested_seed',
]

Settings

Optional configuration:

NESTED_SEED_CONFIG = {
    'reference_key': '$ref',  # Default
}

See Configuration for more details.

Error Handling

The package raises standard Django and Python exceptions:

  • ValueError - Invalid YAML structure or references

  • ObjectDoesNotExist - Database lookup failed

  • MultipleObjectsReturned - Ambiguous database lookup

  • ValidationError - Django model validation failed

  • IntegrityError - Database constraint violation

All operations are wrapped in a database transaction, so any error will rollback all changes.

Testing with Seed Data

Use seed data in your tests:

from django.test import TransactionTestCase
from django.core.management import call_command

class MyTestCase(TransactionTestCase):
    def setUp(self):
        # Load seed data before each test
        call_command('nested_seed', 'fixtures/test_data.yaml')

    def test_something(self):
        # Your test code here
        pass

Note

Use TransactionTestCase instead of TestCase when loading seed data in tests, as the seed loader uses database transactions.

Logging

The package uses Python’s standard logging module. To see debug output:

LOGGING = {
    'version': 1,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'django_nested_seed': {
            'handlers': ['console'],
            'level': 'DEBUG',
        },
    },
}

Contributing

The project is open source and hosted on GitHub:

See Also