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:
- Add to
[default] section first
- Use appropriate
@ type casting
- Add environment variable overrides
- Add to environment-specific sections as needed
- Document in comments what the setting does
Related Skills
- structured-errors - For validation errors
- pydantic-models - For settings validation with Pydantic