koode-taskgraph 0.4.0__tar.gz → 0.4.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/PKG-INFO +80 -74
  2. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/README.md +79 -73
  3. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/PKG-INFO +80 -74
  4. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/pyproject.toml +1 -1
  5. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/ui/main_window.py +1 -0
  6. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/ui/plugins.py +29 -2
  7. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/tests/test_gui_plugins.py +32 -12
  8. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/LICENSE +0 -0
  9. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/SOURCES.txt +0 -0
  10. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/dependency_links.txt +0 -0
  11. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/entry_points.txt +0 -0
  12. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/requires.txt +0 -0
  13. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/top_level.txt +0 -0
  14. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/setup.cfg +0 -0
  15. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/__init__.py +0 -0
  16. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/__main__.py +0 -0
  17. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/app.py +0 -0
  18. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/cli.py +0 -0
  19. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/core/__init__.py +0 -0
  20. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/core/executor.py +0 -0
  21. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/core/model.py +0 -0
  22. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/core/registry.py +0 -0
  23. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/core/serialization.py +0 -0
  24. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/nodes/__init__.py +0 -0
  25. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/nodes/builtin.py +0 -0
  26. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/ui/__init__.py +0 -0
  27. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/ui/items.py +0 -0
  28. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/ui/properties.py +0 -0
  29. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/ui/scene.py +0 -0
  30. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/taskgraph/ui/theme.py +0 -0
  31. {koode_taskgraph-0.4.0 → koode_taskgraph-0.4.1}/tests/test_core.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: koode-taskgraph
3
- Version: 0.4.0
3
+ Version: 0.4.1
4
4
  Summary: An extensible process node graph built with QtPy and PySide6
5
5
  Requires-Python: >=3.10
6
6
  Description-Content-Type: text/markdown
@@ -34,6 +34,80 @@ koode-taskgraph
34
34
  For local development from this repository, use `python -m pip install -e .`.
35
35
  See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
36
36
 
37
+ ## Application Features
38
+
39
+ - Standard commands are organized under the **File**, **Edit**, **Nodes**,
40
+ **Graph**, **Plugins**, and **View** menus.
41
+ - Use the search field at the top of the **Nodes** panel to filter nodes by
42
+ title, type id, or category.
43
+ - Drag a node from **Nodes** to the canvas, or double-click it.
44
+ - Every node has fixed gold **dependency** input/output ports. These control
45
+ process order but do not transfer values. Gold dependency connections show
46
+ an arrowhead pointing from the upstream node toward the downstream node.
47
+ - Declared node inputs and outputs are attribute ports. Attribute connections
48
+ transfer values, but execution order comes only from dependency connections.
49
+ An attribute connection therefore needs a dependency path from its source
50
+ node to its target node.
51
+ - Dependency ports connect only to dependency ports; compatible attribute
52
+ ports connect only to attribute ports.
53
+ - Select one or more nodes on the canvas and press **D** to toggle them
54
+ disabled. Disabled nodes stay in the dependency chain but their process
55
+ functions are skipped. The same command is available from **Edit**.
56
+ - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
57
+ shortcuts. Properties, disabled state, relative positions, and connections
58
+ entirely inside the copied selection are preserved.
59
+ - Select a node to edit generated property controls.
60
+ - Use **Node Name** at the top of the Properties panel to give each node
61
+ instance a descriptive name. Custom names appear in node headers and
62
+ execution messages and are preserved when saving or copying nodes.
63
+ - Select nodes or connections and press **Backspace** or **Delete** to remove
64
+ them. **Edit → Delete Selected** works on every platform too.
65
+ - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
66
+ - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
67
+ from left to right and parallel nodes vertically, then frames the result.
68
+ - **Graph → Add Backdrop** creates a movable notes region behind the graph.
69
+ Select it to edit its title, notes, color, width, and height in Properties.
70
+ Drag the grip in its bottom-right corner to resize it interactively.
71
+ Backdrops are stored in `.taskgraph` files.
72
+ - **Ctrl+R** executes nodes in dependency order.
73
+ - Independent dependency branches execute concurrently. Choose between one
74
+ worker or any even worker count from 2 through 32 under
75
+ **Graph → Worker Count**; the setting is remembered.
76
+ - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
77
+ Pending nodes are cancelled immediately. Running nodes receive a cooperative
78
+ cancellation signal, and built-in command nodes terminate their subprocess
79
+ groups promptly.
80
+ - Clear displayed execution messages with **Graph → Clear Execution Log** or
81
+ from the Execution panel's right-click menu.
82
+ - Node headers show live execution state: amber while running, green when
83
+ finished, red on failure, gray when a disabled node is skipped, and muted
84
+ red when a node is blocked by an upstream failure. Cancelled nodes use a
85
+ purple-gray state.
86
+ Execution coordination runs outside the GUI thread so the final running
87
+ node and parallel running nodes remain visible while work is in progress.
88
+ - A failed node blocks only its downstream dependency branch. Independent
89
+ parallel branches continue running and report their own final states.
90
+ - Closed panels can be restored from **View → Nodes/Properties/Execution**.
91
+ Use **View → Show All Panels** to restore everything at once.
92
+ - Graph files use readable JSON with the `.taskgraph` extension.
93
+
94
+ ## Built-in Nodes
95
+
96
+ - Built-in nodes are organized as **System → Run Command/Print**,
97
+ **Utils → Format Text**, and **Inputs → Text/Number**.
98
+ - **Inputs → Text** outputs a user-provided text value.
99
+ - **Inputs → Number** outputs a user-provided numeric value.
100
+ - **System → Print** prints an incoming value and supports an optional prefix.
101
+ - **System → Run Command** executes a command and exposes stdout, stderr, and
102
+ return code outputs. It supports an optional working directory, shell mode,
103
+ timeout, and failure on non-zero exit. Shell mode executes exactly what the
104
+ graph author enters, so only run trusted graphs.
105
+ - **Utils → Format Text** accepts multiple connections into its `value` input.
106
+ Use positional placeholders such as `{0}`, `{1}`, and `{2}` in the template.
107
+ `{value}` remains available as the first input value for simple one-input
108
+ templates. Connections into multi-input attribute ports show index labels on
109
+ the wire so the template order is visible on the graph.
110
+
37
111
  ## Remove local user settings
38
112
 
39
113
  TaskGraph stores user preferences with Qt `QSettings` under organization
@@ -192,7 +266,7 @@ class Plugin(TaskGraphGuiPlugin):
192
266
  callback=self.build_daily_report,
193
267
  )
194
268
  self.ui.menus.add_command(
195
- "Examples",
269
+ "Examples/Graph Builders",
196
270
  f"{self.plugin_id}.build_daily_report",
197
271
  )
198
272
 
@@ -233,12 +307,13 @@ This repository includes separate practical example plugins in
233
307
  `examples/gui_plugins`:
234
308
 
235
309
  - `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
236
- panel and writing a status message.
310
+ panel and writing a status message from **Examples → UI Panels**.
237
311
  - `command_validate_graph.py` demonstrates the command API by registering a
238
- reusable graph validation command and exposing it in the menu.
312
+ reusable graph validation command and exposing it in
313
+ **Examples → Commands**.
239
314
  - `graph_daily_report.py` demonstrates the graph API by building a reusable
240
315
  daily-report graph with nodes, dependency links, attribute links, and a
241
- backdrop.
316
+ backdrop from **Examples → Graph Builders**.
242
317
 
243
318
  Load that directory, then use the **Examples** menu to run each example.
244
319
 
@@ -246,75 +321,6 @@ GUI plugins are intentionally separate from custom node locations. The
246
321
  headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
247
322
  import Qt widgets without breaking `koode-taskgraph-cli`.
248
323
 
249
- ## Controls
250
-
251
- - Standard commands are organized under the **File**, **Edit**, **Nodes**,
252
- **Graph**, **Plugins**, and **View** menus.
253
- - Use the search field at the top of the **Nodes** panel to filter nodes by
254
- title, type id, or category.
255
- - Drag a node from **Nodes** to the canvas, or double-click it.
256
- - Every node has fixed gold **dependency** input/output ports. These control
257
- process order but do not transfer values. Gold dependency connections show
258
- an arrowhead pointing from the upstream node toward the downstream node.
259
- - Declared node inputs and outputs are attribute ports. Attribute connections
260
- transfer values, but execution order comes only from dependency connections.
261
- An attribute connection therefore needs a dependency path from its source
262
- node to its target node.
263
- - Dependency ports connect only to dependency ports; compatible attribute
264
- ports connect only to attribute ports.
265
- - Select one or more nodes on the canvas and press **D** to toggle them
266
- disabled. Disabled nodes stay in the dependency chain but their process
267
- functions are skipped. The same command is available from **Edit**.
268
- - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
269
- shortcuts. Properties, disabled state, relative positions, and connections
270
- entirely inside the copied selection are preserved.
271
- - Select a node to edit generated property controls.
272
- - Use **Node Name** at the top of the Properties panel to give each node
273
- instance a descriptive name. Custom names appear in node headers and
274
- execution messages and are preserved when saving or copying nodes.
275
- - Select nodes or connections and press **Backspace** or **Delete** to remove
276
- them. **Edit → Delete Selected** works on every platform too.
277
- - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
278
- - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
279
- from left to right and parallel nodes vertically, then frames the result.
280
- - **Graph → Add Backdrop** creates a movable notes region behind the graph.
281
- Select it to edit its title, notes, color, width, and height in Properties.
282
- Drag the grip in its bottom-right corner to resize it interactively.
283
- Backdrops are stored in `.taskgraph` files.
284
- - **Ctrl+R** executes nodes in dependency order.
285
- - Independent dependency branches execute concurrently. Choose between one
286
- worker or any even worker count from 2 through 32 under
287
- **Graph → Worker Count**; the setting is remembered.
288
- - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
289
- Pending nodes are cancelled immediately. Running nodes receive a cooperative
290
- cancellation signal, and built-in command nodes terminate their subprocess
291
- groups promptly.
292
- - Clear displayed execution messages with **Graph → Clear Execution Log** or
293
- from the Execution panel's right-click menu.
294
- - Built-in nodes are organized as **System → Run Command/Print**,
295
- **Utils → Format Text**, and **Inputs → Text/Number**.
296
- - The built-in **System → Run Command** node executes a command and exposes
297
- stdout, stderr, and return code outputs. It supports an optional working
298
- directory, shell mode, timeout, and failure on non-zero exit. Shell mode
299
- executes exactly what the graph author enters, so only run trusted graphs.
300
- - The built-in **Utils → Format Text** node accepts multiple connections into
301
- its `value` input. Use positional placeholders such as `{0}`, `{1}`, and
302
- `{2}` in the template. `{value}` remains available as the first input value
303
- for simple one-input templates. Connections into multi-input attribute ports
304
- show index labels on the wire so the template order is visible on the graph.
305
- - Node headers show live execution state: amber while running, green when
306
- finished, red on failure, gray when a disabled node is skipped, and muted
307
- red when a node is blocked by an upstream failure. Cancelled nodes use a
308
- purple-gray state.
309
- Execution coordination runs outside the GUI thread so the final running
310
- node and parallel running nodes remain visible while work is in progress.
311
- - A failed node blocks only its downstream dependency branch. Independent
312
- parallel branches continue running and report their own final states.
313
- - Closed panels can be restored from **View → Nodes/Properties/Execution**.
314
- Use **View → Show All Panels** to restore everything at once.
315
-
316
- Graph files use readable JSON with the `.taskgraph` extension.
317
-
318
324
  ## Architecture
319
325
 
320
326
  - `core/model.py`: node contract—including inherited dependency port
@@ -23,6 +23,80 @@ koode-taskgraph
23
23
  For local development from this repository, use `python -m pip install -e .`.
24
24
  See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
25
25
 
26
+ ## Application Features
27
+
28
+ - Standard commands are organized under the **File**, **Edit**, **Nodes**,
29
+ **Graph**, **Plugins**, and **View** menus.
30
+ - Use the search field at the top of the **Nodes** panel to filter nodes by
31
+ title, type id, or category.
32
+ - Drag a node from **Nodes** to the canvas, or double-click it.
33
+ - Every node has fixed gold **dependency** input/output ports. These control
34
+ process order but do not transfer values. Gold dependency connections show
35
+ an arrowhead pointing from the upstream node toward the downstream node.
36
+ - Declared node inputs and outputs are attribute ports. Attribute connections
37
+ transfer values, but execution order comes only from dependency connections.
38
+ An attribute connection therefore needs a dependency path from its source
39
+ node to its target node.
40
+ - Dependency ports connect only to dependency ports; compatible attribute
41
+ ports connect only to attribute ports.
42
+ - Select one or more nodes on the canvas and press **D** to toggle them
43
+ disabled. Disabled nodes stay in the dependency chain but their process
44
+ functions are skipped. The same command is available from **Edit**.
45
+ - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
46
+ shortcuts. Properties, disabled state, relative positions, and connections
47
+ entirely inside the copied selection are preserved.
48
+ - Select a node to edit generated property controls.
49
+ - Use **Node Name** at the top of the Properties panel to give each node
50
+ instance a descriptive name. Custom names appear in node headers and
51
+ execution messages and are preserved when saving or copying nodes.
52
+ - Select nodes or connections and press **Backspace** or **Delete** to remove
53
+ them. **Edit → Delete Selected** works on every platform too.
54
+ - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
55
+ - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
56
+ from left to right and parallel nodes vertically, then frames the result.
57
+ - **Graph → Add Backdrop** creates a movable notes region behind the graph.
58
+ Select it to edit its title, notes, color, width, and height in Properties.
59
+ Drag the grip in its bottom-right corner to resize it interactively.
60
+ Backdrops are stored in `.taskgraph` files.
61
+ - **Ctrl+R** executes nodes in dependency order.
62
+ - Independent dependency branches execute concurrently. Choose between one
63
+ worker or any even worker count from 2 through 32 under
64
+ **Graph → Worker Count**; the setting is remembered.
65
+ - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
66
+ Pending nodes are cancelled immediately. Running nodes receive a cooperative
67
+ cancellation signal, and built-in command nodes terminate their subprocess
68
+ groups promptly.
69
+ - Clear displayed execution messages with **Graph → Clear Execution Log** or
70
+ from the Execution panel's right-click menu.
71
+ - Node headers show live execution state: amber while running, green when
72
+ finished, red on failure, gray when a disabled node is skipped, and muted
73
+ red when a node is blocked by an upstream failure. Cancelled nodes use a
74
+ purple-gray state.
75
+ Execution coordination runs outside the GUI thread so the final running
76
+ node and parallel running nodes remain visible while work is in progress.
77
+ - A failed node blocks only its downstream dependency branch. Independent
78
+ parallel branches continue running and report their own final states.
79
+ - Closed panels can be restored from **View → Nodes/Properties/Execution**.
80
+ Use **View → Show All Panels** to restore everything at once.
81
+ - Graph files use readable JSON with the `.taskgraph` extension.
82
+
83
+ ## Built-in Nodes
84
+
85
+ - Built-in nodes are organized as **System → Run Command/Print**,
86
+ **Utils → Format Text**, and **Inputs → Text/Number**.
87
+ - **Inputs → Text** outputs a user-provided text value.
88
+ - **Inputs → Number** outputs a user-provided numeric value.
89
+ - **System → Print** prints an incoming value and supports an optional prefix.
90
+ - **System → Run Command** executes a command and exposes stdout, stderr, and
91
+ return code outputs. It supports an optional working directory, shell mode,
92
+ timeout, and failure on non-zero exit. Shell mode executes exactly what the
93
+ graph author enters, so only run trusted graphs.
94
+ - **Utils → Format Text** accepts multiple connections into its `value` input.
95
+ Use positional placeholders such as `{0}`, `{1}`, and `{2}` in the template.
96
+ `{value}` remains available as the first input value for simple one-input
97
+ templates. Connections into multi-input attribute ports show index labels on
98
+ the wire so the template order is visible on the graph.
99
+
26
100
  ## Remove local user settings
27
101
 
28
102
  TaskGraph stores user preferences with Qt `QSettings` under organization
@@ -181,7 +255,7 @@ class Plugin(TaskGraphGuiPlugin):
181
255
  callback=self.build_daily_report,
182
256
  )
183
257
  self.ui.menus.add_command(
184
- "Examples",
258
+ "Examples/Graph Builders",
185
259
  f"{self.plugin_id}.build_daily_report",
186
260
  )
187
261
 
@@ -222,12 +296,13 @@ This repository includes separate practical example plugins in
222
296
  `examples/gui_plugins`:
223
297
 
224
298
  - `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
225
- panel and writing a status message.
299
+ panel and writing a status message from **Examples → UI Panels**.
226
300
  - `command_validate_graph.py` demonstrates the command API by registering a
227
- reusable graph validation command and exposing it in the menu.
301
+ reusable graph validation command and exposing it in
302
+ **Examples → Commands**.
228
303
  - `graph_daily_report.py` demonstrates the graph API by building a reusable
229
304
  daily-report graph with nodes, dependency links, attribute links, and a
230
- backdrop.
305
+ backdrop from **Examples → Graph Builders**.
231
306
 
232
307
  Load that directory, then use the **Examples** menu to run each example.
233
308
 
@@ -235,75 +310,6 @@ GUI plugins are intentionally separate from custom node locations. The
235
310
  headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
236
311
  import Qt widgets without breaking `koode-taskgraph-cli`.
237
312
 
238
- ## Controls
239
-
240
- - Standard commands are organized under the **File**, **Edit**, **Nodes**,
241
- **Graph**, **Plugins**, and **View** menus.
242
- - Use the search field at the top of the **Nodes** panel to filter nodes by
243
- title, type id, or category.
244
- - Drag a node from **Nodes** to the canvas, or double-click it.
245
- - Every node has fixed gold **dependency** input/output ports. These control
246
- process order but do not transfer values. Gold dependency connections show
247
- an arrowhead pointing from the upstream node toward the downstream node.
248
- - Declared node inputs and outputs are attribute ports. Attribute connections
249
- transfer values, but execution order comes only from dependency connections.
250
- An attribute connection therefore needs a dependency path from its source
251
- node to its target node.
252
- - Dependency ports connect only to dependency ports; compatible attribute
253
- ports connect only to attribute ports.
254
- - Select one or more nodes on the canvas and press **D** to toggle them
255
- disabled. Disabled nodes stay in the dependency chain but their process
256
- functions are skipped. The same command is available from **Edit**.
257
- - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
258
- shortcuts. Properties, disabled state, relative positions, and connections
259
- entirely inside the copied selection are preserved.
260
- - Select a node to edit generated property controls.
261
- - Use **Node Name** at the top of the Properties panel to give each node
262
- instance a descriptive name. Custom names appear in node headers and
263
- execution messages and are preserved when saving or copying nodes.
264
- - Select nodes or connections and press **Backspace** or **Delete** to remove
265
- them. **Edit → Delete Selected** works on every platform too.
266
- - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
267
- - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
268
- from left to right and parallel nodes vertically, then frames the result.
269
- - **Graph → Add Backdrop** creates a movable notes region behind the graph.
270
- Select it to edit its title, notes, color, width, and height in Properties.
271
- Drag the grip in its bottom-right corner to resize it interactively.
272
- Backdrops are stored in `.taskgraph` files.
273
- - **Ctrl+R** executes nodes in dependency order.
274
- - Independent dependency branches execute concurrently. Choose between one
275
- worker or any even worker count from 2 through 32 under
276
- **Graph → Worker Count**; the setting is remembered.
277
- - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
278
- Pending nodes are cancelled immediately. Running nodes receive a cooperative
279
- cancellation signal, and built-in command nodes terminate their subprocess
280
- groups promptly.
281
- - Clear displayed execution messages with **Graph → Clear Execution Log** or
282
- from the Execution panel's right-click menu.
283
- - Built-in nodes are organized as **System → Run Command/Print**,
284
- **Utils → Format Text**, and **Inputs → Text/Number**.
285
- - The built-in **System → Run Command** node executes a command and exposes
286
- stdout, stderr, and return code outputs. It supports an optional working
287
- directory, shell mode, timeout, and failure on non-zero exit. Shell mode
288
- executes exactly what the graph author enters, so only run trusted graphs.
289
- - The built-in **Utils → Format Text** node accepts multiple connections into
290
- its `value` input. Use positional placeholders such as `{0}`, `{1}`, and
291
- `{2}` in the template. `{value}` remains available as the first input value
292
- for simple one-input templates. Connections into multi-input attribute ports
293
- show index labels on the wire so the template order is visible on the graph.
294
- - Node headers show live execution state: amber while running, green when
295
- finished, red on failure, gray when a disabled node is skipped, and muted
296
- red when a node is blocked by an upstream failure. Cancelled nodes use a
297
- purple-gray state.
298
- Execution coordination runs outside the GUI thread so the final running
299
- node and parallel running nodes remain visible while work is in progress.
300
- - A failed node blocks only its downstream dependency branch. Independent
301
- parallel branches continue running and report their own final states.
302
- - Closed panels can be restored from **View → Nodes/Properties/Execution**.
303
- Use **View → Show All Panels** to restore everything at once.
304
-
305
- Graph files use readable JSON with the `.taskgraph` extension.
306
-
307
313
  ## Architecture
308
314
 
309
315
  - `core/model.py`: node contract—including inherited dependency port
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: koode-taskgraph
3
- Version: 0.4.0
3
+ Version: 0.4.1
4
4
  Summary: An extensible process node graph built with QtPy and PySide6
5
5
  Requires-Python: >=3.10
6
6
  Description-Content-Type: text/markdown
@@ -34,6 +34,80 @@ koode-taskgraph
34
34
  For local development from this repository, use `python -m pip install -e .`.
35
35
  See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
36
36
 
37
+ ## Application Features
38
+
39
+ - Standard commands are organized under the **File**, **Edit**, **Nodes**,
40
+ **Graph**, **Plugins**, and **View** menus.
41
+ - Use the search field at the top of the **Nodes** panel to filter nodes by
42
+ title, type id, or category.
43
+ - Drag a node from **Nodes** to the canvas, or double-click it.
44
+ - Every node has fixed gold **dependency** input/output ports. These control
45
+ process order but do not transfer values. Gold dependency connections show
46
+ an arrowhead pointing from the upstream node toward the downstream node.
47
+ - Declared node inputs and outputs are attribute ports. Attribute connections
48
+ transfer values, but execution order comes only from dependency connections.
49
+ An attribute connection therefore needs a dependency path from its source
50
+ node to its target node.
51
+ - Dependency ports connect only to dependency ports; compatible attribute
52
+ ports connect only to attribute ports.
53
+ - Select one or more nodes on the canvas and press **D** to toggle them
54
+ disabled. Disabled nodes stay in the dependency chain but their process
55
+ functions are skipped. The same command is available from **Edit**.
56
+ - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
57
+ shortcuts. Properties, disabled state, relative positions, and connections
58
+ entirely inside the copied selection are preserved.
59
+ - Select a node to edit generated property controls.
60
+ - Use **Node Name** at the top of the Properties panel to give each node
61
+ instance a descriptive name. Custom names appear in node headers and
62
+ execution messages and are preserved when saving or copying nodes.
63
+ - Select nodes or connections and press **Backspace** or **Delete** to remove
64
+ them. **Edit → Delete Selected** works on every platform too.
65
+ - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
66
+ - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
67
+ from left to right and parallel nodes vertically, then frames the result.
68
+ - **Graph → Add Backdrop** creates a movable notes region behind the graph.
69
+ Select it to edit its title, notes, color, width, and height in Properties.
70
+ Drag the grip in its bottom-right corner to resize it interactively.
71
+ Backdrops are stored in `.taskgraph` files.
72
+ - **Ctrl+R** executes nodes in dependency order.
73
+ - Independent dependency branches execute concurrently. Choose between one
74
+ worker or any even worker count from 2 through 32 under
75
+ **Graph → Worker Count**; the setting is remembered.
76
+ - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
77
+ Pending nodes are cancelled immediately. Running nodes receive a cooperative
78
+ cancellation signal, and built-in command nodes terminate their subprocess
79
+ groups promptly.
80
+ - Clear displayed execution messages with **Graph → Clear Execution Log** or
81
+ from the Execution panel's right-click menu.
82
+ - Node headers show live execution state: amber while running, green when
83
+ finished, red on failure, gray when a disabled node is skipped, and muted
84
+ red when a node is blocked by an upstream failure. Cancelled nodes use a
85
+ purple-gray state.
86
+ Execution coordination runs outside the GUI thread so the final running
87
+ node and parallel running nodes remain visible while work is in progress.
88
+ - A failed node blocks only its downstream dependency branch. Independent
89
+ parallel branches continue running and report their own final states.
90
+ - Closed panels can be restored from **View → Nodes/Properties/Execution**.
91
+ Use **View → Show All Panels** to restore everything at once.
92
+ - Graph files use readable JSON with the `.taskgraph` extension.
93
+
94
+ ## Built-in Nodes
95
+
96
+ - Built-in nodes are organized as **System → Run Command/Print**,
97
+ **Utils → Format Text**, and **Inputs → Text/Number**.
98
+ - **Inputs → Text** outputs a user-provided text value.
99
+ - **Inputs → Number** outputs a user-provided numeric value.
100
+ - **System → Print** prints an incoming value and supports an optional prefix.
101
+ - **System → Run Command** executes a command and exposes stdout, stderr, and
102
+ return code outputs. It supports an optional working directory, shell mode,
103
+ timeout, and failure on non-zero exit. Shell mode executes exactly what the
104
+ graph author enters, so only run trusted graphs.
105
+ - **Utils → Format Text** accepts multiple connections into its `value` input.
106
+ Use positional placeholders such as `{0}`, `{1}`, and `{2}` in the template.
107
+ `{value}` remains available as the first input value for simple one-input
108
+ templates. Connections into multi-input attribute ports show index labels on
109
+ the wire so the template order is visible on the graph.
110
+
37
111
  ## Remove local user settings
38
112
 
39
113
  TaskGraph stores user preferences with Qt `QSettings` under organization
@@ -192,7 +266,7 @@ class Plugin(TaskGraphGuiPlugin):
192
266
  callback=self.build_daily_report,
193
267
  )
194
268
  self.ui.menus.add_command(
195
- "Examples",
269
+ "Examples/Graph Builders",
196
270
  f"{self.plugin_id}.build_daily_report",
197
271
  )
198
272
 
@@ -233,12 +307,13 @@ This repository includes separate practical example plugins in
233
307
  `examples/gui_plugins`:
234
308
 
235
309
  - `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
236
- panel and writing a status message.
310
+ panel and writing a status message from **Examples → UI Panels**.
237
311
  - `command_validate_graph.py` demonstrates the command API by registering a
238
- reusable graph validation command and exposing it in the menu.
312
+ reusable graph validation command and exposing it in
313
+ **Examples → Commands**.
239
314
  - `graph_daily_report.py` demonstrates the graph API by building a reusable
240
315
  daily-report graph with nodes, dependency links, attribute links, and a
241
- backdrop.
316
+ backdrop from **Examples → Graph Builders**.
242
317
 
243
318
  Load that directory, then use the **Examples** menu to run each example.
244
319
 
@@ -246,75 +321,6 @@ GUI plugins are intentionally separate from custom node locations. The
246
321
  headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
247
322
  import Qt widgets without breaking `koode-taskgraph-cli`.
248
323
 
249
- ## Controls
250
-
251
- - Standard commands are organized under the **File**, **Edit**, **Nodes**,
252
- **Graph**, **Plugins**, and **View** menus.
253
- - Use the search field at the top of the **Nodes** panel to filter nodes by
254
- title, type id, or category.
255
- - Drag a node from **Nodes** to the canvas, or double-click it.
256
- - Every node has fixed gold **dependency** input/output ports. These control
257
- process order but do not transfer values. Gold dependency connections show
258
- an arrowhead pointing from the upstream node toward the downstream node.
259
- - Declared node inputs and outputs are attribute ports. Attribute connections
260
- transfer values, but execution order comes only from dependency connections.
261
- An attribute connection therefore needs a dependency path from its source
262
- node to its target node.
263
- - Dependency ports connect only to dependency ports; compatible attribute
264
- ports connect only to attribute ports.
265
- - Select one or more nodes on the canvas and press **D** to toggle them
266
- disabled. Disabled nodes stay in the dependency chain but their process
267
- functions are skipped. The same command is available from **Edit**.
268
- - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
269
- shortcuts. Properties, disabled state, relative positions, and connections
270
- entirely inside the copied selection are preserved.
271
- - Select a node to edit generated property controls.
272
- - Use **Node Name** at the top of the Properties panel to give each node
273
- instance a descriptive name. Custom names appear in node headers and
274
- execution messages and are preserved when saving or copying nodes.
275
- - Select nodes or connections and press **Backspace** or **Delete** to remove
276
- them. **Edit → Delete Selected** works on every platform too.
277
- - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
278
- - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
279
- from left to right and parallel nodes vertically, then frames the result.
280
- - **Graph → Add Backdrop** creates a movable notes region behind the graph.
281
- Select it to edit its title, notes, color, width, and height in Properties.
282
- Drag the grip in its bottom-right corner to resize it interactively.
283
- Backdrops are stored in `.taskgraph` files.
284
- - **Ctrl+R** executes nodes in dependency order.
285
- - Independent dependency branches execute concurrently. Choose between one
286
- worker or any even worker count from 2 through 32 under
287
- **Graph → Worker Count**; the setting is remembered.
288
- - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
289
- Pending nodes are cancelled immediately. Running nodes receive a cooperative
290
- cancellation signal, and built-in command nodes terminate their subprocess
291
- groups promptly.
292
- - Clear displayed execution messages with **Graph → Clear Execution Log** or
293
- from the Execution panel's right-click menu.
294
- - Built-in nodes are organized as **System → Run Command/Print**,
295
- **Utils → Format Text**, and **Inputs → Text/Number**.
296
- - The built-in **System → Run Command** node executes a command and exposes
297
- stdout, stderr, and return code outputs. It supports an optional working
298
- directory, shell mode, timeout, and failure on non-zero exit. Shell mode
299
- executes exactly what the graph author enters, so only run trusted graphs.
300
- - The built-in **Utils → Format Text** node accepts multiple connections into
301
- its `value` input. Use positional placeholders such as `{0}`, `{1}`, and
302
- `{2}` in the template. `{value}` remains available as the first input value
303
- for simple one-input templates. Connections into multi-input attribute ports
304
- show index labels on the wire so the template order is visible on the graph.
305
- - Node headers show live execution state: amber while running, green when
306
- finished, red on failure, gray when a disabled node is skipped, and muted
307
- red when a node is blocked by an upstream failure. Cancelled nodes use a
308
- purple-gray state.
309
- Execution coordination runs outside the GUI thread so the final running
310
- node and parallel running nodes remain visible while work is in progress.
311
- - A failed node blocks only its downstream dependency branch. Independent
312
- parallel branches continue running and report their own final states.
313
- - Closed panels can be restored from **View → Nodes/Properties/Execution**.
314
- Use **View → Show All Panels** to restore everything at once.
315
-
316
- Graph files use readable JSON with the `.taskgraph` extension.
317
-
318
324
  ## Architecture
319
325
 
320
326
  - `core/model.py`: node contract—including inherited dependency port
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "koode-taskgraph"
7
- version = "0.4.0"
7
+ version = "0.4.1"
8
8
  readme = "README.md"
9
9
  description = "An extensible process node graph built with QtPy and PySide6"
10
10
  requires-python = ">=3.10"
@@ -142,6 +142,7 @@ class MainWindow(QMainWindow):
142
142
  self.execution_thread: QThread | None = None
143
143
  self.execution_worker: GraphExecutionWorker | None = None
144
144
  self.plugin_actions: list[QAction] = []
145
+ self.plugin_menus = []
145
146
  self.plugin_docks: list[QDockWidget] = []
146
147
  saved_workers = QSettings().value("execution/max_workers", 4, type=int)
147
148
  self.worker_count = min(
@@ -10,7 +10,7 @@ from typing import Callable, ClassVar
10
10
 
11
11
  from qtpy.QtCore import QPointF, Qt
12
12
  from qtpy.QtGui import QAction, QKeySequence
13
- from qtpy.QtWidgets import QDockWidget, QWidget
13
+ from qtpy.QtWidgets import QDockWidget, QMenu, QWidget
14
14
 
15
15
  from taskgraph.core.model import Backdrop, Connection, ProcessNode
16
16
  from taskgraph.core.registry import create_node
@@ -128,7 +128,7 @@ class TaskGraphMenuApi:
128
128
  action.triggered.connect(
129
129
  lambda checked=False: self.root._trigger_callback(callback, checked)
130
130
  )
131
- qt_menu = self.root.window.menu_for_plugin(menu)
131
+ qt_menu = self._menu_for_path(menu)
132
132
  qt_menu.addAction(action)
133
133
  self.root.window.plugin_actions.append(action)
134
134
  return action
@@ -142,6 +142,33 @@ class TaskGraphMenuApi:
142
142
  command.shortcut,
143
143
  )
144
144
 
145
+ def _menu_for_path(self, menu: str):
146
+ parts = [part.strip() for part in menu.split("/") if part.strip()]
147
+ if not parts:
148
+ raise TaskGraphPluginApiError("Plugin menu path cannot be empty")
149
+ current = self.root.window.menu_for_plugin(parts[0])
150
+ path_parts = [parts[0]]
151
+ for part in parts[1:]:
152
+ path_parts.append(part)
153
+ current = self._submenu(current, part, "/".join(path_parts))
154
+ return current
155
+
156
+ def _submenu(self, parent_menu, title: str, path: str):
157
+ key = self.root.window._plugin_menu_key(path)
158
+ if key in self.root.window.menus:
159
+ return self.root.window.menus[key]
160
+ normalized = title.replace("&", "").strip().lower()
161
+ for action in parent_menu.actions():
162
+ submenu = action.menu()
163
+ if submenu and submenu.title().replace("&", "").strip().lower() == normalized:
164
+ self.root.window.menus[key] = submenu
165
+ return submenu
166
+ submenu = QMenu(title, parent_menu)
167
+ parent_menu.addMenu(submenu)
168
+ self.root.window.menus[key] = submenu
169
+ self.root.window.plugin_menus.append(submenu)
170
+ return submenu
171
+
145
172
 
146
173
  class TaskGraphDockApi:
147
174
  """Dock panel helpers exposed to GUI plugins."""
@@ -202,14 +202,20 @@ class GuiPluginTests(unittest.TestCase):
202
202
  ])
203
203
 
204
204
  examples_menu = self.window.menus["examples"]
205
- action_labels = [action.text() for action in examples_menu.actions()]
206
- self.assertEqual(action_labels, [
207
- "Command API: Validate Current Graph",
208
- "Graph API: Build Daily Report Graph",
209
- "UI API: Open Project Notes Panel",
205
+ submenu_labels = [
206
+ action.menu().title() for action in examples_menu.actions()
207
+ if action.menu()
208
+ ]
209
+ self.assertEqual(submenu_labels, [
210
+ "Commands",
211
+ "Graph Builders",
212
+ "UI Panels",
210
213
  ])
211
214
 
212
- self._trigger_example_action("Command API: Validate Current Graph")
215
+ self._trigger_example_action(
216
+ "Examples/Commands",
217
+ "Command API: Validate Current Graph",
218
+ )
213
219
  self.assertEqual(
214
220
  self.window.statusBar().currentMessage(),
215
221
  "Graph validation passed: 0 node(s), 0 connection(s).",
@@ -219,7 +225,10 @@ class GuiPluginTests(unittest.TestCase):
219
225
  self.window.console.toPlainText(),
220
226
  )
221
227
 
222
- self._trigger_example_action("UI API: Open Project Notes Panel")
228
+ self._trigger_example_action(
229
+ "Examples/UI Panels",
230
+ "UI API: Open Project Notes Panel",
231
+ )
223
232
  self.assertEqual(self.window.plugin_docks[-1].windowTitle(), "Project Notes")
224
233
  self.assertEqual(
225
234
  self.window.statusBar().currentMessage(),
@@ -227,6 +236,7 @@ class GuiPluginTests(unittest.TestCase):
227
236
  )
228
237
 
229
238
  self._trigger_example_and_assert_graph(
239
+ menu_path="Examples/Graph Builders",
230
240
  action_text="Graph API: Build Daily Report Graph",
231
241
  node_names=[
232
242
  "Report Title",
@@ -237,17 +247,27 @@ class GuiPluginTests(unittest.TestCase):
237
247
  text_value="Daily Production Report",
238
248
  )
239
249
 
240
- def _trigger_example_action(self, action_text):
241
- examples_menu = self.window.menus["examples"]
250
+ def _trigger_example_action(self, menu_path, action_text):
251
+ menu = self._menu_by_path(menu_path)
242
252
  actions = [
243
- action for action in examples_menu.actions()
253
+ action for action in menu.actions()
244
254
  if action.text() == action_text
245
255
  ]
246
256
  self.assertEqual(len(actions), 1)
247
257
  actions[0].trigger()
248
258
 
249
- def _trigger_example_and_assert_graph(self, action_text, node_names, text_value):
250
- self._trigger_example_action(action_text)
259
+ def _menu_by_path(self, menu_path):
260
+ key = self.window._plugin_menu_key(menu_path)
261
+ return self.window.menus[key]
262
+
263
+ def _trigger_example_and_assert_graph(
264
+ self,
265
+ menu_path,
266
+ action_text,
267
+ node_names,
268
+ text_value,
269
+ ):
270
+ self._trigger_example_action(menu_path, action_text)
251
271
 
252
272
  nodes = list(self.window.scene.graph.nodes.values())
253
273
  self.assertEqual([node.display_name for node in nodes], node_names)
File without changes