Structum Dynaconf (structum-dynaconf)¶

# ❌ Hard-coded configuration
DB_HOST = "localhost"
DB_PORT = 5432

# ❌ No dev/prod separation
# ❌ Secrets in code
# ❌ Zero type validation

# ✅ Multi-layer configuration
# Layer 1: config/app/database.toml (defaults)
# Layer 2: .secrets.toml (passwords)
# Layer 3: STRUCTUM_DATABASE__HOST env var (infra)
# Layer 4: ~/.structum/database_saved.json (user prefs)

config = get_config()
db_host = config.get("database.host")  # Resolves layers by priority

config.get("database.host")      # "localhost"
config.get("database.port")      # 5432
config.get("database.pool_size") # 10

from structum_lab.config import set_config_provider, get_config
from structum_lab.plugins.dynaconf import DynaconfConfigProvider

def setup_config():
    """
    Initialize configuration system.
    Call BEFORE any other code.
    """
    provider = DynaconfConfigProvider(
        root_path=".",  # Project root (where config/ is located)
        env_prefix="STRUCTUM",  # Prefix for env vars
        environments=True,  # Supports [default], [production], etc.
        current_env="development"  # Or from ENV: os.getenv("APP_ENV", "development")
    )
    
    # 🔍 Auto-discover: scans config/app/*.toml
    provider.auto_discover()
    
    # Register as global provider
    set_config_provider(provider)

if __name__ == "__main__":
    setup_config()
    
    # Now you can use config anywhere
    config = get_config()
    db_host = config.get("database.host")
    db_port = config.get("database.port")
    
    print(f"Connecting to {db_host}:{db_port}")

provider = DynaconfConfigProvider(root_path=".")
provider.auto_discover()

# After this call:
# ✅ All files in config/app/*.toml are registered
# ✅ Models in config/models/*.py are linked automatically
# ✅ .secrets.toml (if exists) is merged into every namespace

from structum_lab.plugins.dynaconf import DynaconfConfigProvider
from structum_lab.plugins.dynaconf.exceptions import (
    ConfigDiscoveryError,
    ConfigValidationError
)

provider = DynaconfConfigProvider(root_path=".")

try:
    discovered = provider.auto_discover()
    print(f"✅ Discovered {len(discovered)} namespaces:")
    for ns in discovered:
        print(f"  - {ns}")
except ConfigDiscoveryError as e:
    print(f"❌ Discovery error: {e}")
    # config/ directory missing or permission denied
except ConfigValidationError as e:
    print(f"❌ Validation failed: {e}")
    # Malformed TOML file or Pydantic schema violation

provider = DynaconfConfigProvider(root_path=".")

# Load custom file
provider.load(
    namespace="legacy_system",
    config_file="external/old_config.toml"
)

# Now accessible as:
config = get_config()
value = config.get("legacy_system.some_key")

# ❌ Hidden runtime errors
pool_size = config.get("database.pool_size")  # What does it return? str? int? None?
connections = [None] * pool_size  # 💥 TypeError if pool_size is string

# ✅ Static guarantees
pool_size: int = config.get("database.pool_size")  # Type-safe
# If TOML contains pool_size = "invalid", fails immediately at init

from pydantic import BaseModel, Field, field_validator
from typing import Literal

class AuthConfig(BaseModel):
    """Database authentication."""
    user: str = Field(..., min_length=1, description="Username")
    password: str = Field(..., min_length=8, description="Password (from secrets)")

class DatabaseConfig(BaseModel):
    """Main database configuration."""
    
    host: str = Field(default="localhost", description="DB Hostname")
    port: int = Field(default=5432, ge=1, le=65535, description="DB Port")
    database: str = Field(..., min_length=1, description="Database Name")
    pool_size: int = Field(default=10, ge=1, le=1000, description="Connection Pool Size")
    
    auth: AuthConfig
    
    # Custom validators
    @field_validator('host')
    @classmethod
    def validate_production_host(cls, v, info):
        """In production, block localhost."""
        if info.context and info.context.get('env') == 'production':
            if v in ('localhost', '127.0.0.1'):
                raise ValueError("localhost not allowed in production")
        return v
    
    @field_validator('pool_size')
    @classmethod
    def validate_pool_size(cls, v, info):
        """Pool size must be proportional to environment."""
        env = info.context.get('env', 'development') if info.context else 'development'
        
        if env == 'production' and v < 20:
            raise ValueError(f"Pool size too low for production: {v} (min 20)")
        
        return v

provider = DynaconfConfigProvider(root_path=".")
provider.auto_discover()  # Finds database.toml and DatabaseConfig automatically

# Validation is now active
config = get_config()
port = config.get("database.port")  # Guaranteed to be int between 1-65535

from config.models.database import DatabaseConfig
from structum_lab.plugins.dynaconf import GenericConfigBuilder

builder = GenericConfigBuilder(
    name="database",
    files=["config/app/database.toml"],
    model=DatabaseConfig  # Explicit link
)

provider.register_builder("database", builder)

config = get_config()

# In-memory modification
config.set("database.host", "10.0.0.100")

# Save to disk (optional but recommended)
config.save()

# Created file: ~/.structum/database_saved.json
# {
#   "host": "10.0.0.100"
# }

provider = DynaconfConfigProvider(
    root_path=".",
    runtime_config_dir="/var/lib/myapp/config"
)

config.get("database.auth.password") # "secret123"

from structum_lab.config import on_config_change

@on_config_change("database")
def reload_db_connection(new_config):
    print("Database config changed! Reconnecting...")
    db.reconnect(new_config.database.url)

from structum_lab.plugins.dynaconf import GenericConfigBuilder

builder = GenericConfigBuilder(
    name="complex_system",
    files=[
        "config/base.toml",
        "config/features.toml",
        "/etc/myapp/site.toml"
    ],
    includes=["config/extra/*.toml"],
    model=MyComplexSchema
)

provider.register_builder("complex_system", builder)

class DynaconfConfigProvider:
    def __init__(
        self, 
        root_path: str, 
        env_prefix: str = "STRUCTUM",
        environments: bool = True,
        current_env: str = "development",
        runtime_config_dir: str = None
    ):
        ...

    def auto_discover(self) -> List[str]:
        """Scans for valid config files."""
        ...
        
    def load(self, namespace: str, config_file: str) -> None:
        """Load specific file."""
        ...