Dynaconf Configuration Pattern Enforcer

When adding new configuration to settings.toml, always follow the dynaconf pattern.

✅ Correct Pattern

# settings.toml

[default]
# Base configuration with type casting
api_base_url = "@env API_BASE_URL|http://localhost:8080"
api_timeout = "@int 30"
feature_enabled = "@bool true"
max_retries = "@int 3"

# API endpoints (no @ prefix for strings)
api_endpoint = "/api/v1/endpoint"

[dev_local]
# Override for local development
api_base_url = "@env API_BASE_URL|http://localhost:8080"

[dev_remote]
# Override for remote development
api_base_url = "@env API_BASE_URL|http://gateway-service"

[production]
# Production overrides
api_base_url = "@env API_BASE_URL|https://api.production.com"
api_timeout = "@int 60"

Type Casting Directives

Use appropriate prefixes:

• @env VAR|default - Environment variable with fallback
• @int 123 - Cast to integer
• @bool true - Cast to boolean
• @float 1.5 - Cast to float
• @path ./dir - Convert to Path object
• No prefix - String value

Environment Variable Override

Pattern: APPNAME_SETTING_NAME

Example:

# In settings.toml
api_timeout = "@int 30"

# Override via environment
export APP_API_TIMEOUT=60

Configuration Access

from dynaconf import Dynaconf

settings = Dynaconf(
    settings_files=['settings.toml', '.secrets.toml'],
    environments=True,
    load_dotenv=True,
)

timeout = settings.api_timeout  # Returns int 30
url = settings.api_base_url     # Returns string

Common Patterns

API Configuration:

service_api_base_url = "@env SERVICE_API_URL|http://localhost:8080"
service_endpoint = "/api/v1/endpoint/{param}"
service_timeout = "@int 30"

Feature Flags:

feature_enabled = "@bool true"
feature_beta_mode = "@bool false"

Database Paths:

db_path = "@path data/database.db"

Secrets Management:

# settings.toml (checked into git)
api_key = "@env API_KEY"

# .secrets.toml (gitignored)
api_key = "actual-secret-key"

❌ Anti-Patterns

# ❌ Don't hardcode secrets
api_key = "sk-1234567890"

# ❌ Don't forget type casting for numbers
timeout = "30"  # Will be string, not int

# ❌ Don't mix environments in same section
[default]
api_url = "https://production.com"  # Should be in [production]

Best Practices Checklist

• ✅ Add to [default] section first
• ✅ Use appropriate @ type casting
• ✅ Add environment variable overrides with @env
• ✅ Add to environment-specific sections as needed
• ✅ Document in comments what the setting does
• ✅ Keep secrets in .secrets.toml (gitignored)
• ✅ Use consistent naming conventions (snake_case)
• ✅ Provide sensible defaults

Auto-Apply

When adding configuration:

1. Add to [default] section first
2. Use appropriate @ type casting
3. Add environment variable overrides
4. Add to environment-specific sections as needed
5. Document in comments what the setting does

Related Skills

• structured-errors - For validation errors
• pydantic-models - For settings validation with Pydantic