explainflow 0.1.0

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

ExplainFlow 🔍

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

✨ 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

pip install explainflow

For video export support:

pip install explainflow[video]

For CLI support:

pip install explainflow[cli]

Install everything:

pip install explainflow[all]

📖 Quick Start

Basic Usage

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

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

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

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

# 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 file for details.

🙏 Acknowledgments

• Inspired by Python Tutor
• Built with Rich for beautiful terminal output
• Uses Pillow 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