PyFlowGraph

View Detailed Test Report - Complete test results with individual test details

A universal, node-based visual scripting editor built with Python and PySide6 that bridges traditional data-flow programming with interactive application development. Create, connect, and execute Python code as nodes using either batch processing for data pipelines or live event-driven execution for interactive applications.

PyFlowGraph implements a hybrid execution model that combines two powerful paradigms:

• Batch Mode: Traditional data-flow execution where the entire graph processes data sequentially based on dependencies - perfect for ETL pipelines, data transformations, API integrations, and automated workflows
• Live Mode: Event-driven interactive execution with persistent state and real-time event handling - ideal for building webhook handlers, real-time data processing, monitoring dashboards, and reactive automation systems

This dual approach makes PyFlowGraph uniquely versatile - use the same visual programming environment to build everything from complex workflow automations and API integrations to data transformation pipelines and business process automation. The application provides a Qt-based interface for creating and connecting Python functions as nodes in a directed graph, with automatic pin generation from function signatures and type annotations.

The core architecture follows a "Code as Nodes" philosophy where each node contains actual Python code that can be edited in a built-in IDE. Input and output pins are automatically generated by parsing function signatures and type hints, eliminating manual configuration while maintaining type safety. The innovative Markdown-based file format (.md) stores graphs in a human-readable format that can be version controlled, edited manually, and even processed by AI assistants and LLMs.

---

Features

• Dynamic Node Generation: Pins are created automatically by parsing Python function signatures within each node. Type hints (int, str, float, bool, Tuple) define the data type and color of each pin.
• Blueprint-Style Navigation:
• Pan: Right-click + Drag or Middle-click + Drag.
• Zoom: Mouse Wheel Scroll.
• Select/Move: Left-click to select and drag nodes.
• Hybrid Execution Engine:
• Batch Mode: Traditional execution where the entire graph runs sequentially based on data dependencies
• Live Mode: Interactive execution with real-time event handling and persistent state for building interactive applications
• Event-Driven Interactive System: Built-in event system supporting button clicks, timers, value changes, and user input for creating interactive experiences
• Node Grouping System: Visual containers for organizing related nodes with customizable colors, sizes, and transparency. Groups support dynamic membership, resizing, full CRUD operations with Delete key support, and complete undo/redo functionality.
• Complete Undo/Redo System: Command pattern implementation across all operations including node creation/deletion, connections, moves, property changes, and group operations. Multi-level undo with memory management and composite command support.
• Isolated Execution Environment: Each node runs in its own subprocess with isolated virtual environments for maximum security and dependency management
• Mini-IDE Code Editor:
• A modal dialog provides a spacious and professional coding environment.
• Syntax Highlighting for Python with custom color schemes.
• Line Numbering and Smart Auto-Indentation.
• Tab support and professional editing features.
• Advanced Connection Management:
• Reroute Nodes: Double-click a connection to create a reroute node for better graph organization.
• Connection Replacement: Dragging a new wire to an already connected input pin automatically replaces the old connection.
• Type-Safe Connections: Pin colors indicate data types for visual type checking.
• Intelligent Clipboard System:
• Copy (Ctrl+C) and paste (Ctrl+V) multiple nodes and groups with preserved relationships.
• Internal connections between copied nodes are maintained automatically.
• Smart positioning system offsets pasted nodes based on cursor location.
• Group-aware copy/paste operations maintain group membership.
• Professional UI/UX:
• Custom Dark Theme: Consistent, modern QSS stylesheet throughout the application.
• Font Awesome Integration: Professional iconography for all UI elements.
• Blueprint-Style Navigation: Industry-standard node editor interaction patterns.
• Robust Persistence: Graphs serialize to human-readable Markdown format with embedded metadata, making files both machine-readable and easily editable by humans. Full state preservation including node positions, connections, code, group definitions, and environment requirements. All file operations use UTF-8 encoding for proper international character support.
• Dynamic Interface: Window title automatically updates to display the current graph name for better project identification.

---

Markdown File Format

PyFlowGraph uses a innovative Markdown-based file format (.md) that combines human readability with structured data storage. This format makes graphs both machine-readable for the application and easily editable by humans or AI assistants. The format includes embedded metadata for node positions, connections, and execution requirements while presenting the code in a clean, readable format.

For detailed information about the file format specification, see flow_spec.md.

Example Graphs

The examples/ directory contains sample graphs demonstrating various capabilities:

• data_analysis_dashboard.md - Interactive data visualization dashboard
• file_organizer_automation.md - Automated file organization system
• interactive_game_engine.md - Interactive game with event-driven execution
• password_generator_tool.md - Secure password generation utility
• password_generator_tool_group.md - Password generator with group organization demonstration
• personal_finance_tracker.md - Personal finance management system
• recipe_nutrition_calculator.md - Recipe analysis and nutrition calculator
• social_media_scheduler.md - Social media content scheduling tool
• text_processing_pipeline.md - Advanced text processing workflow
• weather_data_processor.md - Weather data analysis and processing

---

Screenshots

Mini-IDE Code Editor

The integrated Python code editor provides a professional development environment within PyFlowGraph. Features include syntax highlighting with custom color schemes, line numbering, smart auto-indentation, and tab support. The modal dialog design gives developers ample space to write and edit node logic while maintaining the visual context of the graph workflow.

Python Environment Manager

The Python Environment Manager dialog enables sophisticated dependency management for each graph project. Users can specify custom pip requirements that are automatically installed in isolated virtual environments. This ensures each graph has its own clean dependency space, preventing conflicts between different projects while maintaining security through subprocess isolation.

Node Properties Dialog

The Node Properties dialog provides comprehensive configuration options for individual nodes. Users can modify node appearance, behavior settings, and metadata through an intuitive interface. This dialog supports real-time property updates and integrates seamlessly with the undo/redo system for reliable editing workflows.

Node History Dialog

The Node History dialog provides complete visibility into node evolution and changes over time. Users can review edit history, compare different versions of node code, and track modifications through an intuitive timeline interface. This feature supports development workflow tracking and enables easy rollback to previous node states.

Project Structure

The project is organized into modular, single-responsibility Python files:

Core Application Files

• src/main.py: The main entry point for the application. Handles application setup and loads the stylesheet.
• dark_theme.qss: The global Qt Style Sheet that defines the application's dark theme.

Core Engine (src/core/)

• node_graph.py: The QGraphicsScene that manages all nodes, connections, groups, and clipboard logic.
• node.py: Defines the main Node class, including visual appearance and Python code parsing for pin generation.
• pin.py: Defines the input/output pins on nodes with type-safe connections.
• connection.py: Defines the visual Bezier curve connections between pins.
• reroute_node.py: Special organizational nodes for managing connection routing.
• group.py: Visual container system for organizing related nodes with customizable appearance.

User Interface (src/ui/)

• editor/node_editor_window.py: Main QMainWindow hosting all UI elements.
• editor/node_editor_view.py: QGraphicsView handling mouse/keyboard interactions (pan, zoom, copy/paste).
• dialogs/: All dialog components including code editor, settings, node properties, and group management.
• code_editing/: Python code editor with syntax highlighting and smart indentation.

Execution & Environment (src/execution/)

• graph_executor.py: Engine that executes node graphs based on data dependencies.
• environment_manager.py: Virtual environment management for graph-specific dependencies.
• execution_controller.py: Controls batch and live mode execution with subprocess isolation.

Command System (src/commands/)

• Command pattern implementation for comprehensive undo/redo functionality
• node/: Node-specific operations (create, delete, move, property changes)
• Group commands: create, delete, resize, property management
• Connection and reroute commands with full state preservation

Utilities & Configuration

• color_utils.py: Color manipulation utilities for the interface.
• environment_manager.py: Virtual environment management dialog for graph-specific dependencies.
• settings_dialog.py: Application settings configuration interface.
• node_properties_dialog.py: Node property editing interface.
• run.sh / run.bat: Helper scripts for running the application within its virtual environment.
• run_test_gui.bat: Professional GUI test runner launcher.

---

Running the Pre-compiled Version (Windows)

This is the easiest way to run the application without needing to install Python or any dependencies.

1. Go to the Releases Page on GitHub.
2. Find the latest release and download the .zip file (e.g., NodeEditor_Windows_v1.0.0.zip).
3. Unzip the downloaded file to a location of your choice. This will create a new folder.
4. Open the new folder and run the main.exe executable.
5. To test the application, go to File > Load Graph... and open one of the .md files from the examples folder.

---

Setup and Installation

1. Clone the Repository:

   bash git clone [https://github.com/bhowiebkr/PyFlowGraph.git](https://github.com/bhowiebkr/PyFlowGraph.git) cd PyFlowGraph

2. Create a Virtual Environment:

   bash python3 -m venv venv

3. Activate the Environment:

   • On Linux/macOS: source venv/bin/activate
   • On Windows: venv\Scripts\activate

4. Install Dependencies:

   bash pip install PySide6

5. Run the Application: Use the provided scripts, which will automatically activate the environment and run the main script.

   Linux/macOS:

   bash ./run.sh

   Windows:

   cmd run.bat

---

Quick Start Guide

Basic Operations

• Create a Node: Right-click on the canvas and select "Add Node"
• Edit Node Logic: Click the "Edit Code" button on a node to open the integrated code editor
• Connect Nodes: Click and drag from an output pin (right side) to an input pin (left side)
• Navigate:
• Pan: Right-click + drag or middle-click + drag
• Zoom: Mouse wheel scroll
• Select/Move: Left-click to select and drag nodes
• Delete Items: Select any node, reroute node, connection, or group and press Delete
• Execute Graph:
• Batch Mode: Press F5 or use "Run > Execute Graph" menu