granim-viz 0.1.0__tar.gz

granim_viz-0.1.0/LICENSE

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

granim_viz-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: granim-viz
+Version: 0.1.0
+Summary: Write the algorithm, get the animation - instrumented data structures that compile your real Python code into interactive HTML visualizations.
+Author-email: Musaib Bashir <musaibbashir.24@kgpian.iitkgp.ac.in>
+License: MIT
+Project-URL: Homepage, https://github.com/musaibbashir/granim
+Project-URL: Repository, https://github.com/musaibbashir/granim
+Project-URL: Issues, https://github.com/musaibbashir/granim/issues
+Keywords: visualization,animation,algorithms,data-structures,education,linked-list,graph,tree,manim,teaching
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# granim
+
+Write the algorithm. Get the animation.
+
+granim instruments its data structures so that running your *normal* Python code
+produces an interactive, self-contained HTML animation — nodes appear as you
+build, arrows flip as you reverse, frontiers light up in parallel, and debug mode
+shows every variable hopping between nodes.
+
+```python
+import granim as ga
+
+@ga.animate(debug=True)
+def reverse(node):
+    if node is None or node.next is None:
+        return node
+    new_head = reverse(node.next)
+    node.next.next = node
+    node.next = None
+    return new_head
+
+reverse(ga.linked_list([1, 2, 3, 4, 5]).head)   # -> reverse.html, opens in browser
+```
+
+That's the entire integration: one decorator, one constructor. The recursion walks
+to null while the call stack panel fills; on the way back, each arrow visibly
+reverses (granim classifies `node.next.next = node` as an *edge flip*, not a
+delete+add).
+
+## What you get
+
+- **Automatic steps** — each loop iteration is one animation beat; same-line
+  mutations (a BFS frontier) merge into one *parallel* beat. No annotations.
+- **Debug mode** (`debug=True`) — all locals in a side panel, plus on-canvas
+  badges: node-valued variables dock to their node, ints near an array become
+  index pointers (`lo`/`hi`/`mid` under the cells).
+- **Five structures** — `ga.array`, `ga.matrix`, `ga.linked_list`, `ga.tree`,
+  `ga.graph`, all usable (and unit-testable) without recording. Matrix cells
+  animate values (`m[i][j] = v`) and colors (`m[i][j].state = "visited"`).
+- **Your own classes** — `@ga.node(value="val")` instruments any class without
+  inheritance: node-valued fields become labeled edges, the value field animates,
+  everything else is plain storage. Ad-hoc fields on granim nodes work too
+  (`node.random`, `node.child` arc underneath with their name on them).
+  `@ga.container` does the same for wrappers (queues, custom lists): `head`/
+  `tail`-style fields render as floating badges and root the garbage pass, so
+  dropped nodes dim out.
+- **Auto layout** — tidy trees (Buchheim), layered DAGs, force-directed graphs,
+  snake-wrapped lists; positions stay stable between steps instead of jumping.
+- **One file out** — interactive player (play/pause/step/scrub/speed) in a single
+  offline HTML file. Jupyter renders inline automatically.
+- **Zero dependencies.**
+
+## Examples
+
+`examples/` doubles as the acceptance suite:
+
+| file | shows off |
+|---|---|
+| `binary_search.py` | auto index badges, comparison pulses |
+| `reverse_recursive.py` | call stack + arrows flipping on unwind |
+| `reverse_iterative.py` | `prev`/`cur`/`nxt` badges hopping |
+| `bst.py` | tidy tree re-flowing as nodes attach |
+| `bfs.py` | parallel frontier steps, state coloring |
+| `dedup.py` | unlinked nodes dim out (reachability pass) |
+| `floyd.py` | tortoise/hare badges meeting; cycle arc |
+| `flood_fill.py` | matrix: values + colors spreading, deep recursion |
+| `dijkstra.py` | weighted edges, frontier/visited/done coloring |
+| `quicksort.py` | pivot glow, swaps, sorted cells locking in |
+| `edit_distance.py` | DP table filling, dependency-cell pulses |
+| `custom_node.py` | `@ga.node` on a user-owned class (LeetCode 138) |
+| `queue.py` | `@ga.container`: head/tail badges, dequeued nodes dim |
+
+Run any of them: `PYTHONPATH=src python examples/bfs.py` → open the HTML next to it.
+
+## Tests
+
+```
+python tests/run_tests.py        # pure-python pipeline tests (pytest also works)
+node tests/verify_html.js        # replays each example's timeline, checks end state
+```
+
+## Design
+
+`docs/PLAN.md` holds the rationale, `docs/SPEC.md` the contracts. The short version:
+structures emit a small vocabulary of semantic events; a step builder groups them
+into beats (line-scoped via a trace limited to your function); a pure compiler
+classifies edge flips, computes layout keyframes, and serializes a timeline that
+a dependency-free JS player animates. The trace can only ever coarsen steps —
+animation truth comes from the structures.

granim_viz-0.1.0/README.md

@@ -0,0 +1,89 @@
+# granim
+
+Write the algorithm. Get the animation.
+
+granim instruments its data structures so that running your *normal* Python code
+produces an interactive, self-contained HTML animation — nodes appear as you
+build, arrows flip as you reverse, frontiers light up in parallel, and debug mode
+shows every variable hopping between nodes.
+
+```python
+import granim as ga
+
+@ga.animate(debug=True)
+def reverse(node):
+    if node is None or node.next is None:
+        return node
+    new_head = reverse(node.next)
+    node.next.next = node
+    node.next = None
+    return new_head
+
+reverse(ga.linked_list([1, 2, 3, 4, 5]).head)   # -> reverse.html, opens in browser
+```
+
+That's the entire integration: one decorator, one constructor. The recursion walks
+to null while the call stack panel fills; on the way back, each arrow visibly
+reverses (granim classifies `node.next.next = node` as an *edge flip*, not a
+delete+add).
+
+## What you get
+
+- **Automatic steps** — each loop iteration is one animation beat; same-line
+  mutations (a BFS frontier) merge into one *parallel* beat. No annotations.
+- **Debug mode** (`debug=True`) — all locals in a side panel, plus on-canvas
+  badges: node-valued variables dock to their node, ints near an array become
+  index pointers (`lo`/`hi`/`mid` under the cells).
+- **Five structures** — `ga.array`, `ga.matrix`, `ga.linked_list`, `ga.tree`,
+  `ga.graph`, all usable (and unit-testable) without recording. Matrix cells
+  animate values (`m[i][j] = v`) and colors (`m[i][j].state = "visited"`).
+- **Your own classes** — `@ga.node(value="val")` instruments any class without
+  inheritance: node-valued fields become labeled edges, the value field animates,
+  everything else is plain storage. Ad-hoc fields on granim nodes work too
+  (`node.random`, `node.child` arc underneath with their name on them).
+  `@ga.container` does the same for wrappers (queues, custom lists): `head`/
+  `tail`-style fields render as floating badges and root the garbage pass, so
+  dropped nodes dim out.
+- **Auto layout** — tidy trees (Buchheim), layered DAGs, force-directed graphs,
+  snake-wrapped lists; positions stay stable between steps instead of jumping.
+- **One file out** — interactive player (play/pause/step/scrub/speed) in a single
+  offline HTML file. Jupyter renders inline automatically.
+- **Zero dependencies.**
+
+## Examples
+
+`examples/` doubles as the acceptance suite:
+
+| file | shows off |
+|---|---|
+| `binary_search.py` | auto index badges, comparison pulses |
+| `reverse_recursive.py` | call stack + arrows flipping on unwind |
+| `reverse_iterative.py` | `prev`/`cur`/`nxt` badges hopping |
+| `bst.py` | tidy tree re-flowing as nodes attach |
+| `bfs.py` | parallel frontier steps, state coloring |
+| `dedup.py` | unlinked nodes dim out (reachability pass) |
+| `floyd.py` | tortoise/hare badges meeting; cycle arc |
+| `flood_fill.py` | matrix: values + colors spreading, deep recursion |
+| `dijkstra.py` | weighted edges, frontier/visited/done coloring |
+| `quicksort.py` | pivot glow, swaps, sorted cells locking in |
+| `edit_distance.py` | DP table filling, dependency-cell pulses |
+| `custom_node.py` | `@ga.node` on a user-owned class (LeetCode 138) |
+| `queue.py` | `@ga.container`: head/tail badges, dequeued nodes dim |
+
+Run any of them: `PYTHONPATH=src python examples/bfs.py` → open the HTML next to it.
+
+## Tests
+
+```
+python tests/run_tests.py        # pure-python pipeline tests (pytest also works)
+node tests/verify_html.js        # replays each example's timeline, checks end state
+```
+
+## Design
+
+`docs/PLAN.md` holds the rationale, `docs/SPEC.md` the contracts. The short version:
+structures emit a small vocabulary of semantic events; a step builder groups them
+into beats (line-scoped via a trace limited to your function); a pure compiler
+classifies edge flips, computes layout keyframes, and serializes a timeline that
+a dependency-free JS player animates. The trace can only ever coarsen steps —
+animation truth comes from the structures.

granim_viz-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "granim-viz"
+version = "0.1.0"
+description = "Write the algorithm, get the animation - instrumented data structures that compile your real Python code into interactive HTML visualizations."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Musaib Bashir", email = "musaibbashir.24@kgpian.iitkgp.ac.in" }]
+keywords = [
+    "visualization", "animation", "algorithms", "data-structures",
+    "education", "linked-list", "graph", "tree", "manim", "teaching",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Software Development :: Debuggers",
+]
+
+[project.urls]
+Homepage = "https://github.com/musaibbashir/granim"
+Repository = "https://github.com/musaibbashir/granim"
+Issues = "https://github.com/musaibbashir/granim/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"granim.render" = ["player/*"]
+
+[tool.ruff]
+line-length = 100

granim_viz-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

granim_viz-0.1.0/src/granim/__init__.py

@@ -0,0 +1,107 @@
+"""granim — write the algorithm, get the animation.
+
+    import granim as ga
+
+    @ga.animate(debug=True)
+    def rev(node, prev=None):
+        if node is None:
+            return prev
+        nxt = node.next
+        node.next = prev
+        return rev(nxt, node)
+
+    rev(ga.linked_list([1, 2, 3, 4, 5]).head)   # -> rev.html
+"""
+from __future__ import annotations
+
+import functools
+import sys
+import webbrowser
+from pathlib import Path
+
+from .core.recorder import GranimError, Index, Recorder, active
+from .core.trace import Trace
+from .structures.array import Array
+from .structures.graph import Graph, GraphNode
+from .structures.linked_list import LinkedList, ListNode
+from .structures.custom import container, node
+from .structures.matrix import Matrix
+from .structures.tracked import Tracked
+from .structures.tree import Tree, TreeNode
+
+__version__ = "0.1.0"
+__all__ = [
+    "animate", "record", "array", "matrix", "linked_list", "tree", "graph",
+    "node", "container", "index", "GranimError", "ListNode", "TreeNode",
+    "GraphNode",
+]
+
+array = Array
+matrix = Matrix
+linked_list = LinkedList
+tree = Tree
+graph = Graph
+index = Index
+record = Recorder
+
+
+def animate(fn=None, *, debug=False, theme="dark", out=None, show=None,
+            speed=1.0, title=None):
+    """SPEC §2.1. Decorate a function; calling it records, compiles, saves, and
+    opens the animation. Returns the function's result unchanged."""
+    if fn is None:
+        return functools.partial(animate, debug=debug, theme=theme, out=out,
+                                 show=show, speed=speed, title=title)
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        rec = active()
+        if rec is not None:
+            if rec._owner is wrapper:  # recursion through the decorated name
+                return fn(*args, **kwargs)
+            raise GranimError("nested recording: another @animate function is running")
+
+        rec = Recorder(debug=debug, theme=theme, title=title or fn.__name__,
+                       speed=speed, owner=wrapper)
+        from .structures.base import is_node
+        rec.ext_roots = [a._id for a in (*args, *kwargs.values()) if is_node(a)]
+        result, err = None, None
+        with rec:
+            try:
+                with Trace(rec, fn.__code__):
+                    result = fn(*args, **kwargs)
+            except Exception as e:  # finalize + save, then re-raise (SPEC §2.1)
+                err = e
+                rec.error = f"{type(e).__name__}: {e}"
+            if is_node(result):
+                rec.ext_roots.append(result._id)
+
+        path = _out_path(out, fn)
+        rec.save(path)
+        if err is not None:
+            sys.stderr.write(f"granim: saved partial animation to {path}\n")
+            raise err
+        _present(rec, path, show, out)
+        return result._v if isinstance(result, Tracked) else result
+
+    return wrapper
+
+
+def _out_path(out, fn) -> Path:
+    if out is not None:
+        return Path(out)
+    src = Path(fn.__code__.co_filename)
+    base = src.parent if src.is_file() else Path.cwd()
+    return base / f"{fn.__name__}.html"
+
+
+def _present(rec, path, show, out) -> None:
+    in_jupyter = "ipykernel" in sys.modules
+    if show is None:
+        show = out is None
+    if not show:
+        return
+    if in_jupyter:
+        rec.show()
+    else:
+        webbrowser.open(path.resolve().as_uri())

granim_viz-0.1.0/src/granim/core/events.py

@@ -0,0 +1,44 @@
+"""Event model. SPEC §3: a small, closed vocabulary; everything else is derived."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+KINDS = frozenset({
+    "node_add", "node_remove", "edge_set", "read", "compare",
+    "value_set", "state_set", "var_set",
+})
+
+# Kinds that change structure (drive layout keyframes). edge_flip is assigned by
+# the compiler, never emitted.
+STRUCTURAL = frozenset({"node_add", "node_remove", "edge_set"})
+# Kinds eligible for parallel batch-merging (SPEC §5 rule 2).
+BATCHABLE = frozenset({"state_set", "node_add"})
+PASSIVE = frozenset({"read", "compare"})
+
+REPR_MAX = 60
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    seq: int
+    kind: str
+    payload: dict
+    depth: int
+    line: int | None
+    frame: int
+
+
+def safe_repr(value) -> str:
+    from ..structures.base import NodeBase
+    from ..structures.tracked import Tracked
+
+    if isinstance(value, Tracked):
+        value = value._v
+    if isinstance(value, NodeBase):
+        r = f"Node({value._value!r})"
+    else:
+        try:
+            r = repr(value)
+        except Exception:
+            r = f"<{type(value).__name__}>"
+    return r if len(r) <= REPR_MAX else r[: REPR_MAX - 1] + "…"