This release is a pre-release and may not be stable for production use.
trrack
Branching, tree-based provenance tracking for Python. A pure model with no UI
dependencies: a ProvenanceGraph of full-state snapshots you can navigate,
branch, label, and persist.
Part of the trrackpy monorepo; the
trrack-widget package is one
consumer of this core.
Install
uv add trrack # or: pip install trrack
Concepts
- Every state you record is stored as a full snapshot in a
Node. Nodes form a tree: committing from an earlier node creates a branch rather than discarding the later history. - The model is deterministic and I/O-free. It never reads the clock —
timestamps are passed in by the caller via
now— so behavior is fully reproducible and easy to test. - Persistence is an optional, swappable seam (
Store); the model itself holds no opinion about where state is saved.
Quick start
from trrack import ProvenanceGraph
g = ProvenanceGraph({"count": 0}, now="t0")
g.commit({"count": 1}, now="t1")
g.commit({"count": 2}, now="t2")
g.undo() # back to {"count": 1}
g.redo() # forward to {"count": 2}
# Branch: go back, then commit a different state off the earlier node.
g.go_to(g.root.id)
g.commit({"count": 99}, now="t3") # new branch from the root
g.current.state # {"count": 99}
g.is_at_root, g.is_at_latest
Commits are auto-labeled from what changed; pass label= to name them, or
relabel later with g.relabel("checkpoint").
Persistence
Round-trip the whole graph to a JSON file:
g.save("graph.json")
restored = ProvenanceGraph.load("graph.json") # None if the file is absent
save/load use atomic writes (write-to-temp, then os.replace) so a crash
mid-write can never leave a half-written file.
For anything other than a local file, use the Store seam — any object with
save(dict) -> None and load() -> dict | None qualifies (a database, browser
storage, a remote service), with no registry or plugin machinery. JsonFileStore
is the built-in implementation:
from trrack import JsonFileStore
store = JsonFileStore("graph.json")
store.save(g.to_dict())
data = store.load() # None if nothing saved yet
API
ProvenanceGraph(root_state, *, now, root_id=None) |
Create a graph with a single root node. |
.commit(state, *, now, label=None, node_id=None) |
Append state as a child of the current node and move there. |
.undo() / .redo() |
Move to the parent / a child of the current node. |
.go_to(node_id) |
Jump to any node by id. |
.relabel(text, node_id=None) |
Rename a node (defaults to current). |
.current / .root |
The current / root Node. |
.is_at_root / .is_at_latest |
Navigation guards (nothing to undo / redo). |
.to_dict() / ProvenanceGraph.from_dict(data) |
Serialize / deserialize. |
.save(path) / ProvenanceGraph.load(path) |
JSON file persistence. |
A Node exposes id, parent, children, created_at, label, and state.
License
BSD-3-Clause.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file trrack-0.0.1a2.tar.gz.
File metadata
- Download URL: trrack-0.0.1a2.tar.gz
- Upload date:
- Size: 6.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8d91bfdfac71a479d2fa41e58d4f2e5dac06fcc6d6aac98ef46d0aba5dd265da
|
|
| MD5 |
a1dc4aa76b3b718aa989a2a873a7adff
|
|
| BLAKE2b-256 |
7077a50571a39e002d9518caf14f1e4c429775b0b99da84425e3140102988327
|
Provenance
The following attestation bundles were made for trrack-0.0.1a2.tar.gz:
Publisher:
release.yml on kirangadhave/trrackpy
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
trrack-0.0.1a2.tar.gz -
Subject digest:
8d91bfdfac71a479d2fa41e58d4f2e5dac06fcc6d6aac98ef46d0aba5dd265da - Sigstore transparency entry: 1940494751
- Sigstore integration time:
-
Permalink:
kirangadhave/trrackpy@7a93ba18ae1be2ef4dd40d48beec0a73661f139c -
Branch / Tag:
refs/tags/v0.0.1a2 - Owner: https://github.com/kirangadhave
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@7a93ba18ae1be2ef4dd40d48beec0a73661f139c -
Trigger Event:
push
-
Statement type:
File details
Details for the file trrack-0.0.1a2-py3-none-any.whl.
File metadata
- Download URL: trrack-0.0.1a2-py3-none-any.whl
- Upload date:
- Size: 6.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
863f7bdfdc4513ca4043a604af9567a7c7361388b3d59643f6e2df11797f9744
|
|
| MD5 |
4f13f21c91344cd9a67119956b90333f
|
|
| BLAKE2b-256 |
327ffb7dbcfe4cb4d176939a8666f596eec5a62eb4c21fefbde68ea4905999c9
|
Provenance
The following attestation bundles were made for trrack-0.0.1a2-py3-none-any.whl:
Publisher:
release.yml on kirangadhave/trrackpy
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
trrack-0.0.1a2-py3-none-any.whl -
Subject digest:
863f7bdfdc4513ca4043a604af9567a7c7361388b3d59643f6e2df11797f9744 - Sigstore transparency entry: 1940494858
- Sigstore integration time:
-
Permalink:
kirangadhave/trrackpy@7a93ba18ae1be2ef4dd40d48beec0a73661f139c -
Branch / Tag:
refs/tags/v0.0.1a2 - Owner: https://github.com/kirangadhave
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@7a93ba18ae1be2ef4dd40d48beec0a73661f139c -
Trigger Event:
push
-
Statement type:
