django-management-commands

Django Management Commands

Command Structure

Core structure

We put handle() as the first method. We keep logic inline within handle() by default, splitting into helper functions only if they're reusable. Helper methods go below handle(), never above. We include clear docstrings and help text for non-obvious arguments.

Example Structure

from django.core.management.base import BaseCommand

class Command(BaseCommand):
    """Process pending orders and update inventory.

    Analyzes order queue and updates stock levels accordingly.
    """
    help = "Process pending orders"

    def add_arguments(self, parser):
        parser.add_argument(
            '--dry-run',
            action='store_true',
            help='Show what would be done without making changes',
        )

    def handle(self, *args, **options):
        """Execute the command."""
        dry_run = options['dry_run']

        self.stdout.write(self.style.SUCCESS('Starting order processing...'))

        # Command logic here...
        processed_count = self.process_orders(dry_run)

        self.stdout.write(
            self.style.SUCCESS(f'Successfully processed {processed_count} orders')
        )

    def process_orders(self, dry_run):
        """Helper methods below handle()."""
        # Helper logic here
        pass

Handle Method Guidelines

Stats Dictionary Pattern

stats = {
    "total": 0,
    "processed": 0,
    "skipped": {
        "reason_1": 0,
        "reason_2": 0,
    },
    "errors": [],
}

Return stats at the end for logging and monitoring.

Testing

Test Structure

We test with call_command, mock external services, and verify stats dictionary structure.

from django.core.management import call_command
from io import StringIO

def test_command():
    out = StringIO()
    call_command('your_command', stdout=out)
    assert 'Success' in out.getvalue()