FlowSight

FlowSight is a standalone Python GUI application designed for educators and students learning Python programming. It provides an interactive environment where users can visualize code execution, track variable values, and understand control flow in real-time. FlowSight aims to enhance the learning experience by making abstract programming concepts more tangible and accessible.

Features

FlowSight includes five main panels arranged in an intuitive layout:

1. Control Panel (top horizontal strip): Play, pause, step through, and stop code execution. Includes speed control for adjusting execution pace.
2. Code Editor Panel (top-left): Write or paste Python code with syntax highlighting and line numbering for better readability.
3. Visualization Panel (top-right): View a graphical flowchart representation of code execution. Each line of code correlates to exactly one block on the diagram.
4. Variable Tracker Panel (bottom-right): Monitor variable values in real-time with automatic highlighting of changes.
5. Output Panel (bottom-left): View output from print statements and error messages.

Installation

Prerequisites

• Python 3.8 or higher
• tkinter (usually included with Python)
• Graphviz (required for flowchart layout)

Linux/Ubuntu

If tkinter is not installed:

sudo apt-get update
sudo apt-get install python3-tk

macOS

tkinter is typically included with Python on macOS. If needed, install using:

brew install python-tk

Windows

tkinter is included with the standard Python installation from python.org.

Setup

1. Clone this repository:

git clone https://github.com/tmaier-kettering/FlowSight.git
cd FlowSight

2. Install Graphviz (Required for flowchart layout):

Linux/Ubuntu:

sudo apt-get install graphviz
pip install graphviz

macOS:

brew install graphviz
pip install graphviz

Windows:

• Download and install Graphviz from https://graphviz.org/download/
• Add Graphviz to your PATH
• Run: pip install graphviz

3. Verify installation:

dot -V  # Should show Graphviz version

Running FlowSight

Easy Start (Recommended)

Linux/macOS:

./flowsight.sh

Windows:

flowsight.bat

Alternative Methods

Run the application using:

python3 run_flowsight.py

Or directly:

python3 -m src.flowsight.main

Or from the src directory:

cd src
python3 -m flowsight.main

Usage

1. Write Code: Enter your Python code in the Code Editor Panel
2. Generate Flowchart: Click the "Sync" button in the Visualization Panel to create the flowchart
3. Execute:
   • Click "Play" to run the code automatically
   • Click "Step" to execute one line at a time
   • Click "Pause" to pause during execution
   • Click "Stop" to reset and start over
4. Adjust Speed: Change the speed value (in seconds) to control execution pace
5. Monitor: Watch the Variable Tracker and Output panels update in real-time

Example Programs

FlowSight includes several example programs in the examples/ directory:

• variables.py - Variable assignments and basic calculations
• simple_loop.py - Simple for loop with accumulation
• while_loop.py - While loop demonstration
• conditionals.py - If/elif/else statements
• nested_loops.py - Nested loops creating a multiplication table
• factorial.py - Recursive factorial function
• fibonacci.py - Fibonacci sequence with while loop
• prime_numbers.py - Finding prime numbers with nested loops

To try an example, copy the code from an example file and paste it into the Code Editor.

Project Structure

FlowSight/
├── src/
│   └── flowsight/
│       ├── __init__.py
│       ├── main.py                    # Main application entry point
│       ├── panels/                    # UI panel components
│       │   ├── __init__.py
│       │   ├── control_panel.py       # Execution controls
│       │   ├── code_editor.py         # Code editor with syntax highlighting
│       │   ├── visualization.py       # Flowchart visualization
│       │   ├── variable_tracker.py    # Variable monitoring
│       │   └── output.py              # Output display
│       └── engine/                    # Core logic
│           ├── __init__.py
│           ├── execution_engine.py    # Code execution engine
│           └── flowchart_generator.py # Flowchart generation
├── run_flowsight.py                   # Launcher script
├── requirements.txt                   # Dependencies (none needed!)
└── README.md                          # This file

Technical Details

• GUI Framework: tkinter (Python standard library)
• Code Execution: Step-by-step execution with namespace isolation
• Flowchart Generation: Follows the conversion rules in code_to_flowchart/code_to_flowchart_conversion.md
• Flowchart Layout: Uses Graphviz automatic layout engine for optimal positioning and minimal overlaps. Provides professional-quality graph layouts.
• Syntax Highlighting: Custom regex-based syntax highlighting for Python keywords, strings, comments, and numbers

Building Standalone Executable

FlowSight can be bundled as a standalone .exe that includes all dependencies, including Graphviz binaries. See BUILD_GUIDE.md for detailed instructions.

Quick build:

pip install pyinstaller
pyinstaller flowsight.spec

The resulting executable will include Graphviz, so end users don't need to install anything!

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

License

This project is open source and available under the MIT License.