pyviz-tutor 0.1.1

A CLI tool to visualize Python code execution locally.

⚡ PyViz TutorA modern, offline execution visualizer for Python. Trace your code step-by-step in a beautiful, dark-mode interface.Report Bug · Request Feature

🚀 What is it?PyViz Tutor is a CLI tool that works like "Python Tutor" but runs entirely on your local machine.It executes your Python script, captures the line-by-line execution flow (variables, stack, output), and generates a single, self-contained HTML file. You can debug algorithms, teach programming concepts, or simply understand complex logic with a VS Code-inspired visual interface.✨ Features🔒 100% Offline: No data leaves your machine. Everything runs locally.🎨 Modern UI: A beautiful Dark Mode interface inspired by modern IDEs.📦 Zero-Dependency Output: The generated HTML file has all CSS/JS embedded. You can email it to a student or friend, and it just works.⏪ Time Travel: Scrub through your code execution with a slider or play/pause controls.🕵️ Variable Explorer: See local variables change state in real-time with color-coded types.🖥️ Standard Output: View print() statements exactly as they appear during execution.📦 InstallationInstall it globally using pip or uv:# The standard way pip install pyviz-tutor

The modern, fast way (Recommended)

uv tool install pyviz-tutor 🎮 UsageCreate a Python script (e.g., recursion.py):def factorial(n): if n == 0: return 1 return n * factorial(n-1)

print(factorial(5)) Run the visualizer:pyviz recursion.py That's it! Your browser will automatically open viz.html showing the trace.🔧 How it WorksPyViz uses Python's advanced sys.settrace hook to record the state of the interpreter at every line of code.Tracer: The Python engine executes your code and records a "snapshot" of every step (line number, local variables, stdout).Serializer: It handles complex objects safely (converting non-serializable objects like sockets or file handles into string representations).Bundler: It injects this trace data directly into a pre-built HTML template containing a Vue-like reactive frontend.🛠️ DevelopmentIf you want to contribute or modify the source:# Clone the repo git clone https://github.com/yourusername/pyviz-tutor.git cd pyviz-tutor

Install dependencies using uv

uv venv uv pip install -e .

Run tests

pyviz tests/test_script.py 📝 LicenseDistributed under the MIT License. See LICENSE for more information.

Built with ❤️ by [Your Name]