koode-taskgraph 0.5.0__tar.gz → 0.6.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.
Files changed (38) hide show
  1. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/PKG-INFO +1 -1
  2. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/PKG-INFO +1 -1
  3. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/pyproject.toml +1 -1
  4. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/__init__.py +1 -1
  5. koode_taskgraph-0.6.0/taskgraph/__main__.py +5 -0
  6. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/app.py +7 -0
  7. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/cli.py +33 -0
  8. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/core/executor.py +199 -1
  9. koode_taskgraph-0.6.0/taskgraph/core/model.py +964 -0
  10. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/core/registry.py +61 -2
  11. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/core/serialization.py +24 -0
  12. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/nodes/__init__.py +5 -0
  13. koode_taskgraph-0.6.0/taskgraph/nodes/builtin.py +181 -0
  14. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/nodes/systems.py +218 -17
  15. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/nodes/utils.py +23 -0
  16. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/ui/code_editor.py +35 -0
  17. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/ui/items.py +298 -0
  18. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/ui/main_window.py +292 -0
  19. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/ui/plugins.py +404 -11
  20. koode_taskgraph-0.6.0/taskgraph/ui/properties.py +373 -0
  21. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/ui/scene.py +217 -1
  22. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/ui/theme.py +2 -0
  23. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/tests/test_core.py +84 -1
  24. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/tests/test_gui_plugins.py +35 -0
  25. koode_taskgraph-0.5.0/taskgraph/__main__.py +0 -4
  26. koode_taskgraph-0.5.0/taskgraph/core/model.py +0 -358
  27. koode_taskgraph-0.5.0/taskgraph/nodes/builtin.py +0 -96
  28. koode_taskgraph-0.5.0/taskgraph/ui/properties.py +0 -145
  29. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/LICENSE +0 -0
  30. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/README.md +0 -0
  31. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/SOURCES.txt +0 -0
  32. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/dependency_links.txt +0 -0
  33. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/entry_points.txt +0 -0
  34. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/requires.txt +0 -0
  35. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/top_level.txt +0 -0
  36. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/setup.cfg +0 -0
  37. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/core/__init__.py +0 -0
  38. {koode_taskgraph-0.5.0 → koode_taskgraph-0.6.0}/taskgraph/ui/__init__.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: koode-taskgraph
3
- Version: 0.5.0
3
+ Version: 0.6.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
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: koode-taskgraph
3
- Version: 0.5.0
3
+ Version: 0.6.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
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "koode-taskgraph"
7
- version = "0.5.0"
7
+ version = "0.6.0"
8
8
  readme = "README.md"
9
9
  description = "An extensible process node graph built with QtPy and PySide6"
10
10
  requires-python = ">=3.10"
@@ -1,4 +1,4 @@
1
1
  """TaskGraph package."""
2
2
 
3
- __version__ = "0.1.0"
3
+ __version__ = "0.6.0"
4
4
 
@@ -0,0 +1,5 @@
1
+ """Allow ``python -m taskgraph`` to start the Qt application."""
2
+
3
+ from taskgraph.app import main
4
+
5
+ raise SystemExit(main())
@@ -1,3 +1,5 @@
1
+ """Qt application entrypoint for Koode TaskGraph."""
2
+
1
3
  import os
2
4
  import sys
3
5
 
@@ -11,6 +13,11 @@ from taskgraph.ui.plugins import load_gui_plugin_directory
11
13
 
12
14
 
13
15
  def main() -> int:
16
+ """Start the Qt GUI application and load configured extensions.
17
+
18
+ Returns:
19
+ int: Qt application exit code.
20
+ """
14
21
  app = QApplication.instance() or QApplication(sys.argv)
15
22
  app.setApplicationName("TaskGraph")
16
23
  app.setOrganizationName("TaskGraph")
@@ -22,6 +22,17 @@ from taskgraph.nodes import load_builtin_nodes
22
22
 
23
23
 
24
24
  def worker_count(value: str) -> int:
25
+ """Parse and validate the CLI worker-count option.
26
+
27
+ Args:
28
+ value: Raw command-line option value.
29
+
30
+ Returns:
31
+ int: Validated worker count.
32
+
33
+ Raises:
34
+ argparse.ArgumentTypeError: If the value is not an allowed worker count.
35
+ """
25
36
  try:
26
37
  count = int(value)
27
38
  except ValueError as exc:
@@ -34,6 +45,11 @@ def worker_count(value: str) -> int:
34
45
 
35
46
 
36
47
  def build_parser() -> argparse.ArgumentParser:
48
+ """Build the command-line argument parser.
49
+
50
+ Returns:
51
+ argparse.ArgumentParser: Configured parser for ``koode-taskgraph-cli``.
52
+ """
37
53
  parser = argparse.ArgumentParser(
38
54
  prog="koode-taskgraph-cli",
39
55
  description="Execute a TaskGraph file without starting the Qt UI.",
@@ -62,6 +78,14 @@ def build_parser() -> argparse.ArgumentParser:
62
78
 
63
79
 
64
80
  def main(argv: list[str] | None = None) -> int:
81
+ """Run a saved graph from the command line without opening the GUI.
82
+
83
+ Args:
84
+ argv: Optional argument list. When omitted, ``sys.argv`` is used.
85
+
86
+ Returns:
87
+ int: Process-style exit code.
88
+ """
65
89
  args = build_parser().parse_args(argv)
66
90
  graph_path = args.file.expanduser()
67
91
  if not graph_path.is_file():
@@ -86,6 +110,15 @@ def main(argv: list[str] | None = None) -> int:
86
110
  previous_handler = signal.getsignal(signal.SIGINT)
87
111
 
88
112
  def request_cancel(_signum, _frame) -> None:
113
+ """Handle Ctrl+C by requesting cooperative graph cancellation.
114
+
115
+ Args:
116
+ _signum: Received signal number.
117
+ _frame: Interrupted stack frame.
118
+
119
+ Returns:
120
+ None.
121
+ """
89
122
  if not cancel_event.is_set():
90
123
  print("Cancellation requested…", file=sys.stderr)
91
124
  cancel_event.set()
@@ -1,3 +1,5 @@
1
+ """Dependency-based graph execution engine."""
2
+
1
3
  from __future__ import annotations
2
4
 
3
5
  from collections import defaultdict, deque
@@ -12,15 +14,32 @@ VALID_WORKER_COUNTS = (1, *range(2, 33, 2))
12
14
 
13
15
 
14
16
  class GraphExecutionError(RuntimeError):
17
+ """Raised when graph execution fails for validation or node errors.
18
+
19
+ This is the public base exception for graph execution failures.
20
+ """
21
+
15
22
  pass
16
23
 
17
24
 
18
25
  class GraphExecutionCancelled(GraphExecutionError):
26
+ """Raised when graph execution is cancelled by the caller/user.
27
+
28
+ This exception is raised after the executor marks pending nodes cancelled.
29
+ """
30
+
19
31
  pass
20
32
 
21
33
 
22
34
  @dataclass
23
35
  class ExecutionResult:
36
+ """Final graph execution output and executed node order.
37
+
38
+ Attributes:
39
+ order: Node ids in the order they finished successfully.
40
+ outputs: Output dictionaries keyed first by node id, then by port name.
41
+ """
42
+
24
43
  order: list[str]
25
44
  outputs: dict[str, dict[str, Any]]
26
45
 
@@ -32,6 +51,23 @@ def execute_graph(
32
51
  on_node_state: Callable[[str, str], None] | None = None,
33
52
  cancel_event: Event | None = None,
34
53
  ) -> ExecutionResult:
54
+ """Execute a graph with optional logging, state callbacks, and cancellation.
55
+
56
+ Args:
57
+ graph: Graph model to execute.
58
+ on_event: Optional callback for execution log messages.
59
+ max_workers: Number of worker threads to use.
60
+ on_node_state: Optional callback receiving ``(node_id, state)``.
61
+ cancel_event: Optional event used to request cooperative cancellation.
62
+
63
+ Returns:
64
+ ExecutionResult: Completed node order and node outputs.
65
+
66
+ Raises:
67
+ ValueError: If ``max_workers`` is not an allowed worker count.
68
+ GraphExecutionError: If validation or node execution fails.
69
+ GraphExecutionCancelled: If cancellation is requested during execution.
70
+ """
35
71
  return GraphExecutor(
36
72
  graph,
37
73
  on_event=on_event,
@@ -41,6 +77,16 @@ def execute_graph(
41
77
 
42
78
 
43
79
  class GraphExecutor:
80
+ """Run graph nodes according to dependency connections.
81
+
82
+ Attributes:
83
+ graph: Graph model being executed.
84
+ emit: Callback used for execution log messages.
85
+ set_state: Callback used for node visual state changes.
86
+ cancel_event: Event used to request cooperative cancellation.
87
+ outputs: Completed node outputs keyed by node id.
88
+ """
89
+
44
90
  def __init__(
45
91
  self,
46
92
  graph: Graph,
@@ -48,6 +94,17 @@ class GraphExecutor:
48
94
  on_node_state: Callable[[str, str], None] | None = None,
49
95
  cancel_event: Event | None = None,
50
96
  ):
97
+ """Prepare executor state for one graph execution.
98
+
99
+ Args:
100
+ graph: Graph model to execute.
101
+ on_event: Optional callback for execution log messages.
102
+ on_node_state: Optional callback receiving ``(node_id, state)``.
103
+ cancel_event: Optional event used to request cancellation.
104
+
105
+ Returns:
106
+ None.
107
+ """
51
108
  self.graph = graph
52
109
  self.emit = on_event or (lambda _message: None)
53
110
  self.set_state = on_node_state or (lambda _node_id, _state: None)
@@ -65,6 +122,19 @@ class GraphExecutor:
65
122
  self.cancellation_applied = False
66
123
 
67
124
  def execute(self, max_workers: int = 4) -> ExecutionResult:
125
+ """Validate and run the graph, returning node order and outputs.
126
+
127
+ Args:
128
+ max_workers: Number of worker threads used for parallel branches.
129
+
130
+ Returns:
131
+ ExecutionResult: Completed node order and node outputs.
132
+
133
+ Raises:
134
+ ValueError: If ``max_workers`` is not supported.
135
+ GraphExecutionError: If the graph cannot be executed.
136
+ GraphExecutionCancelled: If cancellation is requested.
137
+ """
68
138
  self._validate_worker_count(max_workers)
69
139
  self._prepare_connections()
70
140
  self._validate_attribute_dependencies()
@@ -79,12 +149,31 @@ class GraphExecutor:
79
149
 
80
150
  @staticmethod
81
151
  def _validate_worker_count(max_workers: int) -> None:
152
+ """Reject unsupported worker counts before starting execution.
153
+
154
+ Args:
155
+ max_workers: Requested worker count.
156
+
157
+ Returns:
158
+ None.
159
+
160
+ Raises:
161
+ ValueError: If the worker count is not 1 or an even number up to 32.
162
+ """
82
163
  if max_workers not in VALID_WORKER_COUNTS:
83
164
  raise ValueError(
84
165
  "max_workers must be 1 or an even number between 2 and 32"
85
166
  )
86
167
 
87
168
  def _prepare_connections(self) -> None:
169
+ """Split graph connections into dependency and attribute lookup tables.
170
+
171
+ Returns:
172
+ None.
173
+
174
+ Raises:
175
+ GraphExecutionError: If a connection references a missing node.
176
+ """
88
177
  for edge in self.graph.connections:
89
178
  if (
90
179
  edge.source_node not in self.graph.nodes
@@ -99,6 +188,14 @@ class GraphExecutor:
99
188
  self.incoming[edge.target_node].append(edge)
100
189
 
101
190
  def _validate_attribute_dependencies(self) -> None:
191
+ """Ensure every value connection also has a dependency path.
192
+
193
+ Returns:
194
+ None.
195
+
196
+ Raises:
197
+ GraphExecutionError: If an attribute edge has no dependency path.
198
+ """
102
199
  for edge in self.attribute_edges:
103
200
  if not self._has_dependency_path(edge.source_node, edge.target_node):
104
201
  source = self.graph.nodes[edge.source_node]
@@ -109,6 +206,15 @@ class GraphExecutor:
109
206
  )
110
207
 
111
208
  def _has_dependency_path(self, source: str, target: str) -> bool:
209
+ """Return whether target is reachable from source through dependencies.
210
+
211
+ Args:
212
+ source: Source node id.
213
+ target: Target node id.
214
+
215
+ Returns:
216
+ bool: True when a dependency path connects source to target.
217
+ """
112
218
  pending = [source]
113
219
  visited = set()
114
220
  while pending:
@@ -121,6 +227,14 @@ class GraphExecutor:
121
227
  return False
122
228
 
123
229
  def _run(self, max_workers: int) -> None:
230
+ """Run ready nodes until there is no queued or running work.
231
+
232
+ Args:
233
+ max_workers: Number of worker threads available.
234
+
235
+ Returns:
236
+ None.
237
+ """
124
238
  with ThreadPoolExecutor(
125
239
  max_workers=max_workers,
126
240
  thread_name_prefix="taskgraph",
@@ -137,6 +251,11 @@ class GraphExecutor:
137
251
  self._handle_finished_futures(finished)
138
252
 
139
253
  def _apply_cancellation_if_requested(self) -> None:
254
+ """Mark pending work cancelled after the cancellation event is set.
255
+
256
+ Returns:
257
+ None.
258
+ """
140
259
  if not self.cancel_event.is_set() or self.cancellation_applied:
141
260
  return
142
261
  self.cancellation_applied = True
@@ -155,6 +274,15 @@ class GraphExecutor:
155
274
  pool: ThreadPoolExecutor,
156
275
  max_workers: int,
157
276
  ) -> None:
277
+ """Submit queued nodes to the thread pool while capacity is available.
278
+
279
+ Args:
280
+ pool: Thread pool used to execute node ``process`` methods.
281
+ max_workers: Maximum number of simultaneously running futures.
282
+
283
+ Returns:
284
+ None.
285
+ """
158
286
  while self.queue and len(self.running) < max_workers:
159
287
  node_id = self.queue.popleft()
160
288
  if node_id in self.terminal:
@@ -173,9 +301,21 @@ class GraphExecutor:
173
301
  self.emit(f"Running {node.display_name}")
174
302
  self.set_state(node_id, "running")
175
303
  node._cancel_event = self.cancel_event
304
+ node._event_callback = self.emit
176
305
  self.running[pool.submit(node.process, node_inputs)] = node_id
177
306
 
178
307
  def _inputs_for(self, node_id: str) -> dict[str, Any]:
308
+ """Build the process input dictionary for a ready node.
309
+
310
+ Args:
311
+ node_id: Id of the node that is about to run.
312
+
313
+ Returns:
314
+ dict[str, Any]: Input values keyed by target input port name.
315
+
316
+ Raises:
317
+ GraphExecutionError: If a required upstream output is missing.
318
+ """
179
319
  node = self.graph.nodes[node_id]
180
320
  node_inputs: dict[str, Any] = {}
181
321
  for edge in self.incoming[node_id]:
@@ -210,6 +350,14 @@ class GraphExecutor:
210
350
  self,
211
351
  finished: set[Future[dict[str, Any]]],
212
352
  ) -> None:
353
+ """Collect completed node results and update dependency state.
354
+
355
+ Args:
356
+ finished: Futures returned by completed node executions.
357
+
358
+ Returns:
359
+ None.
360
+ """
213
361
  for future in finished:
214
362
  node_id = self.running.pop(future)
215
363
  node = self.graph.nodes[node_id]
@@ -227,6 +375,7 @@ class GraphExecutor:
227
375
  continue
228
376
  finally:
229
377
  node._cancel_event = None
378
+ node._event_callback = None
230
379
 
231
380
  if not isinstance(result, dict):
232
381
  self._fail_branch(
@@ -240,18 +389,43 @@ class GraphExecutor:
240
389
 
241
390
  @staticmethod
242
391
  def _discard_cancelled_future(future: Future[dict[str, Any]]) -> None:
392
+ """Drain a future result after cancellation without surfacing errors.
393
+
394
+ Args:
395
+ future: Future to drain.
396
+
397
+ Returns:
398
+ None.
399
+ """
243
400
  try:
244
401
  future.result()
245
402
  except Exception:
246
403
  pass
247
404
 
248
405
  def _mark_cancelled(self, node_id: str) -> None:
406
+ """Record one node as cancelled and emit its execution state.
407
+
408
+ Args:
409
+ node_id: Id of the cancelled node.
410
+
411
+ Returns:
412
+ None.
413
+ """
249
414
  node = self.graph.nodes[node_id]
250
415
  self.terminal.add(node_id)
251
416
  self.set_state(node_id, "cancelled")
252
417
  self.emit(f"Cancelled {node.display_name}")
253
418
 
254
419
  def _complete(self, node_id: str, result: dict[str, Any]) -> None:
420
+ """Store one node result and queue newly unblocked downstream nodes.
421
+
422
+ Args:
423
+ node_id: Id of the completed node.
424
+ result: Output dictionary returned by the node.
425
+
426
+ Returns:
427
+ None.
428
+ """
255
429
  self.outputs[node_id] = result
256
430
  self.order.append(node_id)
257
431
  self.terminal.add(node_id)
@@ -261,7 +435,15 @@ class GraphExecutor:
261
435
  self.queue.append(target)
262
436
 
263
437
  def _fail_branch(self, node_id: str, message: str) -> None:
264
- """Fail one node and block only nodes that depend on its output."""
438
+ """Fail one node and block only nodes that depend on its output.
439
+
440
+ Args:
441
+ node_id: Id of the failed node.
442
+ message: Failure message to report.
443
+
444
+ Returns:
445
+ None.
446
+ """
265
447
  if node_id in self.terminal:
266
448
  return
267
449
  self.terminal.add(node_id)
@@ -282,6 +464,14 @@ class GraphExecutor:
282
464
  pending.extend(self.downstream[blocked_id])
283
465
 
284
466
  def _raise_if_cancelled(self) -> None:
467
+ """Raise the public cancellation error after all state is marked.
468
+
469
+ Returns:
470
+ None.
471
+
472
+ Raises:
473
+ GraphExecutionCancelled: If cancellation was requested.
474
+ """
285
475
  if not self.cancel_event.is_set():
286
476
  return
287
477
  for node_id in self.graph.nodes:
@@ -291,6 +481,14 @@ class GraphExecutor:
291
481
  raise GraphExecutionCancelled("Graph execution cancelled")
292
482
 
293
483
  def _raise_if_unresolved_or_failed(self) -> None:
484
+ """Raise a final error for cycles, blocked work, or node failures.
485
+
486
+ Returns:
487
+ None.
488
+
489
+ Raises:
490
+ GraphExecutionError: If any node failed or unresolved nodes remain.
491
+ """
294
492
  unresolved = set(self.graph.nodes) - self.terminal
295
493
  if unresolved:
296
494
  self.failures.append("The graph contains a cycle and cannot be executed")