tomlstack 0.1.2__py3-none-any.whl

tomlstack/__init__.py

@@ -0,0 +1,3 @@
+from .api import TomlStack, load
+
+__all__ = ["TomlStack", "load"]

tomlstack/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.2'
+__version_tuple__ = version_tuple = (0, 1, 2)
+
+__commit_id__ = commit_id = None

tomlstack/api.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .base import PathHist, PathKey
+from .interpolate import resolve_interpolations
+from .loader import LoadResult, load_toml_with_includes
+from .nodes import Node
+from .path_expr import get_by_path
+
+
+@dataclass
+class TomlStack:
+    _raw_data: dict[str, Any]
+    _resolved_data: dict[str, Any] | None
+    _history: dict[PathKey, list[PathHist]]
+
+    # TODO: OK?
+    @property
+    def view(self) -> dict[str, Any]:
+        if self._resolved_data is None:
+            return self._raw_data
+        else:
+            return self._resolved_data
+
+    def resolve(self) -> TomlStack:
+        if self._resolved_data is None:
+            self._resolved_data = resolve_interpolations(self._raw_data)
+        return self
+
+    def to_dict(self, resolve: bool = True) -> dict[str, Any]:
+        if resolve:
+            if self._resolved_data is None:
+                self.resolve()
+            assert self._resolved_data is not None
+            return self._resolved_data
+        return self._raw_data
+
+    def to_toml(self) -> str:
+        raise NotImplementedError("to_toml is reserved for future implementation")
+
+    def __getitem__(self, key: str) -> Node:
+        if key not in self._raw_data:
+            raise KeyError(key)
+        return Node(self, (key,))
+
+    def _get_raw(self, path: PathKey) -> Any:
+        return get_by_path(self._raw_data, path)
+
+    def _get_value(self, path: PathKey) -> Any:
+        if self._resolved_data is None:
+            self.resolve()
+        assert self._resolved_data is not None
+        return get_by_path(self._resolved_data, path)
+
+    def include_tree(self, level: int = 0, absolute: bool = False): ...
+
+    # history[()]可以记录整个文件的层级, 可以导出文件层级, 形如
+    #
+    # main.toml
+    # ├─ ./a.toml
+    # │  └─ @root/base.toml
+    # ├─ /abs/path/c.toml
+    # │  └─ @root/base.toml
+    # └─ ./b.toml
+    #    └─ @root/base.toml
+    #
+    # main.toml -> /abs/project/main.toml
+    # ├─ ./a.toml  -> /abs/path/a.toml
+    # │  └─ @root/base.toml -> /abs/shared/base.toml
+    # └─ ./b.toml  -> /abs/path/b.toml
+    #    └─ @root/base.toml -> /abs/shared/base.toml
+
+
+def load(path: str | Path) -> TomlStack:
+    result: LoadResult = load_toml_with_includes(Path(path))
+    return TomlStack(
+        _raw_data=result.data, _resolved_data=None, _history=result.history
+    )

tomlstack/base.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+PathKey = tuple[str | int, ...]
+
+UNDECLARED_VERSION = 0
+SUPPORTED_VERSIONS = {1}
+
+
+@dataclass(frozen=True, slots=True)
+class PathRec:
+    raw: str  # original path
+    path: Path  # resolved absolute path
+
+
+@dataclass(frozen=True, slots=True)
+class PathHist:
+    raw: str
+    path: Path
+    depth: int
+
+
+@dataclass(frozen=True, slots=True)
+class RawToml:
+    path: Path
+    meta: dict[str, Any]
+    body: dict[str, Any]
+    includes: list[str]

tomlstack/errors.py

@@ -0,0 +1,46 @@
+class TomlConfError(Exception):
+    """Base error for tomlconf."""
+
+
+class ContentError(TomlConfError):
+    """Raised when content validation fails."""
+
+
+class MetaError(TomlConfError):
+    """Base error for meta errors."""
+
+
+class IncludeError(TomlConfError):
+    """Raised when include resolution fails."""
+
+
+class TomlFormatError(TomlConfError):
+    """Raised when TOML parsing fails."""
+
+
+class VersionError(MetaError):
+    """Raised when version requirement is not met."""
+
+
+class IncludeInvalidError(IncludeError):
+    """Raised when include specification is invalid."""
+
+
+class IncludeCycleError(IncludeError):
+    """Raised when include cycle is detected."""
+
+
+class MergeError(TomlConfError):
+    """Raised when merge process fails."""
+
+
+class InterpolationError(TomlConfError):
+    """Raised when interpolation fails."""
+
+
+class InterpolationUndefinedError(InterpolationError):
+    """Raised when interpolation path is undefined."""
+
+
+class InterpolationCycleError(InterpolationError):
+    """Raised when interpolation cycle is detected."""

tomlstack/include.py

@@ -0,0 +1,121 @@
+"""
+
+```toml
+__meta__.include.root = "./parent"
+# __meta__.include.anchors.root = "./parent
+__meta__.include.anchors.project = "/abs/path/project"
+
+include = [
+    "./relative.toml",
+    "../relative.toml",
+    "/abs/path/absolute.toml",
+    "@root/anchor.toml",
+    "@project/anchor.toml",
+]
+```
+
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Self
+
+from .base import PathRec, RawToml
+from .errors import IncludeError
+
+
+@dataclass
+class IncludeSpec:
+    ref: Path  # parent dir of current.toml
+    anchors: dict[str, PathRec] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.ref.is_absolute():
+            raise ValueError(f"IncludeSpec.ref must be absolute path, got: {self.ref}")
+
+    @staticmethod
+    def _include_relative(path: str) -> bool:
+        return path.startswith("./") or path.startswith("../")
+
+    @staticmethod
+    def _include_absolute(path: str) -> bool:
+        return Path(path).is_absolute()
+
+    @staticmethod
+    def _include_anchor(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, ref: Path, anchor_path: str) -> Path:
+        if cls._include_relative(anchor_path):
+            return (ref / anchor_path).resolve()
+        if cls._include_absolute(anchor_path):
+            return Path(anchor_path).resolve()
+        raise ValueError(
+            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._include_relative(include_path):
+            return (self.ref / include_path).resolve()
+
+        if self._include_absolute(include_path):
+            return Path(include_path).resolve()
+
+        if self._include_anchor(include_path):
+            label, _, rest = include_path[1:].partition("/")
+            if label not in self.anchors:
+                raise IncludeError(f"Undefined include anchor: {label}")
+            return (self.anchors[label].path / rest).resolve()
+
+        raise IncludeError(
+            f"Invalid include path format: {include_path}. "
+            "Use ./ or ../ or @label/ or absolute path."
+        )
+
+    @classmethod
+    def from_toml(cls, toml: RawToml) -> Self:
+        ref: Path = toml.path.parent
+
+        include = toml.meta.get("include")
+        if include is None:
+            return cls(ref=ref)
+        if not isinstance(include, dict):
+            raise IncludeError("Invalid __meta__.include table")
+
+        anchors_raw = include.get("anchors")
+        if anchors_raw is None:
+            anchors_raw = {}
+        if not isinstance(anchors_raw, dict):
+            raise IncludeError("Invalid __meta__.include.anchors table")
+
+        anchors: dict[str, PathRec] = {}
+        for label, raw_value in anchors_raw.items():
+            if not isinstance(label, str) or not isinstance(raw_value, str):
+                raise IncludeError("Anchor labels and values must be strings")
+            anchors[label] = PathRec(
+                raw=raw_value, path=cls.resolve_anchor_path(ref, raw_value)
+            )
+
+        # magic root anchor
+        if "root" in include:
+            root_value = include["root"]
+            if not isinstance(root_value, str):
+                raise IncludeError("Invalid __meta__.include.root")
+
+            if "root" not in anchors:
+                anchors["root"] = PathRec(
+                    raw=root_value, path=cls.resolve_anchor_path(ref, root_value)
+                )
+            else:
+                if anchors["root"].raw != root_value:
+                    raise IncludeError(
+                        "Conflict between __meta__.include.root and "
+                        "__meta__.include.anchors.root"
+                    )
+
+        return cls(ref=ref, anchors=anchors)

tomlstack/interpolate.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import date, datetime, time
+from typing import Any
+
+from .errors import (
+    InterpolationCycleError,
+    InterpolationError,
+    InterpolationUndefinedError,
+)
+from .loader import PathKey
+from .path_expr import get_by_path, parse_path_expr, path_to_str
+
+EXPR_RE = re.compile(r"\$\{([^{}]+)\}")
+ALLOWED_EMBED_TYPES = (str, int, float, date, time, datetime)
+
+
+@dataclass
+class _State:
+    raw: dict[str, Any]
+    cache: dict[PathKey, Any]
+    stack: list[PathKey]
+
+
+def resolve_interpolations(raw_data: dict[str, Any]) -> dict[str, Any]:
+    state = _State(raw=raw_data, cache={}, stack=[])
+    return _resolve_value(raw_data, (), state)
+
+
+def _resolve_path(path: PathKey, state: _State) -> Any:
+    if path in state.cache:
+        return state.cache[path]
+    if path in state.stack:
+        chain = " -> ".join(path_to_str(p) for p in [*state.stack, path])
+        raise InterpolationCycleError(f"Interpolation cycle detected: {chain}")
+
+    state.stack.append(path)
+    try:
+        raw_value = get_by_path(state.raw, path)
+        resolved = _resolve_value(raw_value, path, state)
+        state.cache[path] = resolved
+        return resolved
+    finally:
+        state.stack.pop()
+
+
+def _resolve_value(value: Any, path: PathKey, state: _State) -> Any:
+    if isinstance(value, dict):
+        return {k: _resolve_value(v, (*path, k), state) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_resolve_value(v, (*path, i), state) for i, v in enumerate(value)]
+    if isinstance(value, str):
+        return _resolve_string(value, path, state)
+    return value
+
+
+def _resolve_string(value: str, path: PathKey, state: _State) -> Any:
+    matches = list(EXPR_RE.finditer(value))
+    if not matches:
+        return value
+
+    if len(matches) == 1 and matches[0].span() == (0, len(value)):
+        expr = matches[0].group(1)
+        ref_path, fmt_spec = _parse_expr(expr, path)
+        ref_value = _resolve_reference(ref_path, expr, path, state)
+        if fmt_spec is None:
+            return ref_value
+        return _format_value(ref_value, fmt_spec)
+
+    parts: list[str] = []
+    last = 0
+    for match in matches:
+        start, end = match.span()
+        parts.append(value[last:start])
+
+        expr = match.group(1)
+        ref_path, fmt_spec = _parse_expr(expr, path)
+        ref_value = _resolve_reference(ref_path, expr, path, state)
+        if not isinstance(ref_value, ALLOWED_EMBED_TYPES):
+            raise InterpolationError(
+                f"Embedded interpolation in {path_to_str(path)} "
+                "only supports str/int/float/date/time/datetime, "
+                f"got {type(ref_value).__name__}"
+            )
+        if fmt_spec is None:
+            parts.append(str(ref_value))
+        else:
+            parts.append(_format_value(ref_value, fmt_spec))
+        last = end
+
+    parts.append(value[last:])
+    return "".join(parts)
+
+
+def _parse_expr(expr: str, path: PathKey) -> tuple[PathKey, str | None]:
+    ref, sep, fmt_spec = expr.partition(":")
+    ref = ref.strip()
+    fmt_spec_opt = fmt_spec if sep else None
+    try:
+        ref_path = parse_path_expr(ref)
+    except ValueError as exc:
+        raise InterpolationError(
+            f"Invalid interpolation expression '{expr}' at {path_to_str(path)}: {exc}"
+        ) from exc
+    return ref_path, fmt_spec_opt
+
+
+def _resolve_reference(
+    ref_path: PathKey, expr: str, cur_path: PathKey, state: _State
+) -> Any:
+    try:
+        return _resolve_path(ref_path, state)
+    except KeyError as exc:
+        raise InterpolationUndefinedError(
+            f"Undefined interpolation '{expr}' at {path_to_str(cur_path)}"
+        ) from exc
+
+
+def _format_value(value: Any, fmt_spec: str) -> str:
+    if isinstance(value, (date, time, datetime)):
+        return value.strftime(fmt_spec)
+    return format(value, fmt_spec)

tomlstack/loader.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import tomllib
+from contextlib import contextmanager
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .base import (
+    SUPPORTED_VERSIONS,
+    UNDECLARED_VERSION,
+    PathHist,
+    PathKey,
+    PathRec,
+    RawToml,
+)
+from .errors import ContentError, IncludeCycleError, VersionError
+from .include import IncludeSpec
+
+INTERNAL_FIELDS = {"include", "__meta__"}
+ROOT_HISTORY_KEY: PathKey = ()
+
+
+@dataclass
+class LoadResult:
+    data: dict[str, Any]
+    history: dict[PathKey, list[PathHist]]
+
+
+@dataclass
+class _LoadContext:
+    file_stack: list[PathRec] = field(default_factory=list)
+    # current include stack for cycle detection
+    file_versions: dict[Path, int] = field(default_factory=dict)
+    # mapping of file paths to their declared or inferred version
+
+    @property
+    def depth(self) -> int:
+        return len(self.file_stack)
+
+    def _render_include_chain(self) -> str:
+        return "\n".join(f"\t{f.raw} -> {f.path}" for f in self.file_stack)
+
+    @contextmanager
+    def enter_file(self, entry: PathRec):
+        toml = parse_raw_file(entry.path)
+
+        self._validate_cycle_include(entry)
+        try:
+            version = self._get_version(toml.meta)
+            self._validate_version(version)
+        except VersionError as e:
+            raise VersionError(
+                f"Version conflict when including {entry.raw!r} "
+                f"resolved as {entry.path}\n"
+                "Current include chain:\n" + self._render_include_chain()
+            ) from e
+
+        self.file_stack.append(entry)
+        self.file_versions[entry.path] = version
+        try:
+            yield toml
+        finally:
+            self.file_stack.pop()
+
+    @classmethod
+    def _get_version(cls, meta: dict[str, Any]) -> int:
+        v = meta.get("version")
+        if v is None:
+            return UNDECLARED_VERSION
+        if not isinstance(v, int):
+            raise VersionError(f"Invalid type __meta__.version {v!r}")
+        if v not in SUPPORTED_VERSIONS:
+            raise VersionError(f"Unsupported __meta__.version {v!r}")
+        return v
+
+    def _validate_version(self, version: int) -> None:
+        if version == UNDECLARED_VERSION:
+            return
+        declared_version = set(self.file_versions.values())
+        declared_version.discard(UNDECLARED_VERSION)
+        declared_version.add(version)
+
+        if len(declared_version) > 1:
+            raise VersionError(
+                f"Conflicting __meta__.version value {version} "
+                f"with declared {declared_version!r}"
+            )
+
+    def _validate_cycle_include(self, entry: PathRec) -> None:
+
+        def render_cycle_include() -> str:
+            root = self.file_stack[0]
+            msg = f"Include cycle detected when load {root.raw!r}\n"
+            for f in self.file_stack + [entry]:
+                if f.path == entry.path:
+                    msg += f"\t=> {f.raw} -> {f.path}\n"
+                else:
+                    msg += f"\t   {f.raw} -> {f.path}\n"
+            return msg
+
+        for file in self.file_stack:
+            if file.path == entry.path:
+                raise IncludeCycleError(render_cycle_include())
+
+
+def load_toml_with_includes(root_file: Path) -> LoadResult:
+    abs_path = root_file.expanduser().resolve()
+    result = _load_file(PathRec(raw=str(root_file), path=abs_path), _LoadContext())
+    return result
+
+
+def _load_file(entry: PathRec, ctx: _LoadContext) -> LoadResult:
+
+    with ctx.enter_file(entry) as toml:
+        current_data = toml.body
+        current_history = record_history(
+            toml.body, PathHist(raw=entry.raw, path=entry.path, depth=ctx.depth)
+        )
+        include_spec = IncludeSpec.from_toml(toml)
+        if toml.includes:
+            merged_data: dict[str, Any] = {}
+            merged_history: dict[PathKey, list[PathHist]] = {}
+            for raw_path in toml.includes:
+                abs_path = include_spec.resolve_include_path(raw_path)
+                included = _load_file(PathRec(raw=raw_path, path=abs_path), ctx)
+                merged_data = merge_data(merged_data, included.data)
+                merged_history = merge_history(merged_history, included.history)
+            merged_data = merge_data(merged_data, current_data)
+            merged_history = merge_history(merged_history, current_history)
+            return LoadResult(data=merged_data, history=merged_history)
+        else:
+            return LoadResult(data=current_data, history=current_history)
+
+
+def record_history(data: Any, hist: PathHist):
+    history: dict[PathKey, list[PathHist]] = {}
+
+    def walk(value: Any, path: PathKey) -> None:
+        history.setdefault(path, []).append(hist)
+        if isinstance(value, dict):
+            for key, child in value.items():
+                walk(child, (*path, key))
+        elif isinstance(value, list):
+            for idx, child in enumerate(value):
+                walk(child, (*path, idx))
+
+    walk(data, ROOT_HISTORY_KEY)
+    return history
+
+
+def merge_data(low: dict[str, Any], high: dict[str, Any]) -> dict[str, Any]:
+    """Merge two dictionaries with high priority overriding low priority."""
+    result: dict[str, Any] = deepcopy(low)
+    for key, high_value in high.items():
+        if (
+            key in result
+            and isinstance(result[key], dict)
+            and isinstance(high_value, dict)
+        ):
+            result[key] = merge_data(result[key], high_value)
+        else:
+            result[key] = deepcopy(high_value)
+    return result
+
+
+def merge_history(
+    low: dict[PathKey, list[PathHist]], high: dict[PathKey, list[PathHist]]
+) -> dict[PathKey, list[PathHist]]:
+    merged = {path: entries[:] for path, entries in low.items()}  # !!! important?
+    for path, entries in high.items():
+        merged.setdefault(path, []).extend(entries)
+    return merged
+
+
+def parse_raw_file(path: Path) -> RawToml:
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+
+    if not isinstance(data, dict):
+        raise ContentError(f"Top-level TOML object must be a table: {path}")
+
+    meta = data.pop("__meta__", {})
+    if not isinstance(meta, dict):
+        raise ContentError(f"Invalid __meta__ table in {path}")
+
+    includes: list[str] = []
+    raw_include = data.pop("include", None)
+
+    if raw_include is None:
+        pass
+    elif isinstance(raw_include, str):
+        includes.append(raw_include)
+    elif isinstance(raw_include, list) and all(
+        isinstance(item, str) for item in raw_include
+    ):
+        includes.extend(raw_include)
+    else:
+        raise ContentError(f"Invalid include specification in {path}")
+
+    return RawToml(path=path, meta=meta, body=data, includes=includes)

tomlstack/nodes.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from .base import PathHist
+from .loader import PathKey
+
+
+@dataclass
+class Node:
+    _cfg: ConfigProtocol
+    key: PathKey
+
+    def __post_init__(self) -> None:
+        if self.key not in self._cfg._history:
+            raise KeyError(f"Node path does not exist: {self.key}")
+
+    @property
+    def raw(self) -> Any:
+        return self._cfg._get_raw(self.key)
+
+    @property
+    def value(self) -> Any:
+        return self._cfg._get_value(self.key)
+
+    @property
+    def resolved(self) -> Any:
+        return self.value
+
+    @property
+    def origin(self) -> PathHist:
+        return self._cfg._history[self.key][-1]
+
+    @property
+    def history(self) -> tuple[PathHist, ...]:
+        return tuple(self._cfg._history[self.key])
+
+    def preview(self) -> str:
+        return _render_preview(self.raw)
+
+    def __getitem__(self, key: str | int) -> Node:
+        value = self.raw
+        if isinstance(key, int):
+            if not isinstance(value, list):
+                raise TypeError(f"Cannot index non-list node with int key: {self.key}")
+            if key < 0 or key >= len(value):
+                raise IndexError(key)
+            return Node(self._cfg, (*self.key, key))
+        if isinstance(key, str):
+            if not isinstance(value, dict):
+                raise TypeError(f"Cannot index non-dict node with str key: {self.key}")
+            if key not in value:
+                raise KeyError(key)
+            return Node(self._cfg, (*self.key, key))
+        raise TypeError(f"Unsupported key type: {type(key)!r}")
+
+    def __repr__(self) -> str:
+        return (
+            f"Node(path={self.key!r}, raw={self.raw!r}, "
+            f"value={self.value!r}, origin={self.origin!r})"
+        )
+
+
+class ConfigProtocol(Protocol):
+    _history: dict[PathKey, list[PathHist]]
+
+    def _get_raw(self, path: PathKey) -> Any: ...
+
+    def _get_value(self, path: PathKey) -> Any: ...
+
+
+def _render_preview(value: Any, indent: int = 0) -> str:
+    pad = "  " * indent
+    if isinstance(value, dict):
+        lines = ["{"]
+        for key, child in value.items():
+            child_rendered = _render_preview(child, indent + 1)
+            lines.append(f"{pad}  {key}: {child_rendered}")
+        lines.append(f"{pad}" + "}")
+        return "\n".join(lines)
+    if isinstance(value, list):
+        lines = ["["]
+        for child in value:
+            child_rendered = _render_preview(child, indent + 1)
+            lines.append(f"{pad}  {child_rendered}")
+        lines.append(f"{pad}" + "]")
+        return "\n".join(lines)
+    return repr(value)

tomlstack/path_expr.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .loader import PathKey
+
+
+def parse_path_expr(expr: str) -> PathKey:
+    expr = expr.strip()
+    if not expr:
+        raise ValueError("Empty interpolation path")
+
+    tokens: list[str | int] = []
+    i = 0
+    n = len(expr)
+
+    while i < n:
+        if expr[i] in ".]":
+            raise ValueError(f"Invalid token at position {i} in path '{expr}'")
+
+        start = i
+        while i < n and expr[i] not in ".[":
+            i += 1
+        key = expr[start:i]
+        if not key:
+            raise ValueError(f"Invalid empty key in path '{expr}'")
+        tokens.append(key)
+
+        while i < n and expr[i] == "[":
+            i += 1
+            idx_start = i
+            while i < n and expr[i] != "]":
+                i += 1
+            if i >= n or expr[i] != "]":
+                raise ValueError(f"Unclosed list index in path '{expr}'")
+            idx_token = expr[idx_start:i]
+            if not idx_token.isdigit():
+                raise ValueError(
+                    f"List index must be non-negative integer in path '{expr}'"
+                )
+            tokens.append(int(idx_token))
+            i += 1
+
+        if i < n:
+            if expr[i] != ".":
+                raise ValueError(f"Unexpected token '{expr[i]}' in path '{expr}'")
+            i += 1
+
+    return tuple(tokens)
+
+
+def get_by_path(data: Any, path: PathKey) -> Any:
+    cur = data
+    for part in path:
+        if isinstance(part, str):
+            if not isinstance(cur, dict) or part not in cur:
+                raise KeyError(part)
+            cur = cur[part]
+        else:
+            if not isinstance(cur, list) or part < 0 or part >= len(cur):
+                raise KeyError(part)
+            cur = cur[part]
+    return cur
+
+
+def path_to_str(path: PathKey) -> str:
+    if not path:
+        return "<root>"
+
+    out = ""
+    for part in path:
+        if isinstance(part, str):
+            if out:
+                out += "."
+            out += part
+        else:
+            out += f"[{part}]"
+    return out

tomlstack-0.1.2.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: tomlstack
+Version: 0.1.2
+Summary: TOML configuration loader with include/merge/interpolation
+Project-URL: Homepage, https://github.com/wxzhao7/tomlstack
+Project-URL: Repository, https://github.com/wxzhao7/tomlstack
+Project-URL: Issues, https://github.com/wxzhao7/tomlstack/issues
+Author: wxzhao7
+License: MIT
+License-File: LICENSE
+Keywords: config,configuration,include,interpolation,toml
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: ruff>=0.8; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.3; extra == 'test'
+Provides-Extra: typing
+Requires-Dist: mypy>=1.11; extra == 'typing'
+Description-Content-Type: text/markdown
+
+# tomlstack
+
+`tomlstack` is a lightweight TOML config loader for Python 3.11+ with:
+
+- top-level `include` loading
+- deterministic merge by include order
+- `${path}` interpolation with cycle/undefined checks
+- node-level provenance (`origin`, `explain`, `history`)
+
+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.
+
+## 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 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())
+```
+
+## 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 `__meta__.include.anchors`)
+- absolute path
+- any other form raises error with hint: `Use ./ or ../ or @label/`
+
+### Meta Include Directives
+
+```toml
+[__meta__]
+version = 1
+
+[__meta__.include]
+root = "../.."
+
+[__meta__.include.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`)
+
+## 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 happens on `cfg.resolve()`
+- 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`
+- 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`
+
+## Public API
+
+- `cfg = load("f.toml")`
+- `cfg.resolve()`
+- `cfg.to_dict()`
+- `node = cfg["proj"][0]["path"]["foo"]`
+- `node.raw`
+- `node.value`
+- `node.origin`
+- `node.history`
+- `node.preview()`
+- `cfg.to_toml()` -> `NotImplementedError`
+
+## 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:
+
+```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.1.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+tomlstack/__init__.py,sha256=Ty_LfLLtbhRtBdljPFD8iAi1-aBZwO7KjRLaf28P_L0,66
+tomlstack/_version.py,sha256=Ok5oAXdWgR9aghaFXTafTeDW6sYO3uVe6d2Nket57R4,704
+tomlstack/api.py,sha256=K0eORVr3oUeZmbkntmmKTNo9KjnMABqT82hYwGzLnvw,2499
+tomlstack/base.py,sha256=tBpAWYBM7uWXXAzVXVqRiH7tVEwJ16a4EijzB7gDrCY,527
+tomlstack/errors.py,sha256=obgckjG712JLrtHaPKLb2dooXxNwUkRDKct58LF620w,1051
+tomlstack/include.py,sha256=7OOfn4jOcsB1IrZNpUW51X4PiU6bEz4V4sedZXwODt4,3988
+tomlstack/interpolate.py,sha256=DFc1LQBEgshZKlRpIng1aNjKsqnO9m-FHedkdlJ-4po,3919
+tomlstack/loader.py,sha256=Yc__9VWO2sSzVwzxCc2WjwnjZQBGHhGvSpf-4gcWGYs,6765
+tomlstack/nodes.py,sha256=n8M7R1PWAqietCbQfnhIpQ8d4eZY4m_nvod41FClpUg,2658
+tomlstack/path_expr.py,sha256=AerF4cHe4PW8_MXhtXnOuIdNSXc-dTp9r18f5s1mhfY,2062
+tomlstack-0.1.2.dist-info/METADATA,sha256=kh6u5vqyNYnQv8m-NhB0ZOZxo-6I0KhY0N-7ObddGqc,5048
+tomlstack-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tomlstack-0.1.2.dist-info/licenses/LICENSE,sha256=gKh4DjA6O7KsySQQCSgIShkcS__qcT7dCoeclv0Dpfc,1064
+tomlstack-0.1.2.dist-info/RECORD,,

tomlstack-0.1.2.dist-info/WHEEL

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

tomlstack-0.1.2.dist-info/licenses/LICENSE

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