koode-taskgraph 0.3.1__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 (33) hide show
  1. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/PKG-INFO +195 -98
  2. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/README.md +194 -97
  3. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/PKG-INFO +195 -98
  4. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/pyproject.toml +1 -1
  5. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/app.py +3 -9
  6. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/cli.py +1 -1
  7. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/nodes/builtin.py +7 -3
  8. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/ui/items.py +66 -20
  9. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/ui/main_window.py +52 -24
  10. koode_taskgraph-0.4.1/taskgraph/ui/plugins.py +512 -0
  11. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/tests/test_core.py +99 -0
  12. koode_taskgraph-0.4.1/tests/test_gui_plugins.py +386 -0
  13. koode_taskgraph-0.3.1/taskgraph/ui/plugins.py +0 -208
  14. koode_taskgraph-0.3.1/tests/test_gui_plugins.py +0 -159
  15. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/LICENSE +0 -0
  16. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/SOURCES.txt +0 -0
  17. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/dependency_links.txt +0 -0
  18. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/entry_points.txt +0 -0
  19. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/requires.txt +0 -0
  20. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/koode_taskgraph.egg-info/top_level.txt +0 -0
  21. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/setup.cfg +0 -0
  22. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/__init__.py +0 -0
  23. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/__main__.py +0 -0
  24. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/core/__init__.py +0 -0
  25. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/core/executor.py +0 -0
  26. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/core/model.py +0 -0
  27. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/core/registry.py +0 -0
  28. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/core/serialization.py +0 -0
  29. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/nodes/__init__.py +0 -0
  30. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/ui/__init__.py +0 -0
  31. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/ui/properties.py +0 -0
  32. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/ui/scene.py +0 -0
  33. {koode_taskgraph-0.3.1 → koode_taskgraph-0.4.1}/taskgraph/ui/theme.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: koode-taskgraph
3
- Version: 0.3.1
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,122 @@ 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
+
111
+ ## Remove local user settings
112
+
113
+ TaskGraph stores user preferences with Qt `QSettings` under organization
114
+ `TaskGraph` and application `TaskGraph`. Settings include saved custom node
115
+ locations and the execution worker count. GUI plugin locations are session-only
116
+ and are not saved, but older versions may have saved GUI plugin locations.
117
+
118
+ Default locations:
119
+
120
+ - **macOS:** `~/Library/Preferences/com.taskgraph.TaskGraph.plist`
121
+ - **Linux:** `~/.config/TaskGraph/TaskGraph.conf`
122
+ - If `XDG_CONFIG_HOME` is set:
123
+ `$XDG_CONFIG_HOME/TaskGraph/TaskGraph.conf`
124
+ - **Windows:** Registry key
125
+ `HKEY_CURRENT_USER\Software\TaskGraph\TaskGraph`
126
+
127
+ Quit TaskGraph before removing settings.
128
+
129
+ macOS:
130
+
131
+ ```bash
132
+ defaults delete com.taskgraph.TaskGraph
133
+ ```
134
+
135
+ Linux:
136
+
137
+ ```bash
138
+ rm ~/.config/TaskGraph/TaskGraph.conf
139
+ ```
140
+
141
+ Windows Command Prompt:
142
+
143
+ ```bat
144
+ reg delete HKCU\Software\TaskGraph\TaskGraph /f
145
+ ```
146
+
147
+ Windows PowerShell:
148
+
149
+ ```powershell
150
+ Remove-Item -Path "HKCU:\Software\TaskGraph\TaskGraph" -Recurse -Force
151
+ ```
152
+
37
153
  ## Headless CLI
38
154
 
39
155
  Execute a saved graph without starting Qt or opening a window:
@@ -51,7 +167,7 @@ koode-taskgraph-cli \
51
167
  --node-path /path/to/custom_nodes
52
168
  ```
53
169
 
54
- `--node-path` may be repeated. `TASKGRAPH_NODE_PATH` is also supported with
170
+ `--node-path` may be repeated. `TASKGRAPH_CUSTOM_NODES` is also supported with
55
171
  the normal platform path separator. Use `--json` for structured results,
56
172
  `--quiet` to hide progress messages, and `Ctrl+C` to cancel execution.
57
173
 
@@ -97,132 +213,113 @@ also live anywhere on disk:
97
213
  2. Select **Nodes → Add Custom Node Location…** and choose that directory.
98
214
  3. Restarting TaskGraph reloads the saved location automatically.
99
215
 
100
- Alternatively, set `TASKGRAPH_NODE_PATH` before launching. Separate multiple
216
+ Alternatively, set `TASKGRAPH_CUSTOM_NODES` before launching. Separate multiple
101
217
  directories with the platform path separator (`:` on macOS/Linux and `;` on
102
218
  Windows):
103
219
 
104
220
  ```bash
105
- TASKGRAPH_NODE_PATH="/path/to/company_nodes:/path/to/my_nodes" koode-taskgraph
221
+ TASKGRAPH_CUSTOM_NODES="/path/to/company_nodes:/path/to/my_nodes" koode-taskgraph
106
222
  ```
107
223
 
108
224
  Files beginning with `_` are ignored. Importing a custom node module executes
109
225
  its Python code, so only add trusted directories. The editor, property panel,
110
226
  serialization, and executor require no other changes.
111
227
 
228
+ This repository includes a practical custom node example in
229
+ `examples/custom_nodes/text_cleanup.py`. Load `examples/custom_nodes` from
230
+ **Nodes → Add Custom Node Location…** or with:
231
+
232
+ ```bash
233
+ TASKGRAPH_CUSTOM_NODES="/path/to/taskgraph/examples/custom_nodes" koode-taskgraph
234
+ ```
235
+
236
+ The example adds **Examples → Clean Text**, which trims text, optionally
237
+ collapses whitespace, and applies a selectable case conversion.
238
+
112
239
  ## Add a GUI plugin
113
240
 
114
- GUI plugins can add menus, actions, docks, and graph-building commands without
241
+ GUI plugins can add menus, commands, docks, and graph-building tools without
115
242
  editing TaskGraph source. Put one or more `.py` files in a plugin directory and
116
- define `register_taskgraph_plugin(api)`:
243
+ define `class Plugin(TaskGraphGuiPlugin)`.
244
+
245
+ The plugin API is split into namespaces. Inside `TaskGraphGuiPlugin` subclasses
246
+ these are available as:
247
+
248
+ - `self.commands` registers reusable commands.
249
+ - `self.ui` exposes GUI features such as menus, docks, and status messages.
250
+ - `self.graph` creates nodes, connects ports, reads the graph model, and adds
251
+ backdrops.
117
252
 
118
253
  ```python
119
- def register_taskgraph_plugin(api):
120
- def build_template_graph():
121
- text = api.create_node(
254
+ from taskgraph.ui.plugins import TaskGraphGuiPlugin
255
+
256
+
257
+ class Plugin(TaskGraphGuiPlugin):
258
+ plugin_id = "example.graph_daily_report"
259
+ name = "Daily Report Graph Builder"
260
+ version = "1.0.0"
261
+
262
+ def setup(self):
263
+ self.commands.register(
264
+ f"{self.plugin_id}.build_daily_report",
265
+ label="Graph API: Build Daily Report Graph",
266
+ callback=self.build_daily_report,
267
+ )
268
+ self.ui.menus.add_command(
269
+ "Examples/Graph Builders",
270
+ f"{self.plugin_id}.build_daily_report",
271
+ )
272
+
273
+ def build_daily_report(self):
274
+ text = self.graph.create_node(
122
275
  "input.text",
123
- name="Message",
124
- values={"text": "hello world"},
276
+ name="Report Title",
277
+ values={"text": "Daily Production Report"},
125
278
  position=(0, 0),
126
279
  )
127
- formatter = api.create_node(
128
- "text.format",
129
- name="Format Message",
130
- values={"template": "Output: {value}"},
131
- position=(280, 0),
132
- )
133
- printer = api.create_node(
280
+ printer = self.graph.create_node(
134
281
  "output.print",
135
- name="Print Result",
136
- position=(560, 0),
282
+ name="Print Report",
283
+ position=(320, 0),
137
284
  )
138
- api.connect_dependency(text, formatter)
139
- api.connect_attribute(text, "text", formatter, "value")
140
- api.connect_dependency(formatter, printer)
141
- api.connect_attribute(formatter, "text", printer, "value")
142
- api.add_backdrop(
143
- title="Template Notes",
285
+ self.graph.connect_dependency(text, printer)
286
+ self.graph.connect_attribute(text, "text", printer, "value")
287
+ self.graph.add_backdrop(
288
+ title="Daily Report Template",
144
289
  note="This graph was created by a GUI plugin.",
145
290
  position=(-40, -140),
146
- size=(720, 180),
291
+ size=(650, 170),
147
292
  )
148
-
149
- api.add_menu_action("Tools", "Build Template Graph", build_template_graph)
150
293
  ```
151
294
 
152
- Load GUI plugins from **Plugins → Add GUI Plugin Location…**. Restarting
153
- TaskGraph reloads saved plugin locations automatically. Alternatively, set
154
- `TASKGRAPH_PLUGIN_PATH` before launching, using the same platform path
155
- separator rules as `TASKGRAPH_NODE_PATH`.
295
+ Older flat helpers such as `api.create_node(...)` and
296
+ `api.add_menu_action(...)`, plus the old `register_taskgraph_plugin(api)`
297
+ function entrypoint, are still supported for compatibility. New plugins should
298
+ use the OOP `Plugin` class and namespaced API.
156
299
 
157
- This repository includes minimal example plugins in `examples/gui_plugins`.
158
- Load that directory, then run **Examples → Create Hello World Print Graph** or
159
- **Examples → Create Bingooo Print Graph**.
300
+ Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
301
+ session. GUI plugin locations are not saved or automatically reloaded on the
302
+ next launch. To load GUI plugins at startup, set `TASKGRAPH_GUI_PLUGINS` before
303
+ launching, using the same platform path separator rules as
304
+ `TASKGRAPH_CUSTOM_NODES`.
160
305
 
161
- GUI plugins are intentionally separate from custom node locations. The
162
- headless CLI loads `TASKGRAPH_NODE_PATH` only, so UI plugin code can safely
163
- import Qt widgets without breaking `koode-taskgraph-cli`.
306
+ This repository includes separate practical example plugins in
307
+ `examples/gui_plugins`:
164
308
 
165
- ## Controls
309
+ - `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
310
+ panel and writing a status message from **Examples → UI Panels**.
311
+ - `command_validate_graph.py` demonstrates the command API by registering a
312
+ reusable graph validation command and exposing it in
313
+ **Examples → Commands**.
314
+ - `graph_daily_report.py` demonstrates the graph API by building a reusable
315
+ daily-report graph with nodes, dependency links, attribute links, and a
316
+ backdrop from **Examples → Graph Builders**.
166
317
 
167
- - Standard commands are organized under the **File**, **Edit**, **Nodes**,
168
- **Graph**, **Plugins**, and **View** menus.
169
- - Drag a node from **Nodes** to the canvas, or double-click it.
170
- - Every node has fixed gold **dependency** input/output ports. These control
171
- process order but do not transfer values. Gold dependency connections show
172
- an arrowhead pointing from the upstream node toward the downstream node.
173
- - Declared node inputs and outputs are attribute ports. Attribute connections
174
- transfer values, but execution order comes only from dependency connections.
175
- An attribute connection therefore needs a dependency path from its source
176
- node to its target node.
177
- - Dependency ports connect only to dependency ports; compatible attribute
178
- ports connect only to attribute ports.
179
- - Select one or more nodes on the canvas and press **D** to toggle them
180
- disabled. Disabled nodes stay in the dependency chain but their process
181
- functions are skipped. The same command is available from **Edit**.
182
- - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
183
- shortcuts. Properties, disabled state, relative positions, and connections
184
- entirely inside the copied selection are preserved.
185
- - Select a node to edit generated property controls.
186
- - Use **Node Name** at the top of the Properties panel to give each node
187
- instance a descriptive name. Custom names appear in node headers and
188
- execution messages and are preserved when saving or copying nodes.
189
- - Select nodes or connections and press **Backspace** or **Delete** to remove
190
- them. **Edit → Delete Selected** works on every platform too.
191
- - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
192
- - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
193
- from left to right and parallel nodes vertically, then frames the result.
194
- - **Graph → Add Backdrop** creates a movable notes region behind the graph.
195
- Select it to edit its title, notes, color, width, and height in Properties.
196
- Drag the grip in its bottom-right corner to resize it interactively.
197
- Backdrops are stored in `.taskgraph` files.
198
- - **Ctrl+R** executes nodes in dependency order.
199
- - Independent dependency branches execute concurrently. Choose between one
200
- worker or any even worker count from 2 through 32 under
201
- **Graph → Worker Count**; the setting is remembered.
202
- - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
203
- Pending nodes are cancelled immediately. Running nodes receive a cooperative
204
- cancellation signal, and built-in command nodes terminate their subprocess
205
- groups promptly.
206
- - Clear displayed execution messages with **Graph → Clear Execution Log** or
207
- from the Execution panel's right-click menu.
208
- - Built-in nodes are organized as **System → Run Command/Print**,
209
- **Utils → Format Text**, and **Inputs → Text/Number**.
210
- - The built-in **System → Run Command** node executes a command and exposes
211
- stdout, stderr, and return code outputs. It supports an optional working
212
- directory, shell mode, timeout, and failure on non-zero exit. Shell mode
213
- executes exactly what the graph author enters, so only run trusted graphs.
214
- - Node headers show live execution state: amber while running, green when
215
- finished, red on failure, gray when a disabled node is skipped, and muted
216
- red when a node is blocked by an upstream failure. Cancelled nodes use a
217
- purple-gray state.
218
- Execution coordination runs outside the GUI thread so the final running
219
- node and parallel running nodes remain visible while work is in progress.
220
- - A failed node blocks only its downstream dependency branch. Independent
221
- parallel branches continue running and report their own final states.
222
- - Closed panels can be restored from **View → Nodes/Properties/Execution**.
223
- Use **View → Show All Panels** to restore everything at once.
318
+ Load that directory, then use the **Examples** menu to run each example.
224
319
 
225
- Graph files use readable JSON with the `.taskgraph` extension.
320
+ GUI plugins are intentionally separate from custom node locations. The
321
+ headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
322
+ import Qt widgets without breaking `koode-taskgraph-cli`.
226
323
 
227
324
  ## Architecture
228
325