dd-config 0.1.0

Unified configuration management for the dd-* ecosystem

dd-config

Unified configuration management for the dd-* ecosystem — load, merge, validate and convert config files across multiple formats with a single clean API.

Install

pip install dd-config                    # JSON + INI + .env support (stdlib only)
pip install "dd-config[yaml]"            # + YAML support
pip install "dd-config[all]"             # all formats including TOML

Quick start

from dd_config import Config

# Load a YAML config
cfg = Config.load("splflow.yaml")

# Plain key access
adapter = cfg["llm_adapter"]            # "ollama"

# Dot-path access for nested keys
host = cfg["database.host"]

# Safe get with default
port = cfg.get("database.port", 5432)

# Layer overrides on top (later files win)
cfg = Config.load("base.yaml", overrides=["local.yaml", ".env"])

Supported formats

Format	Extension	Extra required
JSON	.json	none (stdlib)
YAML	.yaml, .yml	pip install "dd-config[yaml]"
TOML	.toml	pip install "dd-config[all]"
INI	.ini, .cfg	none (stdlib)
Env	.env	none (stdlib)

Features

• Multi-format — one API for JSON, YAML, TOML, INI, .env
• Auto-detection — format inferred from file extension
• Layered loading — base config + multiple override files; last writer wins
• Dot-path access — cfg["server.port"] instead of cfg["server"]["port"]
• Env interpolation — ${VAR:-default} tokens expanded on load
• Format conversion — Config.convert("app.yaml", "app.json")
• Validation — required-key and type checks raise ValidationError
• Plain dict — cfg.to_dict() returns a plain Python dict; no magic objects
• Lazy deps — YAML/TOML libraries only imported when actually used

Validation

cfg.validate(required=["llm_adapter", "database.host"])
cfg.validate(schema={"database.port": int, "debug": bool})

Saving & converting

cfg["llm_adapter"] = "openrouter"
cfg.save("splflow.yaml")               # write back to YAML
Config.convert("splflow.yaml", "splflow.json")   # one-liner format conversion

Environment variable interpolation

Values like ${OPENROUTER_API_KEY:-} in config files are expanded from the environment at load time. Useful for secrets that must not be committed to VCS:

openrouter:
  api_key: ${OPENROUTER_API_KEY}
  base_url: https://openrouter.ai/api/v1

Merge

base = Config.load("base.yaml")
local = Config.load("local.yaml")
merged = base.merge(local)             # local wins on conflict; non-destructive

License

MIT © 2026 digital-duck