Skip to content

Commit c04d1b2

Browse files
bhowiebkrBryan Howard
bhowiebkr
and
Bryan Howard
authored
Epic: Next Feature Development - Build System and Documentation Improvements (#46)
* Refactor documentation structure with organized directories - Restructured docs into logical categories: developer_guide, implementation, issues, project, reference, user_guide - Updated README.md and prd.md with current project state - Improved documentation organization for better navigation and maintenance 🤖 Generated with [Claude Code](https://claude.ai/code) * Fix CommandHistory method call error in code editor Replace incorrect 'push()' calls with 'execute_command()' in: - CodeEditorDialog: Fix AttributeError when accepting code changes - Test files: Update mock assertions to use correct method Resolves error: 'CommandHistory' object has no attribute 'push' 🤖 Generated with [Claude Code](https://claude.ai/code) * Fix connection deserialization for nodes with named output pins Resolves issue where graphs using @outputs: docstring annotations failed to execute due to ambiguous pin name resolution during connection creation. Changes: - Add get_pin_by_name_and_direction() method to Node class for precise pin lookup - Update NodeGraph.deserialize() to use direction-aware pin resolution - Ensure start pins are always output pins and end pins are input pins - Maintain backward compatibility with existing graphs This enables human-readable pin names from docstring @outputs: annotations while preserving reliable connection resolution between nodes. 🤖 Generated with [Claude Code](https://claude.ai/code) * Update password generator example with named output pins and enhanced pin display - Add @outputs: docstring annotations to all functions in password generator example - Remove UUID references from connections for cleaner human-readable format - Update connection names to use semantic pin names instead of generic output_N - Add pin type display functionality with settings-based visibility control - Update GUI handler to use named output 'result' instead of 'output_1' This demonstrates the working implementation of named output pins and provides a cleaner, more maintainable graph format without embedded UUIDs. 🤖 Generated with [Claude Code](https://claude.ai/code) * Add pin type visibility settings and named output examples Settings Enhancement: - Add checkbox in Settings dialog for toggling pin type display - Implement refresh_pin_labels() to update all pins when settings change - Save show_pin_types setting with default value true Pin Display Updates: - Pin labels can now show/hide type information (e.g., 'length (int)') - Dynamic updates when user changes the setting via Settings dialog - Maintains clean display option for users who prefer minimal UI Example Files: - Add named_output_example.md demonstrating @outputs: docstring usage - Add named_output_test.md for testing named output functionality - Provides reference implementations for future graph development This completes the named output pins feature with full UI integration and comprehensive examples for developers. 🤖 Generated with [Claude Code](https://claude.ai/code) * Fix pin renaming to preserve connections when editing docstring outputs Resolves issue where editing @outputs: names in entry point node docstrings caused pins to disappear instead of being renamed with connections preserved. Changes: - Add rename_pin() method to update pin names while preserving connections - Implement _update_data_pins() with position-based pin matching algorithm - Replace naive pin removal/recreation with intelligent pin updates - Preserve connections, pin types, and visual properties during renames Pin Update Logic: - Match pins by position/index rather than name for reliable updates - Rename existing pins when docstring names change - Add new pins only when count increases - Remove pins only from the end when count decreases - Maintain all existing connections and properties This enables seamless editing of @outputs: annotations without losing graph connectivity or requiring manual reconnection of pins. 🤖 Generated with [Claude Code](https://claude.ai/code) * Fix pin type updates and label refresh when editing function signatures Ensures that when pin types are changed in function annotations, both the pin type property and visual labels are updated correctly. Changes: - Detect pin type changes during pin updates - Update pin.pin_type when function signature types change - Call update_label_text() to refresh visual display with new type - Handle both name and type changes in the same update cycle Test Results: - Pin type changes: str->int, int->float, complex types (List, Dict) ✓ - Label updates: "Data (str)" -> "Data (int)" correctly ✓ - Connection preservation: Connections maintained through type changes ✓ - Input pin types: Function parameter type changes working ✓ This completes the pin editing experience - users can now edit both @outputs: names and function signature types seamlessly with full visual feedback and connection preservation. 🤖 Generated with [Claude Code](https://claude.ai/code) * Update examples with named output pins and fix connection issues - Add @outputs annotations to all example node functions for proper named pin support - Fix connection pin names in weather_data_processor.md, nvidia_gpu_computer_vision_pipeline.md, and recipe_nutrition_calculator.md - Update recipe_nutrition_calculator.md with complete GUI state handlers and example recipe - Add file dialog folder memory functionality to remember last used directory - Ensure proper data flow through all example pipelines with correct named pin connections 🤖 Generated with [Claude Code](https://claude.ai/code) * Clean up examples directory by removing outdated example files Remove example files that were not updated with named output pin support: - Procedural_Sci-Fi_World_Generator.md - data_analysis_dashboard.md - file_organizer_automation.md - interactive_game_engine.md - named_output_example.md - named_output_test.md - password_generator_tool.md - personal_finance_tracker.md - social_media_scheduler.md - text_processing_pipeline.md Keeping core examples that have been updated with proper @outputs annotations: - password_generator_tool_group.md - weather_data_processor.md - nvidia_gpu_computer_vision_pipeline.md - recipe_nutrition_calculator.md 🤖 Generated with [Claude Code](https://claude.ai/code) * Fix build script errors and organize builds into single directory - Fix syntax errors in user prompts that caused batch script failures - Remove interactive prompts to enable automated builds - Organize all build artifacts into builds/ directory structure - Fix PowerShell download command for Python runtime - Update deprecated Nuitka console option to modern syntax - Add python runtime validation to ensure Lib directory exists - Remove manual exit prompt for automated workflow - Add builds/ to .gitignore to prevent build artifact commits 🤖 Generated with [Claude Code](https://claude.ai/code) --------- Co-authored-by: Bryan Howard <[email protected]>
1 parent 3fbbd27 commit c04d1b2

File tree

65 files changed

+13889
-5055
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+13889
-5055
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ __pycache__/
99
# Distribution / packaging
1010
.Python
1111
build/
12+
builds/
1213
develop-eggs/
1314
dist/
1415
downloads/

‎build_local.bat‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
@echo off
2+
setlocal enabledelayedexpansion
3+
4+
echo ===============================================
5+
echo PyFlowGraph Local Build Script
6+
echo ===============================================
7+
echo.
8+
9+
REM Check if we're in the correct directory
10+
if not exist "src\main.py" (
11+
echo ERROR: main.py not found in src directory
12+
echo Please run this script from the PyFlowGraph root directory
13+
pause
14+
exit /b 1
15+
)
16+
17+
if not exist "requirements.txt" (
18+
echo ERROR: requirements.txt not found
19+
echo Please run this script from the PyFlowGraph root directory
20+
pause
21+
exit /b 1
22+
)
23+
24+
echo [1/6] Checking prerequisites...
25+
26+
REM Check if Python is installed
27+
python --version >nul 2>&1
28+
if errorlevel 1 (
29+
echo ERROR: Python is not installed or not in PATH
30+
echo Please install Python 3.11 or later
31+
pause
32+
exit /b 1
33+
)
34+
35+
REM Check if zstd is available (needed for runtime download)
36+
zstd --version >nul 2>&1
37+
if errorlevel 1 (
38+
echo WARNING: zstd not found. You may need to install it for Python runtime download.
39+
echo You can install it with: choco install zstandard
40+
echo Or download manually from: https://facebook.github.io/zstd/
41+
echo Continuing without zstd - will try PowerShell for decompression...
42+
)
43+
44+
echo [2/6] Installing/updating dependencies...
45+
pip install -r requirements.txt
46+
if errorlevel 1 (
47+
echo ERROR: Failed to install dependencies
48+
pause
49+
exit /b 1
50+
)
51+
52+
echo [3/6] Preparing Portable Python Runtime...
53+
54+
REM Check if python_runtime already exists
55+
if exist "python_runtime" (
56+
echo Python runtime already exists, skipping download...
57+
goto :build_app
58+
)
59+
60+
echo Downloading Python runtime (this may take a while)...
61+
set "PYTHON_URL=https://github.com/astral-sh/python-build-standalone/releases/download/20250808/cpython-3.11.13+20250808-x86_64-pc-windows-msvc-pgo-full.tar.zst"
62+
63+
REM Download using PowerShell with better error handling
64+
powershell -Command "try { Write-Host 'Downloading Python runtime...'; Invoke-WebRequest -Uri '%PYTHON_URL%' -OutFile 'python-standalone.tar.zst' -UseBasicParsing; Write-Host 'Download completed.' } catch { Write-Host 'ERROR: Failed to download Python runtime'; Write-Host $_.Exception.Message; exit 1 }"
65+
if errorlevel 1 goto :error
66+
67+
REM Verify download was successful
68+
if not exist "python-standalone.tar.zst" (
69+
echo ERROR: Download failed - python-standalone.tar.zst not found
70+
goto :error
71+
)
72+
73+
echo Decompressing Python runtime...
74+
zstd -d python-standalone.tar.zst -o python-standalone.tar >nul 2>&1
75+
if errorlevel 1 (
76+
echo ERROR: Failed to decompress runtime with zstd
77+
echo Please install zstd using one of these methods:
78+
echo choco install zstandard
79+
echo winget install Facebook.zstd
80+
echo scoop install zstd
81+
echo Or download from: https://facebook.github.io/zstd/
82+
goto :error
83+
)
84+
85+
REM Verify decompression was successful
86+
if not exist "python-standalone.tar" (
87+
echo ERROR: Decompression failed - python-standalone.tar not found
88+
goto :error
89+
)
90+
91+
echo Extracting Python runtime...
92+
tar -xf python-standalone.tar
93+
if errorlevel 1 (
94+
echo ERROR: Failed to extract tar file
95+
goto :error
96+
)
97+
98+
REM Verify extraction was successful
99+
if not exist "python\install" (
100+
echo ERROR: Extraction failed - python\install directory not found
101+
goto :error
102+
)
103+
104+
echo Moving Python runtime to final location...
105+
if not exist "python_runtime" mkdir python_runtime
106+
echo Copying Python runtime files with all subdirectories...
107+
robocopy "python\install" "python_runtime" /E /NP /NFL /NDL
108+
if errorlevel 8 (
109+
echo ERROR: Failed to copy Python runtime files
110+
goto :error
111+
)
112+
113+
REM Verify critical directories exist
114+
if not exist "python_runtime\Lib" (
115+
echo ERROR: Python runtime missing Lib directory - extraction incomplete
116+
echo Contents of python_runtime:
117+
dir "python_runtime" /B
118+
goto :error
119+
)
120+
121+
REM Clean up temporary files
122+
if exist "python" rmdir /s /q "python" >nul 2>&1
123+
if exist "python-standalone.tar.zst" del "python-standalone.tar.zst" >nul 2>&1
124+
if exist "python-standalone.tar" del "python-standalone.tar" >nul 2>&1
125+
126+
echo Python runtime prepared successfully.
127+
128+
:build_app
129+
echo [4/6] Building application with Nuitka...
130+
131+
REM Create builds directory if it doesn't exist
132+
if not exist "builds" mkdir builds
133+
134+
REM Clean previous build
135+
if exist "builds\NodeEditor_Build" (
136+
echo Cleaning previous build...
137+
rmdir /s /q "builds\NodeEditor_Build"
138+
if exist "builds\NodeEditor_Build" (
139+
echo ERROR: Could not remove previous build directory
140+
goto :error
141+
)
142+
)
143+
144+
echo Running Nuitka build (this will take several minutes)...
145+
if not exist "src" (
146+
echo ERROR: src directory not found
147+
goto :error
148+
)
149+
150+
cd src
151+
python -m nuitka ^
152+
--standalone ^
153+
--enable-plugin=pyside6 ^
154+
--include-qt-plugins=platforms ^
155+
--output-dir=../builds/NodeEditor_Build ^
156+
--output-filename=PyFlowGraph.exe ^
157+
--nofollow-import-to=tkinter,unittest,setuptools,pip,wheel ^
158+
--windows-console-mode=disable ^
159+
--remove-output ^
160+
--lto=yes ^
161+
--include-data-dir=../examples=examples ^
162+
--include-data-dir=resources=resources ^
163+
--include-data-file=../dark_theme.qss=dark_theme.qss ^
164+
--assume-yes-for-downloads ^
165+
main.py
166+
167+
set NUITKA_RESULT=%ERRORLEVEL%
168+
cd ..
169+
170+
if %NUITKA_RESULT% neq 0 (
171+
echo ERROR: Nuitka build failed with exit code %NUITKA_RESULT%
172+
goto :error
173+
)
174+
175+
echo [5/6] Copying Python runtime to build...
176+
177+
set "DIST_DIR=builds\NodeEditor_Build\main.dist"
178+
179+
if not exist "%DIST_DIR%" (
180+
echo ERROR: Expected Nuitka output directory not found: %DIST_DIR%
181+
echo Available directories in builds\NodeEditor_Build:
182+
if exist "builds\NodeEditor_Build" dir "builds\NodeEditor_Build" /B
183+
goto :error
184+
)
185+
186+
if not exist "%DIST_DIR%\PyFlowGraph.exe" (
187+
echo ERROR: PyFlowGraph.exe not found in build output
188+
echo Contents of %DIST_DIR%:
189+
dir "%DIST_DIR%" /B
190+
goto :error
191+
)
192+
193+
echo Copying python_runtime to build directory...
194+
if not exist "python_runtime" (
195+
echo ERROR: python_runtime directory not found
196+
goto :error
197+
)
198+
199+
robocopy "python_runtime" "%DIST_DIR%\python_runtime" /E /NP /NFL /NDL >nul 2>&1
200+
if errorlevel 8 (
201+
echo ERROR: Failed to copy Python runtime to build directory
202+
goto :error
203+
)
204+
205+
echo [6/6] Finalizing build...
206+
207+
REM Get current timestamp for version using PowerShell with error handling
208+
for /f "tokens=*" %%i in ('powershell -Command "try { Get-Date -Format 'yyyyMMdd-HHmmss' } catch { 'unknown' }"') do set "timestamp=%%i"
209+
210+
if "%timestamp%"=="unknown" (
211+
echo WARNING: Could not get timestamp, using default name
212+
set "timestamp=build"
213+
)
214+
215+
echo Organizing build in builds directory...
216+
217+
set "FINAL_DIR=builds\PyFlowGraph-Windows-local-%timestamp%"
218+
219+
REM Remove existing final directory if it exists
220+
if exist "%FINAL_DIR%" (
221+
echo Removing existing build: %FINAL_DIR%
222+
rmdir /s /q "%FINAL_DIR%"
223+
)
224+
225+
REM Move the build directory to final location
226+
move "%DIST_DIR%" "%FINAL_DIR%" >nul 2>&1
227+
if errorlevel 1 (
228+
echo ERROR: Failed to rename build directory
229+
echo Source: %DIST_DIR%
230+
echo Target: %FINAL_DIR%
231+
goto :error
232+
)
233+
234+
REM Verify the final executable exists
235+
if not exist "%FINAL_DIR%\PyFlowGraph.exe" (
236+
echo ERROR: PyFlowGraph.exe not found in final build directory
237+
goto :error
238+
)
239+
240+
echo.
241+
echo ===============================================
242+
echo BUILD COMPLETED SUCCESSFULLY!
243+
echo ===============================================
244+
echo.
245+
echo All builds are organized in the 'builds' folder
246+
echo Build location: %FINAL_DIR%
247+
echo Executable: %FINAL_DIR%\PyFlowGraph.exe
248+
echo.
249+
echo Contents of build directory:
250+
dir "%FINAL_DIR%" /B
251+
echo.
252+
253+
REM Build completed - showing final information
254+
echo To run PyFlowGraph: %FINAL_DIR%\PyFlowGraph.exe
255+
256+
echo Build complete.
257+
exit /b 0
258+
259+
:error
260+
echo.
261+
echo ===============================================
262+
echo BUILD FAILED!
263+
echo ===============================================
264+
echo Please check the error messages above and try again.
265+
echo.
266+
echo Common solutions:
267+
echo - Install zstd: choco install zstandard
268+
echo - Install Python 3.11+
269+
echo - Install Visual Studio Build Tools
270+
echo - Check internet connection for downloads
271+
echo.
272+
pause
273+
exit /b 1

‎docs/README.md‎

Lines changed: 63 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,80 @@
11
# PyFlowGraph Documentation
22

3-
This directory contains comprehensive documentation for the PyFlowGraph project, organized by purpose and audience.
3+
This directory contains comprehensive documentation for the PyFlowGraph project, organized following BMAD-inspired structure with clear separation between user documentation, developer resources, and technical references.
44

55
## Quick Navigation
66

7-
### For Product Strategy & Planning
8-
- **[PRD](prd.md)** - Product Requirements Document
9-
- **[Roadmap](roadmap.md)** - Feature development roadmap and priorities
10-
- **[Competitive Analysis](competitive-analysis.md)** - Missing features vs competitors
7+
### For Users
8+
- **[User Guide](user_guide/)** - Getting started, tutorials, and examples
9+
- [Getting Started](user_guide/getting_started.md) - Installation and first workflow
10+
- [Tutorials](user_guide/tutorials/) - Step-by-step guides
11+
- [Examples](user_guide/examples/) - Sample workflows and use cases
1112

12-
### For Architecture & Technical Design
13-
- **[Technical Architecture](architecture/technical_architecture.md)** - Core system architecture
14-
- **[Brownfield Architecture](architecture/brownfield-architecture.md)** - Legacy system considerations
15-
- **[Source Tree](architecture/source-tree.md)** - Codebase organization
16-
- **[Tech Stack](architecture/tech-stack.md)** - Technology choices and rationale
17-
- **[Coding Standards](architecture/coding-standards.md)** - Development guidelines
13+
### For Developers
14+
- **[Developer Guide](developer_guide/)** - Development environment and contribution guidelines
15+
- [Testing Guide](developer_guide/testing-guide.md) - Test runner and testing strategies
16+
- [Implementation Notes](developer_guide/implementation-notes.md) - Technical priorities
17+
- [AI Agents Guide](developer_guide/ai-agents-guide.md) - Working with AI assistants
1818

19-
### For Feature Specifications
20-
- **[Flow Specification](specifications/flow_spec.md)** - Core flow format specification
21-
- **[UI/UX Specifications](specifications/ui-ux-specifications.md)** - Interface design specs
22-
- **[Priority 1 Features](specifications/priority-1-features-project-brief.md)** - Critical feature brief
19+
### For Technical Reference
20+
- **[Reference](reference/)** - Complete technical documentation
21+
- [Architecture](reference/architecture/) - System design and technical architecture
22+
- [Specifications](reference/specifications/) - Feature and interface specifications
23+
- [API](reference/api/) - API documentation (planned)
2324

24-
### For Development & Implementation
25-
- **[Testing Guide](development/testing-guide.md)** - Test runner and testing strategies
26-
- **[Implementation Notes](development/implementation-notes.md)** - Technical implementation priorities
27-
- **[Fixes Directory](development/fixes/)** - Specific implementation and fix plans
25+
### For Project Management
26+
- **[Project](project/)** - Strategic planning and development tracking
27+
- [PRD](project/prd.md) - Product Requirements Document
28+
- [Roadmap](project/roadmap.md) - Feature development roadmap
29+
- [Epics](project/epics/) - Epic and story tracking
2830

29-
## Document Organization
31+
### For Issue Tracking
32+
- **[Issues](issues/)** - Bug reports and issue resolution
33+
- [Active Issues](issues/active/) - Current unresolved issues
34+
- [Resolved Issues](issues/resolved/) - Completed issue resolutions
3035

31-
### Strategic Documents
32-
High-level product and business documentation for stakeholders and product planning.
36+
### For Implementation Details
37+
- **[Implementation](implementation/)** - Detailed implementation plans and fixes
38+
- [Fixes](implementation/fixes/) - Specific fix implementations
39+
- [Migration Plans](implementation/migration_plans/) - Code reorganization plans
3340

34-
### Architecture Documents
35-
Technical architecture, system design, and structural documentation for architects and senior developers.
41+
## Document Organization Philosophy
3642

37-
### Specifications
38-
Detailed feature and interface specifications for development teams.
43+
This documentation structure follows industry best practices with clear separation of concerns:
3944

40-
### Development Documentation
41-
Implementation guides, testing procedures, and development tooling for active contributors.
45+
### User-Focused Documentation (`user_guide/`)
46+
Practical guides for end users, including tutorials, examples, and getting started materials.
47+
48+
### Developer Documentation (`developer_guide/`)
49+
Technical development information for contributors, including testing, setup, and implementation guidance.
50+
51+
### Reference Material (`reference/`)
52+
Comprehensive technical specifications, architecture documentation, and API references for detailed technical understanding.
53+
54+
### Project Management (`project/`)
55+
Strategic documents, planning materials, and development tracking for stakeholders and project coordination.
56+
57+
### Issue Management (`issues/`)
58+
Structured bug tracking and issue resolution with proper categorization and documentation.
59+
60+
### Implementation Details (`implementation/`)
61+
Specific implementation plans, migration strategies, and detailed technical solutions.
4262

4363
## Contributing to Documentation
4464

4565
When adding new documentation:
46-
- Place strategic docs in the root `docs/` directory
47-
- Place technical architecture in `architecture/`
48-
- Place feature specs in `specifications/`
49-
- Place implementation details in `development/`
50-
- Update this README with new document links
66+
- Place user-focused content in `user_guide/`
67+
- Place developer information in `developer_guide/`
68+
- Place technical specifications in `reference/`
69+
- Place strategic content in `project/`
70+
- Place bug reports in `issues/`
71+
- Place implementation details in `implementation/`
72+
- Always update relevant README files with new document links
73+
- Follow existing naming conventions and organization patterns
74+
75+
## Navigation Tips
76+
77+
- Each major section has its own README with detailed navigation
78+
- Related documents are cross-referenced for easy discovery
79+
- Status information is maintained for active development items
80+
- Historical documents are preserved in appropriate subdirectories

0 commit comments

Comments
 (0)