jps-config-manager

A lightweight, layered configuration management library for Python that merges constants, default YAML files, and user-provided configs with optional fallback control.

---

🚀 Overview

jps-config-manager provides a clean, unified configuration system for Python applications and CLI tools.
It supports:

• A project's Python constants (e.g., constants.py)
• A default configuration YAML file
• A user-supplied configuration file provided via --config-file
• Optional fallback behavior (enabled by default, user-controlled via default_fallback: false)
• Strong validation and typed accessors

It is ideal for applications that require predictable, validated, hierarchical configuration loading (e.g., pipelines, services, CLI utilities).

---

✨ Features

✅ Layered Configuration

Configuration is merged in the following order:

1. Project defaults (constants.py)
2. Default YAML file (e.g., conf/config.yaml)
3. User-provided YAML file (--config-file)

Later layers override earlier ones.

✅ Optional Fallback Support

Users may disable fallback entirely:

behavior:
  default_fallback: false

When disabled, all required values must be explicitly provided. Missing keys raise descriptive validation errors.

✅ Singleton Manager

A global configuration object ensures consistent access across your application:

from jps_config_manager import ConfigManager

cfg = ConfigManager.instance()

✅ Typed Getters

Strongly-typed retrieval:

• get_str()
• get_int()
• get_float()
• get_bool()
• get_list()
• get_path()
• get_file()
• get_dir()

✅ YAML Loading + Validation

Includes robust YAML loading (safe_load) and validation of required config keys.

✅ Dotted-Path Access

Native support for hierarchical lookups:

cfg.get("pipeline.depth_metric")

📁 Example Project Integration

Project directory layout

project_a/
├── src/project_a/
│   ├── cli.py
│   ├── constants.py
│   ├── main.py
│   └── ...
├── conf/config.yaml
└── pyproject.toml

constants.py

DEFAULTS = {
    "pipeline": {
        "depth_metric": "median",
        "trim_prop": 0.1,
    },
    "paths": {
        "reference": "/opt/ref.fasta"
    },
    "behavior": {
        "default_fallback": True,
    }
}

CLI entrypoint (cli.py)

import typer
from jps_config_manager import ConfigManager
from project_a import constants

app = typer.Typer()

@app.command()
def run(config_file: str = typer.Option(None, "--config-file")):
    ConfigManager.initialize(
        project_defaults=constants.DEFAULTS,
        default_config_file="conf/config.yaml",
        user_config_file=config_file,
    )

    run_pipeline()

Using the configuration in the application

from jps_config_manager import ConfigManager

def run_pipeline():
    cfg = ConfigManager.instance()

    metric = cfg.get_str("pipeline.depth_metric")
    trim = cfg.get_float("pipeline.trim_prop")
    ref  = cfg.get_file("paths.reference")

    print("Using:", metric, trim, ref)

🧪 Example Usage (Minimal)

Using fallback (default)

pipeline:
  depth_metric: trimmed_mean

Result configuration:

• depth_metric → "trimmed_mean"
• trim_prop → 0.1 (default)
• behavior.default_fallback → True

Disabling fallback

behavior:
  default_fallback: false

pipeline:
  depth_metric: trimmed_mean

Missing trim_prop will raise:

ValueError: Missing required configuration value at: pipeline.trim_prop

📦 Installation

pip install jps-config-manager

Or from source:

make install

🧪 Development

make fix && make format && make lint
make test

The test suite includes:

• YAML loader tests
• Deep merge tests
• Fallback logic tests
• Validation tests
• ConfigManager singleton tests
• Typed getter tests
• Path resolution tests

📜 License

MIT License © Jaideep Sundaram