trrack 0.0.1a1__tar.gz

trrack-0.0.1a1/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+
+# uv / virtual environments
+.venv/
+
+# Test / coverage / type caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Node / pnpm
+node_modules/
+*.tsbuildinfo
+npm-debug.log*
+pnpm-debug.log*
+
+# Built frontend bundle (shipped in the wheel via hatch artifacts, not committed)
+packages/trrack-widget/src/trrack_widget/static/
+
+# marimo generated session snapshots / layouts
+__marimo__/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+*.swp
+
+# Agent working dir
+.context/

trrack-0.0.1a1/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: trrack
+Version: 0.0.1a1
+Summary: Branching tree-based provenance tracking for Python.
+Project-URL: Homepage, https://github.com/kirangadhave/trrackpy
+Project-URL: Repository, https://github.com/kirangadhave/trrackpy
+Author: Kiran Gadhave
+License-Expression: BSD-3-Clause
+Keywords: history,provenance,time-travel,trrack,undo
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# trrack
+
+Branching tree-based provenance tracking for Python. Pure model, no UI deps.

trrack-0.0.1a1/README.md

@@ -0,0 +1,3 @@
+# trrack
+
+Branching tree-based provenance tracking for Python. Pure model, no UI deps.

trrack-0.0.1a1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "trrack"
+version = "0.0.1a1"
+description = "Branching tree-based provenance tracking for Python."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+license = "BSD-3-Clause"
+authors = [{ name = "Kiran Gadhave" }]
+keywords = ["provenance", "history", "undo", "time-travel", "trrack"]
+classifiers = [
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/kirangadhave/trrackpy"
+Repository = "https://github.com/kirangadhave/trrackpy"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/trrack"]

trrack-0.0.1a1/src/trrack/__init__.py

@@ -0,0 +1,15 @@
+"""Branching tree-based provenance tracking for Python.
+
+Pure model with no UI dependencies: a :class:`ProvenanceGraph` of full-state
+snapshots, plus an optional :class:`Store` seam for persistence.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from .graph import Node, ProvenanceGraph
+from .persist import JsonFileStore, Store
+
+__all__ = ["JsonFileStore", "Node", "ProvenanceGraph", "Store"]
+__version__ = version("trrack")

trrack-0.0.1a1/src/trrack/graph.py

@@ -0,0 +1,165 @@
+"""The provenance graph model: full-state snapshot nodes and navigation."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import asdict, dataclass
+from typing import TYPE_CHECKING
+
+from .persist import read_json, write_json_atomic
+
+if TYPE_CHECKING:
+    import os
+
+
+@dataclass
+class Node:
+    """A single full-state snapshot and its position in the graph."""
+
+    id: str
+    parent: str | None
+    children: list[str]
+    created_at: str
+    label: str
+    state: dict
+
+
+class ProvenanceGraph:
+    """A branching graph of full-state snapshots.
+
+    Pure model: no widget or marimo imports. Timestamps are supplied by the
+    caller via ``now`` so the model performs no I/O and stays deterministic.
+    """
+
+    def __init__(
+        self,
+        root_state: dict,
+        *,
+        now: str,
+        root_id: str | None = None,
+    ) -> None:
+        """Create the graph with a single root holding ``root_state``."""
+        rid = root_id or uuid.uuid4().hex
+        root = Node(
+            id=rid,
+            parent=None,
+            children=[],
+            created_at=now,
+            label="initial",
+            state=dict(root_state),
+        )
+        self.nodes: dict[str, Node] = {rid: root}
+        self.root_id = rid
+        self.current_id = rid
+
+    @property
+    def current(self) -> Node:
+        """The node the graph is currently positioned at."""
+        return self.nodes[self.current_id]
+
+    @property
+    def root(self) -> Node:
+        """The root node the graph started from."""
+        return self.nodes[self.root_id]
+
+    @property
+    def is_at_root(self) -> bool:
+        """Whether the current node is the root (nothing to undo)."""
+        return self.current.parent is None
+
+    @property
+    def is_at_latest(self) -> bool:
+        """Whether the current node is a leaf (nothing to redo)."""
+        return not self.current.children
+
+    def commit(
+        self,
+        state: dict,
+        *,
+        now: str,
+        label: str | None = None,
+        node_id: str | None = None,
+    ) -> Node:
+        """Append ``state`` as a child of the current node and move there."""
+        nid = node_id or uuid.uuid4().hex
+        parent = self.current
+        resolved_label = (
+            label if label is not None else self._auto_label(parent.state, state)
+        )
+        node = Node(
+            id=nid,
+            parent=parent.id,
+            children=[],
+            created_at=now,
+            label=resolved_label,
+            state=dict(state),
+        )
+        self.nodes[nid] = node
+        parent.children.append(nid)
+        self.current_id = nid
+        return node
+
+    def undo(self) -> Node | None:
+        """Move to the parent of the current node, or ``None`` at the root."""
+        node = self.current
+        if node.parent is None:
+            return None
+        self.current_id = node.parent
+        return self.current
+
+    def redo(self) -> Node | None:
+        """Move to the newest child of the current node, or ``None`` at a leaf."""
+        node = self.current
+        if not node.children:
+            return None
+        self.current_id = node.children[-1]  # newest child (append order)
+        return self.current
+
+    def go_to(self, node_id: str) -> Node:
+        """Jump to ``node_id``; raises ``KeyError`` if it is unknown."""
+        if node_id not in self.nodes:
+            raise KeyError(node_id)
+        self.current_id = node_id
+        return self.current
+
+    def relabel(self, text: str, node_id: str | None = None) -> None:
+        """Set the label of ``node_id`` (default: the current node) to ``text``."""
+        self.nodes[node_id or self.current_id].label = text
+
+    def to_dict(self) -> dict:
+        """Serialize the whole graph to plain JSON-compatible data."""
+        return {
+            "nodes": {nid: asdict(node) for nid, node in self.nodes.items()},
+            "root_id": self.root_id,
+            "current_id": self.current_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> ProvenanceGraph:
+        """Reconstruct a graph from :meth:`to_dict` output."""
+        tree = cls.__new__(cls)
+        tree.nodes = {nid: Node(**nd) for nid, nd in data["nodes"].items()}
+        tree.root_id = data["root_id"]
+        tree.current_id = data["current_id"]
+        return tree
+
+    def save(self, path: str | os.PathLike[str]) -> None:
+        """Write the serialized graph to ``path`` atomically."""
+        write_json_atomic(path, self.to_dict())
+
+    @classmethod
+    def load(cls, path: str | os.PathLike[str]) -> ProvenanceGraph | None:
+        """Load a graph from ``path``, or return ``None`` if it is absent."""
+        data = read_json(path)
+        if data is None:
+            return None
+        return cls.from_dict(data)
+
+    @staticmethod
+    def _auto_label(old: dict, new: dict) -> str:
+        changes = []
+        for key in sorted(set(old) | set(new)):
+            before, after = old.get(key), new.get(key)
+            if before != after:
+                changes.append(f"{key}: {before} → {after}")
+        return ", ".join(changes) if changes else "(no change)"

trrack-0.0.1a1/src/trrack/persist.py

@@ -0,0 +1,74 @@
+"""JSON persistence for a full-snapshot ProvenanceGraph.
+
+A ``Store`` is the single extension seam: anything with ``save(dict)`` and
+``load() -> dict | None`` can back persistence, so a future backend (a database,
+browser storage, a remote service) is a drop-in without a plugin registry.
+``JsonFileStore`` is the only implementation today.
+
+v1 serializes the entire graph on every save: cost is O(total nodes x snapshot
+size). That is imperceptible at interactive scale (tens-hundreds of small-state
+nodes) and only matters with very large graphs or large per-node state. The
+scaling answer, when needed, is a diff-node model -- store patches between nodes
+with periodic full-state checkpoints, so per-save cost tracks changed state
+rather than total state. Out of scope here; tracked as a future option.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    import os
+
+
+@runtime_checkable
+class Store(Protocol):
+    """A persistence backend for a serialized provenance payload."""
+
+    def save(self, data: dict) -> None:
+        """Persist ``data``, replacing any previously saved payload."""
+        ...
+
+    def load(self) -> dict | None:
+        """Return the saved payload, or ``None`` if nothing is stored."""
+        ...
+
+
+def write_json_atomic(path: str | os.PathLike[str], data: dict) -> None:
+    """Write ``data`` as JSON, replacing ``path`` atomically.
+
+    The write goes to a sibling temp file first and is then moved into place
+    with ``Path.replace`` so a crash mid-write can never leave a half-written,
+    unparsable file at ``path``.
+    """
+    path = pathlib.Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(data), encoding="utf-8")
+    tmp.replace(path)
+
+
+def read_json(path: str | os.PathLike[str]) -> dict | None:
+    """Return the parsed JSON at ``path``, or ``None`` if it does not exist."""
+    path = pathlib.Path(path)
+    if not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+class JsonFileStore:
+    """A ``Store`` that round-trips the payload through one JSON file."""
+
+    def __init__(self, path: str | os.PathLike[str]) -> None:
+        """Back persistence with the JSON file at ``path``."""
+        self._path = path
+
+    def save(self, data: dict) -> None:
+        """Write ``data`` to the file, atomically replacing prior contents."""
+        write_json_atomic(self._path, data)
+
+    def load(self) -> dict | None:
+        """Return the file's parsed payload, or ``None`` if it is absent."""
+        return read_json(self._path)

trrack-0.0.1a1/tests/test_graph.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import pytest
+
+from trrack.graph import Node, ProvenanceGraph
+
+
+def test_root_node_created_from_state():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    root = tree.root
+    assert isinstance(root, Node)
+    assert root.id == "r"
+    assert root.parent is None
+    assert root.children == []
+    assert root.created_at == "t0"
+    assert root.label == "initial"
+    assert root.state == {"count": 0}
+    assert tree.current is root
+    assert tree.current_id == "r"
+
+
+def test_commit_appends_child_and_advances_current():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    node = tree.commit({"count": 1}, now="t1", node_id="a")
+    assert node.id == "a"
+    assert node.parent == "r"
+    assert node.state == {"count": 1}
+    assert tree.root.children == ["a"]
+    assert tree.current is node
+    assert node.label == "count: 0 → 1"
+
+
+def test_auto_label_multiple_traits_sorted():
+    tree = ProvenanceGraph({"a": 1, "b": 1}, now="t0", root_id="r")
+    node = tree.commit({"a": 2, "b": 3}, now="t1")
+    assert node.label == "a: 1 → 2, b: 1 → 3"
+
+
+def test_explicit_label_overrides_auto():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    node = tree.commit({"count": 1}, now="t1", label="mine")
+    assert node.label == "mine"
+
+
+def test_undo_moves_to_parent_and_stops_at_root():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    tree.commit({"count": 1}, now="t1", node_id="a")
+    parent = tree.undo()
+    assert parent is not None
+    assert parent.id == "r"
+    assert tree.undo() is None
+    assert tree.current_id == "r"
+
+
+def test_redo_follows_newest_child():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    tree.commit({"count": 1}, now="t1", node_id="a")
+    tree.undo()
+    tree.commit({"count": 2}, now="t2", node_id="b")  # sibling of "a"
+    tree.undo()  # back to root
+    newest = tree.redo()
+    assert newest is not None
+    assert newest.id == "b"  # newest child wins
+    assert tree.redo() is None  # "b" is a leaf
+
+
+def test_commit_after_undo_creates_branch():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    tree.commit({"count": 1}, now="t1", node_id="a")
+    tree.undo()
+    tree.commit({"count": 9}, now="t2", node_id="b")
+    assert sorted(tree.root.children) == ["a", "b"]
+    assert tree.nodes["a"].parent == "r"
+    assert tree.nodes["b"].parent == "r"
+
+
+def test_go_to_sets_current():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    tree.commit({"count": 1}, now="t1", node_id="a")
+    assert tree.go_to("r").id == "r"
+    assert tree.current_id == "r"
+
+
+def test_go_to_unknown_raises():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    with pytest.raises(KeyError):
+        tree.go_to("nope")
+
+
+def test_relabel_current_and_explicit():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    tree.commit({"count": 1}, now="t1", node_id="a")
+    tree.relabel("renamed")
+    assert tree.nodes["a"].label == "renamed"
+    tree.relabel("root!", node_id="r")
+    assert tree.nodes["r"].label == "root!"
+
+
+def test_to_dict_from_dict_round_trip():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    tree.commit({"count": 1}, now="t1", node_id="a")
+    tree.undo()
+    tree.commit({"count": 9}, now="t2", node_id="b")
+    tree.go_to("a")
+
+    d = tree.to_dict()
+    assert d["root_id"] == "r"
+    assert d["current_id"] == "a"
+    assert set(d["nodes"]) == {"r", "a", "b"}
+
+    restored = ProvenanceGraph.from_dict(d)
+    assert restored.root_id == "r"
+    assert restored.current_id == "a"
+    assert sorted(restored.root.children) == ["a", "b"]
+    assert restored.nodes["b"].state == {"count": 9}
+    assert restored.to_dict() == d
+
+
+def test_is_at_root_and_is_at_latest():
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    assert tree.is_at_root
+    assert tree.is_at_latest
+
+    tree.commit({"count": 1}, now="t1", node_id="a")
+    assert not tree.is_at_root
+    assert tree.is_at_latest
+
+    tree.undo()
+    assert tree.is_at_root
+    assert not tree.is_at_latest
+
+
+def test_save_and_load_round_trip(tmp_path):
+    tree = ProvenanceGraph({"count": 0}, now="t0", root_id="r")
+    tree.commit({"count": 1}, now="t1", node_id="a")
+    tree.undo()
+    path = tmp_path / "graph.json"
+
+    tree.save(path)
+    restored = ProvenanceGraph.load(path)
+
+    assert restored is not None
+    assert restored.to_dict() == tree.to_dict()
+
+
+def test_load_missing_returns_none(tmp_path):
+    assert ProvenanceGraph.load(tmp_path / "absent.json") is None

trrack-0.0.1a1/tests/test_persist.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import json
+
+from trrack.persist import JsonFileStore, read_json, write_json_atomic
+
+
+def test_read_json_missing_returns_none(tmp_path):
+    assert read_json(tmp_path / "absent.json") is None
+
+
+def test_write_then_read_round_trip(tmp_path):
+    path = tmp_path / "state.json"
+    write_json_atomic(path, {"count": 1})
+    assert read_json(path) == {"count": 1}
+
+
+def test_overwrite_leaves_valid_json_and_no_temp_file(tmp_path):
+    path = tmp_path / "state.json"
+    write_json_atomic(path, {"count": 1})
+    write_json_atomic(path, {"count": 2})
+    assert json.loads(path.read_text(encoding="utf-8")) == {"count": 2}
+    assert list(path.parent.iterdir()) == [path]
+
+
+def test_json_file_store_round_trip(tmp_path):
+    store = JsonFileStore(tmp_path / "state.json")
+    assert store.load() is None
+    store.save({"count": 7})
+    assert store.load() == {"count": 7}