Metadata-Version: 2.4
Name: dynamic-config-loader
Version: 1.0.0
Summary: A lightweight, strategy-driven engine to dynamically discover and recursively deep-merge layered YAML configurations.
Author-email: Avinash Kumar <halfhiddencode@gmail.com>
Project-URL: Homepage, https://github.com/halfhiddencode/python-dynamic-config-loader
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0.1
Dynamic: license-file

# Dynamic Configuration Loader

A lightweight, production-grade, strategy-driven configuration orchestration engine designed to dynamically discover, alphabetically sort, and recursively deep-merge multi-layered YAML configurations across variable filesystem paths.

--------------------------------------------------------------------------
Copyright (C) 2026 Avinash Kumar <halfhiddencode AT gmail DOT com>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
--------------------------------------------------------------------------

## Core Features

- **Layered Ingestion Architecture:** Seeds a master configuration matrix from a static baseline file and patches runtime override layers over it dynamically.
- **Dynamic Multi-Directory Scanning:** Discovers and processes external asset folders via an isolated environment variable vector (`PYTHON_ADDITIONAL_CONFIG`).
- **Deterministic Processing Loop:** Enforces explicit alphabetical sorting on all discovered override files to make overlapping configuration mutations completely predictable.
- **Recursive Deep Merges:** Protects nested dictionary tracking structures from structural wiping or collision drops during runtime updates.
- **Zero Bulk Dependencies:** Relies entirely on native Python system standards and `pyyaml` for all parsing metrics.

---

## Installation

Ensure your Python environment is active and run the package requirements installer command:

```bash
pip install -r requirements.txt
```

Your `requirements.txt` file must contain:

```text
pyyaml==6.0.1
```

---

## Quick Start & Usage

### 1. Define Your Configuration Architecture

Set up your files to match this example structural multi-layer layout:

**Baseline File:** `test_configs/base_config.yaml`

```yaml
app_name: "Production Gateway"
debug_mode: false
database:
  host: "127.0.0.1"
  port: 5432
  pool_size: 20
```

**Override Patch File:** `test_configs/overrides/01_dev_patch.yaml`

```yaml
debug_mode: true
database:
  host: "internal-dev-cluster.local"

```

### 2. Execute the Loader Code

Import the engine into your main execution entry point script (e.g., `run.py`):

```python
import os
import json
from src.dynamic_config_loader import DynamicConfigLoader

# 1. Point the system context env variable to your overrides directory
os.environ["PYTHON_ADDITIONAL_CONFIG"] = "./test_configs/overrides, ./test_configs/someotherdir"

# 2. Instantiate the loading engine with your baseline tracking path
loader = DynamicConfigLoader(default_config_path="./test_configs/base_config.yaml")

# 3. Trigger the ingestion engine pipeline loop
final_config = loader.load()

# 4. Access your compiled matrix data properties safely
print(json.dumps(final_config, indent=4))

```

### 3. Expected Output Matrix

```json
{
    "app_name": "Production Gateway",
    "debug_mode": true,
    "database": {
        "host": "internal-dev-cluster.local",
        "port": 5432,
        "pool_size": 20
    }
}
```
---

## Automated Unit Testing

This project includes a dedicated validation testing suite that leverages Python's built-in `unittest` module, requiring zero external dependencies.

### Running the Tests via Terminal

To verify that the configuration loader and the deep merge logic are working correctly, run the standard Python test discovery command from the root folder of your project:

```bash
python -m unittest discover -s tests
```
