trrack 0.0.1a1__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+trrack/__init__.py,sha256=VMJGW8zTL4AHNdars1qVsE6as0ZrwS_ntF7fVNQlZHI,460
+trrack/graph.py,sha256=Hl2--xPmXRZRpyOVi6G2P8dTYi4s1PfdZQn_qSYtt7M,5124
+trrack/persist.py,sha256=S6Dfg5Vd0dQu99cQJo-BloMk0sWdHYOldDeSGyl7418,2704
+trrack-0.0.1a1.dist-info/METADATA,sha256=PKcxj6m7k_LxQv-YweoGX8B6qfAP-gS4_WB42Bop-Nc,843
+trrack-0.0.1a1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+trrack-0.0.1a1.dist-info/RECORD,,

trrack-0.0.1a1.dist-info/WHEEL

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