Durango is a lightweight configuration management toolkit that layers strongly typed settings, configuration files, environment variables, and programmatic overrides using Pydantic Settings. It is designed for CLI tools and services that need predictable precedence, multi-format config files, and clear error reporting.
- Config precedence: defaults → config file → environment variables → user overrides.
- Format flexibility: parse YAML, JSON, or TOML files by default with optional extras.
- Typed settings: describe your configuration with Pydantic models and receive fully validated objects.
- Reload aware: refresh configuration at runtime and hook into lifecycle callbacks.
- Extensible: adapt environment prefixes, merge behaviour, and file lookup strategies to fit your application.
Durango is published on PyPI as durango. Install it with your preferred tool:
# Using uv (recommended)
uv add durango
# Using pip
pip install durangoDurango supports Python 3.9 through 3.12.
from durango import ConfigManager, DurangoSettings
class AppSettings(DurangoSettings):
debug: bool = False
api_url: str
manager = ConfigManager(
settings_type=AppSettings,
identifier="MYAPP",
default_file="~/.config/myapp/settings.yaml",
)
settings = manager.load()
print(settings.api_url)If ~/.config/myapp/settings.yaml does not exist, Durango will create it and populate it with the model defaults before layering environment variables and runtime overrides.
Environment variables take the form MYAPP__API_URL=true. To override a nested section named database, use MYAPP__DATABASE__URL.
- Docs site (WIP): see
docs/ - Architecture notes:
ARCH.md - Working session notes:
notes/STATUS.md
See docs/contributing.md for full setup, workflow, and review guidelines. Highlights:
- Install dependencies with
uv sync --all-extras --dev. - Run
uv run invoke cibefore opening a pull request. - Publishing and release automation are covered in docs/publishing.md.
Durango is available under the MIT License. See LICENSE for details.