ghostconfig 0.1.0__py3-none-any.whl

ghostconfig/__init__.py

@@ -0,0 +1,3 @@
+from ghostconfig.ghost_config import GhostConfig, MissingConfigError
+
+__all__ = ["GhostConfig", "MissingConfigError"]

ghostconfig/ghost_config.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any
+
+from omegaconf import DictConfig, ListConfig, OmegaConf
+
+from . import suggestions as suggestions_module
+from . import tracker as tracker_module
+
+_SENTINEL = object()
+_GHOST_LIST_LENGTH = 2
+
+
+class MissingConfigError(Exception):
+    pass
+
+
+class GhostConfig:
+    def __init__(
+        self,
+        source: dict | pathlib.Path | str | Any,
+        *,
+        _tracker: tracker_module.AccessTracker | None = None,
+        _prefix: str = "",
+        _is_ghost: bool = False,
+    ) -> None:
+        if _tracker is not None:
+            self._data = source
+            self._tracker = _tracker
+            self._prefix = _prefix
+            self._is_ghost = _is_ghost
+            return
+
+        self._is_ghost = False
+        self._prefix = ""
+
+        if isinstance(source, (str, pathlib.Path)):
+            path = pathlib.Path(source)
+            if path.suffix in (".yaml", ".yml"):
+                self._data = OmegaConf.load(path)
+                self._tracker = tracker_module.AccessTracker(source_format="yaml", source_path=path)
+            elif path.suffix == ".json":
+                with path.open() as file:
+                    data = json.load(file)
+                self._data = OmegaConf.create(data)
+                self._tracker = tracker_module.AccessTracker(source_format="json", source_path=path)
+            else:
+                raise ValueError(
+                    f"Unsupported file extension: {path.suffix!r}. Use .yaml, .yml, or .json."
+                )
+        elif isinstance(source, dict):
+            self._data = OmegaConf.create(source)
+            self._tracker = tracker_module.AccessTracker(source_format="dict")
+        else:
+            raise TypeError(f"Expected a dict or file path, got {type(source).__name__!r}.")
+
+    def get(self, key: str | int, default: Any = _SENTINEL) -> Any:
+        full_key = f"{self._prefix}.{key}" if self._prefix else str(key)
+
+        if self._is_ghost:
+            if default is _SENTINEL:
+                return GhostConfig(
+                    None, _tracker=self._tracker, _prefix=full_key, _is_ghost=True
+                )
+            self._tracker.record_missing(full_key, default)
+            return default
+
+        found, value = self._lookup(key)
+
+        if not found:
+            if default is _SENTINEL:
+                return GhostConfig(
+                    None, _tracker=self._tracker, _prefix=full_key, _is_ghost=True
+                )
+            self._tracker.record_missing(full_key, default)
+            return default
+
+        if isinstance(value, DictConfig):
+            if default is not _SENTINEL:
+                raise TypeError(
+                    f"Key {key!r} holds a nested config, but a default was provided. "
+                    "Call get(key) without a default to navigate into a sub-config."
+                )
+            return GhostConfig(
+                value, _tracker=self._tracker, _prefix=full_key, _is_ghost=False
+            )
+
+        if isinstance(value, ListConfig):
+            if default is not _SENTINEL:
+                return OmegaConf.to_container(value, resolve=True)
+            return GhostConfig(
+                value, _tracker=self._tracker, _prefix=full_key, _is_ghost=False
+            )
+
+        return value
+
+    def check(self) -> None:
+        if not self._tracker.missing:
+            return
+        suggestion = suggestions_module.format_suggestion(
+            self._tracker.missing,
+            self._tracker.source_format,
+        )
+        source_description = self._tracker.source_format
+        if self._tracker.source_path is not None:
+            source_description += f" ({self._tracker.source_path})"
+        missing_paths = "\n".join(f"  {key}: {value!r}" for key, value in self._tracker.missing.items())
+        raise MissingConfigError(
+            f"The following parameters were used but missing from the config.\n"
+            f"Missing keys:\n{missing_paths}\n\n"
+            f"Since this started from a {source_description}, you should add:\n\n"
+            f"{suggestion}"
+        )
+
+    def __iter__(self):  # type: ignore[override]
+        if self._is_ghost:
+            for index in range(_GHOST_LIST_LENGTH):
+                full_key = f"{self._prefix}.{index}" if self._prefix else str(index)
+                yield GhostConfig(
+                    None, _tracker=self._tracker, _prefix=full_key, _is_ghost=True
+                )
+            return
+
+        if isinstance(self._data, ListConfig):
+            for index, item in enumerate(self._data):
+                full_key = f"{self._prefix}.{index}" if self._prefix else str(index)
+                if isinstance(item, (DictConfig, ListConfig)):
+                    yield GhostConfig(
+                        item, _tracker=self._tracker, _prefix=full_key, _is_ghost=False
+                    )
+                else:
+                    yield item
+            return
+
+        raise TypeError(
+            f"Cannot iterate over a non-list config at key {self._prefix!r}. "
+            "Use get(key) without a default to navigate into a sub-config."
+        )
+
+    def _lookup(self, key: str | int) -> tuple[bool, Any]:
+        if isinstance(self._data, DictConfig) and isinstance(key, str):
+            try:
+                value = self._data[key]
+                return True, value
+            except (KeyError, Exception):
+                return False, None
+
+        if isinstance(self._data, ListConfig) and isinstance(key, int):
+            if 0 <= key < len(self._data):
+                return True, self._data[key]
+            return False, None
+
+        return False, None

ghostconfig/suggestions.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import json
+import pprint
+from typing import Any, Literal, cast
+
+import yaml
+
+
+def build_nested(missing: dict[str, Any]) -> Any:
+    """Explode dotted-path keys back into a nested dict.
+
+    Path segments that are consecutive integers starting from 0 are converted
+    to lists so the YAML/JSON suggestion uses proper list syntax.
+    """
+    nested: dict[str, Any] = {}
+    for dotted_path, default_value in missing.items():
+        parts = dotted_path.split(".")
+        node = nested
+        for part in parts[:-1]:
+            if part not in node or not isinstance(node[part], dict):
+                node[part] = {}
+            node = node[part]
+        node[parts[-1]] = default_value
+    return _convert_integer_keys_to_lists(nested)
+
+
+def _convert_integer_keys_to_lists(node: Any) -> Any:
+    """Recursively replace dicts whose keys are consecutive ints (0, 1, …) with lists."""
+    if not isinstance(node, dict):
+        return node
+    converted = {key: _convert_integer_keys_to_lists(value) for key, value in node.items()}
+    try:
+        integer_keys = sorted(int(key) for key in converted)
+        if integer_keys == list(range(len(integer_keys))):
+            return [converted[str(i)] for i in integer_keys]
+    except ValueError:
+        pass
+    return converted
+
+
+def format_suggestion(
+    missing: dict[str, Any],
+    source_format: Literal["yaml", "json", "dict"],
+) -> str:
+    nested = build_nested(missing)
+    if source_format == "yaml":
+        return cast(str, yaml.safe_dump(nested, sort_keys=False, default_flow_style=False))
+    if source_format == "json":
+        return json.dumps(nested, indent=2)
+    return pprint.pformat(nested, sort_dicts=False)

ghostconfig/tracker.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import pathlib
+from typing import Any, Literal
+
+
+class AccessTracker:
+    """Tracks leaf accesses that could not be satisfied from the backing config data."""
+
+    def __init__(
+        self,
+        source_format: Literal["yaml", "json", "dict"] = "dict",
+        source_path: pathlib.Path | str | None = None,
+    ) -> None:
+        self.source_format = source_format
+        self.source_path = pathlib.Path(source_path) if source_path is not None else None
+        self.missing: dict[str, Any] = {}
+
+    def record_missing(self, dotted_path: str, default: Any) -> None:
+        """Record a missing key. First write wins (repeated access keeps first default)."""
+        if dotted_path not in self.missing:
+            self.missing[dotted_path] = default

ghostconfig-0.1.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: ghostconfig
+Version: 0.1.0
+Summary: A config system that is lazily validated as parameters are used
+Project-URL: Homepage, https://github.com/ChainBreak/ghostconfig
+License: MIT License
+        
+        Copyright (c) 2026 Thomas Rowntree
+        
+        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
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: omegaconf
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ghostconfig
+
+A config system that is lazily validated as parameters are used.
+
+## Installation
+
+```bash
+pip install ghostconfig
+```
+
+## Usage
+
+### Creating a config
+
+```python
+import ghostconfig
+
+# From a YAML file (OmegaConf interpolations supported)
+config = ghostconfig.GhostConfig("path/to/config.yaml")
+
+# From a JSON file
+config = ghostconfig.GhostConfig("path/to/config.json")
+
+# From a plain Python dict
+config = ghostconfig.GhostConfig({"num_epochs": 10, "learning_rate": 0.001})
+```
+
+### Reading values
+
+`get(key)` with no default returns a `GhostConfig` sub-config (real or ghost).
+`get(key, default)` returns the leaf value (type inferred from the default).
+
+```python
+# Given config.yaml:
+# model:
+#   layers: 4
+#   block: resnet
+# dataset:
+#   path: my/data/
+#   augmentations: [crop]
+
+model_config = config.get("model")    # GhostConfig
+layers = model_config.get("layers", 1)  # 4
+
+# Accessing a key that doesn't exist in the YAML is fine at this point —
+# a "ghost" GhostConfig is returned and the access is recorded.
+training_config = config.get("training")
+learning_rate = training_config.get("learning_rate", 0.001)  # returns 0.001
+```
+
+### Validating at setup time
+
+Call `check()` once all parameters have been read. It raises `MissingConfigError`
+with a suggestion showing exactly what to add to your config file.
+
+```python
+config.check()
+# MissingConfigError:
+# The following parameters were used but missing from the config.
+# Since this started from a yaml (path/to/config.yaml), you should add:
+#
+# training:
+#   learning_rate: 0.001
+```
+
+If multiple keys are missing they are merged into a single suggestion block.
+The format matches the source: YAML for `.yaml` files, JSON for `.json` files,
+and a Python dict literal for dict-based configs.
+
+## Development
+
+### Setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+Or install with test dependencies:
+
+```bash
+pip install pytest
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+To run with verbose output:
+
+```bash
+pytest -v
+```
+
+## Building and Publishing to PyPI
+
+### Prerequisites
+
+```bash
+pip install build twine
+```
+
+### Build the distribution
+
+```bash
+python -m build
+```
+
+This creates a `dist/` directory containing a `.whl` and `.tar.gz` file.
+
+### Upload to PyPI
+
+First, upload to [TestPyPI](https://test.pypi.org/) to verify everything looks correct:
+
+```bash
+twine upload --repository testpypi dist/*
+```
+
+When ready, upload to the real PyPI:
+
+```bash
+twine upload dist/*
+```
+
+You will be prompted for your PyPI credentials. It is recommended to use an [API token](https://pypi.org/manage/account/token/) instead of your password.
+
+To avoid entering credentials each time, create a `~/.pypirc` file:
+
+```ini
+[pypi]
+  username = __token__
+  password = pypi-your-api-token-here
+```

ghostconfig-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ghostconfig/__init__.py,sha256=HAr141EZVz0U4Ol_KyzTqy0SvwvmyCn6tfb38wOAJ00,118
+ghostconfig/ghost_config.py,sha256=UdwlE9mFRo-mkYX6m0LO82w8irP2zmpm3ad-8TZ-JRY,5682
+ghostconfig/suggestions.py,sha256=FpyJ6GZKT-wqh25PX509jDyI7rvPIgMg90B2gdx4pzo,1721
+ghostconfig/tracker.py,sha256=kXdskexhXscV9mBpUhOU37TE_GyxIn5hkgGjx7xIJeM,793
+ghostconfig-0.1.0.dist-info/METADATA,sha256=wVAsizDX0OC4_Ujfxb3gv_dUsI3LkiIg2L-Q07zZDOo,4599
+ghostconfig-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ghostconfig-0.1.0.dist-info/licenses/LICENSE,sha256=_9m5tH_fHIphCPTVjZ2KgcjC7I3HbxroRNAsnBcJPu8,1072
+ghostconfig-0.1.0.dist-info/RECORD,,

ghostconfig-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ghostconfig-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Rowntree
+
+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.