tomlstack 0.1.2__tar.gz → 0.2.0rc1__tar.gz

{tomlstack-0.1.2 → tomlstack-0.2.0rc1}/.gitignore

@@ -135,6 +135,9 @@ venv.bak/
 .dmypy.json
 dmypy.json
 
+# ruff
+.ruff_cache/
+
 # Pyre type checker
 .pyre/
 
@@ -153,7 +156,7 @@ cython_debug/
 
 
 # custom
-
+.codex
 .vscode/*
 # hatch-vcs generated version file
 src/tomlstack/_version.py

{tomlstack-0.1.2 → tomlstack-0.2.0rc1}/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on Keep a Changelog,
 and this project follows Semantic Versioning.
 
+## [0.2.0] - 2026-06-24
+
+### Added
+
+- Include-tree inspection through `cfg.include_tree`.
+- Node provenance and interpolation dependency inspection through `TomlNode`.
+- Specific errors for invalid TOML, undefined interpolation references, and
+  interpolation cycles.
+
+### Changed
+
+- Configuration loading now binds each value to its source history internally,
+  making merge and interpolation provenance consistent.
+- `TomlNode` is the public node-query type; nodes and `TomlStack` instances are
+  created through configuration loading and navigation only.
+
+### Removed
+
+- `TomlStack.view`; use `cfg.raw` for unexpanded data or `cfg.to_dict()` for a
+  resolved snapshot.
+- `TomlStack.to_dict(resolve=False)`; use `cfg.raw`.
+- `TomlHist` and `TomlFile.str_`; history now contains `TomlFile` values with
+  `reference` and resolved `path` fields.
+- Legacy metadata/version directives and their associated error classes.
+
 ## [0.1.2] - 2026-03-01
 
 - first publish version

{tomlstack-0.1.2 → tomlstack-0.2.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tomlstack
-Version: 0.1.2
+Version: 0.2.0rc1
 Summary: TOML configuration loader with include/merge/interpolation
 Project-URL: Homepage, https://github.com/wxzhao7/tomlstack
 Project-URL: Repository, https://github.com/wxzhao7/tomlstack
@@ -39,12 +39,14 @@ Description-Content-Type: text/markdown
 `tomlstack` is a lightweight TOML config loader for Python 3.11+ with:
 
 - top-level `include` loading
+- include-tree inspection with raw and resolved paths
 - deterministic merge by include order
 - `${path}` interpolation with cycle/undefined checks
-- node-level provenance (`origin`, `explain`, `history`)
+- node-level provenance (`origin`, `history`, `dependencies`)
 
 tomlstack does not try to be a configuration framework.
-It address two missing pieces to TOML: file composition and safe interpolation — while keeping files self-contained and explainable.
+It addresses two missing pieces in TOML: file composition and safe interpolation,
+while keeping files self-contained and explainable.
 
 ## Install
 
@@ -79,15 +81,17 @@ port = 5432
 Python:
 
 ```python
-from tomlstack import load
+from tomlstack import TomlNode, load
 
 cfg = load("main.toml")
 print(cfg["db"]["url"].raw)    # raw interpolation string
-cfg.resolve()
 print(cfg["db"]["url"].value)  # resolved value
 print(cfg["db"]["url"].origin)
 print(cfg["db"]["url"].history)
-print(cfg.to_dict())
+print(cfg["db"]["url"].dependencies)
+print(cfg["db"]["url"].explain())
+print(cfg.raw)                   # raw configuration snapshot
+print(cfg.to_dict())             # resolved configuration snapshot
 ```
 
 ## Include Semantics
@@ -95,28 +99,20 @@ print(cfg.to_dict())
 - top-level `include` only; nested `include` is treated as normal data
 - syntax: string or list of strings
 - valid include path forms:
-- `./...` or `../...`
-- `@label/...` (label from `__meta__.include.anchors`)
-- absolute path
-- any other form raises error with hint: `Use ./ or ../ or @label/`
+  - `./...` or `../...`
+  - `@label/...` (label from `tomlstack.anchors`)
+  - absolute path
+- any other form raises an error with a path-format hint
 
 ### Meta Include Directives
 
 ```toml
-[__meta__]
-version = 1
-
-[__meta__.include]
-root = "../.."
-
-[__meta__.include.anchors]
+[tomlstack.anchors]
 proj = "./shared"
 ```
 
-- `__meta__.include.root` is sugar for `anchors.root`
-- if both `root` and `anchors.root` exist and resolve differently, error
-- anchor/root path values must be absolute or start with `./` or `../`
-- if any file explicitly sets `__meta__.version`, all files in include chain must share one supported version (`1`)
+- anchors are local to the file that declares them
+- anchor path values must be absolute or start with `./` or `../`
 
 ## Merge Rules
 
@@ -135,41 +131,62 @@ Conflict behavior:
 
 ## Interpolation Semantics
 
-- interpolation happens on `cfg.resolve()`
+- interpolation is resolved lazily by `cfg.resolve()`, `cfg.to_dict()`, or
+  `node.value`
 - path syntax supports dot and list index: `${db.apps[0]}`
 - full-string interpolation (`"${db.port}"`) keeps source type
 - embedded interpolation (`"postgres://${db.host}:${db.port}"`) allows only:
-- `str`, `int`, `float`, `date`, `time`, `datetime`
+  - `str`, `int`, `float`, `bool`, `date`, `time`, `datetime`
 - formatting syntax: `${path:spec}`
 - for `date/time/datetime`, formatting uses `strftime`
 - otherwise uses Python `format(value, spec)`
-- undefined reference raises `InterpolationUndefinedError`
-- interpolation cycle raises `InterpolationCycleError`
+- invalid interpolation syntax and formatting failures raise `InterpolationError`
+- undefined references raise `InterpolationUndefinedError`
+- interpolation cycles raise `InterpolationCycleError`
+
+Invalid TOML raises `TomlFormatError`; invalid include paths and anchors raise
+`IncludeError`.
 
 ## Public API
 
 - `cfg = load("f.toml")`
+- `cfg.raw` — raw configuration snapshot
 - `cfg.resolve()`
-- `cfg.to_dict()`
-- `node = cfg["proj"][0]["path"]["foo"]`
+- `cfg.to_dict()` — resolved configuration snapshot
+- `cfg.include_tree` — `IncludeNode` load-occurrence tree
+- `cfg.include_tree.render()` — render raw include references
+- `cfg.include_tree.render(absolute=True)` — include references with resolved paths
+- `node: TomlNode = cfg["proj"][0]["path"]["foo"]`
 - `node.raw`
 - `node.value`
 - `node.origin`
 - `node.history`
+- `node.dependencies` — direct interpolation dependencies
+- `node.explain()` — transitive interpolation trace
 - `node.preview()`
 - `cfg.to_toml()` -> `NotImplementedError`
 
+`cfg.raw`, `cfg.to_dict()`, `node.raw`, and `node.value` return independent data
+snapshots; mutating their dictionaries or lists does not modify the loaded
+configuration. `TomlNode` instances are created by configuration navigation and are
+not constructed directly.
+
+History records definitions of the same data path from lowest to highest priority.
+When a list or value type is replaced, its old child paths are discarded. Resolving an
+interpolation does not change the history of the node containing the expression.
+Each history entry is a `TomlFile` with its raw `reference` and resolved absolute
+`path`.
+
+Dependencies describe interpolation separately from merge history. A full replacement
+such as `target = "${source}"` leaves `target.history` at the file that defined
+`target`, while `target.dependencies` records the source path and its history.
+
 ## Current Limitations
 
 - interpolation path parser supports unquoted dot keys and numeric list indices
 - no nested interpolation expressions
 - `to_toml()` is not implemented yet
 
-## TODO
-
-- [ ] review the details of interpolation
-- [ ] explain history with interpolation
-
 ## Release To PyPI
 
 Build package:

tomlstack-0.2.0rc1/README.md

@@ -0,0 +1,178 @@
+# tomlstack
+
+`tomlstack` is a lightweight TOML config loader for Python 3.11+ with:
+
+- top-level `include` loading
+- include-tree inspection with raw and resolved paths
+- deterministic merge by include order
+- `${path}` interpolation with cycle/undefined checks
+- node-level provenance (`origin`, `history`, `dependencies`)
+
+tomlstack does not try to be a configuration framework.
+It addresses two missing pieces in TOML: file composition and safe interpolation,
+while keeping files self-contained and explainable.
+
+## Install
+
+```bash
+pip install tomlstack
+```
+
+## Quick Start
+
+`main.toml`:
+
+```toml
+include = [
+    "./base.toml",
+    "./prod.toml",
+]
+
+[db]
+url = "postgres://${db.user}:${db.pass}@${db.host}:${db.port}"
+```
+
+`base.toml`:
+
+```toml
+[db]
+user = "alice"
+pass = "secret"
+host = "localhost"
+port = 5432
+```
+
+Python:
+
+```python
+from tomlstack import TomlNode, load
+
+cfg = load("main.toml")
+print(cfg["db"]["url"].raw)    # raw interpolation string
+print(cfg["db"]["url"].value)  # resolved value
+print(cfg["db"]["url"].origin)
+print(cfg["db"]["url"].history)
+print(cfg["db"]["url"].dependencies)
+print(cfg["db"]["url"].explain())
+print(cfg.raw)                   # raw configuration snapshot
+print(cfg.to_dict())             # resolved configuration snapshot
+```
+
+## Include Semantics
+
+- top-level `include` only; nested `include` is treated as normal data
+- syntax: string or list of strings
+- valid include path forms:
+  - `./...` or `../...`
+  - `@label/...` (label from `tomlstack.anchors`)
+  - absolute path
+- any other form raises an error with a path-format hint
+
+### Meta Include Directives
+
+```toml
+[tomlstack.anchors]
+proj = "./shared"
+```
+
+- anchors are local to the file that declares them
+- anchor path values must be absolute or start with `./` or `../`
+
+## Merge Rules
+
+Load order for current file:
+
+1. merge first include
+2. merge second include
+3. ...
+4. merge current file (highest priority)
+
+Conflict behavior:
+
+- dict: recursive merge, later wins on key conflict
+- list: later value replaces whole list
+- scalar: later value replaces earlier
+
+## Interpolation Semantics
+
+- interpolation is resolved lazily by `cfg.resolve()`, `cfg.to_dict()`, or
+  `node.value`
+- path syntax supports dot and list index: `${db.apps[0]}`
+- full-string interpolation (`"${db.port}"`) keeps source type
+- embedded interpolation (`"postgres://${db.host}:${db.port}"`) allows only:
+  - `str`, `int`, `float`, `bool`, `date`, `time`, `datetime`
+- formatting syntax: `${path:spec}`
+- for `date/time/datetime`, formatting uses `strftime`
+- otherwise uses Python `format(value, spec)`
+- invalid interpolation syntax and formatting failures raise `InterpolationError`
+- undefined references raise `InterpolationUndefinedError`
+- interpolation cycles raise `InterpolationCycleError`
+
+Invalid TOML raises `TomlFormatError`; invalid include paths and anchors raise
+`IncludeError`.
+
+## Public API
+
+- `cfg = load("f.toml")`
+- `cfg.raw` — raw configuration snapshot
+- `cfg.resolve()`
+- `cfg.to_dict()` — resolved configuration snapshot
+- `cfg.include_tree` — `IncludeNode` load-occurrence tree
+- `cfg.include_tree.render()` — render raw include references
+- `cfg.include_tree.render(absolute=True)` — include references with resolved paths
+- `node: TomlNode = cfg["proj"][0]["path"]["foo"]`
+- `node.raw`
+- `node.value`
+- `node.origin`
+- `node.history`
+- `node.dependencies` — direct interpolation dependencies
+- `node.explain()` — transitive interpolation trace
+- `node.preview()`
+- `cfg.to_toml()` -> `NotImplementedError`
+
+`cfg.raw`, `cfg.to_dict()`, `node.raw`, and `node.value` return independent data
+snapshots; mutating their dictionaries or lists does not modify the loaded
+configuration. `TomlNode` instances are created by configuration navigation and are
+not constructed directly.
+
+History records definitions of the same data path from lowest to highest priority.
+When a list or value type is replaced, its old child paths are discarded. Resolving an
+interpolation does not change the history of the node containing the expression.
+Each history entry is a `TomlFile` with its raw `reference` and resolved absolute
+`path`.
+
+Dependencies describe interpolation separately from merge history. A full replacement
+such as `target = "${source}"` leaves `target.history` at the file that defined
+`target`, while `target.dependencies` records the source path and its history.
+
+## Current Limitations
+
+- interpolation path parser supports unquoted dot keys and numeric list indices
+- no nested interpolation expressions
+- `to_toml()` is not implemented yet
+
+## Release To PyPI
+
+Build package:
+
+```bash
+uv run --with build python -m build
+```
+
+Upload to TestPyPI first:
+
+```bash
+uv run --with twine python -m twine upload --repository testpypi dist/*
+```
+
+Verify install from TestPyPI:
+
+```bash
+python -m pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple tomlstack
+```
+
+Upload to PyPI:
+
+```bash
+uv run --with twine python -m twine upload dist/*
+```

tomlstack-0.2.0rc1/src/tomlstack/__init__.py

@@ -0,0 +1,13 @@
+from .api import TomlStack, load
+from .nodes import TomlNode
+from .types import IncludeNode, InterpolationDependency, ResolutionTrace, TraceNode
+
+__all__ = [
+    "IncludeNode",
+    "InterpolationDependency",
+    "ResolutionTrace",
+    "TomlStack",
+    "TomlNode",
+    "TraceNode",
+    "load",
+]

tomlstack-0.2.0rc1/src/tomlstack/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0rc1'
+__version_tuple__ = version_tuple = (0, 2, 0, 'rc1')
+
+__commit_id__ = commit_id = None

tomlstack-0.2.0rc1/src/tomlstack/api.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+from os import PathLike
+from typing import Any
+
+from .interpolate import _ResolutionResult, _resolve_interpolations
+from .loader import _load_toml_with_includes, _LoadedToml
+from .nodes import TomlNode
+from .path_expr import get_by_path
+from .trace import _build_resolution_trace
+from .tree import _DataNode
+from .types import (
+    DataPath,
+    IncludeNode,
+    InterpolationDependency,
+    ResolutionTrace,
+    TomlFile,
+)
+
+
+@dataclass(init=False)
+class TomlStack:
+    _root: _DataNode
+    _include_tree: IncludeNode
+    _resolution: _ResolutionResult | None = field(
+        init=False, default=None, repr=False, compare=False, hash=False
+    )
+
+    def __init__(self, *_: object, **__: object) -> None:
+        raise TypeError("TomlStack instances are created by load()")
+
+    @classmethod
+    def _from_loaded(cls, loaded: _LoadedToml) -> TomlStack:
+        stack = object.__new__(cls)
+        stack._root = loaded.root
+        stack._include_tree = loaded.include_tree
+        stack._resolution = None
+        return stack
+
+    @property
+    def raw(self) -> Any:
+        return deepcopy(self._root.materialized)
+
+    def resolve(self) -> TomlStack:
+        if self._resolution is None:
+            self._resolution = _resolve_interpolations(self._root)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        self.resolve()
+        assert self._resolution is not None
+        return deepcopy(self._resolution.data)
+
+    def to_toml(self) -> str:
+        raise NotImplementedError("to_toml is reserved for future implementation")
+
+    def __getitem__(self, key: str) -> TomlNode:
+        if not isinstance(self._root.value, dict) or key not in self._root.value:
+            raise KeyError(key)
+        return TomlNode._from_path(self, (key,))
+
+    def _get_raw(self, path: DataPath) -> Any:
+        return deepcopy(self._root._get_subnode(path).materialized)
+
+    def _get_history(self, path: DataPath) -> tuple[TomlFile, ...]:
+        return self._root._get_subnode(path).history
+
+    def _get_value(self, path: DataPath) -> Any:
+        self.resolve()
+        assert self._resolution is not None
+        return deepcopy(get_by_path(self._resolution.data, path))
+
+    def _get_dependencies(self, path: DataPath) -> tuple[InterpolationDependency, ...]:
+        self.resolve()
+        assert self._resolution is not None
+        return self._resolution.direct_dependencies.get(path, ())
+
+    def _get_trace(self, path: DataPath) -> ResolutionTrace:
+        self.resolve()
+        assert self._resolution is not None
+        return _build_resolution_trace(
+            self._root,
+            path,
+            self._resolution.direct_dependencies,
+        )
+
+    @property
+    def include_tree(self) -> IncludeNode:
+        return self._include_tree
+
+
+def load(path: str | PathLike[str]) -> TomlStack:
+    return TomlStack._from_loaded(_load_toml_with_includes(path))

tomlstack-0.2.0rc1/src/tomlstack/errors.py

@@ -0,0 +1,34 @@
+class TomlStackError(Exception):
+    """Base error for tomlstack."""
+
+
+class DataPathError(TomlStackError):
+    """Raised when path parsing or resolution fails."""
+
+
+class ContentError(TomlStackError):
+    """Raised when content validation fails."""
+
+
+class IncludeError(TomlStackError):
+    """Raised when include resolution fails."""
+
+
+class TomlFormatError(TomlStackError):
+    """Raised when TOML parsing fails."""
+
+
+class IncludeCycleError(IncludeError):
+    """Raised when include cycle is detected."""
+
+
+class InterpolationError(TomlStackError):
+    """Raised when interpolation fails."""
+
+
+class InterpolationUndefinedError(InterpolationError):
+    """Raised when interpolation path is undefined."""
+
+
+class InterpolationCycleError(InterpolationError):
+    """Raised when interpolation cycle is detected."""

tomlstack-0.2.0rc1/src/tomlstack/include.py

@@ -0,0 +1,66 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Self
+
+from .errors import IncludeError
+from .types import TomlFile
+
+
+@dataclass
+class _IncludeResolver:
+    including_file: TomlFile
+    anchor_roots: dict[str, Path]
+
+    @staticmethod
+    def _is_relative(path: str) -> bool:
+        return path.startswith("./") or path.startswith("../")
+
+    @staticmethod
+    def _is_absolute(path: str) -> bool:
+        return Path(path).is_absolute()
+
+    @staticmethod
+    def _is_anchor_path(path: str) -> bool:
+        if not path.startswith("@"):
+            return False
+        label, sep, value = path[1:].partition("/")
+        return bool(label and sep and value)
+
+    @classmethod
+    def resolve_anchor_path(cls, base_dir: Path, anchor_path: str) -> Path:
+        if cls._is_absolute(anchor_path):
+            return Path(anchor_path).resolve()
+        if cls._is_relative(anchor_path):
+            return (base_dir / anchor_path).resolve()
+        raise IncludeError(
+            f"Invalid anchor path: {anchor_path}. "
+            "Anchor values must be absolute or start with ./ or ../"
+        )
+
+    def resolve_include_path(self, include_path: str) -> Path:
+        if self._is_absolute(include_path):
+            return Path(include_path).resolve()
+
+        if self._is_relative(include_path):
+            return (self.including_file.path.parent / include_path).resolve()
+
+        if self._is_anchor_path(include_path):
+            label, _, rest = include_path[1:].partition("/")
+            if label not in self.anchor_roots:
+                raise IncludeError(f"Undefined include anchor: {label}")
+            return (self.anchor_roots[label] / rest).resolve()
+
+        raise IncludeError(
+            f"Invalid include path format: {include_path}. "
+            "Use ./ or ../ or @label/ or absolute path."
+        )
+
+    @classmethod
+    def from_toml(cls, file: TomlFile, raw_anchors: dict[str, str]) -> Self:
+        anchor_roots: dict[str, Path] = {}
+        base_dir = file.path.parent
+
+        for label, raw_value in raw_anchors.items():
+            anchor_roots[label] = cls.resolve_anchor_path(base_dir, raw_value)
+
+        return cls(including_file=file, anchor_roots=anchor_roots)