jps-config-manager 0.0.0
A lightweight, layered configuration management library for Python that merges constants, default YAML files, and user-provided configs with optional fallback control.
License: MIT
Requires Python: >=3.10
Keywords: cookiecutter, bootstrap, project-generator, automation

# jps-config-manager

![Build](https://github.com/jai-python3/jps-config-manager/actions/workflows/test.yml/badge.svg)
![Publish to PyPI](https://github.com/jai-python3/jps-config-manager/actions/workflows/publish-to-pypi.yml/badge.svg)
[![codecov](https://codecov.io/gh/jai-python3/jps-config-manager/branch/main/graph/badge.svg)](https://codecov.io/gh/jai-python3/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:

```yaml
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:

```python
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:

```python
cfg.get("pipeline.depth_metric")
```

### 📁 Example Project Integration
Project directory layout
```bash
project_a/
├── src/project_a/
│   ├── cli.py
│   ├── constants.py
│   ├── main.py
│   └── ...
├── conf/config.yaml
└── pyproject.toml
```

### constants.py


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


### CLI entrypoint (cli.py)

```python
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

```python
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)
```yaml
pipeline:
  depth_metric: trimmed_mean
```

Result configuration:

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

Disabling fallback
```yaml
behavior:
  default_fallback: false

pipeline:
  depth_metric: trimmed_mean
```


Missing trim_prop will raise:

```bash
ValueError: Missing required configuration value at: pipeline.trim_prop
```



### 📦 Installation
```bash
pip install jps-config-manager
```


Or from source:

```bash
make install
```

### 🧪 Development
```bash
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