koode-taskgraph 0.4.0__tar.gz → 0.5.0__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.
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/PKG-INFO +101 -87
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/README.md +100 -86
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/PKG-INFO +101 -87
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/SOURCES.txt +3 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/pyproject.toml +1 -1
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/cli.py +1 -1
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/model.py +172 -4
- koode_taskgraph-0.5.0/taskgraph/nodes/builtin.py +96 -0
- koode_taskgraph-0.5.0/taskgraph/nodes/systems.py +265 -0
- koode_taskgraph-0.5.0/taskgraph/nodes/utils.py +24 -0
- koode_taskgraph-0.5.0/taskgraph/ui/code_editor.py +69 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/items.py +3 -2
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/main_window.py +1 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/plugins.py +34 -92
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/properties.py +15 -63
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/theme.py +4 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/tests/test_core.py +73 -4
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/tests/test_gui_plugins.py +124 -78
- koode_taskgraph-0.4.0/taskgraph/nodes/builtin.py +0 -156
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/LICENSE +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/dependency_links.txt +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/entry_points.txt +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/requires.txt +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/top_level.txt +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/setup.cfg +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/__init__.py +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/__main__.py +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/app.py +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/__init__.py +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/executor.py +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/registry.py +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/serialization.py +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/nodes/__init__.py +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/__init__.py +0 -0
- {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/scene.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: koode-taskgraph
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
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,91 @@ 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/Python Script/Print**,
|
|
97
|
+
**Utils → Format Text**, and **Inputs → String/Number/Path/List/Dict**.
|
|
98
|
+
- **Inputs → String** outputs a user-provided string value.
|
|
99
|
+
- **Inputs → Number** outputs a user-provided numeric value.
|
|
100
|
+
- **Inputs → Path** outputs a user-selected file or directory path.
|
|
101
|
+
- **Inputs → List** outputs a JSON-authored Python list.
|
|
102
|
+
- **Inputs → Dict** outputs a JSON-authored Python dictionary.
|
|
103
|
+
- **System → Print** prints an incoming value and supports an optional prefix.
|
|
104
|
+
- **System → Run Command** executes a command and exposes stdout, stderr, and
|
|
105
|
+
return code outputs. It supports an optional working directory, shell mode,
|
|
106
|
+
timeout, and failure on non-zero exit. Shell mode executes exactly what the
|
|
107
|
+
graph author enters, so only run trusted graphs.
|
|
108
|
+
- **System → Python Script** runs user-provided Python code in a subprocess.
|
|
109
|
+
The script must define `process(inputs)` and return a dictionary. Connected
|
|
110
|
+
values arrive through the multi-input `value` port as `inputs["value"]` and
|
|
111
|
+
`inputs["values"]`. The node exposes `result`, captured `stdout`, and
|
|
112
|
+
captured `stderr`. The code editor uses a monospace font, keeps line wrapping
|
|
113
|
+
off, inserts spaces with **Tab**, and unindents with **Shift+Tab**. Python
|
|
114
|
+
Script runs arbitrary code with the same user permissions as TaskGraph, so
|
|
115
|
+
only run trusted graphs.
|
|
116
|
+
- **Utils → Format Text** accepts multiple connections into its `value` input.
|
|
117
|
+
Use positional placeholders such as `{0}`, `{1}`, and `{2}` in the template.
|
|
118
|
+
`{value}` remains available as the first input value for simple one-input
|
|
119
|
+
templates. Connections into multi-input attribute ports show index labels on
|
|
120
|
+
the wire so the template order is visible on the graph.
|
|
121
|
+
|
|
37
122
|
## Remove local user settings
|
|
38
123
|
|
|
39
124
|
TaskGraph stores user preferences with Qt `QSettings` under organization
|
|
@@ -109,7 +194,7 @@ node to edit its properties, then click **Run graph**.
|
|
|
109
194
|
Create a module in `taskgraph/nodes/` and define a `ProcessNode` subclass:
|
|
110
195
|
|
|
111
196
|
```python
|
|
112
|
-
from taskgraph.core.model import
|
|
197
|
+
from taskgraph.core.model import PortSpec, ProcessNode, TextProperty
|
|
113
198
|
from taskgraph.core.registry import register_node
|
|
114
199
|
|
|
115
200
|
@register_node
|
|
@@ -120,17 +205,17 @@ class PrefixText(ProcessNode):
|
|
|
120
205
|
inputs = (PortSpec("value", "any"),)
|
|
121
206
|
outputs = (PortSpec("text", "text"),)
|
|
122
207
|
properties = (
|
|
123
|
-
|
|
208
|
+
TextProperty("prefix", "Prefix", "Result: "),
|
|
124
209
|
)
|
|
125
210
|
|
|
126
211
|
def process(self, inputs):
|
|
127
212
|
return {"text": f"{self.prefix}{inputs.get('value', '')}"}
|
|
128
213
|
```
|
|
129
214
|
|
|
130
|
-
Property
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
215
|
+
Property specs map to generated controls in the Properties panel:
|
|
216
|
+
`TextProperty`, `MultilineProperty`, `BoolProperty`, `IntProperty`,
|
|
217
|
+
`FloatProperty`, `ChoiceProperty`, and `PathProperty`. Use typed specs for new
|
|
218
|
+
nodes so property-specific behavior stays with the property declaration.
|
|
134
219
|
|
|
135
220
|
Modules in `taskgraph/nodes/` are discovered automatically. Custom modules can
|
|
136
221
|
also live anywhere on disk:
|
|
@@ -192,15 +277,15 @@ class Plugin(TaskGraphGuiPlugin):
|
|
|
192
277
|
callback=self.build_daily_report,
|
|
193
278
|
)
|
|
194
279
|
self.ui.menus.add_command(
|
|
195
|
-
"Examples",
|
|
280
|
+
"Examples/Graph Builders",
|
|
196
281
|
f"{self.plugin_id}.build_daily_report",
|
|
197
282
|
)
|
|
198
283
|
|
|
199
284
|
def build_daily_report(self):
|
|
200
285
|
text = self.graph.create_node(
|
|
201
|
-
"input.
|
|
286
|
+
"input.string",
|
|
202
287
|
name="Report Title",
|
|
203
|
-
values={"
|
|
288
|
+
values={"string": "Daily Production Report"},
|
|
204
289
|
position=(0, 0),
|
|
205
290
|
)
|
|
206
291
|
printer = self.graph.create_node(
|
|
@@ -209,7 +294,7 @@ class Plugin(TaskGraphGuiPlugin):
|
|
|
209
294
|
position=(320, 0),
|
|
210
295
|
)
|
|
211
296
|
self.graph.connect_dependency(text, printer)
|
|
212
|
-
self.graph.connect_attribute(text, "
|
|
297
|
+
self.graph.connect_attribute(text, "string", printer, "value")
|
|
213
298
|
self.graph.add_backdrop(
|
|
214
299
|
title="Daily Report Template",
|
|
215
300
|
note="This graph was created by a GUI plugin.",
|
|
@@ -218,10 +303,7 @@ class Plugin(TaskGraphGuiPlugin):
|
|
|
218
303
|
)
|
|
219
304
|
```
|
|
220
305
|
|
|
221
|
-
|
|
222
|
-
`api.add_menu_action(...)`, plus the old `register_taskgraph_plugin(api)`
|
|
223
|
-
function entrypoint, are still supported for compatibility. New plugins should
|
|
224
|
-
use the OOP `Plugin` class and namespaced API.
|
|
306
|
+
GUI plugins must define an OOP `Plugin` class and use the namespaced API.
|
|
225
307
|
|
|
226
308
|
Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
|
|
227
309
|
session. GUI plugin locations are not saved or automatically reloaded on the
|
|
@@ -233,12 +315,13 @@ This repository includes separate practical example plugins in
|
|
|
233
315
|
`examples/gui_plugins`:
|
|
234
316
|
|
|
235
317
|
- `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
|
|
236
|
-
panel and writing a status message
|
|
318
|
+
panel and writing a status message from **Examples → UI Panels**.
|
|
237
319
|
- `command_validate_graph.py` demonstrates the command API by registering a
|
|
238
|
-
reusable graph validation command and exposing it in
|
|
320
|
+
reusable graph validation command and exposing it in
|
|
321
|
+
**Examples → Commands**.
|
|
239
322
|
- `graph_daily_report.py` demonstrates the graph API by building a reusable
|
|
240
323
|
daily-report graph with nodes, dependency links, attribute links, and a
|
|
241
|
-
backdrop
|
|
324
|
+
backdrop from **Examples → Graph Builders**.
|
|
242
325
|
|
|
243
326
|
Load that directory, then use the **Examples** menu to run each example.
|
|
244
327
|
|
|
@@ -246,75 +329,6 @@ GUI plugins are intentionally separate from custom node locations. The
|
|
|
246
329
|
headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
|
|
247
330
|
import Qt widgets without breaking `koode-taskgraph-cli`.
|
|
248
331
|
|
|
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
332
|
## Architecture
|
|
319
333
|
|
|
320
334
|
- `core/model.py`: node contract—including inherited dependency port
|
|
@@ -23,6 +23,91 @@ 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/Python Script/Print**,
|
|
86
|
+
**Utils → Format Text**, and **Inputs → String/Number/Path/List/Dict**.
|
|
87
|
+
- **Inputs → String** outputs a user-provided string value.
|
|
88
|
+
- **Inputs → Number** outputs a user-provided numeric value.
|
|
89
|
+
- **Inputs → Path** outputs a user-selected file or directory path.
|
|
90
|
+
- **Inputs → List** outputs a JSON-authored Python list.
|
|
91
|
+
- **Inputs → Dict** outputs a JSON-authored Python dictionary.
|
|
92
|
+
- **System → Print** prints an incoming value and supports an optional prefix.
|
|
93
|
+
- **System → Run Command** executes a command and exposes stdout, stderr, and
|
|
94
|
+
return code outputs. It supports an optional working directory, shell mode,
|
|
95
|
+
timeout, and failure on non-zero exit. Shell mode executes exactly what the
|
|
96
|
+
graph author enters, so only run trusted graphs.
|
|
97
|
+
- **System → Python Script** runs user-provided Python code in a subprocess.
|
|
98
|
+
The script must define `process(inputs)` and return a dictionary. Connected
|
|
99
|
+
values arrive through the multi-input `value` port as `inputs["value"]` and
|
|
100
|
+
`inputs["values"]`. The node exposes `result`, captured `stdout`, and
|
|
101
|
+
captured `stderr`. The code editor uses a monospace font, keeps line wrapping
|
|
102
|
+
off, inserts spaces with **Tab**, and unindents with **Shift+Tab**. Python
|
|
103
|
+
Script runs arbitrary code with the same user permissions as TaskGraph, so
|
|
104
|
+
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
|
+
|
|
26
111
|
## Remove local user settings
|
|
27
112
|
|
|
28
113
|
TaskGraph stores user preferences with Qt `QSettings` under organization
|
|
@@ -98,7 +183,7 @@ node to edit its properties, then click **Run graph**.
|
|
|
98
183
|
Create a module in `taskgraph/nodes/` and define a `ProcessNode` subclass:
|
|
99
184
|
|
|
100
185
|
```python
|
|
101
|
-
from taskgraph.core.model import
|
|
186
|
+
from taskgraph.core.model import PortSpec, ProcessNode, TextProperty
|
|
102
187
|
from taskgraph.core.registry import register_node
|
|
103
188
|
|
|
104
189
|
@register_node
|
|
@@ -109,17 +194,17 @@ class PrefixText(ProcessNode):
|
|
|
109
194
|
inputs = (PortSpec("value", "any"),)
|
|
110
195
|
outputs = (PortSpec("text", "text"),)
|
|
111
196
|
properties = (
|
|
112
|
-
|
|
197
|
+
TextProperty("prefix", "Prefix", "Result: "),
|
|
113
198
|
)
|
|
114
199
|
|
|
115
200
|
def process(self, inputs):
|
|
116
201
|
return {"text": f"{self.prefix}{inputs.get('value', '')}"}
|
|
117
202
|
```
|
|
118
203
|
|
|
119
|
-
Property
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
204
|
+
Property specs map to generated controls in the Properties panel:
|
|
205
|
+
`TextProperty`, `MultilineProperty`, `BoolProperty`, `IntProperty`,
|
|
206
|
+
`FloatProperty`, `ChoiceProperty`, and `PathProperty`. Use typed specs for new
|
|
207
|
+
nodes so property-specific behavior stays with the property declaration.
|
|
123
208
|
|
|
124
209
|
Modules in `taskgraph/nodes/` are discovered automatically. Custom modules can
|
|
125
210
|
also live anywhere on disk:
|
|
@@ -181,15 +266,15 @@ class Plugin(TaskGraphGuiPlugin):
|
|
|
181
266
|
callback=self.build_daily_report,
|
|
182
267
|
)
|
|
183
268
|
self.ui.menus.add_command(
|
|
184
|
-
"Examples",
|
|
269
|
+
"Examples/Graph Builders",
|
|
185
270
|
f"{self.plugin_id}.build_daily_report",
|
|
186
271
|
)
|
|
187
272
|
|
|
188
273
|
def build_daily_report(self):
|
|
189
274
|
text = self.graph.create_node(
|
|
190
|
-
"input.
|
|
275
|
+
"input.string",
|
|
191
276
|
name="Report Title",
|
|
192
|
-
values={"
|
|
277
|
+
values={"string": "Daily Production Report"},
|
|
193
278
|
position=(0, 0),
|
|
194
279
|
)
|
|
195
280
|
printer = self.graph.create_node(
|
|
@@ -198,7 +283,7 @@ class Plugin(TaskGraphGuiPlugin):
|
|
|
198
283
|
position=(320, 0),
|
|
199
284
|
)
|
|
200
285
|
self.graph.connect_dependency(text, printer)
|
|
201
|
-
self.graph.connect_attribute(text, "
|
|
286
|
+
self.graph.connect_attribute(text, "string", printer, "value")
|
|
202
287
|
self.graph.add_backdrop(
|
|
203
288
|
title="Daily Report Template",
|
|
204
289
|
note="This graph was created by a GUI plugin.",
|
|
@@ -207,10 +292,7 @@ class Plugin(TaskGraphGuiPlugin):
|
|
|
207
292
|
)
|
|
208
293
|
```
|
|
209
294
|
|
|
210
|
-
|
|
211
|
-
`api.add_menu_action(...)`, plus the old `register_taskgraph_plugin(api)`
|
|
212
|
-
function entrypoint, are still supported for compatibility. New plugins should
|
|
213
|
-
use the OOP `Plugin` class and namespaced API.
|
|
295
|
+
GUI plugins must define an OOP `Plugin` class and use the namespaced API.
|
|
214
296
|
|
|
215
297
|
Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
|
|
216
298
|
session. GUI plugin locations are not saved or automatically reloaded on the
|
|
@@ -222,12 +304,13 @@ This repository includes separate practical example plugins in
|
|
|
222
304
|
`examples/gui_plugins`:
|
|
223
305
|
|
|
224
306
|
- `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
|
|
225
|
-
panel and writing a status message
|
|
307
|
+
panel and writing a status message from **Examples → UI Panels**.
|
|
226
308
|
- `command_validate_graph.py` demonstrates the command API by registering a
|
|
227
|
-
reusable graph validation command and exposing it in
|
|
309
|
+
reusable graph validation command and exposing it in
|
|
310
|
+
**Examples → Commands**.
|
|
228
311
|
- `graph_daily_report.py` demonstrates the graph API by building a reusable
|
|
229
312
|
daily-report graph with nodes, dependency links, attribute links, and a
|
|
230
|
-
backdrop
|
|
313
|
+
backdrop from **Examples → Graph Builders**.
|
|
231
314
|
|
|
232
315
|
Load that directory, then use the **Examples** menu to run each example.
|
|
233
316
|
|
|
@@ -235,75 +318,6 @@ GUI plugins are intentionally separate from custom node locations. The
|
|
|
235
318
|
headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
|
|
236
319
|
import Qt widgets without breaking `koode-taskgraph-cli`.
|
|
237
320
|
|
|
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
321
|
## Architecture
|
|
308
322
|
|
|
309
323
|
- `core/model.py`: node contract—including inherited dependency port
|