Django-CFG vs Alternatives: Complete Comparison Guide

# settings.py
import environ
 
env = environ.Env(
    DEBUG=(bool, False),
    DATABASE_URL=(str, 'sqlite:///db.sqlite3')
)
 
# Read .env file
environ.Env.read_env()
 
# Configure database
DEBUG = env('DEBUG')  # Runtime casting to bool
DATABASES = {
    'default': env.db('DATABASE_URL')  # Parses DATABASE_URL string
}
 
# Issues:
# - No startup validation (wrong URL format fails at connection time)
# - No IDE autocomplete for env('DEBUG')
# - Type casting errors silent until runtime
# - Can't tell what config is required vs optional

# config.py
from django_cfg import DjangoConfig, DatabaseConfig
from typing import Dict
from .environment import env
 
class MyConfig(DjangoConfig):
    """Type-safe configuration with validation"""
 
    debug: bool = False  # Pydantic validates boolean
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,      # Already validated from YAML
            host=env.database.host,      # Type-safe: str
            port=env.database.port,      # Type-safe: int
        )
    }
 
# Benefits:
# ✅ Startup validation (fails before Django loads if invalid)
# ✅ Full IDE autocomplete (env.database.<TAB> shows fields)
# ✅ Type safety (port is int, not string)
# ✅ Self-documenting (field descriptions as hints)

# settings.py - Manual CORS setup
ALLOWED_HOSTS = env.list('ALLOWED_HOSTS', default=['localhost'])
 
CORS_ALLOWED_ORIGINS = [
    f"https://{host}" for host in ALLOWED_HOSTS
    if host not in ['localhost', '127.0.0.1']
]
CORS_ALLOW_CREDENTIALS = True
CSRF_TRUSTED_ORIGINS = CORS_ALLOWED_ORIGINS
SECURE_CROSS_ORIGIN_OPENER_POLICY = "same-origin-allow-popups"
 
# Issues:
# - 5+ separate settings to manage
# - Easy to forget one setting
# - No validation of host format
# - Requires django-cors-headers package

# config.py - Single field auto-generates all CORS settings
class MyConfig(DjangoConfig):
    security_domains: list[str] = ["myapp.com", "www.myapp.com"]
 
    # Auto-generates:
    # - ALLOWED_HOSTS
    # - CORS_ALLOWED_ORIGINS (with https://)
    # - CORS_ALLOW_CREDENTIALS
    # - CSRF_TRUSTED_ORIGINS
    # - SECURE_CROSS_ORIGIN_OPENER_POLICY
    # - SECURE_SSL_REDIRECT (in production)
    # - SECURE_HSTS_SECONDS
    # All validated and consistent
 
# Benefits:
# ✅ 1 field → 7+ Django settings
# ✅ No manual CORS package configuration
# ✅ Impossible to have inconsistent CORS/CSRF settings

# BEFORE: django-environ
import environ
env = environ.Env()
DEBUG = env.bool('DEBUG', default=False)
DATABASES = {'default': env.db('DATABASE_URL')}
 
# AFTER: Django-CFG
from django_cfg import DjangoConfig, DatabaseConfig
from .environment import env  # Pydantic YAML loader
 
class MyConfig(DjangoConfig):
    debug: bool = env.debug  # Type-safe from YAML
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            name=env.database.name,
            # ... other fields
        )
    }

# settings.py - Traditional approach
INSTALLED_APPS = [
    'django.contrib.admin',
    'rest_framework',  # Need to install
    'rest_framework_simplejwt',  # Need to install
    # ... manual configuration
]
 
# Manual JWT setup
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
}
 
# Then manually:
# 1. Set up Streamlit project structure
# 2. Configure subprocess management
# 3. Handle process lifecycle
# 4. Set up authentication flow
# 5. Configure port discovery
# 6. Handle hot reload
 
# Total: Complex subprocess management

# config.py
from django_cfg import DjangoConfig, StreamlitAdminConfig
 
config = DjangoConfig(
    project_name="My Project",
 
    # That's it! Streamlit auto-starts with Django:
    streamlit_admin=StreamlitAdminConfig(
        app_path="streamlit",
        port=8501,
        auto_start=True,
    ),
)
 
# Everything else is automatic:
# ✅ Starts as Django child process
# ✅ Auto-finds free port if busy
# ✅ JWT authentication configured
# ✅ Dies when Django dies
# ✅ Works in single Docker container
 
# Total: 1 config block + zero manual setup

┌─────────────────────────────────────────────────────────────┐
│                    Django Process                            │
│                                                               │
│  python manage.py runserver                                  │
│       │                                                       │
│       └──► Spawns Streamlit as child process                │
│            │                                                  │
│            ├── Port 8501 (or next free)                      │
│            ├── Inherits Django settings                      │
│            └── Auto-dies when Django stops                   │
│                                                               │
│  Console output:                                             │
│  Streamlit started on port 8501 (PID: 12345)                │
│  Streamlit admin available at: http://localhost:8501        │
└─────────────────────────────────────────────────────────────┘

# streamlit/extensions.py
from core.registry import page_registry
import streamlit as st
 
# Register custom group
page_registry.register_group("Project", icon="briefcase", order=50)
 
# Register custom page
@page_registry.register("Analytics", icon="bar-chart-line", group="Project")
def render_analytics_page():
    st.title("Analytics")
 
    col1, col2, col3 = st.columns(3)
    with col1:
        st.metric("Total Users", "1,234", "+12%")
    with col2:
        st.metric("Active Today", "567", "+5%")
    with col3:
        st.metric("Revenue", "$12,345", "+8%")

# settings.py
from decouple import config, Csv
 
DEBUG = config('DEBUG', default=False, cast=bool)
SECRET_KEY = config('SECRET_KEY')
ALLOWED_HOSTS = config('ALLOWED_HOSTS', default='localhost', cast=Csv())
 
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': config('DB_NAME'),
        'USER': config('DB_USER'),
        'PASSWORD': config('DB_PASSWORD'),
        'HOST': config('DB_HOST', default='localhost'),
        'PORT': config('DB_PORT', default=5432, cast=int),
    }
}
 
# Issues:
# - Still verbose (manual dict construction)
# - No startup validation
# - Type casting per-variable
# - No IDE hints

# config.py
from django_cfg import DjangoConfig, DatabaseConfig
from .environment import env
 
class MyConfig(DjangoConfig):
    secret_key: str = env.secret_key
    debug: bool = False
    security_domains: list[str] = ["localhost"]
 
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,
            user=env.database.user,
            password=env.database.password,
            host=env.database.host,
            port=env.database.port,
        )
    }
 
# Benefits:
# ✅ More concise (no manual dict construction)
# ✅ Type-safe (Pydantic validates all fields)
# ✅ IDE autocomplete works

# config.py
from pydantic_settings import BaseSettings
from pydantic import Field
 
class Settings(BaseSettings):
    """Generic settings (not Django-aware)"""
 
    debug: bool = False
    secret_key: str = Field(..., min_length=50)
 
    db_name: str
    db_user: str
    db_password: str
    db_host: str = "localhost"
    db_port: int = 5432
 
    class Config:
        env_file = ".env"
 
settings = Settings()
 
# Now manually convert to Django settings.py
DEBUG = settings.debug
SECRET_KEY = settings.secret_key
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',  # Manual
        'NAME': settings.db_name,
        'USER': settings.db_user,
        'PASSWORD': settings.db_password,
        'HOST': settings.db_host,
        'PORT': settings.db_port,
    }
}
# Still need to manually configure ALLOWED_HOSTS, CORS, etc.
 
# Issues:
# - No Django settings generation (manual conversion)
# - No smart defaults (have to specify everything)
# - No built-in Django features
# - 100-150 lines for full configuration

# config.py
from django_cfg import DjangoConfig, DatabaseConfig
from typing import Dict
from .environment import env
 
class MyConfig(DjangoConfig):
    """Django-aware settings with smart defaults"""
 
    secret_key: str = env.secret_key
    debug: bool = False
    security_domains: list[str] = ["localhost"]
 
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,
            user=env.database.user,
            password=env.database.password,
            host=env.database.host,
            port=env.database.port,
        )
    }
 
# In settings.py - auto-generates all Django settings
config = MyConfig()
globals().update(config.get_all_settings())
# Generates: DATABASES, ALLOWED_HOSTS, CORS_*, INSTALLED_APPS, MIDDLEWARE, etc.
 
# Benefits:
# ✅ Automatic Django settings generation
# ✅ Smart defaults (MIDDLEWARE, INSTALLED_APPS pre-configured)
# ✅ Django-specific models (DatabaseConfig, CacheConfig, etc.)
# ✅ 30-50 lines for full configuration

# BEFORE: pydantic-settings
from pydantic_settings import BaseSettings
 
class Settings(BaseSettings):
    db_name: str
    db_user: str
    # ... 20+ fields
 
settings = Settings()
 
# Manual Django conversion
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': settings.db_name,
        # ... manual mapping
    }
}
 
# AFTER: Django-CFG
from django_cfg import DjangoConfig, DatabaseConfig
 
class MyConfig(DjangoConfig):
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,
            # DatabaseConfig handles the rest
        )
    }
 
config = MyConfig()
globals().update(config.get_all_settings())  # Auto-generates DATABASES

# settings.py - 200+ lines
import os
from pathlib import Path
 
BASE_DIR = Path(__file__).resolve().parent.parent
 
# ❌ String parsing everywhere
SECRET_KEY = os.environ.get('SECRET_KEY', 'insecure-default')
DEBUG = os.environ.get('DEBUG', 'False').lower() in ('true', '1', 'yes')
 
# ❌ Manual list parsing
ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', 'localhost').split(',')
 
# ❌ Manual CORS configuration (multiple settings)
CORS_ALLOWED_ORIGINS = [
    f"https://{host}" for host in ALLOWED_HOSTS
    if host not in ['localhost', '127.0.0.1']
]
CORS_ALLOW_CREDENTIALS = True
CSRF_TRUSTED_ORIGINS = CORS_ALLOWED_ORIGINS
 
# ❌ Manual database configuration
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME', 'mydb'),
        'USER': os.environ.get('DB_USER', 'postgres'),
        'PASSWORD': os.environ.get('DB_PASSWORD', ''),
        'HOST': os.environ.get('DB_HOST', 'localhost'),
        'PORT': int(os.environ.get('DB_PORT', '5432')),  # Manual int()
    }
}
 
# ... 100+ more lines for cache, email, static, templates, etc.
 
# Issues:
# - No type validation
# - No IDE autocomplete
# - Manual type conversion (can fail silently)
# - Hard to test (global variables)
# - Configuration errors only caught at runtime

# config.py - 30-50 lines
from django_cfg import DjangoConfig, DatabaseConfig
from typing import Dict
from .environment import env
 
class MyConfig(DjangoConfig):
    """Type-safe, validated configuration"""
 
    secret_key: str = env.secret_key
    debug: bool = False
    security_domains: list[str] = ["myapp.com"]
 
    databases: Dict[str, DatabaseConfig] = {
        "default": DatabaseConfig(
            engine="django.db.backends.postgresql",
            name=env.database.name,
            user=env.database.user,
            password=env.database.password,
            host=env.database.host,
            port=env.database.port,
        )
    }
 
# settings.py - 2 lines
config = MyConfig()
globals().update(config.get_all_settings())
 
# Benefits:
# ✅ 85% less code
# ✅ Type-safe (Pydantic)
# ✅ IDE autocomplete
# ✅ Validation at startup
# ✅ Easy to test (just instantiate class)

START: Evaluate your project needs

Q1: Is this a production Django application?
├─ NO → Use django-environ or settings.py
└─ YES → Continue to Q2

Q2: Do you need type safety and validation?
├─ NO → Use django-environ
└─ YES → Continue to Q3

Q3: Is this Django-only or multi-framework?
├─ Multi-framework → Use pydantic-settings
└─ Django-only → Continue to Q4

Q4: Do you need modern admin interfaces (React/Next.js)?
├─ YES → Use Django-CFG ✅ (only option with built-in Next.js)
└─ NO → Continue to Q5

Q5: Do you want built-in apps or AI features?
├─ NO → Use pydantic-settings
└─ YES → Use Django-CFG ✅

Q6: Is your team comfortable with Pydantic?
├─ NO → Use django-environ (simpler)
└─ YES → Use Django-CFG ✅

# Use django-environ for gradual migration
import environ
env_compat = environ.Env()
 
# Use Django-CFG for new configuration
from django_cfg import DjangoConfig
 
class MyConfig(DjangoConfig):
    # New config in Django-CFG
    security_domains: list[str] = ["myapp.com"]
 
config = MyConfig()
settings = config.get_all_settings()
 
# Keep legacy django-environ settings
settings['LEGACY_SETTING'] = env_compat('LEGACY_SETTING')
 
globals().update(settings)

# Export current config to settings.py
config = MyConfig()
settings_dict = config.get_all_settings()
 
# Print as Python code
for key, value in settings_dict.items():
    print(f"{key} = {repr(value)}")
 
# Copy output to new settings.py