dd-config 0.1.0__tar.gz

dd_config-0.1.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

dd_config-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 digital-duck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dd_config-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: dd-config
+Version: 0.1.0
+Summary: Unified configuration management for the dd-* ecosystem
+Project-URL: Homepage, https://github.com/digital-duck/dd-config
+Project-URL: Repository, https://github.com/digital-duck/dd-config
+Author-email: Digital Duck <p2p2learn@outlook.com>
+License: MIT License
+        
+        Copyright (c) 2026 digital-duck
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: config,configuration,env,ini,json,toml,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: tomli-w>=1.0; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: toml
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'toml'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# dd-config
+
+Unified configuration management for the `dd-*` ecosystem — load, merge, validate and
+convert config files across multiple formats with a single clean API.
+
+## Install
+
+```bash
+pip install dd-config                    # JSON + INI + .env support (stdlib only)
+pip install "dd-config[yaml]"            # + YAML support
+pip install "dd-config[all]"             # all formats including TOML
+```
+
+## Quick start
+
+```python
+from dd_config import Config
+
+# Load a YAML config
+cfg = Config.load("splflow.yaml")
+
+# Plain key access
+adapter = cfg["llm_adapter"]            # "ollama"
+
+# Dot-path access for nested keys
+host = cfg["database.host"]
+
+# Safe get with default
+port = cfg.get("database.port", 5432)
+
+# Layer overrides on top (later files win)
+cfg = Config.load("base.yaml", overrides=["local.yaml", ".env"])
+```
+
+## Supported formats
+
+| Format | Extension | Extra required |
+|--------|-----------|----------------|
+| JSON   | `.json`   | none (stdlib)  |
+| YAML   | `.yaml`, `.yml` | `pip install "dd-config[yaml]"` |
+| TOML   | `.toml`   | `pip install "dd-config[all]"` |
+| INI    | `.ini`, `.cfg` | none (stdlib) |
+| Env    | `.env`    | none (stdlib)  |
+
+## Features
+
+- **Multi-format** — one API for JSON, YAML, TOML, INI, `.env`
+- **Auto-detection** — format inferred from file extension
+- **Layered loading** — base config + multiple override files; last writer wins
+- **Dot-path access** — `cfg["server.port"]` instead of `cfg["server"]["port"]`
+- **Env interpolation** — `${VAR:-default}` tokens expanded on load
+- **Format conversion** — `Config.convert("app.yaml", "app.json")`
+- **Validation** — required-key and type checks raise `ValidationError`
+- **Plain dict** — `cfg.to_dict()` returns a plain Python dict; no magic objects
+- **Lazy deps** — YAML/TOML libraries only imported when actually used
+
+## Validation
+
+```python
+cfg.validate(required=["llm_adapter", "database.host"])
+cfg.validate(schema={"database.port": int, "debug": bool})
+```
+
+## Saving & converting
+
+```python
+cfg["llm_adapter"] = "openrouter"
+cfg.save("splflow.yaml")               # write back to YAML
+Config.convert("splflow.yaml", "splflow.json")   # one-liner format conversion
+```
+
+## Environment variable interpolation
+
+Values like `${OPENROUTER_API_KEY:-}` in config files are expanded from the
+environment at load time. Useful for secrets that must not be committed to VCS:
+
+```yaml
+openrouter:
+  api_key: ${OPENROUTER_API_KEY}
+  base_url: https://openrouter.ai/api/v1
+```
+
+## Merge
+
+```python
+base = Config.load("base.yaml")
+local = Config.load("local.yaml")
+merged = base.merge(local)             # local wins on conflict; non-destructive
+```
+
+## License
+
+MIT © 2026 digital-duck

dd_config-0.1.0/README.md

@@ -0,0 +1,93 @@
+# dd-config
+
+Unified configuration management for the `dd-*` ecosystem — load, merge, validate and
+convert config files across multiple formats with a single clean API.
+
+## Install
+
+```bash
+pip install dd-config                    # JSON + INI + .env support (stdlib only)
+pip install "dd-config[yaml]"            # + YAML support
+pip install "dd-config[all]"             # all formats including TOML
+```
+
+## Quick start
+
+```python
+from dd_config import Config
+
+# Load a YAML config
+cfg = Config.load("splflow.yaml")
+
+# Plain key access
+adapter = cfg["llm_adapter"]            # "ollama"
+
+# Dot-path access for nested keys
+host = cfg["database.host"]
+
+# Safe get with default
+port = cfg.get("database.port", 5432)
+
+# Layer overrides on top (later files win)
+cfg = Config.load("base.yaml", overrides=["local.yaml", ".env"])
+```
+
+## Supported formats
+
+| Format | Extension | Extra required |
+|--------|-----------|----------------|
+| JSON   | `.json`   | none (stdlib)  |
+| YAML   | `.yaml`, `.yml` | `pip install "dd-config[yaml]"` |
+| TOML   | `.toml`   | `pip install "dd-config[all]"` |
+| INI    | `.ini`, `.cfg` | none (stdlib) |
+| Env    | `.env`    | none (stdlib)  |
+
+## Features
+
+- **Multi-format** — one API for JSON, YAML, TOML, INI, `.env`
+- **Auto-detection** — format inferred from file extension
+- **Layered loading** — base config + multiple override files; last writer wins
+- **Dot-path access** — `cfg["server.port"]` instead of `cfg["server"]["port"]`
+- **Env interpolation** — `${VAR:-default}` tokens expanded on load
+- **Format conversion** — `Config.convert("app.yaml", "app.json")`
+- **Validation** — required-key and type checks raise `ValidationError`
+- **Plain dict** — `cfg.to_dict()` returns a plain Python dict; no magic objects
+- **Lazy deps** — YAML/TOML libraries only imported when actually used
+
+## Validation
+
+```python
+cfg.validate(required=["llm_adapter", "database.host"])
+cfg.validate(schema={"database.port": int, "debug": bool})
+```
+
+## Saving & converting
+
+```python
+cfg["llm_adapter"] = "openrouter"
+cfg.save("splflow.yaml")               # write back to YAML
+Config.convert("splflow.yaml", "splflow.json")   # one-liner format conversion
+```
+
+## Environment variable interpolation
+
+Values like `${OPENROUTER_API_KEY:-}` in config files are expanded from the
+environment at load time. Useful for secrets that must not be committed to VCS:
+
+```yaml
+openrouter:
+  api_key: ${OPENROUTER_API_KEY}
+  base_url: https://openrouter.ai/api/v1
+```
+
+## Merge
+
+```python
+base = Config.load("base.yaml")
+local = Config.load("local.yaml")
+merged = base.merge(local)             # local wins on conflict; non-destructive
+```
+
+## License
+
+MIT © 2026 digital-duck

dd_config-0.1.0/cookbook/01_basics/README.md

@@ -0,0 +1,17 @@
+# 01 — dd-config Basics
+
+Demonstrates core `dd-config` features:
+
+- Load JSON / YAML config files
+- Dot-path access (`cfg["database.host"]`)
+- Override layering (base + local + `.env`)
+- Format conversion (`Config.convert`)
+- Validation (required keys + type checking)
+- Env-var interpolation (`${VAR:-default}`)
+
+## Run
+
+```bash
+pip install -r requirements.txt
+python main.py
+```

dd_config-0.1.0/cookbook/01_basics/main.py

@@ -0,0 +1,136 @@
+"""dd-config basics cookbook.
+
+Run with:
+    python main.py
+"""
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+from dd_config import Config, ValidationError
+
+
+def section(title: str) -> None:
+    print(f"\n{'='*60}")
+    print(f"  {title}")
+    print('='*60)
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        root = Path(tmpdir)
+
+        # ------------------------------------------------------------------ #
+        # 1. Write sample config files
+        # ------------------------------------------------------------------ #
+        base_cfg = root / "app.json"
+        base_cfg.write_text(json.dumps({
+            "app": "my-service",
+            "port": 8080,
+            "debug": False,
+            "database": {
+                "host": "${DB_HOST:-localhost}",
+                "port": 5432,
+                "name": "mydb",
+            },
+        }, indent=2))
+
+        local_cfg = root / "local.json"
+        local_cfg.write_text(json.dumps({"debug": True, "port": 9090}))
+
+        env_file = root / ".env"
+        env_file.write_text("DB_HOST=db.example.com\nAPI_KEY=secret123\n")
+
+        # ------------------------------------------------------------------ #
+        # 2. Basic load
+        # ------------------------------------------------------------------ #
+        section("1. Basic load")
+        cfg = Config.load(base_cfg)
+        print(f"app    : {cfg['app']}")
+        print(f"port   : {cfg['port']}")
+        print(f"repr   : {cfg}")
+
+        # ------------------------------------------------------------------ #
+        # 3. Dot-path access
+        # ------------------------------------------------------------------ #
+        section("2. Dot-path access")
+        print(f"database.host : {cfg['database.host']}")
+        print(f"database.port : {cfg['database.port']}")
+        print(f"get missing   : {cfg.get('missing_key', 'DEFAULT')}")
+
+        # ------------------------------------------------------------------ #
+        # 4. Layered loading with overrides
+        # ------------------------------------------------------------------ #
+        section("3. Layered loading (base + local + .env)")
+        full_cfg = Config.load(base_cfg, overrides=[local_cfg, env_file])
+        print(f"port (overridden)       : {full_cfg['port']}")
+        print(f"debug (overridden)      : {full_cfg['debug']}")
+        print(f"database.host (from env): {full_cfg['database.host']}")
+        print(f"API_KEY (from .env)     : {full_cfg.get('API_KEY', 'NOT FOUND')}")
+        print(f"sources: {full_cfg.info.sources}")
+
+        # ------------------------------------------------------------------ #
+        # 5. Mutation + save
+        # ------------------------------------------------------------------ #
+        section("4. Mutation + save")
+        cfg["port"] = 7070
+        cfg["database.name"] = "newdb"
+        out = root / "updated.json"
+        cfg.save(out)
+        reloaded = Config.load(out)
+        print(f"saved port        : {reloaded['port']}")
+        print(f"saved db name     : {reloaded['database.name']}")
+
+        # ------------------------------------------------------------------ #
+        # 6. Format conversion
+        # ------------------------------------------------------------------ #
+        section("5. Format conversion (JSON → YAML)")
+        try:
+            import yaml  # noqa: F401
+            yaml_out = root / "app.yaml"
+            Config.convert(base_cfg, yaml_out)
+            yaml_cfg = Config.load(yaml_out)
+            print(f"YAML app  : {yaml_cfg['app']}")
+            print(f"YAML port : {yaml_cfg['port']}")
+        except ImportError:
+            print("pyyaml not installed — skipping YAML conversion demo")
+
+        # ------------------------------------------------------------------ #
+        # 7. Validation
+        # ------------------------------------------------------------------ #
+        section("6. Validation")
+        cfg2 = Config.load(base_cfg)
+        try:
+            cfg2.validate(
+                required=["app", "database.host"],
+                schema={"port": int, "app": str},
+            )
+            print("Validation passed ✓")
+        except ValidationError as exc:
+            print(f"Validation failed: {exc}")
+
+        # Trigger a validation failure
+        cfg3 = Config.from_dict({"app": "test"})
+        try:
+            cfg3.validate(required=["missing_required_key"])
+        except ValidationError as exc:
+            print(f"Expected ValidationError caught: {exc}")
+
+        # ------------------------------------------------------------------ #
+        # 8. Info / introspection
+        # ------------------------------------------------------------------ #
+        section("7. Introspection")
+        info = cfg2.info
+        print(f"format  : {info.format}")
+        print(f"sources : {info.sources}")
+        print(f"keys    : {list(cfg2.keys())}")
+        d = cfg2.to_dict()
+        print(f"to_dict type: {type(d).__name__}")
+
+    print("\nAll done!")
+
+
+if __name__ == "__main__":
+    main()

dd_config-0.1.0/cookbook/01_basics/requirements.txt

@@ -0,0 +1 @@
+dd-config[all]