koode-taskgraph 0.1.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 (30) hide show
  1. koode_taskgraph-0.1.0/PKG-INFO +7 -0
  2. koode_taskgraph-0.1.0/README.md +205 -0
  3. koode_taskgraph-0.1.0/koode_taskgraph.egg-info/PKG-INFO +7 -0
  4. koode_taskgraph-0.1.0/koode_taskgraph.egg-info/SOURCES.txt +28 -0
  5. koode_taskgraph-0.1.0/koode_taskgraph.egg-info/dependency_links.txt +1 -0
  6. koode_taskgraph-0.1.0/koode_taskgraph.egg-info/entry_points.txt +3 -0
  7. koode_taskgraph-0.1.0/koode_taskgraph.egg-info/requires.txt +2 -0
  8. koode_taskgraph-0.1.0/koode_taskgraph.egg-info/top_level.txt +1 -0
  9. koode_taskgraph-0.1.0/pyproject.toml +20 -0
  10. koode_taskgraph-0.1.0/setup.cfg +4 -0
  11. koode_taskgraph-0.1.0/taskgraph/__init__.py +4 -0
  12. koode_taskgraph-0.1.0/taskgraph/__main__.py +4 -0
  13. koode_taskgraph-0.1.0/taskgraph/app.py +53 -0
  14. koode_taskgraph-0.1.0/taskgraph/cli.py +123 -0
  15. koode_taskgraph-0.1.0/taskgraph/core/__init__.py +2 -0
  16. koode_taskgraph-0.1.0/taskgraph/core/executor.py +232 -0
  17. koode_taskgraph-0.1.0/taskgraph/core/model.py +190 -0
  18. koode_taskgraph-0.1.0/taskgraph/core/registry.py +90 -0
  19. koode_taskgraph-0.1.0/taskgraph/core/serialization.py +35 -0
  20. koode_taskgraph-0.1.0/taskgraph/nodes/__init__.py +14 -0
  21. koode_taskgraph-0.1.0/taskgraph/nodes/builtin.py +152 -0
  22. koode_taskgraph-0.1.0/taskgraph/ui/__init__.py +1 -0
  23. koode_taskgraph-0.1.0/taskgraph/ui/items.py +403 -0
  24. koode_taskgraph-0.1.0/taskgraph/ui/main_window.py +578 -0
  25. koode_taskgraph-0.1.0/taskgraph/ui/plugins.py +208 -0
  26. koode_taskgraph-0.1.0/taskgraph/ui/properties.py +165 -0
  27. koode_taskgraph-0.1.0/taskgraph/ui/scene.py +426 -0
  28. koode_taskgraph-0.1.0/taskgraph/ui/theme.py +30 -0
  29. koode_taskgraph-0.1.0/tests/test_core.py +310 -0
  30. koode_taskgraph-0.1.0/tests/test_gui_plugins.py +88 -0
@@ -0,0 +1,7 @@
1
+ Metadata-Version: 2.4
2
+ Name: koode-taskgraph
3
+ Version: 0.1.0
4
+ Summary: An extensible process node graph built with QtPy and PySide6
5
+ Requires-Python: >=3.10
6
+ Requires-Dist: PySide6>=6.7
7
+ Requires-Dist: QtPy>=2.4
@@ -0,0 +1,205 @@
1
+ # TaskGraph
2
+
3
+ TaskGraph is a small, extensible process graph editor built from scratch with
4
+ Python, QtPy, and PySide6.
5
+
6
+ ## Run
7
+
8
+ ```bash
9
+ python -m venv .venv
10
+ source .venv/bin/activate
11
+ python -m pip install koode-taskgraph
12
+ taskgraph
13
+ ```
14
+
15
+ For local development from this repository, use `python -m pip install -e .`.
16
+
17
+ ## Headless CLI
18
+
19
+ Execute a saved graph without starting Qt or opening a window:
20
+
21
+ ```bash
22
+ taskgraphcli --file /path/to/workflow.taskgraph
23
+ ```
24
+
25
+ Select the worker count and load external node locations when needed:
26
+
27
+ ```bash
28
+ taskgraphcli \
29
+ --file /path/to/workflow.taskgraph \
30
+ --workers 8 \
31
+ --node-path /path/to/custom_nodes
32
+ ```
33
+
34
+ `--node-path` may be repeated. `TASKGRAPH_NODE_PATH` is also supported with
35
+ the normal platform path separator. Use `--json` for structured results,
36
+ `--quiet` to hide progress messages, and `Ctrl+C` to cancel execution.
37
+
38
+ Exit codes are `0` for success, `1` for graph execution failure, `2` for
39
+ arguments/loading errors, and `130` for cancellation.
40
+
41
+ Double-click a node type in the left panel to add it. Drag from an output port
42
+ on the right of a node to an input port on the left of another node. Select a
43
+ node to edit its properties, then click **Run graph**.
44
+
45
+ ## Add a node
46
+
47
+ Create a module in `taskgraph/nodes/` and define a `ProcessNode` subclass:
48
+
49
+ ```python
50
+ from taskgraph.core.model import NodeProperty, PortSpec, ProcessNode
51
+ from taskgraph.core.registry import register_node
52
+
53
+ @register_node
54
+ class PrefixText(ProcessNode):
55
+ type_id = "custom.prefix_text"
56
+ title = "Prefix Text"
57
+ category = "Custom"
58
+ inputs = (PortSpec("value", "any"),)
59
+ outputs = (PortSpec("text", "text"),)
60
+ properties = (
61
+ NodeProperty("prefix", "Prefix", "text", "Result: "),
62
+ )
63
+
64
+ def process(self, inputs):
65
+ return {"text": f"{self.prefix}{inputs.get('value', '')}"}
66
+ ```
67
+
68
+ Modules in `taskgraph/nodes/` are discovered automatically. Custom modules can
69
+ also live anywhere on disk:
70
+
71
+ 1. Put one or more standalone `.py` node modules in a directory.
72
+ 2. Select **Nodes → Add Custom Node Location…** and choose that directory.
73
+ 3. Restarting TaskGraph reloads the saved location automatically.
74
+
75
+ Alternatively, set `TASKGRAPH_NODE_PATH` before launching. Separate multiple
76
+ directories with the platform path separator (`:` on macOS/Linux and `;` on
77
+ Windows):
78
+
79
+ ```bash
80
+ TASKGRAPH_NODE_PATH="/path/to/company_nodes:/path/to/my_nodes" taskgraph
81
+ ```
82
+
83
+ Files beginning with `_` are ignored. Importing a custom node module executes
84
+ its Python code, so only add trusted directories. The editor, property panel,
85
+ serialization, and executor require no other changes.
86
+
87
+ ## Add a GUI plugin
88
+
89
+ GUI plugins can add menus, actions, docks, and graph-building commands without
90
+ editing TaskGraph source. Put one or more `.py` files in a plugin directory and
91
+ define `register_taskgraph_plugin(api)`:
92
+
93
+ ```python
94
+ def register_taskgraph_plugin(api):
95
+ def build_template_graph():
96
+ text = api.create_node(
97
+ "input.text",
98
+ name="Message",
99
+ values={"text": "hello world"},
100
+ position=(0, 0),
101
+ )
102
+ formatter = api.create_node(
103
+ "text.format",
104
+ name="Format Message",
105
+ values={"template": "Output: {value}"},
106
+ position=(280, 0),
107
+ )
108
+ printer = api.create_node(
109
+ "output.print",
110
+ name="Print Result",
111
+ position=(560, 0),
112
+ )
113
+ api.connect_dependency(text, formatter)
114
+ api.connect_attribute(text, "text", formatter, "value")
115
+ api.connect_dependency(formatter, printer)
116
+ api.connect_attribute(formatter, "text", printer, "value")
117
+ api.add_backdrop(
118
+ title="Template Notes",
119
+ note="This graph was created by a GUI plugin.",
120
+ position=(-40, -140),
121
+ size=(720, 180),
122
+ )
123
+
124
+ api.add_menu_action("Tools", "Build Template Graph", build_template_graph)
125
+ ```
126
+
127
+ Load GUI plugins from **Plugins → Add GUI Plugin Location…**. Restarting
128
+ TaskGraph reloads saved plugin locations automatically. Alternatively, set
129
+ `TASKGRAPH_PLUGIN_PATH` before launching, using the same platform path
130
+ separator rules as `TASKGRAPH_NODE_PATH`.
131
+
132
+ GUI plugins are intentionally separate from custom node locations. The
133
+ headless CLI loads `TASKGRAPH_NODE_PATH` only, so UI plugin code can safely
134
+ import Qt widgets without breaking `taskgraphcli`.
135
+
136
+ ## Controls
137
+
138
+ - Standard commands are organized under the **File**, **Edit**, **Nodes**,
139
+ **Graph**, **Plugins**, and **View** menus.
140
+ - Drag a node from **Nodes** to the canvas, or double-click it.
141
+ - Every node has fixed gold **dependency** input/output ports. These control
142
+ process order but do not transfer values. Gold dependency connections show
143
+ an arrowhead pointing from the upstream node toward the downstream node.
144
+ - Declared node inputs and outputs are attribute ports. Attribute connections
145
+ transfer values, but execution order comes only from dependency connections.
146
+ An attribute connection therefore needs a dependency path from its source
147
+ node to its target node.
148
+ - Dependency ports connect only to dependency ports; compatible attribute
149
+ ports connect only to attribute ports.
150
+ - Select one or more nodes on the canvas and press **D** to toggle them
151
+ disabled. Disabled nodes stay in the dependency chain but their process
152
+ functions are skipped. The same command is available from **Edit**.
153
+ - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
154
+ shortcuts. Properties, disabled state, relative positions, and connections
155
+ entirely inside the copied selection are preserved.
156
+ - Select a node to edit generated property controls.
157
+ - Use **Node Name** at the top of the Properties panel to give each node
158
+ instance a descriptive name. Custom names appear in node headers and
159
+ execution messages and are preserved when saving or copying nodes.
160
+ - Select nodes or connections and press **Backspace** or **Delete** to remove
161
+ them. **Edit → Delete Selected** works on every platform too.
162
+ - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
163
+ - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
164
+ from left to right and parallel nodes vertically, then frames the result.
165
+ - **Graph → Add Backdrop** creates a movable notes region behind the graph.
166
+ Select it to edit its title, notes, color, width, and height in Properties.
167
+ Drag the grip in its bottom-right corner to resize it interactively.
168
+ Backdrops are stored in `.taskgraph` files.
169
+ - **Ctrl+R** executes nodes in dependency order.
170
+ - Independent dependency branches execute concurrently. Choose between one
171
+ worker or any even worker count from 2 through 32 under
172
+ **Graph → Worker Count**; the setting is remembered.
173
+ - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
174
+ Pending nodes are cancelled immediately. Running nodes receive a cooperative
175
+ cancellation signal, and built-in command nodes terminate their subprocess
176
+ groups promptly.
177
+ - Clear displayed execution messages with **Graph → Clear Execution Log** or
178
+ from the Execution panel's right-click menu.
179
+ - Built-in nodes are organized as **System → Run Command/Print**,
180
+ **Utils → Format Text**, and **Inputs → Text/Number**.
181
+ - The built-in **System → Run Command** node executes a command and exposes
182
+ stdout, stderr, and return code outputs. It supports an optional working
183
+ directory, shell mode, timeout, and failure on non-zero exit. Shell mode
184
+ executes exactly what the graph author enters, so only run trusted graphs.
185
+ - Node headers show live execution state: amber while running, green when
186
+ finished, red on failure, gray when a disabled node is skipped, and muted
187
+ red when a node is blocked by an upstream failure. Cancelled nodes use a
188
+ purple-gray state.
189
+ Execution coordination runs outside the GUI thread so the final running
190
+ node and parallel running nodes remain visible while work is in progress.
191
+ - A failed node blocks only its downstream dependency branch. Independent
192
+ parallel branches continue running and report their own final states.
193
+ - Closed panels can be restored from **View → Nodes/Properties/Execution**.
194
+ Use **View → Show All Panels** to restore everything at once.
195
+
196
+ Graph files use readable JSON with the `.taskgraph` extension.
197
+
198
+ ## Architecture
199
+
200
+ - `core/model.py`: node contract—including inherited dependency port
201
+ specifications—and serializable graph model
202
+ - `core/registry.py`: decorator-based built-in and external node discovery
203
+ - `core/executor.py`: validation and dependency-ordered execution
204
+ - `ui/`: graphics editor, node items, property editor, and main window
205
+ - `nodes/`: built-in examples and the extension point for new processes
@@ -0,0 +1,7 @@
1
+ Metadata-Version: 2.4
2
+ Name: koode-taskgraph
3
+ Version: 0.1.0
4
+ Summary: An extensible process node graph built with QtPy and PySide6
5
+ Requires-Python: >=3.10
6
+ Requires-Dist: PySide6>=6.7
7
+ Requires-Dist: QtPy>=2.4
@@ -0,0 +1,28 @@
1
+ README.md
2
+ pyproject.toml
3
+ koode_taskgraph.egg-info/PKG-INFO
4
+ koode_taskgraph.egg-info/SOURCES.txt
5
+ koode_taskgraph.egg-info/dependency_links.txt
6
+ koode_taskgraph.egg-info/entry_points.txt
7
+ koode_taskgraph.egg-info/requires.txt
8
+ koode_taskgraph.egg-info/top_level.txt
9
+ taskgraph/__init__.py
10
+ taskgraph/__main__.py
11
+ taskgraph/app.py
12
+ taskgraph/cli.py
13
+ taskgraph/core/__init__.py
14
+ taskgraph/core/executor.py
15
+ taskgraph/core/model.py
16
+ taskgraph/core/registry.py
17
+ taskgraph/core/serialization.py
18
+ taskgraph/nodes/__init__.py
19
+ taskgraph/nodes/builtin.py
20
+ taskgraph/ui/__init__.py
21
+ taskgraph/ui/items.py
22
+ taskgraph/ui/main_window.py
23
+ taskgraph/ui/plugins.py
24
+ taskgraph/ui/properties.py
25
+ taskgraph/ui/scene.py
26
+ taskgraph/ui/theme.py
27
+ tests/test_core.py
28
+ tests/test_gui_plugins.py
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ taskgraph = taskgraph.app:main
3
+ taskgraphcli = taskgraph.cli:main
@@ -0,0 +1,2 @@
1
+ PySide6>=6.7
2
+ QtPy>=2.4
@@ -0,0 +1,20 @@
1
+ [build-system]
2
+ requires = ["setuptools>=69", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "koode-taskgraph"
7
+ version = "0.1.0"
8
+ description = "An extensible process node graph built with QtPy and PySide6"
9
+ requires-python = ">=3.10"
10
+ dependencies = [
11
+ "PySide6>=6.7",
12
+ "QtPy>=2.4",
13
+ ]
14
+
15
+ [project.scripts]
16
+ taskgraph = "taskgraph.app:main"
17
+ taskgraphcli = "taskgraph.cli:main"
18
+
19
+ [tool.setuptools.packages.find]
20
+ include = ["taskgraph*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """TaskGraph package."""
2
+
3
+ __version__ = "0.1.0"
4
+
@@ -0,0 +1,4 @@
1
+ from taskgraph.app import main
2
+
3
+ raise SystemExit(main())
4
+
@@ -0,0 +1,53 @@
1
+ import os
2
+ import sys
3
+
4
+ from qtpy.QtCore import QSettings
5
+ from qtpy.QtWidgets import QApplication
6
+
7
+ from taskgraph.core.registry import load_custom_node_directory
8
+ from taskgraph.nodes import load_builtin_nodes
9
+ from taskgraph.ui.main_window import MainWindow
10
+ from taskgraph.ui.plugins import load_gui_plugin_directory
11
+
12
+
13
+ def main() -> int:
14
+ app = QApplication.instance() or QApplication(sys.argv)
15
+ app.setApplicationName("TaskGraph")
16
+ app.setOrganizationName("TaskGraph")
17
+ load_builtin_nodes()
18
+ saved_locations = QSettings().value("nodes/custom_locations", [])
19
+ if isinstance(saved_locations, str):
20
+ saved_locations = [saved_locations]
21
+ environment_locations = [
22
+ path for path in os.environ.get("TASKGRAPH_NODE_PATH", "").split(os.pathsep)
23
+ if path
24
+ ]
25
+ load_errors = []
26
+ for location in dict.fromkeys([*saved_locations, *environment_locations]):
27
+ try:
28
+ load_custom_node_directory(location)
29
+ except Exception as exc:
30
+ load_errors.append(f"{location}: {exc}")
31
+ window = MainWindow()
32
+ saved_plugin_locations = QSettings().value("plugins/custom_locations", [])
33
+ if isinstance(saved_plugin_locations, str):
34
+ saved_plugin_locations = [saved_plugin_locations]
35
+ environment_plugin_locations = [
36
+ path for path in os.environ.get("TASKGRAPH_PLUGIN_PATH", "").split(os.pathsep)
37
+ if path
38
+ ]
39
+ for location in dict.fromkeys([
40
+ *saved_plugin_locations,
41
+ *environment_plugin_locations,
42
+ ]):
43
+ try:
44
+ load_gui_plugin_directory(location, window)
45
+ except Exception as exc:
46
+ load_errors.append(f"{location}: {exc}")
47
+ window.palette.reload()
48
+ if load_errors:
49
+ window.console.appendPlainText(
50
+ "Custom loading errors:\n" + "\n".join(load_errors)
51
+ )
52
+ window.show()
53
+ return app.exec()
@@ -0,0 +1,123 @@
1
+ """Headless command-line runner for TaskGraph files."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import os
8
+ from pathlib import Path
9
+ import signal
10
+ import sys
11
+ from threading import Event
12
+
13
+ from taskgraph.core.executor import (
14
+ VALID_WORKER_COUNTS,
15
+ GraphExecutionCancelled,
16
+ GraphExecutionError,
17
+ execute_graph,
18
+ )
19
+ from taskgraph.core.registry import load_custom_node_directory
20
+ from taskgraph.core.serialization import load_graph
21
+ from taskgraph.nodes import load_builtin_nodes
22
+
23
+
24
+ def worker_count(value: str) -> int:
25
+ try:
26
+ count = int(value)
27
+ except ValueError as exc:
28
+ raise argparse.ArgumentTypeError("worker count must be an integer") from exc
29
+ if count not in VALID_WORKER_COUNTS:
30
+ raise argparse.ArgumentTypeError(
31
+ "worker count must be 1 or an even number from 2 through 32"
32
+ )
33
+ return count
34
+
35
+
36
+ def build_parser() -> argparse.ArgumentParser:
37
+ parser = argparse.ArgumentParser(
38
+ prog="taskgraphcli",
39
+ description="Execute a TaskGraph file without starting the Qt UI.",
40
+ )
41
+ parser.add_argument(
42
+ "--file", "-f", required=True, type=Path,
43
+ help="path to a .taskgraph or compatible JSON graph file",
44
+ )
45
+ parser.add_argument(
46
+ "--workers", "-w", type=worker_count, default=4,
47
+ help="parallel workers: 1 or an even number from 2 through 32 (default: 4)",
48
+ )
49
+ parser.add_argument(
50
+ "--node-path", action="append", default=[], metavar="DIRECTORY",
51
+ help="custom node directory; may be passed more than once",
52
+ )
53
+ parser.add_argument(
54
+ "--quiet", action="store_true",
55
+ help="suppress progress messages and print only the final status",
56
+ )
57
+ parser.add_argument(
58
+ "--json", action="store_true",
59
+ help="print the execution result as JSON",
60
+ )
61
+ return parser
62
+
63
+
64
+ def main(argv: list[str] | None = None) -> int:
65
+ args = build_parser().parse_args(argv)
66
+ graph_path = args.file.expanduser()
67
+ if not graph_path.is_file():
68
+ print(f"taskgraphcli: graph file not found: {graph_path}", file=sys.stderr)
69
+ return 2
70
+
71
+ try:
72
+ load_builtin_nodes()
73
+ environment_paths = [
74
+ path
75
+ for path in os.environ.get("TASKGRAPH_NODE_PATH", "").split(os.pathsep)
76
+ if path
77
+ ]
78
+ for location in dict.fromkeys([*environment_paths, *args.node_path]):
79
+ load_custom_node_directory(location)
80
+ graph = load_graph(graph_path)
81
+ except Exception as exc:
82
+ print(f"taskgraphcli: could not load graph: {exc}", file=sys.stderr)
83
+ return 2
84
+
85
+ cancel_event = Event()
86
+ previous_handler = signal.getsignal(signal.SIGINT)
87
+
88
+ def request_cancel(_signum, _frame) -> None:
89
+ if not cancel_event.is_set():
90
+ print("Cancellation requested…", file=sys.stderr)
91
+ cancel_event.set()
92
+
93
+ signal.signal(signal.SIGINT, request_cancel)
94
+ event_stream = sys.stderr if args.json else sys.stdout
95
+ emit = None if args.quiet else lambda message: print(message, file=event_stream)
96
+ try:
97
+ result = execute_graph(
98
+ graph,
99
+ on_event=emit,
100
+ max_workers=args.workers,
101
+ cancel_event=cancel_event,
102
+ )
103
+ except GraphExecutionCancelled as exc:
104
+ print(f"taskgraphcli: {exc}", file=sys.stderr)
105
+ return 130
106
+ except GraphExecutionError as exc:
107
+ print(f"taskgraphcli: execution failed:\n{exc}", file=sys.stderr)
108
+ return 1
109
+ finally:
110
+ signal.signal(signal.SIGINT, previous_handler)
111
+
112
+ if args.json:
113
+ print(json.dumps({
114
+ "order": result.order,
115
+ "outputs": result.outputs,
116
+ }, indent=2, default=repr))
117
+ else:
118
+ print(f"Completed {len(result.order)} node(s).")
119
+ return 0
120
+
121
+
122
+ if __name__ == "__main__":
123
+ raise SystemExit(main())
@@ -0,0 +1,2 @@
1
+ """Core graph model and execution engine."""
2
+