3.3 KiB
3.3 KiB
name, description
| name | description |
|---|---|
| dynaconf-config | Automatically applies when adding configuration settings. Ensures proper dynaconf pattern with @env, @int, @bool type casting in settings.toml and environment-specific overrides. |
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