⚡ PyViz Tutor

A modern, offline execution visualizer for Python. Trace your code step-by-step in a beautiful, dark-mode interface.

🚀 What is it?

PyViz Tutor is a CLI tool that works like https://pythontutor.com/ 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. Perfect for debugging algorithms, teaching programming concepts, or understanding complex logic with a VS Code-inspired visual interface.

✨ Features

• 🔒 100% Offline: No data leaves your machine. Everything runs locally.
• 🎨 Modern UI: Beautiful Dark Mode interface inspired by modern IDEs.
• 📦 Zero-Dependency Output: Generated HTML file has all CSS/JS embedded. Share it easily.
• ⏪ Time Travel: Scrub through execution with slider or play/pause controls.
• 🕵️ Variable Explorer: Watch local variables change state in real-time with color-coded types.
• 🖥️ Standard Output: View print() statements exactly as they appear during execution.

📦 Installation

Install globally using pip or uv:

# Standard way
pip install pyviz-tutor

# Modern, fast way (Recommended)
uv tool install pyviz-tutor

🎮 Usage

Create 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

Your browser will automatically open viz.html showing the trace.

🔧 How it Works

• Tracer: Uses sys.settrace to record interpreter state at every line.
• Serializer: Converts complex objects safely into string representations.
• Bundler: Injects trace data into a pre-built HTML template with a reactive frontend.

🛠️ Development

Want to contribute or modify the source?

# Clone the repo
git clone https://github.com/azmatsiddique/pyviz-tutor.git
cd pyviz-tutor

# Install dependencies using uv
uv venv
uv pip install -e .

# Run tests
pyviz tests/test_script.py

📝 License

Distributed under the MIT License. See LICENSE for details.