144 lines
3.3 KiB
Markdown
144 lines
3.3 KiB
Markdown
---
|
|
name: dynaconf-config
|
|
description: 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
|
|
|
|
```toml
|
|
# 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:
|
|
```toml
|
|
# In settings.toml
|
|
api_timeout = "@int 30"
|
|
|
|
# Override via environment
|
|
export APP_API_TIMEOUT=60
|
|
```
|
|
|
|
## Configuration Access
|
|
|
|
```python
|
|
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:**
|
|
```toml
|
|
service_api_base_url = "@env SERVICE_API_URL|http://localhost:8080"
|
|
service_endpoint = "/api/v1/endpoint/{param}"
|
|
service_timeout = "@int 30"
|
|
```
|
|
|
|
**Feature Flags:**
|
|
```toml
|
|
feature_enabled = "@bool true"
|
|
feature_beta_mode = "@bool false"
|
|
```
|
|
|
|
**Database Paths:**
|
|
```toml
|
|
db_path = "@path data/database.db"
|
|
```
|
|
|
|
**Secrets Management:**
|
|
```toml
|
|
# settings.toml (checked into git)
|
|
api_key = "@env API_KEY"
|
|
|
|
# .secrets.toml (gitignored)
|
|
api_key = "actual-secret-key"
|
|
```
|
|
|
|
## ❌ Anti-Patterns
|
|
|
|
```toml
|
|
# ❌ 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
|