koode-taskgraph 0.4.1__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.4.1 → koode_taskgraph-0.6.0}/PKG-INFO +25 -17
  2. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/README.md +24 -16
  3. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/PKG-INFO +25 -17
  4. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/SOURCES.txt +3 -0
  5. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/pyproject.toml +1 -1
  6. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/__init__.py +1 -1
  7. koode_taskgraph-0.6.0/taskgraph/__main__.py +5 -0
  8. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/app.py +7 -0
  9. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/cli.py +34 -1
  10. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/core/executor.py +199 -1
  11. koode_taskgraph-0.6.0/taskgraph/core/model.py +964 -0
  12. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/core/registry.py +61 -2
  13. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/core/serialization.py +24 -0
  14. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/nodes/__init__.py +5 -0
  15. koode_taskgraph-0.6.0/taskgraph/nodes/builtin.py +181 -0
  16. koode_taskgraph-0.6.0/taskgraph/nodes/systems.py +466 -0
  17. koode_taskgraph-0.6.0/taskgraph/nodes/utils.py +47 -0
  18. koode_taskgraph-0.6.0/taskgraph/ui/code_editor.py +104 -0
  19. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/ui/items.py +301 -2
  20. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/ui/main_window.py +292 -0
  21. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/ui/plugins.py +402 -94
  22. koode_taskgraph-0.6.0/taskgraph/ui/properties.py +373 -0
  23. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/ui/scene.py +217 -1
  24. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/ui/theme.py +6 -0
  25. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/tests/test_core.py +157 -5
  26. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/tests/test_gui_plugins.py +127 -66
  27. koode_taskgraph-0.4.1/taskgraph/__main__.py +0 -4
  28. koode_taskgraph-0.4.1/taskgraph/core/model.py +0 -190
  29. koode_taskgraph-0.4.1/taskgraph/nodes/builtin.py +0 -156
  30. koode_taskgraph-0.4.1/taskgraph/ui/properties.py +0 -193
  31. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/LICENSE +0 -0
  32. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/dependency_links.txt +0 -0
  33. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/entry_points.txt +0 -0
  34. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/requires.txt +0 -0
  35. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/koode_taskgraph.egg-info/top_level.txt +0 -0
  36. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/setup.cfg +0 -0
  37. {koode_taskgraph-0.4.1 → koode_taskgraph-0.6.0}/taskgraph/core/__init__.py +0 -0
  38. {koode_taskgraph-0.4.1 → 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.4.1
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
@@ -93,15 +93,26 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
93
93
 
94
94
  ## Built-in Nodes
95
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.
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
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.
100
103
  - **System → Print** prints an incoming value and supports an optional prefix.
101
104
  - **System → Run Command** executes a command and exposes stdout, stderr, and
102
105
  return code outputs. It supports an optional working directory, shell mode,
103
106
  timeout, and failure on non-zero exit. Shell mode executes exactly what the
104
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.
105
116
  - **Utils → Format Text** accepts multiple connections into its `value` input.
106
117
  Use positional placeholders such as `{0}`, `{1}`, and `{2}` in the template.
107
118
  `{value}` remains available as the first input value for simple one-input
@@ -183,7 +194,7 @@ node to edit its properties, then click **Run graph**.
183
194
  Create a module in `taskgraph/nodes/` and define a `ProcessNode` subclass:
184
195
 
185
196
  ```python
186
- from taskgraph.core.model import NodeProperty, PortSpec, ProcessNode
197
+ from taskgraph.core.model import PortSpec, ProcessNode, TextProperty
187
198
  from taskgraph.core.registry import register_node
188
199
 
189
200
  @register_node
@@ -194,17 +205,17 @@ class PrefixText(ProcessNode):
194
205
  inputs = (PortSpec("value", "any"),)
195
206
  outputs = (PortSpec("text", "text"),)
196
207
  properties = (
197
- NodeProperty("prefix", "Prefix", "text", "Result: "),
208
+ TextProperty("prefix", "Prefix", "Result: "),
198
209
  )
199
210
 
200
211
  def process(self, inputs):
201
212
  return {"text": f"{self.prefix}{inputs.get('value', '')}"}
202
213
  ```
203
214
 
204
- Property kinds map to generated controls in the Properties panel: `"text"` for
205
- a line edit, `"file"` for a file path field with a Browse button, `"bool"` for
206
- a checkbox, `"int"`/`"float"` for numeric fields, and `"choice"` for a
207
- dropdown using `choices`.
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.
208
219
 
209
220
  Modules in `taskgraph/nodes/` are discovered automatically. Custom modules can
210
221
  also live anywhere on disk:
@@ -272,9 +283,9 @@ class Plugin(TaskGraphGuiPlugin):
272
283
 
273
284
  def build_daily_report(self):
274
285
  text = self.graph.create_node(
275
- "input.text",
286
+ "input.string",
276
287
  name="Report Title",
277
- values={"text": "Daily Production Report"},
288
+ values={"string": "Daily Production Report"},
278
289
  position=(0, 0),
279
290
  )
280
291
  printer = self.graph.create_node(
@@ -283,7 +294,7 @@ class Plugin(TaskGraphGuiPlugin):
283
294
  position=(320, 0),
284
295
  )
285
296
  self.graph.connect_dependency(text, printer)
286
- self.graph.connect_attribute(text, "text", printer, "value")
297
+ self.graph.connect_attribute(text, "string", printer, "value")
287
298
  self.graph.add_backdrop(
288
299
  title="Daily Report Template",
289
300
  note="This graph was created by a GUI plugin.",
@@ -292,10 +303,7 @@ class Plugin(TaskGraphGuiPlugin):
292
303
  )
293
304
  ```
294
305
 
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.
306
+ GUI plugins must define an OOP `Plugin` class and use the namespaced API.
299
307
 
300
308
  Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
301
309
  session. GUI plugin locations are not saved or automatically reloaded on the
@@ -82,15 +82,26 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
82
82
 
83
83
  ## Built-in Nodes
84
84
 
85
- - Built-in nodes are organized as **System → Run Command/Print**,
86
- **Utils → Format Text**, and **Inputs → Text/Number**.
87
- - **Inputs → Text** outputs a user-provided text value.
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
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.
89
92
  - **System → Print** prints an incoming value and supports an optional prefix.
90
93
  - **System → Run Command** executes a command and exposes stdout, stderr, and
91
94
  return code outputs. It supports an optional working directory, shell mode,
92
95
  timeout, and failure on non-zero exit. Shell mode executes exactly what the
93
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.
94
105
  - **Utils → Format Text** accepts multiple connections into its `value` input.
95
106
  Use positional placeholders such as `{0}`, `{1}`, and `{2}` in the template.
96
107
  `{value}` remains available as the first input value for simple one-input
@@ -172,7 +183,7 @@ node to edit its properties, then click **Run graph**.
172
183
  Create a module in `taskgraph/nodes/` and define a `ProcessNode` subclass:
173
184
 
174
185
  ```python
175
- from taskgraph.core.model import NodeProperty, PortSpec, ProcessNode
186
+ from taskgraph.core.model import PortSpec, ProcessNode, TextProperty
176
187
  from taskgraph.core.registry import register_node
177
188
 
178
189
  @register_node
@@ -183,17 +194,17 @@ class PrefixText(ProcessNode):
183
194
  inputs = (PortSpec("value", "any"),)
184
195
  outputs = (PortSpec("text", "text"),)
185
196
  properties = (
186
- NodeProperty("prefix", "Prefix", "text", "Result: "),
197
+ TextProperty("prefix", "Prefix", "Result: "),
187
198
  )
188
199
 
189
200
  def process(self, inputs):
190
201
  return {"text": f"{self.prefix}{inputs.get('value', '')}"}
191
202
  ```
192
203
 
193
- Property kinds map to generated controls in the Properties panel: `"text"` for
194
- a line edit, `"file"` for a file path field with a Browse button, `"bool"` for
195
- a checkbox, `"int"`/`"float"` for numeric fields, and `"choice"` for a
196
- dropdown using `choices`.
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.
197
208
 
198
209
  Modules in `taskgraph/nodes/` are discovered automatically. Custom modules can
199
210
  also live anywhere on disk:
@@ -261,9 +272,9 @@ class Plugin(TaskGraphGuiPlugin):
261
272
 
262
273
  def build_daily_report(self):
263
274
  text = self.graph.create_node(
264
- "input.text",
275
+ "input.string",
265
276
  name="Report Title",
266
- values={"text": "Daily Production Report"},
277
+ values={"string": "Daily Production Report"},
267
278
  position=(0, 0),
268
279
  )
269
280
  printer = self.graph.create_node(
@@ -272,7 +283,7 @@ class Plugin(TaskGraphGuiPlugin):
272
283
  position=(320, 0),
273
284
  )
274
285
  self.graph.connect_dependency(text, printer)
275
- self.graph.connect_attribute(text, "text", printer, "value")
286
+ self.graph.connect_attribute(text, "string", printer, "value")
276
287
  self.graph.add_backdrop(
277
288
  title="Daily Report Template",
278
289
  note="This graph was created by a GUI plugin.",
@@ -281,10 +292,7 @@ class Plugin(TaskGraphGuiPlugin):
281
292
  )
282
293
  ```
283
294
 
284
- Older flat helpers such as `api.create_node(...)` and
285
- `api.add_menu_action(...)`, plus the old `register_taskgraph_plugin(api)`
286
- function entrypoint, are still supported for compatibility. New plugins should
287
- use the OOP `Plugin` class and namespaced API.
295
+ GUI plugins must define an OOP `Plugin` class and use the namespaced API.
288
296
 
289
297
  Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
290
298
  session. GUI plugin locations are not saved or automatically reloaded on the
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: koode-taskgraph
3
- Version: 0.4.1
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
@@ -93,15 +93,26 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
93
93
 
94
94
  ## Built-in Nodes
95
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.
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
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.
100
103
  - **System → Print** prints an incoming value and supports an optional prefix.
101
104
  - **System → Run Command** executes a command and exposes stdout, stderr, and
102
105
  return code outputs. It supports an optional working directory, shell mode,
103
106
  timeout, and failure on non-zero exit. Shell mode executes exactly what the
104
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.
105
116
  - **Utils → Format Text** accepts multiple connections into its `value` input.
106
117
  Use positional placeholders such as `{0}`, `{1}`, and `{2}` in the template.
107
118
  `{value}` remains available as the first input value for simple one-input
@@ -183,7 +194,7 @@ node to edit its properties, then click **Run graph**.
183
194
  Create a module in `taskgraph/nodes/` and define a `ProcessNode` subclass:
184
195
 
185
196
  ```python
186
- from taskgraph.core.model import NodeProperty, PortSpec, ProcessNode
197
+ from taskgraph.core.model import PortSpec, ProcessNode, TextProperty
187
198
  from taskgraph.core.registry import register_node
188
199
 
189
200
  @register_node
@@ -194,17 +205,17 @@ class PrefixText(ProcessNode):
194
205
  inputs = (PortSpec("value", "any"),)
195
206
  outputs = (PortSpec("text", "text"),)
196
207
  properties = (
197
- NodeProperty("prefix", "Prefix", "text", "Result: "),
208
+ TextProperty("prefix", "Prefix", "Result: "),
198
209
  )
199
210
 
200
211
  def process(self, inputs):
201
212
  return {"text": f"{self.prefix}{inputs.get('value', '')}"}
202
213
  ```
203
214
 
204
- Property kinds map to generated controls in the Properties panel: `"text"` for
205
- a line edit, `"file"` for a file path field with a Browse button, `"bool"` for
206
- a checkbox, `"int"`/`"float"` for numeric fields, and `"choice"` for a
207
- dropdown using `choices`.
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.
208
219
 
209
220
  Modules in `taskgraph/nodes/` are discovered automatically. Custom modules can
210
221
  also live anywhere on disk:
@@ -272,9 +283,9 @@ class Plugin(TaskGraphGuiPlugin):
272
283
 
273
284
  def build_daily_report(self):
274
285
  text = self.graph.create_node(
275
- "input.text",
286
+ "input.string",
276
287
  name="Report Title",
277
- values={"text": "Daily Production Report"},
288
+ values={"string": "Daily Production Report"},
278
289
  position=(0, 0),
279
290
  )
280
291
  printer = self.graph.create_node(
@@ -283,7 +294,7 @@ class Plugin(TaskGraphGuiPlugin):
283
294
  position=(320, 0),
284
295
  )
285
296
  self.graph.connect_dependency(text, printer)
286
- self.graph.connect_attribute(text, "text", printer, "value")
297
+ self.graph.connect_attribute(text, "string", printer, "value")
287
298
  self.graph.add_backdrop(
288
299
  title="Daily Report Template",
289
300
  note="This graph was created by a GUI plugin.",
@@ -292,10 +303,7 @@ class Plugin(TaskGraphGuiPlugin):
292
303
  )
293
304
  ```
294
305
 
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.
306
+ GUI plugins must define an OOP `Plugin` class and use the namespaced API.
299
307
 
300
308
  Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
301
309
  session. GUI plugin locations are not saved or automatically reloaded on the
@@ -18,7 +18,10 @@ taskgraph/core/registry.py
18
18
  taskgraph/core/serialization.py
19
19
  taskgraph/nodes/__init__.py
20
20
  taskgraph/nodes/builtin.py
21
+ taskgraph/nodes/systems.py
22
+ taskgraph/nodes/utils.py
21
23
  taskgraph/ui/__init__.py
24
+ taskgraph/ui/code_editor.py
22
25
  taskgraph/ui/items.py
23
26
  taskgraph/ui/main_window.py
24
27
  taskgraph/ui/plugins.py
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "koode-taskgraph"
7
- version = "0.4.1"
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,13 +45,18 @@ 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.",
40
56
  )
41
57
  parser.add_argument(
42
58
  "--file", "-f", required=True, type=Path,
43
- help="path to a .taskgraph or compatible JSON graph file",
59
+ help="path to a .taskgraph file",
44
60
  )
45
61
  parser.add_argument(
46
62
  "--workers", "-w", type=worker_count, default=4,
@@ -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()