Metadata-Version: 2.4
Name: explainflow
Version: 0.1.0
Summary: Code Execution Visualizer & Explainer - Generate step-by-step visual explanations of Python code
Author-email: DevaVirathan <devavirathan.mahalingam@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/DevaVirathan/explainflow
Project-URL: Documentation, https://github.com/DevaVirathan/explainflow#readme
Project-URL: Repository, https://github.com/DevaVirathan/explainflow
Project-URL: Issues, https://github.com/DevaVirathan/explainflow/issues
Keywords: education,visualization,code-explanation,debugging,teaching,learning,python-tutor,step-by-step
Classifier: Development Status :: 3 - Alpha
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow>=10.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: video
Requires-Dist: imageio>=2.31.0; extra == "video"
Requires-Dist: imageio-ffmpeg>=0.4.8; extra == "video"
Provides-Extra: cli
Requires-Dist: typer>=0.9.0; extra == "cli"
Provides-Extra: all
Requires-Dist: explainflow[cli,dev,video]; extra == "all"
Dynamic: license-file

# ExplainFlow 🔍

**Code Execution Visualizer & Explainer** - Generate step-by-step visual explanations of Python code execution.

[![PyPI version](https://badge.fury.io/py/explainflow.svg)](https://badge.fury.io/py/explainflow)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

## ✨ Features

- 🎯 **Step-by-step execution tracing** - See exactly what happens at each line
- 📊 **Variable state visualization** - Track how variables change over time
- 🖼️ **Export to images** - Generate PNG diagrams for documentation
- 🎬 **Export to GIF/video** - Create animated explanations for tutorials
- 🎨 **Beautiful terminal output** - Rich console visualization
- 📝 **Memory diagrams** - Visualize object references and data structures
- 🔄 **Loop unwinding** - See each iteration of loops clearly
- 📚 **Perfect for teaching** - Create educational content effortlessly

## 🚀 Installation

```bash
pip install explainflow
```

For video export support:
```bash
pip install explainflow[video]
```

For CLI support:
```bash
pip install explainflow[cli]
```

Install everything:
```bash
pip install explainflow[all]
```

## 📖 Quick Start

### Basic Usage

```python
from explainflow import explain

# Explain a simple code snippet
code = '''
x = 5
y = 10
result = x + y
print(result)
'''

# Generate step-by-step explanation
explain(code)
```

### Export to Image

```python
from explainflow import explain, export_image

code = '''
numbers = [1, 2, 3, 4, 5]
total = 0
for n in numbers:
    total += n
print(total)
'''

# Generate and export as image
trace = explain(code, output="silent")
export_image(trace, "loop_explanation.png")
```

### Export to GIF

```python
from explainflow import explain, export_gif

code = '''
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

result = factorial(5)
'''

trace = explain(code, output="silent")
export_gif(trace, "factorial.gif", fps=1)
```

### Using the Decorator

```python
from explainflow import trace

@trace
def bubble_sort(arr):
    n = len(arr)
    for i in range(n):
        for j in range(0, n-i-1):
            if arr[j] > arr[j+1]:
                arr[j], arr[j+1] = arr[j+1], arr[j]
    return arr

# This will automatically trace and explain the execution
bubble_sort([64, 34, 25, 12, 22, 11, 90])
```

## 🖥️ CLI Usage

```bash
# Explain a Python file
explainflow run mycode.py

# Export as image
explainflow run mycode.py --output explanation.png

# Export as GIF
explainflow run mycode.py --output explanation.gif --fps 2

# Watch mode - re-run on file changes
explainflow watch mycode.py
```

## 📚 Use Cases

### For Students
- Understand how loops and recursion work
- Debug your code visually
- Study algorithm execution step-by-step

### For Teachers
- Create visual explanations for lectures
- Generate diagrams for assignments
- Build interactive tutorials

### For Documentation
- Add visual code explanations to docs
- Create GIFs for README files
- Generate step-by-step guides

### For Debugging
- Trace variable changes
- Understand control flow
- Find logic errors visually

## 🛠️ API Reference

### Core Functions

#### `explain(code, output="rich", max_steps=1000)`
Execute and explain code step-by-step.

- `code`: Python code string to explain
- `output`: Output mode - "rich" (terminal), "silent", "simple"
- `max_steps`: Maximum execution steps to trace
- Returns: `ExecutionTrace` object

#### `export_image(trace, filename, theme="dark")`
Export execution trace as a PNG image.

#### `export_gif(trace, filename, fps=1, theme="dark")`
Export execution trace as an animated GIF.

#### `@trace` decorator
Decorator to automatically trace function execution.

## 🎨 Themes

ExplainFlow supports multiple themes:
- `dark` (default) - Dark background, easy on eyes
- `light` - Light background for printing
- `colorblind` - Accessible color scheme

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by [Python Tutor](http://pythontutor.com/)
- Built with [Rich](https://github.com/Textualize/rich) for beautiful terminal output
- Uses [Pillow](https://python-pillow.org/) for image generation

## 📬 Contact

- Create an issue for bug reports or feature requests
- Star ⭐ the repo if you find it useful!

---

Made with ❤️ for the Python community
