CfgForge

Multi-source configuration loader and merger for Python. Supports env, json, yaml, and toml — with priority-based merging, dot-path access, and type checking.

Features

• Load multiple config sources in order; later ones override earlier ones
• Dot-path access: config.get("db.host")
• Type validation: config.expect("db.port", int)
• Required keys: config.get("api.key", required=True)
• Optional dependencies: install only what you need
• Clear error messages for missing keys, wrong types, and parse failures

Installation

pip install CfgForge

With YAML support:

pip install CfgForge[yaml]

With all optional formats:

pip install CfgForge[all]

Quick Start

from CfgForge import config

# Load sources (later overrides earlier)
config.load(".env", "config.yaml", defaults={"db.host": "localhost"})

# Read by dot-path
host = config.get("db.host")                # "localhost"
port = config.get("db.port", 5432)          # with default
key  = config.get("api.key", required=True) # raises if missing

# Type check
port = config.expect("db.port", int)

Supported Formats

API Reference

config.load(*paths, defaults=None)

Load one or more config files. Later sources override earlier ones. defaults has the lowest priority.

config.load(".env", "config.yaml", defaults={"db.host": "localhost"})

config.get(key, default=None, required=False)

Read a value by dot-path.

config.get("db.host")                 # None if missing
config.get("db.host", "localhost")    # fallback value
config.get("db.host", required=True)  # raises if missing

config.expect(key, type_)

Read a value and validate its type.

port = config.expect("db.port", int)   # raises ConfigTypeError if not int

config.has(key)

Check whether a key exists.

if config.has("db.password"):
    ...

config.update(data)

Inject config manually (useful for tests or runtime overrides).

config.update({"db": {"host": "localhost"}})

config.all()

Return a shallow copy of all config data.

data = config.all()

Exception Hierarchy

CfgForgeError
├── ConfigNotFoundError
├── ConfigTypeError
└── ConfigFileError

Catch all at once:

from CfgForge import CfgForgeError

try:
    config.load("config.yaml")
    config.get("db.host", required=True)
except CfgForgeError as e:
    print(f"Config error: {e}")

License

MIT