# ⚡ 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**:

```bash
# Standard way
pip install pyviz-tutor

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

---

## 🎮 Usage  

Create a Python script (e.g., `recursion.py`):

```python
def factorial(n):
    if n == 0: return 1
    return n * factorial(n-1)

print(factorial(5))
```

Run the visualizer:

```bash
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?

```bash
# 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.

---

<div align="center">Built with ❤️ by Azmat</div>
