pyalgoviz 0.1.0__tar.gz

pyalgoviz-0.1.0/LICENSE

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

pyalgoviz-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: pyalgoviz
+Version: 0.1.0
+Summary: Pseudocode-driven 2D algorithm visualizer
+Author-email: Kavindu Fernando <kavindufernando329@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/F3rNaNDEZ57/GraphicsAlgoVisualizer
+Project-URL: Repository, https://github.com/F3rNaNDEZ57/GraphicsAlgoVisualizer
+Project-URL: Issues, https://github.com/F3rNaNDEZ57/GraphicsAlgoVisualizer/issues
+Keywords: algorithm-visualization,tkinter,education,pseudocode,dsl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Education
+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 :: Education
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: customtkinter>=5.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# GraphicsAlgoVisualizer
+
+A pseudocode-driven 2D algorithm visualizer built with Python and CustomTkinter. Write algorithms in a simple DSL, pick a canvas type, and watch them execute step-by-step with animated visuals, speed control, and presentation mode.
+
+---
+
+## ✨ Features
+
+- **Pseudocode DSL** — Write algorithms in a clean, Python-like subset with `for`, `while`, `if/elif/else`, variables, expressions, and built-in functions. No Python knowledge required.
+- **Multiple Canvas Types** — Grid, Array, and Graph canvases with dedicated renderers and built-in operations.
+- **Bundled Algorithm Presets** — Bresenham line drawing, Bubble sort, BFS pathfinding, and Dijkstra's shortest path ship out of the box as TOML presets.
+- **In-App Graph Editor** — Click to add nodes, drag between nodes to create edges, set weights — build custom networks visually.
+- **Step-by-Step Playback** — Play, pause, step forward, adjust speed, and see line-by-line highlighting of the executing pseudocode.
+- **Presentation Mode** — A distraction-free, canvas-only view for demos and classroom walkthroughs.
+- **Theme System** — Centralized theme tokens drive all canvas and UI colors for a consistent look.
+- **Plugin Architecture** — Drop-in and entry-point based plugin loading. Extend the visualizer with custom canvas types (see the bundled `pyalgoviz-heap-canvas` example).
+- **User Presets** — Save your own algorithms as `.toml` preset files and load them from a user presets directory.
+
+---
+
+## 📋 Prerequisites
+
+- **Python 3.11+**
+- **Tkinter** (usually ships with Python; see platform notes below)
+- **Git** (to clone the repo)
+
+---
+
+## 🚀 Getting Started
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/F3rNaNDEZ57/GraphicsAlgoVisualizer.git
+cd GraphicsAlgoVisualizer
+```
+
+### 2. Create a Virtual Environment
+
+#### macOS / Linux
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+#### Windows (PowerShell)
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+#### Windows (Command Prompt)
+
+```cmd
+python -m venv .venv
+.venv\Scripts\activate.bat
+```
+
+### 3. Install the Package
+
+Install in editable (development) mode so changes take effect immediately:
+
+```bash
+pip install -e ".[dev]"
+```
+
+> **Note:** The `[dev]` extra includes `pytest` for running tests.
+
+### 4. Run the Visualizer
+
+```bash
+pyalgoviz
+```
+
+Or run directly as a module:
+
+```bash
+python -m pyalgoviz.app
+```
+
+---
+
+## 🖥️ Platform-Specific Notes
+
+### macOS
+
+Tkinter is included with the official Python installer from [python.org](https://www.python.org). If you installed Python via Homebrew, you may need to install it separately:
+
+```bash
+brew install python-tk@3.11
+```
+
+### Linux (Debian / Ubuntu)
+
+```bash
+sudo apt update
+sudo apt install python3-tk
+```
+
+### Linux (Fedora)
+
+```bash
+sudo dnf install python3-tkinter
+```
+
+### Linux (Arch)
+
+```bash
+sudo pacman -S tk
+```
+
+### Windows
+
+Tkinter is bundled with the standard Python installer from [python.org](https://www.python.org). No extra steps needed — just make sure to check **"tcl/tk and IDLE"** during installation if using the custom installer.
+
+---
+
+## 🏗️ Project Structure
+
+```
+GraphicsAlgoVisualizer/
+├── src/pyalgoviz/
+│   ├── app.py                  # Entry point
+│   ├── theme.py                # Centralized theme tokens
+│   ├── canvas_types.py         # Side-effect import to register canvas types
+│   ├── plugins.py              # Plugin discovery and loading
+│   ├── preset_loader.py        # TOML preset loader
+│   ├── canvas/                 # Canvas types, renderers, and registry
+│   │   ├── base.py             # Abstract base canvas
+│   │   ├── registry.py         # Canvas type registry
+│   │   ├── grid_canvas.py      # Grid canvas (e.g., Bresenham)
+│   │   ├── array_canvas.py     # Array canvas (e.g., Bubble sort)
+│   │   ├── graph_canvas.py     # Graph canvas (e.g., BFS, Dijkstra)
+│   │   └── tk_*_renderer.py    # Tkinter renderers for each canvas
+│   ├── engine/                 # Step engine and playback state
+│   │   ├── runner.py           # Runs pseudocode on a canvas
+│   │   └── playback.py         # Play/pause/step state machine
+│   ├── pseudocode/             # DSL interpreter
+│   │   ├── interpreter.py      # Pseudocode interpreter
+│   │   ├── builtins_registry.py# Built-in functions (SetCell, Enqueue, etc.)
+│   │   ├── step_event.py       # Step event payloads
+│   │   └── errors.py           # Error types
+│   ├── presets/                 # Bundled TOML algorithm presets
+│   │   ├── bresenham-line.toml
+│   │   ├── bubble-sort.toml
+│   │   ├── bfs-pathfinding.toml
+│   │   └── dijkstra-shortest-path.toml
+│   └── ui/                     # CustomTkinter UI layer
+│       ├── main_window.py      # Main application window
+│       ├── graph_editor_model.py  # Headless graph editor model
+│       └── graph_editor_view.py   # Visual graph editor widget
+├── plugins/                    # Drop-in plugin directory
+│   └── pyalgoviz-heap-canvas/    # Example plugin
+├── tests/                      # Test suite (pytest)
+├── pyproject.toml              # Project metadata and build config
+└── .gitignore
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+pytest
+```
+
+Run with verbose output:
+
+```bash
+pytest -v
+```
+
+Run a specific test file:
+
+```bash
+pytest tests/test_interpreter.py
+```
+
+---
+
+## 📝 Writing a Custom Preset
+
+Presets are `.toml` files that define an algorithm's pseudocode, canvas type, and parameters. Place them in the bundled `src/pyalgoviz/presets/` directory or the user presets directory.
+
+**Example — a simple grid algorithm:**
+
+```toml
+[meta]
+name = "My Algorithm"
+canvas = "grid"
+
+[params]
+width = 20
+height = 20
+
+[source]
+code = """
+for x in Range(0, 10):
+    SetCell(x, x, "visited")
+"""
+```
+
+### Supported Canvas Types
+
+| Canvas  | Use Case                        | Key Builtins                          |
+|---------|---------------------------------|---------------------------------------|
+| `grid`  | 2D grid algorithms              | `SetCell`, `GetCell`, `Mark`          |
+| `array` | Sorting / linear data           | `Swap`, `Compare`, `SetIndex`         |
+| `graph` | Graph traversal / shortest path | `Enqueue`, `Dequeue`, `MarkEdge`      |
+
+---
+
+## 🔌 Plugins
+
+The visualizer supports two plugin mechanisms:
+
+1. **Drop-in plugins** — Place a Python package in the `plugins/` directory. It will be auto-discovered on startup.
+2. **Entry-point plugins** — Register a `pyalgoviz.canvases` entry point in your package's `pyproject.toml`. Installed packages with this entry point are loaded automatically.
+
+See [`plugins/pyalgoviz-heap-canvas/`](plugins/pyalgoviz-heap-canvas/) for a working example.
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Run the tests (`pytest`)
+5. Commit with a descriptive message (`git commit -m "Add my feature"`)
+6. Push to your fork (`git push origin feature/my-feature`)
+7. Open a Pull Request
+
+---
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE) for details.

pyalgoviz-0.1.0/README.md

@@ -0,0 +1,240 @@
+# GraphicsAlgoVisualizer
+
+A pseudocode-driven 2D algorithm visualizer built with Python and CustomTkinter. Write algorithms in a simple DSL, pick a canvas type, and watch them execute step-by-step with animated visuals, speed control, and presentation mode.
+
+---
+
+## ✨ Features
+
+- **Pseudocode DSL** — Write algorithms in a clean, Python-like subset with `for`, `while`, `if/elif/else`, variables, expressions, and built-in functions. No Python knowledge required.
+- **Multiple Canvas Types** — Grid, Array, and Graph canvases with dedicated renderers and built-in operations.
+- **Bundled Algorithm Presets** — Bresenham line drawing, Bubble sort, BFS pathfinding, and Dijkstra's shortest path ship out of the box as TOML presets.
+- **In-App Graph Editor** — Click to add nodes, drag between nodes to create edges, set weights — build custom networks visually.
+- **Step-by-Step Playback** — Play, pause, step forward, adjust speed, and see line-by-line highlighting of the executing pseudocode.
+- **Presentation Mode** — A distraction-free, canvas-only view for demos and classroom walkthroughs.
+- **Theme System** — Centralized theme tokens drive all canvas and UI colors for a consistent look.
+- **Plugin Architecture** — Drop-in and entry-point based plugin loading. Extend the visualizer with custom canvas types (see the bundled `pyalgoviz-heap-canvas` example).
+- **User Presets** — Save your own algorithms as `.toml` preset files and load them from a user presets directory.
+
+---
+
+## 📋 Prerequisites
+
+- **Python 3.11+**
+- **Tkinter** (usually ships with Python; see platform notes below)
+- **Git** (to clone the repo)
+
+---
+
+## 🚀 Getting Started
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/F3rNaNDEZ57/GraphicsAlgoVisualizer.git
+cd GraphicsAlgoVisualizer
+```
+
+### 2. Create a Virtual Environment
+
+#### macOS / Linux
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+#### Windows (PowerShell)
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+#### Windows (Command Prompt)
+
+```cmd
+python -m venv .venv
+.venv\Scripts\activate.bat
+```
+
+### 3. Install the Package
+
+Install in editable (development) mode so changes take effect immediately:
+
+```bash
+pip install -e ".[dev]"
+```
+
+> **Note:** The `[dev]` extra includes `pytest` for running tests.
+
+### 4. Run the Visualizer
+
+```bash
+pyalgoviz
+```
+
+Or run directly as a module:
+
+```bash
+python -m pyalgoviz.app
+```
+
+---
+
+## 🖥️ Platform-Specific Notes
+
+### macOS
+
+Tkinter is included with the official Python installer from [python.org](https://www.python.org). If you installed Python via Homebrew, you may need to install it separately:
+
+```bash
+brew install python-tk@3.11
+```
+
+### Linux (Debian / Ubuntu)
+
+```bash
+sudo apt update
+sudo apt install python3-tk
+```
+
+### Linux (Fedora)
+
+```bash
+sudo dnf install python3-tkinter
+```
+
+### Linux (Arch)
+
+```bash
+sudo pacman -S tk
+```
+
+### Windows
+
+Tkinter is bundled with the standard Python installer from [python.org](https://www.python.org). No extra steps needed — just make sure to check **"tcl/tk and IDLE"** during installation if using the custom installer.
+
+---
+
+## 🏗️ Project Structure
+
+```
+GraphicsAlgoVisualizer/
+├── src/pyalgoviz/
+│   ├── app.py                  # Entry point
+│   ├── theme.py                # Centralized theme tokens
+│   ├── canvas_types.py         # Side-effect import to register canvas types
+│   ├── plugins.py              # Plugin discovery and loading
+│   ├── preset_loader.py        # TOML preset loader
+│   ├── canvas/                 # Canvas types, renderers, and registry
+│   │   ├── base.py             # Abstract base canvas
+│   │   ├── registry.py         # Canvas type registry
+│   │   ├── grid_canvas.py      # Grid canvas (e.g., Bresenham)
+│   │   ├── array_canvas.py     # Array canvas (e.g., Bubble sort)
+│   │   ├── graph_canvas.py     # Graph canvas (e.g., BFS, Dijkstra)
+│   │   └── tk_*_renderer.py    # Tkinter renderers for each canvas
+│   ├── engine/                 # Step engine and playback state
+│   │   ├── runner.py           # Runs pseudocode on a canvas
+│   │   └── playback.py         # Play/pause/step state machine
+│   ├── pseudocode/             # DSL interpreter
+│   │   ├── interpreter.py      # Pseudocode interpreter
+│   │   ├── builtins_registry.py# Built-in functions (SetCell, Enqueue, etc.)
+│   │   ├── step_event.py       # Step event payloads
+│   │   └── errors.py           # Error types
+│   ├── presets/                 # Bundled TOML algorithm presets
+│   │   ├── bresenham-line.toml
+│   │   ├── bubble-sort.toml
+│   │   ├── bfs-pathfinding.toml
+│   │   └── dijkstra-shortest-path.toml
+│   └── ui/                     # CustomTkinter UI layer
+│       ├── main_window.py      # Main application window
+│       ├── graph_editor_model.py  # Headless graph editor model
+│       └── graph_editor_view.py   # Visual graph editor widget
+├── plugins/                    # Drop-in plugin directory
+│   └── pyalgoviz-heap-canvas/    # Example plugin
+├── tests/                      # Test suite (pytest)
+├── pyproject.toml              # Project metadata and build config
+└── .gitignore
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+pytest
+```
+
+Run with verbose output:
+
+```bash
+pytest -v
+```
+
+Run a specific test file:
+
+```bash
+pytest tests/test_interpreter.py
+```
+
+---
+
+## 📝 Writing a Custom Preset
+
+Presets are `.toml` files that define an algorithm's pseudocode, canvas type, and parameters. Place them in the bundled `src/pyalgoviz/presets/` directory or the user presets directory.
+
+**Example — a simple grid algorithm:**
+
+```toml
+[meta]
+name = "My Algorithm"
+canvas = "grid"
+
+[params]
+width = 20
+height = 20
+
+[source]
+code = """
+for x in Range(0, 10):
+    SetCell(x, x, "visited")
+"""
+```
+
+### Supported Canvas Types
+
+| Canvas  | Use Case                        | Key Builtins                          |
+|---------|---------------------------------|---------------------------------------|
+| `grid`  | 2D grid algorithms              | `SetCell`, `GetCell`, `Mark`          |
+| `array` | Sorting / linear data           | `Swap`, `Compare`, `SetIndex`         |
+| `graph` | Graph traversal / shortest path | `Enqueue`, `Dequeue`, `MarkEdge`      |
+
+---
+
+## 🔌 Plugins
+
+The visualizer supports two plugin mechanisms:
+
+1. **Drop-in plugins** — Place a Python package in the `plugins/` directory. It will be auto-discovered on startup.
+2. **Entry-point plugins** — Register a `pyalgoviz.canvases` entry point in your package's `pyproject.toml`. Installed packages with this entry point are loaded automatically.
+
+See [`plugins/pyalgoviz-heap-canvas/`](plugins/pyalgoviz-heap-canvas/) for a working example.
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Run the tests (`pytest`)
+5. Commit with a descriptive message (`git commit -m "Add my feature"`)
+6. Push to your fork (`git push origin feature/my-feature`)
+7. Open a Pull Request
+
+---
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE) for details.

pyalgoviz-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyalgoviz"
+dynamic = ["version"]
+description = "Pseudocode-driven 2D algorithm visualizer"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kavindu Fernando", email = "kavindufernando329@gmail.com" }]
+requires-python = ">=3.11"
+keywords = ["algorithm-visualization", "tkinter", "education", "pseudocode", "dsl"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: X11 Applications",
+    "Intended Audience :: Education",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["customtkinter>=5.2"]
+
+[project.urls]
+Homepage = "https://github.com/F3rNaNDEZ57/GraphicsAlgoVisualizer"
+Repository = "https://github.com/F3rNaNDEZ57/GraphicsAlgoVisualizer"
+Issues = "https://github.com/F3rNaNDEZ57/GraphicsAlgoVisualizer/issues"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+pyalgoviz = "pyalgoviz.app:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pyalgoviz = ["presets/*.toml"]
+
+[tool.setuptools.dynamic]
+version = { attr = "pyalgoviz.__version__" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pyalgoviz-0.1.0/setup.cfg

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

pyalgoviz-0.1.0/src/pyalgoviz/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pyalgoviz-0.1.0/src/pyalgoviz/app.py

@@ -0,0 +1,8 @@
+def main() -> None:
+    from pyalgoviz.ui.main_window import launch
+
+    launch()
+
+
+if __name__ == "__main__":
+    main()

pyalgoviz-0.1.0/src/pyalgoviz/canvas/array_canvas.py

@@ -0,0 +1,65 @@
+"""Array/bars visualization model for sorting-family algorithms. No
+rendering/GUI dependency. The canvas owns the values being visualized —
+pseudocode reads/mutates them only through builtins (Value, SetValue, Swap,
+Compare), never through a raw Python list variable.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+
+class ArrayCanvas:
+    def __init__(self, values: list[int]):
+        self._initial_values = list(values)
+        self.values: list[int] = list(values)
+        self._change_listeners: list[Callable[[], None]] = []
+        self._highlight_listeners: list[Callable[[list[int], str], None]] = []
+
+    def on_change(self, listener: Callable[[], None]) -> None:
+        self._change_listeners.append(listener)
+
+    def on_highlight(self, listener: Callable[[list[int], str], None]) -> None:
+        self._highlight_listeners.append(listener)
+
+    def detach_listeners(self) -> None:
+        """Drops every registered listener -- used when a renderer bound to
+        this canvas is being replaced (e.g. presentation-mode zoom), so the
+        old renderer's now-destroyed Tk widget doesn't keep getting notified
+        alongside the new one."""
+        self._change_listeners.clear()
+        self._highlight_listeners.clear()
+
+    def get(self, i: int) -> int:
+        return self.values[int(i)]
+
+    def length(self) -> int:
+        return len(self.values)
+
+    def set_value(self, i: int, value: int) -> None:
+        i = int(i)
+        self.values[i] = value
+        self._notify_change()
+        self._notify_highlight([i], "write")
+
+    def swap(self, i: int, j: int) -> None:
+        i, j = int(i), int(j)
+        self.values[i], self.values[j] = self.values[j], self.values[i]
+        self._notify_change()
+        self._notify_highlight([i, j], "swap")
+
+    def compare(self, i: int, j: int) -> None:
+        self._notify_highlight([int(i), int(j)], "compare")
+
+    def clear(self) -> None:
+        self.values = list(self._initial_values)
+        self._notify_change()
+        self._notify_highlight([], "clear")
+
+    def _notify_change(self) -> None:
+        for listener in self._change_listeners:
+            listener()
+
+    def _notify_highlight(self, indices: list[int], kind: str) -> None:
+        for listener in self._highlight_listeners:
+            listener(indices, kind)

pyalgoviz-0.1.0/src/pyalgoviz/canvas/array_type.py

@@ -0,0 +1,28 @@
+"""Registers the "array" canvas type."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .array_canvas import ArrayCanvas
+from .registry import CanvasType, ParamSpec, register
+from .tk_array_renderer import TkArrayRenderer
+
+DEFAULT_VALUES = [8, 3, 9, 1, 6, 4, 7, 2, 5]
+
+
+def _make_canvas(params: dict[str, Any]) -> ArrayCanvas:
+    values = params.get("values", DEFAULT_VALUES)
+    return ArrayCanvas([int(v) for v in values])
+
+
+ARRAY_CANVAS_TYPE = CanvasType(
+    id="array",
+    canvas_params=[ParamSpec("values", "int_list", default=DEFAULT_VALUES, label="Values")],
+    make_canvas=_make_canvas,
+    viz_builtins={"Swap": "swap", "SetValue": "set_value", "Compare": "compare"},
+    plain_builtins={"Value": "get", "Length": "length"},
+    renderers={"tk": TkArrayRenderer},
+)
+
+register(ARRAY_CANVAS_TYPE)