django-nested-seed 0.1.2

Django package for seeding data with nested relationships via YAML

Django Nested Seed

A Django package for loading seed data from YAML files with support for nested relationships.

Installation

pip install django-nested-seed

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    'django_nested_seed',
]

Quick Start

Create data.yaml:

testapp:
  Author:
    - $ref: alice
      user:
        username: "alice"
        email: "[e-mail]"
      pen_name: "Alice Smith"
      bio: "Software engineer"

  Book:
    - title: "Python Patterns"
      author: "$alice"
      publisher:
        name: "Tech Books Inc"
        country: "UK"
      status: "PUBLISHED"

Load it:

python manage.py nested_seed data.yaml --verbose

More Examples

See the examples/ directory for complete examples of each feature:

• Basic models - Simple objects with primitive fields
• ForeignKey (Nested) - Create related objects inline
• ForeignKey (Referenced) - Reference objects using $ref_key
• ForeignKey (Mixed) - Combine nested and referenced approaches
• Reverse ForeignKey - Nest child collections under parent
• OneToOne relationships - Nested one-to-one fields
• ManyToMany - M2M with references
• ManyToMany (Through) - M2M with custom through models
• Mixed ManyToMany - M2M with both references and inline objects
• Complex Multi-Level - Comprehensive example combining all features
• Database Lookups - Reference existing database records using @lookup
• Mixed References and Lookups - Combine $ref and @lookup

YAML Structure

# All models use list format with Django app_label and ModelName
app_label:
  ModelName:
    # Basic object without reference
    - field_name: value
      other_field: value

    # Object with explicit reference key (for later use)
    - $ref: my_key      # Reference key for this object
      field_name: value

    # Auto-generated key (modelname_0, modelname_1, etc.)
    - field_name: value

    # ForeignKey - inline nested object
    - field_name: value
      related_field:
        nested_field: value

    # ForeignKey - reference to existing object (defined in YAML)
    - field_name: value
      related_field: "$my_key"    # Reference using $ref_key

    # ForeignKey - reference to existing database record
    - field_name: value
      related_field: "@pk:123"    # Lookup by primary key
    - field_name: value
      related_field: "@username:alice"    # Lookup by field
    - field_name: value
      related_field: "@{name:John,email:[e-mail]}"    # Lookup by multiple fields

    # OneToOne - nested directly under parent
    - field_name: value
      one_to_one_field:
        nested_field: value

    # Reverse ForeignKey - nested collection
    - field_name: value
      reverse_relation_set:       # Django reverse accessor
        - child_field: value
        - child_field: value

    # ManyToMany - list of references
    - field_name: value
      many_to_many_field:
        - "$ref_key_1"            # Reference YAML object
        - "$ref_key_2"

    # ManyToMany - with database lookups
    - field_name: value
      many_to_many_field:
        - "@slug:python"          # Reference existing database record
        - "@pk:42"

    # ManyToMany - mixed references, lookups, and inline objects
    - field_name: value
      many_to_many_field:
        - "$ref_key"              # Reference YAML object
        - "@slug:existing"        # Reference database record
        - inline_field: value     # Create new object inline

    # ManyToMany with through model (extra fields)
    - field_name: value
      many_to_many_field:
        - related_object: "$ref_key"
          extra_field: value      # Through model field
          date_field: "2024-01-01"

# Reference keys must be unique across all models

Features

• Zero configuration
• Supports OneToOne, ForeignKey, and ManyToMany relationships
• ManyToMany with custom through models (extra fields on intermediate table)
• Mixed relation references and inline definitions
• Database lookups - Reference existing database records
• Transaction safety with automatic rollback on errors
• Multiple files can be loaded together
• Topological sorting handles dependencies automatically

Database Lookups

Reference existing database records using @lookup syntax instead of creating new ones:

Lookup by primary key:

author: "@pk:123"  # Lookup by primary key

Lookup by single field:

author: "@username:alice"  # Lookup by unique field
category: "@slug:python"   # Lookup by slug

Lookup by multiple fields:

publisher: "@{name:O'Reilly Media,country:USA}"  # Lookup by multiple fields

With Django's related field syntax:

author: "@user__username:alice"  # Lookup Author where user.username='alice'

In ManyToMany fields:

Book:
  - title: "Django Book"
    categories:
      - "$new_category"    # Reference YAML object
      - "@slug:existing"   # Reference database record

Features:

• Results are cached to avoid redundant queries
• Clear error messages if record not found
• Works with ForeignKey, OneToOne, and ManyToMany fields
• Can be mixed with $ref references in the same file

Configuration

Custom Reference Key

Change the reference key field name in settings.py:

NESTED_SEED_CONFIG = {
    'reference_key': 'rid',  # Use 'rid' instead of '$ref'
}

Then use it in your YAML:

app:
  Category:
    - rid: python  # Using custom reference key
      name: "Python"

Development

uv sync
uv run pytest

Requirements

• Python 3.10+
• Django 4.2+
• PyYAML 6.0+

License

MIT