dynamic-config-loader 2.5.0__tar.gz → 2.7.0__tar.gz

{dynamic_config_loader-2.5.0/src/dynamic_config_loader.egg-info → dynamic_config_loader-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamic-config-loader
-Version: 2.5.0
+Version: 2.7.0
 Summary: An enterprise-grade configuration orchestration engine designed to ingest, cascade, and deeply merge multiple configuration file layers.
 Author-email: Avinash Kumar <halfhiddencode@gmail.com>
 License: 
@@ -237,51 +237,79 @@ 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 configuration files.
+A lightweight, production-grade, strategy-driven configuration orchestration engine designed to dynamically discover, cascade, and deep-merge multi-layered configuration files.
 
-## Supported Formats
+---
 
-The orchestration engine natively parses and cascades the following configuration formats:
-* **YAML** (`.yaml`, `.yml`)
-* **JSON** (`.json`)
-* **XML** (`.xml`)
-* **TOML** (`.toml`)
-* **INI / Conf** (`.ini`, `.conf`)
-* **Java Properties** (`.properties`)
-* **Dotenv** (`.env`)
+> [!TIP]
+> ### 👋 NEW TO DYNAMIC CONFIG LOADER? START HERE!
+> 
+> Choose your role to find the fastest path to get up and running:
+> 
+> * **🆕 Application Developer (First Time User):** Start with the **[3-Line Quick Start Tutorial](docs/tutorials/getting_started.md)**.
+> * **🚀 DevOps / SRE Engineer:** Check the **[Configuration Lifecycle Matrix](docs/guides/user_usage.md#1-minimal-to-advanced-configuration-lifecycle-guide)** & **[K8s Deployment Scenarios](docs/guides/user_usage.md#7-production-deployment-scenarios)**.
+> * **🛠️ Open-Source Contributor:** See the **[Track A vs Track B Contributor Guide](docs/guides/contributor_guide.md#1-contributing-features-vs-format-strategies)**.
+> * **📦 Maintainer / DevOps Release:** Read the **[Release & OIDC Deployment Guide](docs/guides/release_guide.md)**.
 
 ---
 
-```text
-Copyright (C) 2026 Avinash Kumar <halfhiddencode AT gmail DOT com>
+## 📌 Quick Navigation Index
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+- [⚡ Minimal Quick Start](#-quick-start-minimal-3-lines)
+- [📦 Installation](#-installation)
+- [⚙️ Supported Configuration Formats](#%EF%B8%8F-supported-configuration-formats)
+- [🔀 Multi-Layer Overrides & Environment Injection](#-multi-layer-overrides--environment-injection)
+- [📖 Documentation Index](#-documentation-index)
+- [🎨 System Architecture Visualizer](#-system-architecture)
 
-    http://www.apache.org/licenses/LICENSE-2.0
+---
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-```
+### 🚀 Configuration Lifecycle Matrix: Minimal to Advanced
+
+| Lifecycle Phase | Component Requirement | How It Works in Code / Environment | Primary Purpose |
+| :--- | :--- | :--- | :--- |
+| **1. Local Dev (Coding Time)** | `[OPTIONAL FALLBACK]` | `loader = DynamicConfigLoader("config.yaml")` | Local fallback file for offline developer workstations. |
+| **2. Image Build (CI/CD Build Time)** | `[REQUIRED IN CODE]` | `loader = DynamicConfigLoader()` | **Image Immutability!** Zero hardcoded secrets in Docker image. |
+| **3. Deployment (K8s Runtime Time)** | `[OPTIONAL AT DEPLOYMENT]` | `export PYTHON_ADDITIONAL_CONFIG="/etc/config/prod.yaml"` | Mounts K8s ConfigMaps & Vault secrets into container at runtime. |
+| **4. Live Ops Overrides (Runtime)** | `[OPTIONAL AT RUNTIME]` | `export DCL_ENV_LOADER=true` <br> `export DCL_PORT=8080` | Overrides specific keys in memory dynamically without rebuilding image. |
 
 ---
 
-## Project Metadata
-* **Maintainer:** Avinash Kumar
-* **Target Ecosystem:** Python 3.8+ / GitLab Source Hosting and PyPI Package Registry
-* **Official Repository:** [python-dynamic-config-loader](https://gitlab.com/halfhiddencode/python-dynamic-config-loader)
-* **Licensing:** Apache License, Version 2.0
-* **Core Design Patterns:** Strategy Pattern, Registry Factory
+### Minimal Execution Code Snippets
+
+#### Mode 1: Container / Kubernetes Mode (`[RECOMMENDED FOR PROD]`)
+
+> [!NOTE]
+> **[OPTIONAL FILE PATH - CAN SKIP!]**
+> If you don't have a local config file, **YOU CAN SKIP IT!** In production container deployments, you do NOT need any hardcoded file paths in your code. The engine will handle configuration loading automatically at deployment time via environment variables (`PYTHON_ADDITIONAL_CONFIG` or `DCL_`).
+
+```python
+from dynamic_config_loader import DynamicConfigLoader
+
+# Zero hardcoded file paths! Fully handled at deployment time
+loader = DynamicConfigLoader()
+config = loader.load()
+```
+
+#### Mode 2: Local Development Mode (`[OPTIONAL FALLBACK]`)
+
+> [!NOTE]
+> **[LOCAL FALLBACK ONLY]**
+> Useful for local developer laptops so you can run `python app.py` offline without configuring environment variables.
+
+```python
+from dynamic_config_loader import DynamicConfigLoader
+
+# Optional local fallback file
+loader = DynamicConfigLoader("config.yaml")
+config = loader.load()
+```
 
 ---
 
-## Installation
+## 📦 Installation
 
-Install the package directly from PyPI:
+Install from PyPI via `pip`:
 
 ```bash
 pip install dynamic-config-loader
@@ -295,39 +323,68 @@ pip install -e .
 
 ---
 
-## Quick Start
+## ⚙️ Supported Configuration Formats
 
-```python
-import os
-from dynamic_config_loader import DynamicConfigLoader
+The orchestration engine natively ingests, parses, and cascades **7 configuration formats**:
 
-# 1. (Optional) Provide path override layers via system environment
-os.environ["PYTHON_ADDITIONAL_CONFIG"] = "/app/configs/overrides_directory"
+| Format | Extensions | Key Behavior & Conversion | Guide Link |
+| :--- | :--- | :--- | :--- |
+| **YAML** | `.yaml`, `.yml` | Native YAML indentation & deep dictionary parsing | [View Details](docs/guides/user_usage.md#71-yaml-strategy-yamlstrategy) |
+| **JSON** | `.json` | Strict JSON objects & typed arrays | [View Details](docs/guides/user_usage.md#72-json-strategy-jsonstrategy) |
+| **Dotenv** | `.env` | **100% Flat Keys** (`SERVICE_GATEWAY_NAME` $\rightarrow$ `config["service_gateway_name"]`) | [View Details](docs/guides/user_usage.md#87-dotenv-strategy-envstrategy) |
+| **TOML** | `.toml` | Section headers (`[table]`), inline tables, & datetimes | [View Details](docs/guides/user_usage.md#74-toml-strategy-tomlstrategy) |
+| **INI / Conf** | `.ini`, `.conf` | Section headers (`[section]`) & automatic primitive type casting | [View Details](docs/guides/user_usage.md#75-ini--conf-strategy-inistrategy) |
+| **Java Properties**| `.properties` | Dot notation (`app.database.port=5432` $\rightarrow$ `app.database.port`) | [View Details](docs/guides/user_usage.md#76-java-properties-strategy-propertiesstrategy) |
+| **XML** | `.xml` | Tag element hierarchies auto-converted into Python dicts | [View Details](docs/guides/user_usage.md#73-xml-strategy-xmlstrategy) |
 
-# 2. Instantiate with a local base configuration file
-loader = DynamicConfigLoader(default_config_path="/app/configs/base_defaults.yaml")
+---
 
-# 3. Load and compile configurations
-config = loader.load()
-print(config["database"]["host"])
+## 🔀 Multi-Layer Overrides & Environment Injection
+
+<details>
+<summary><b>Click to expand Advanced Environment Overrides & Logging Options</b></summary>
+
+### 1. External File/Directory Overrides (`PYTHON_ADDITIONAL_CONFIG`)
+Specify an external file or directory of override files via system environment variables:
+
+```bash
+export PYTHON_ADDITIONAL_CONFIG="/etc/app/production_overrides.yaml"
 ```
 
+### 2. Environment Variable Injection (`DCL_ENV_LOADER=true`)
+Inject or override specific keys dynamically at runtime using environment variables:
+
+```bash
+export DCL_ENV_LOADER=true
+export DCL_PORT=9000
+export DCL_LOG_LEVEL=info
+```
+
+### 3. Log Redaction Controls (`ENABLE_UNSAFE_LOGGING`)
+* **Default (Safe Mode):** Sensitive passwords and tokens are redacted (`[REDACTED]`) in logs.
+* **Unsafe Mode (`ENABLE_UNSAFE_LOGGING=true`):** Exposes raw values during local debug sessions.
+
+</details>
+
 ---
 
-## Documentation Index
+## 🎨 System Architecture
+
+![Master Architecture Pipeline & Deep Merge Visualizer](docs/images/master_architecture_deep_merge.svg)
+
+---
 
-The complete enterprise documentation is organized under the Diátaxis framework layout rules within the `docs/` directory. No emojis are used in the index or guidelines.
+## 📖 Documentation Index
 
-| Track | Target Document | Description |
+| Guide Track | Link | Description |
 | :--- | :--- | :--- |
-| **Getting Started** | [Getting Started Tutorial](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/tutorials/getting_started.md) | Onboarding sequence, repeatable format tracks, and installation via GitLab Package Registry. |
-| **Operations Guide** | [Advanced Ingestion and Path Traversal Guide](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/guides/user_usage.md) | Path parsing matrix, edge-case refusals, Central Config Manager pattern, and log masking safety details. |
-| **Contributor Guide** | [Format Strategy Contribution Guide](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/guides/contributor_guide.md) | Abstract base strategy class signatures, factory registration hooks, and copy-pasteable JSON blueprints. |
-| **Technical Reference** | [Core Architecture Reference](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/reference/architecture.md) | System design architecture, UML mapping, execution pipelines, and logging safety compliance matrices. |
+| **🚀 Getting Started Tutorial** | [getting_started.md](docs/tutorials/getting_started.md) | Step-by-step onboarding & minimal execution tracks. |
+| **📖 Operations & Usage Guide** | [user_usage.md](docs/guides/user_usage.md) | Complete format matrix, K8s/DevOps deployment scenarios, & path edge cases. |
+| **🛠️ Contributor Guide** | [contributor_guide.md](docs/guides/contributor_guide.md) | Adding custom format strategies & factory registry hooks. |
+| **🚀 Release & OIDC Guide** | [release_guide.md](docs/guides/release_guide.md) | OIDC Trusted Publishing, version bump rules, & PyPI deployment protocols. |
+| **🏗️ Architecture Reference** | [architecture.md](docs/reference/architecture.md) | System design, UML diagrams, & deep merge algorithms. |
 
 ---
 
-## Repository Ledgers
-* Version History: [CHANGELOG.md](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/CHANGELOG.md)
-* Security Policy: [SECURITY.md](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/SECURITY.md)
-* Contribution Protocols: [CONTRIBUTING.md](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/CONTRIBUTING.md)
+## 📜 License
+Licensed under the [Apache License, Version 2.0](LICENSE).

dynamic_config_loader-2.7.0/README.md

@@ -0,0 +1,153 @@
+# Dynamic Configuration Loader
+
+A lightweight, production-grade, strategy-driven configuration orchestration engine designed to dynamically discover, cascade, and deep-merge multi-layered configuration files.
+
+---
+
+> [!TIP]
+> ### 👋 NEW TO DYNAMIC CONFIG LOADER? START HERE!
+> 
+> Choose your role to find the fastest path to get up and running:
+> 
+> * **🆕 Application Developer (First Time User):** Start with the **[3-Line Quick Start Tutorial](docs/tutorials/getting_started.md)**.
+> * **🚀 DevOps / SRE Engineer:** Check the **[Configuration Lifecycle Matrix](docs/guides/user_usage.md#1-minimal-to-advanced-configuration-lifecycle-guide)** & **[K8s Deployment Scenarios](docs/guides/user_usage.md#7-production-deployment-scenarios)**.
+> * **🛠️ Open-Source Contributor:** See the **[Track A vs Track B Contributor Guide](docs/guides/contributor_guide.md#1-contributing-features-vs-format-strategies)**.
+> * **📦 Maintainer / DevOps Release:** Read the **[Release & OIDC Deployment Guide](docs/guides/release_guide.md)**.
+
+---
+
+## 📌 Quick Navigation Index
+
+- [⚡ Minimal Quick Start](#-quick-start-minimal-3-lines)
+- [📦 Installation](#-installation)
+- [⚙️ Supported Configuration Formats](#%EF%B8%8F-supported-configuration-formats)
+- [🔀 Multi-Layer Overrides & Environment Injection](#-multi-layer-overrides--environment-injection)
+- [📖 Documentation Index](#-documentation-index)
+- [🎨 System Architecture Visualizer](#-system-architecture)
+
+---
+
+### 🚀 Configuration Lifecycle Matrix: Minimal to Advanced
+
+| Lifecycle Phase | Component Requirement | How It Works in Code / Environment | Primary Purpose |
+| :--- | :--- | :--- | :--- |
+| **1. Local Dev (Coding Time)** | `[OPTIONAL FALLBACK]` | `loader = DynamicConfigLoader("config.yaml")` | Local fallback file for offline developer workstations. |
+| **2. Image Build (CI/CD Build Time)** | `[REQUIRED IN CODE]` | `loader = DynamicConfigLoader()` | **Image Immutability!** Zero hardcoded secrets in Docker image. |
+| **3. Deployment (K8s Runtime Time)** | `[OPTIONAL AT DEPLOYMENT]` | `export PYTHON_ADDITIONAL_CONFIG="/etc/config/prod.yaml"` | Mounts K8s ConfigMaps & Vault secrets into container at runtime. |
+| **4. Live Ops Overrides (Runtime)** | `[OPTIONAL AT RUNTIME]` | `export DCL_ENV_LOADER=true` <br> `export DCL_PORT=8080` | Overrides specific keys in memory dynamically without rebuilding image. |
+
+---
+
+### Minimal Execution Code Snippets
+
+#### Mode 1: Container / Kubernetes Mode (`[RECOMMENDED FOR PROD]`)
+
+> [!NOTE]
+> **[OPTIONAL FILE PATH - CAN SKIP!]**
+> If you don't have a local config file, **YOU CAN SKIP IT!** In production container deployments, you do NOT need any hardcoded file paths in your code. The engine will handle configuration loading automatically at deployment time via environment variables (`PYTHON_ADDITIONAL_CONFIG` or `DCL_`).
+
+```python
+from dynamic_config_loader import DynamicConfigLoader
+
+# Zero hardcoded file paths! Fully handled at deployment time
+loader = DynamicConfigLoader()
+config = loader.load()
+```
+
+#### Mode 2: Local Development Mode (`[OPTIONAL FALLBACK]`)
+
+> [!NOTE]
+> **[LOCAL FALLBACK ONLY]**
+> Useful for local developer laptops so you can run `python app.py` offline without configuring environment variables.
+
+```python
+from dynamic_config_loader import DynamicConfigLoader
+
+# Optional local fallback file
+loader = DynamicConfigLoader("config.yaml")
+config = loader.load()
+```
+
+---
+
+## 📦 Installation
+
+Install from PyPI via `pip`:
+
+```bash
+pip install dynamic-config-loader
+```
+
+Or install in editable mode for local development:
+
+```bash
+pip install -e .
+```
+
+---
+
+## ⚙️ Supported Configuration Formats
+
+The orchestration engine natively ingests, parses, and cascades **7 configuration formats**:
+
+| Format | Extensions | Key Behavior & Conversion | Guide Link |
+| :--- | :--- | :--- | :--- |
+| **YAML** | `.yaml`, `.yml` | Native YAML indentation & deep dictionary parsing | [View Details](docs/guides/user_usage.md#71-yaml-strategy-yamlstrategy) |
+| **JSON** | `.json` | Strict JSON objects & typed arrays | [View Details](docs/guides/user_usage.md#72-json-strategy-jsonstrategy) |
+| **Dotenv** | `.env` | **100% Flat Keys** (`SERVICE_GATEWAY_NAME` $\rightarrow$ `config["service_gateway_name"]`) | [View Details](docs/guides/user_usage.md#87-dotenv-strategy-envstrategy) |
+| **TOML** | `.toml` | Section headers (`[table]`), inline tables, & datetimes | [View Details](docs/guides/user_usage.md#74-toml-strategy-tomlstrategy) |
+| **INI / Conf** | `.ini`, `.conf` | Section headers (`[section]`) & automatic primitive type casting | [View Details](docs/guides/user_usage.md#75-ini--conf-strategy-inistrategy) |
+| **Java Properties**| `.properties` | Dot notation (`app.database.port=5432` $\rightarrow$ `app.database.port`) | [View Details](docs/guides/user_usage.md#76-java-properties-strategy-propertiesstrategy) |
+| **XML** | `.xml` | Tag element hierarchies auto-converted into Python dicts | [View Details](docs/guides/user_usage.md#73-xml-strategy-xmlstrategy) |
+
+---
+
+## 🔀 Multi-Layer Overrides & Environment Injection
+
+<details>
+<summary><b>Click to expand Advanced Environment Overrides & Logging Options</b></summary>
+
+### 1. External File/Directory Overrides (`PYTHON_ADDITIONAL_CONFIG`)
+Specify an external file or directory of override files via system environment variables:
+
+```bash
+export PYTHON_ADDITIONAL_CONFIG="/etc/app/production_overrides.yaml"
+```
+
+### 2. Environment Variable Injection (`DCL_ENV_LOADER=true`)
+Inject or override specific keys dynamically at runtime using environment variables:
+
+```bash
+export DCL_ENV_LOADER=true
+export DCL_PORT=9000
+export DCL_LOG_LEVEL=info
+```
+
+### 3. Log Redaction Controls (`ENABLE_UNSAFE_LOGGING`)
+* **Default (Safe Mode):** Sensitive passwords and tokens are redacted (`[REDACTED]`) in logs.
+* **Unsafe Mode (`ENABLE_UNSAFE_LOGGING=true`):** Exposes raw values during local debug sessions.
+
+</details>
+
+---
+
+## 🎨 System Architecture
+
+![Master Architecture Pipeline & Deep Merge Visualizer](docs/images/master_architecture_deep_merge.svg)
+
+---
+
+## 📖 Documentation Index
+
+| Guide Track | Link | Description |
+| :--- | :--- | :--- |
+| **🚀 Getting Started Tutorial** | [getting_started.md](docs/tutorials/getting_started.md) | Step-by-step onboarding & minimal execution tracks. |
+| **📖 Operations & Usage Guide** | [user_usage.md](docs/guides/user_usage.md) | Complete format matrix, K8s/DevOps deployment scenarios, & path edge cases. |
+| **🛠️ Contributor Guide** | [contributor_guide.md](docs/guides/contributor_guide.md) | Adding custom format strategies & factory registry hooks. |
+| **🚀 Release & OIDC Guide** | [release_guide.md](docs/guides/release_guide.md) | OIDC Trusted Publishing, version bump rules, & PyPI deployment protocols. |
+| **🏗️ Architecture Reference** | [architecture.md](docs/reference/architecture.md) | System design, UML diagrams, & deep merge algorithms. |
+
+---
+
+## 📜 License
+Licensed under the [Apache License, Version 2.0](LICENSE).

{dynamic_config_loader-2.5.0 → dynamic_config_loader-2.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dynamic-config-loader"
-version = "2.5.0"
+version = "2.7.0"
 description = "An enterprise-grade configuration orchestration engine designed to ingest, cascade, and deeply merge multiple configuration file layers."
 readme = "README.md"
 requires-python = ">=3.8"

{dynamic_config_loader-2.5.0 → dynamic_config_loader-2.7.0}/src/dynamic_config_loader/environment.py

@@ -56,11 +56,18 @@ def inject_environment_variables(
         if env_key.startswith(prefix):
             # Strip prefix
             sliced_key = env_key[len(prefix):]
-            if not sliced_key:
-                continue
+            parsed_val = _parse_env_value(env_val)
+
+            # Resolution order:
+            # 1. Explicit double-underscore '__': Splits into nested objects (e.g. DCL_AUTH__TENANT_ID -> config_data["auth"]["tenant_id"])
+            # 2. Default: Preserves as 100% FLAT key (e.g. DCL_SERVICE_GATEWAY_NAME -> config_data["service_gateway_name"])
+            flat_key = sliced_key.strip().lower()
+
+            if "__" in sliced_key:
+                parts = [p.lower() for p in sliced_key.split("__") if p]
+            else:
+                parts = [flat_key]
 
-            # Case Normalization and tokenizing
-            parts = [p.lower() for p in sliced_key.split("_") if p]
             if not parts:
                 continue
 

{dynamic_config_loader-2.5.0 → dynamic_config_loader-2.7.0}/src/dynamic_config_loader/strategies/env/parser.py

@@ -46,15 +46,11 @@ def parse_env_file(file_path: Path) -> Dict[str, Any]:
         with open(file_path, "r", encoding="utf-8") as f:
             for line in f:
                 line = line.strip()
-                # Ignore empty lines and comment lines starting with '#'
-                if not line or line.startswith("#"):
-                    continue
-
-                if "=" not in line:
+                if not line or line.startswith("#") or line.startswith("!") or "=" not in line:
                     continue
 
                 key, val = line.split("=", 1)
-                key = key.strip()
+                key = key.strip().lower()
                 val = val.strip()
 
                 if not key:
@@ -67,18 +63,7 @@ def parse_env_file(file_path: Path) -> Dict[str, Any]:
                     val = val[1:-1]
 
                 parsed_val = _parse_env_file_value(val)
-
-                # Tokenize key by single underscore delimiter to align with env injection track
-                parts = [p.lower() for p in key.split("_") if p]
-                if not parts:
-                    continue
-
-                curr = data
-                for part in parts[:-1]:
-                    if part not in curr or not isinstance(curr[part], dict):
-                        curr[part] = {}
-                    curr = curr[part]
-                curr[parts[-1]] = parsed_val
+                data[key] = parsed_val
 
     except (IOError, PermissionError) as e:
         logger.exception(f"Failed to read or parse dotenv file: {file_path.name}", exc_info=e)

{dynamic_config_loader-2.5.0 → dynamic_config_loader-2.7.0/src/dynamic_config_loader.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamic-config-loader
-Version: 2.5.0
+Version: 2.7.0
 Summary: An enterprise-grade configuration orchestration engine designed to ingest, cascade, and deeply merge multiple configuration file layers.
 Author-email: Avinash Kumar <halfhiddencode@gmail.com>
 License: 
@@ -237,51 +237,79 @@ 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 configuration files.
+A lightweight, production-grade, strategy-driven configuration orchestration engine designed to dynamically discover, cascade, and deep-merge multi-layered configuration files.
 
-## Supported Formats
+---
 
-The orchestration engine natively parses and cascades the following configuration formats:
-* **YAML** (`.yaml`, `.yml`)
-* **JSON** (`.json`)
-* **XML** (`.xml`)
-* **TOML** (`.toml`)
-* **INI / Conf** (`.ini`, `.conf`)
-* **Java Properties** (`.properties`)
-* **Dotenv** (`.env`)
+> [!TIP]
+> ### 👋 NEW TO DYNAMIC CONFIG LOADER? START HERE!
+> 
+> Choose your role to find the fastest path to get up and running:
+> 
+> * **🆕 Application Developer (First Time User):** Start with the **[3-Line Quick Start Tutorial](docs/tutorials/getting_started.md)**.
+> * **🚀 DevOps / SRE Engineer:** Check the **[Configuration Lifecycle Matrix](docs/guides/user_usage.md#1-minimal-to-advanced-configuration-lifecycle-guide)** & **[K8s Deployment Scenarios](docs/guides/user_usage.md#7-production-deployment-scenarios)**.
+> * **🛠️ Open-Source Contributor:** See the **[Track A vs Track B Contributor Guide](docs/guides/contributor_guide.md#1-contributing-features-vs-format-strategies)**.
+> * **📦 Maintainer / DevOps Release:** Read the **[Release & OIDC Deployment Guide](docs/guides/release_guide.md)**.
 
 ---
 
-```text
-Copyright (C) 2026 Avinash Kumar <halfhiddencode AT gmail DOT com>
+## 📌 Quick Navigation Index
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+- [⚡ Minimal Quick Start](#-quick-start-minimal-3-lines)
+- [📦 Installation](#-installation)
+- [⚙️ Supported Configuration Formats](#%EF%B8%8F-supported-configuration-formats)
+- [🔀 Multi-Layer Overrides & Environment Injection](#-multi-layer-overrides--environment-injection)
+- [📖 Documentation Index](#-documentation-index)
+- [🎨 System Architecture Visualizer](#-system-architecture)
 
-    http://www.apache.org/licenses/LICENSE-2.0
+---
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-```
+### 🚀 Configuration Lifecycle Matrix: Minimal to Advanced
+
+| Lifecycle Phase | Component Requirement | How It Works in Code / Environment | Primary Purpose |
+| :--- | :--- | :--- | :--- |
+| **1. Local Dev (Coding Time)** | `[OPTIONAL FALLBACK]` | `loader = DynamicConfigLoader("config.yaml")` | Local fallback file for offline developer workstations. |
+| **2. Image Build (CI/CD Build Time)** | `[REQUIRED IN CODE]` | `loader = DynamicConfigLoader()` | **Image Immutability!** Zero hardcoded secrets in Docker image. |
+| **3. Deployment (K8s Runtime Time)** | `[OPTIONAL AT DEPLOYMENT]` | `export PYTHON_ADDITIONAL_CONFIG="/etc/config/prod.yaml"` | Mounts K8s ConfigMaps & Vault secrets into container at runtime. |
+| **4. Live Ops Overrides (Runtime)** | `[OPTIONAL AT RUNTIME]` | `export DCL_ENV_LOADER=true` <br> `export DCL_PORT=8080` | Overrides specific keys in memory dynamically without rebuilding image. |
 
 ---
 
-## Project Metadata
-* **Maintainer:** Avinash Kumar
-* **Target Ecosystem:** Python 3.8+ / GitLab Source Hosting and PyPI Package Registry
-* **Official Repository:** [python-dynamic-config-loader](https://gitlab.com/halfhiddencode/python-dynamic-config-loader)
-* **Licensing:** Apache License, Version 2.0
-* **Core Design Patterns:** Strategy Pattern, Registry Factory
+### Minimal Execution Code Snippets
+
+#### Mode 1: Container / Kubernetes Mode (`[RECOMMENDED FOR PROD]`)
+
+> [!NOTE]
+> **[OPTIONAL FILE PATH - CAN SKIP!]**
+> If you don't have a local config file, **YOU CAN SKIP IT!** In production container deployments, you do NOT need any hardcoded file paths in your code. The engine will handle configuration loading automatically at deployment time via environment variables (`PYTHON_ADDITIONAL_CONFIG` or `DCL_`).
+
+```python
+from dynamic_config_loader import DynamicConfigLoader
+
+# Zero hardcoded file paths! Fully handled at deployment time
+loader = DynamicConfigLoader()
+config = loader.load()
+```
+
+#### Mode 2: Local Development Mode (`[OPTIONAL FALLBACK]`)
+
+> [!NOTE]
+> **[LOCAL FALLBACK ONLY]**
+> Useful for local developer laptops so you can run `python app.py` offline without configuring environment variables.
+
+```python
+from dynamic_config_loader import DynamicConfigLoader
+
+# Optional local fallback file
+loader = DynamicConfigLoader("config.yaml")
+config = loader.load()
+```
 
 ---
 
-## Installation
+## 📦 Installation
 
-Install the package directly from PyPI:
+Install from PyPI via `pip`:
 
 ```bash
 pip install dynamic-config-loader
@@ -295,39 +323,68 @@ pip install -e .
 
 ---
 
-## Quick Start
+## ⚙️ Supported Configuration Formats
 
-```python
-import os
-from dynamic_config_loader import DynamicConfigLoader
+The orchestration engine natively ingests, parses, and cascades **7 configuration formats**:
 
-# 1. (Optional) Provide path override layers via system environment
-os.environ["PYTHON_ADDITIONAL_CONFIG"] = "/app/configs/overrides_directory"
+| Format | Extensions | Key Behavior & Conversion | Guide Link |
+| :--- | :--- | :--- | :--- |
+| **YAML** | `.yaml`, `.yml` | Native YAML indentation & deep dictionary parsing | [View Details](docs/guides/user_usage.md#71-yaml-strategy-yamlstrategy) |
+| **JSON** | `.json` | Strict JSON objects & typed arrays | [View Details](docs/guides/user_usage.md#72-json-strategy-jsonstrategy) |
+| **Dotenv** | `.env` | **100% Flat Keys** (`SERVICE_GATEWAY_NAME` $\rightarrow$ `config["service_gateway_name"]`) | [View Details](docs/guides/user_usage.md#87-dotenv-strategy-envstrategy) |
+| **TOML** | `.toml` | Section headers (`[table]`), inline tables, & datetimes | [View Details](docs/guides/user_usage.md#74-toml-strategy-tomlstrategy) |
+| **INI / Conf** | `.ini`, `.conf` | Section headers (`[section]`) & automatic primitive type casting | [View Details](docs/guides/user_usage.md#75-ini--conf-strategy-inistrategy) |
+| **Java Properties**| `.properties` | Dot notation (`app.database.port=5432` $\rightarrow$ `app.database.port`) | [View Details](docs/guides/user_usage.md#76-java-properties-strategy-propertiesstrategy) |
+| **XML** | `.xml` | Tag element hierarchies auto-converted into Python dicts | [View Details](docs/guides/user_usage.md#73-xml-strategy-xmlstrategy) |
 
-# 2. Instantiate with a local base configuration file
-loader = DynamicConfigLoader(default_config_path="/app/configs/base_defaults.yaml")
+---
 
-# 3. Load and compile configurations
-config = loader.load()
-print(config["database"]["host"])
+## 🔀 Multi-Layer Overrides & Environment Injection
+
+<details>
+<summary><b>Click to expand Advanced Environment Overrides & Logging Options</b></summary>
+
+### 1. External File/Directory Overrides (`PYTHON_ADDITIONAL_CONFIG`)
+Specify an external file or directory of override files via system environment variables:
+
+```bash
+export PYTHON_ADDITIONAL_CONFIG="/etc/app/production_overrides.yaml"
 ```
 
+### 2. Environment Variable Injection (`DCL_ENV_LOADER=true`)
+Inject or override specific keys dynamically at runtime using environment variables:
+
+```bash
+export DCL_ENV_LOADER=true
+export DCL_PORT=9000
+export DCL_LOG_LEVEL=info
+```
+
+### 3. Log Redaction Controls (`ENABLE_UNSAFE_LOGGING`)
+* **Default (Safe Mode):** Sensitive passwords and tokens are redacted (`[REDACTED]`) in logs.
+* **Unsafe Mode (`ENABLE_UNSAFE_LOGGING=true`):** Exposes raw values during local debug sessions.
+
+</details>
+
 ---
 
-## Documentation Index
+## 🎨 System Architecture
+
+![Master Architecture Pipeline & Deep Merge Visualizer](docs/images/master_architecture_deep_merge.svg)
+
+---
 
-The complete enterprise documentation is organized under the Diátaxis framework layout rules within the `docs/` directory. No emojis are used in the index or guidelines.
+## 📖 Documentation Index
 
-| Track | Target Document | Description |
+| Guide Track | Link | Description |
 | :--- | :--- | :--- |
-| **Getting Started** | [Getting Started Tutorial](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/tutorials/getting_started.md) | Onboarding sequence, repeatable format tracks, and installation via GitLab Package Registry. |
-| **Operations Guide** | [Advanced Ingestion and Path Traversal Guide](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/guides/user_usage.md) | Path parsing matrix, edge-case refusals, Central Config Manager pattern, and log masking safety details. |
-| **Contributor Guide** | [Format Strategy Contribution Guide](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/guides/contributor_guide.md) | Abstract base strategy class signatures, factory registration hooks, and copy-pasteable JSON blueprints. |
-| **Technical Reference** | [Core Architecture Reference](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/reference/architecture.md) | System design architecture, UML mapping, execution pipelines, and logging safety compliance matrices. |
+| **🚀 Getting Started Tutorial** | [getting_started.md](docs/tutorials/getting_started.md) | Step-by-step onboarding & minimal execution tracks. |
+| **📖 Operations & Usage Guide** | [user_usage.md](docs/guides/user_usage.md) | Complete format matrix, K8s/DevOps deployment scenarios, & path edge cases. |
+| **🛠️ Contributor Guide** | [contributor_guide.md](docs/guides/contributor_guide.md) | Adding custom format strategies & factory registry hooks. |
+| **🚀 Release & OIDC Guide** | [release_guide.md](docs/guides/release_guide.md) | OIDC Trusted Publishing, version bump rules, & PyPI deployment protocols. |
+| **🏗️ Architecture Reference** | [architecture.md](docs/reference/architecture.md) | System design, UML diagrams, & deep merge algorithms. |
 
 ---
 
-## Repository Ledgers
-* Version History: [CHANGELOG.md](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/CHANGELOG.md)
-* Security Policy: [SECURITY.md](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/SECURITY.md)
-* Contribution Protocols: [CONTRIBUTING.md](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/CONTRIBUTING.md)
+## 📜 License
+Licensed under the [Apache License, Version 2.0](LICENSE).

{dynamic_config_loader-2.5.0 → dynamic_config_loader-2.7.0}/tests/test_env_injection.py

@@ -39,9 +39,9 @@ class TestEnvInjection(unittest.TestCase):
         Verifies that configuration parameters are injected correctly with the default prefix.
         """
         os.environ["DCL_ENV_LOADER"] = "true"
-        os.environ["DCL_DATABASE_PORT"] = "9000"
-        os.environ["DCL_DATABASE_USER"] = "postgres_env"
-        os.environ["DCL_NEW_FEATURE_ENABLED"] = "true"
+        os.environ["DCL_DATABASE__PORT"] = "9000"
+        os.environ["DCL_DATABASE__USER"] = "postgres_env"
+        os.environ["DCL_SERVICE_GATEWAY_NAME"] = "payment_gateway"
 
         loader = DynamicConfigLoader(default_config_path=str(self.base_file))
         result = loader.load()
@@ -49,14 +49,41 @@ class TestEnvInjection(unittest.TestCase):
         # Check nested structures are created or overridden
         self.assertEqual(result["database"]["port"], 9000)  # String "9000" is parsed to int 9000
         self.assertEqual(result["database"]["user"], "postgres_env")
-        self.assertTrue(result["new"]["feature"]["enabled"])  # String "true" is parsed to bool True
+        self.assertEqual(result["service_gateway_name"], "payment_gateway")  # Single _ is 100% flat!
+
+    def test_injection_double_underscore_delimiter(self):
+        """
+        Verifies that double-underscore '__' preserves single underscores in injected key names.
+        """
+        os.environ["DCL_ENV_LOADER"] = "true"
+        os.environ["DCL_AUTH__TENANT_ID"] = "5fa1dea3-2af8-4cd5"
+        os.environ["DCL_AWS_S3__BUCKET_NAME"] = "my-bucket-prod"
+
+        loader = DynamicConfigLoader(default_config_path=str(self.base_file))
+        result = loader.load()
+
+        self.assertEqual(result["auth"]["tenant_id"], "5fa1dea3-2af8-4cd5")
+        self.assertEqual(result["aws_s3"]["bucket_name"], "my-bucket-prod")
+
+    def test_injection_flat_key_override(self):
+        """
+        Verifies that DCL_APP_NAME cleanly overrides a flat key 'app_name' from baseline.
+        """
+        os.environ["DCL_ENV_LOADER"] = "true"
+        os.environ["DCL_APP_NAME"] = "Overridden Gateway App"
+
+        env_file = self.TEST_DIR / "test_configs" / "base_config.env"
+        loader = DynamicConfigLoader(default_config_path=str(env_file))
+        result = loader.load()
+
+        self.assertEqual(result["app_name"], "Overridden Gateway App")
 
     def test_injection_custom_prefix(self):
         """
         Verifies that configuration parameters are injected correctly using a custom prefix.
         """
         os.environ["DCL_ENV_LOADER"] = "true"
-        os.environ["MYAPP_DB_HOST"] = "remote.db"
+        os.environ["MYAPP_DB__HOST"] = "remote.db"
 
         # Pass custom prefix to constructor
         loader = DynamicConfigLoader(default_config_path=str(self.base_file), prefix="MYAPP_")

{dynamic_config_loader-2.5.0 → dynamic_config_loader-2.7.0}/tests/test_env_strategy.py

@@ -36,10 +36,30 @@ class TestEnvStrategy(unittest.TestCase):
         Verifies that parse_env_file correctly parses env variables and translates primitive types.
         """
         data = parse_env_file(self.base_file)
-        self.assertEqual(data["app"]["name"], "Test Env Gateway")
-        self.assertFalse(data["debug"]["mode"])
-        self.assertEqual(data["database"]["port"], 5432)
-        self.assertEqual(data["database"]["host"], "127.0.0.1")
+        self.assertEqual(data["app_name"], "Test Env Gateway")
+        self.assertFalse(data["debug_mode"])
+        self.assertEqual(data["database_port"], 5432)
+        self.assertEqual(data["database_host"], "127.0.0.1")
+
+    def test_flat_env_key_parsing(self):
+        """
+        Verifies that dotenv files return 100% flat dictionary mappings without creating nested sub-dictionaries.
+        """
+        import tempfile
+        with tempfile.NamedTemporaryFile("w+", suffix=".env", delete=False) as f:
+            f.write("AUTH__TENANT_ID=5fa1dea3\n")
+            f.write("AWS_S3__BUCKET_NAME=my-bucket\n")
+            f.write("SERVICE_GATEWAY_NAME=my_app\n")
+            temp_path = Path(f.name)
+
+        try:
+            data = parse_env_file(temp_path)
+            self.assertEqual(data["auth__tenant_id"], "5fa1dea3")
+            self.assertEqual(data["aws_s3__bucket_name"], "my-bucket")
+            self.assertEqual(data["service_gateway_name"], "my_app")
+        finally:
+            if temp_path.exists():
+                temp_path.unlink()
 
     def test_env_deep_merging(self):
         """
@@ -80,10 +100,10 @@ class TestEnvStrategy(unittest.TestCase):
         loader = DynamicConfigLoader(default_config_path=str(self.base_file))
         result = loader.load()
 
-        self.assertEqual(result["app"]["name"], "Test Env Gateway")
-        self.assertTrue(result["debug"]["mode"])
-        self.assertEqual(result["database"]["host"], "env-dev-cluster.local")
-        self.assertEqual(result["database"]["port"], 5432)
+        self.assertEqual(result["app_name"], "Test Env Gateway")
+        self.assertTrue(result["debug_mode"])
+        self.assertEqual(result["database_host"], "env-dev-cluster.local")
+        self.assertEqual(result["database_port"], 5432)
 
     def test_env_log_masking(self):
         """

dynamic_config_loader-2.5.0/README.md

@@ -1,96 +0,0 @@
-# Dynamic Configuration Loader
-
-A lightweight, production-grade, strategy-driven configuration orchestration engine designed to dynamically discover, alphabetically sort, and recursively deep-merge multi-layered configuration files.
-
-## Supported Formats
-
-The orchestration engine natively parses and cascades the following configuration formats:
-* **YAML** (`.yaml`, `.yml`)
-* **JSON** (`.json`)
-* **XML** (`.xml`)
-* **TOML** (`.toml`)
-* **INI / Conf** (`.ini`, `.conf`)
-* **Java Properties** (`.properties`)
-* **Dotenv** (`.env`)
-
----
-
-```text
-Copyright (C) 2026 Avinash Kumar <halfhiddencode AT gmail DOT com>
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-```
-
----
-
-## Project Metadata
-* **Maintainer:** Avinash Kumar
-* **Target Ecosystem:** Python 3.8+ / GitLab Source Hosting and PyPI Package Registry
-* **Official Repository:** [python-dynamic-config-loader](https://gitlab.com/halfhiddencode/python-dynamic-config-loader)
-* **Licensing:** Apache License, Version 2.0
-* **Core Design Patterns:** Strategy Pattern, Registry Factory
-
----
-
-## Installation
-
-Install the package directly from PyPI:
-
-```bash
-pip install dynamic-config-loader
-```
-
-Or install in editable mode for local development:
-
-```bash
-pip install -e .
-```
-
----
-
-## Quick Start
-
-```python
-import os
-from dynamic_config_loader import DynamicConfigLoader
-
-# 1. (Optional) Provide path override layers via system environment
-os.environ["PYTHON_ADDITIONAL_CONFIG"] = "/app/configs/overrides_directory"
-
-# 2. Instantiate with a local base configuration file
-loader = DynamicConfigLoader(default_config_path="/app/configs/base_defaults.yaml")
-
-# 3. Load and compile configurations
-config = loader.load()
-print(config["database"]["host"])
-```
-
----
-
-## Documentation Index
-
-The complete enterprise documentation is organized under the Diátaxis framework layout rules within the `docs/` directory. No emojis are used in the index or guidelines.
-
-| Track | Target Document | Description |
-| :--- | :--- | :--- |
-| **Getting Started** | [Getting Started Tutorial](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/tutorials/getting_started.md) | Onboarding sequence, repeatable format tracks, and installation via GitLab Package Registry. |
-| **Operations Guide** | [Advanced Ingestion and Path Traversal Guide](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/guides/user_usage.md) | Path parsing matrix, edge-case refusals, Central Config Manager pattern, and log masking safety details. |
-| **Contributor Guide** | [Format Strategy Contribution Guide](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/guides/contributor_guide.md) | Abstract base strategy class signatures, factory registration hooks, and copy-pasteable JSON blueprints. |
-| **Technical Reference** | [Core Architecture Reference](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/docs/reference/architecture.md) | System design architecture, UML mapping, execution pipelines, and logging safety compliance matrices. |
-
----
-
-## Repository Ledgers
-* Version History: [CHANGELOG.md](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/CHANGELOG.md)
-* Security Policy: [SECURITY.md](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/SECURITY.md)
-* Contribution Protocols: [CONTRIBUTING.md](https://gitlab.com/halfhiddencode/python-dynamic-config-loader/-/blob/main/CONTRIBUTING.md)