nkparser 0.2.0__tar.gz → 0.4.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.
@@ -0,0 +1,30 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.4.0] - 2026-11-18
9
+
10
+ ### Added
11
+
12
+ - `nkparser diff OLD NEW` lists nodes added, removed and changed between two scripts. It exits 1 when the scripts differ. Use `--ignore xpos,ypos,selected` to skip knobs and `--format json` for machine-readable output.
13
+ - `nkparser git-diff` works as a git external diff driver, so `git diff` shows node changes for `.nk` files.
14
+ - `nkparser graph` prints the node graph as versioned JSON for editor previews.
15
+ - `--format json` for the `tree` and `show` commands.
16
+ - `diff_scripts()` and `graph_json()` in the Python API.
17
+ - The parser reports an error for `end_group` without a matching `Group`.
18
+
19
+ ### Fixed
20
+
21
+ - Groups now parse and serialize in the layout Nuke writes: knobs inside `Group { }`, children after the closing brace, up to `end_group`. Earlier versions wrote `end_group` inside the braces.
22
+ - Group children keep their `set`, `push` and `add_layer` statements in file order when written back.
23
+ - Knob values that span several lines (curves, multi-line strings) parse as one knob.
24
+ - The `duplicate-name` warning checks names per group. The same name in two groups is no longer reported.
25
+ - `nkparser --version` and `nkparser.__version__` report the installed version. They reported 0.1.0 in every release.
26
+ - The README no longer lists an `nkparse` console script, which does not exist.
27
+
28
+ ## [0.3.0] - 2026-03-30
29
+
30
+ First release with a changelog. See the git history for earlier changes.
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: nkparser
3
- Version: 0.2.0
3
+ Version: 0.4.0
4
4
  Summary: Parse, query, and serialize Foundry Nuke .nk script files
5
5
  Author-email: Virgil Sisoe <28490646+sisoe24@users.noreply.github.com>
6
6
  Requires-Python: >=3.10
@@ -38,11 +38,10 @@ uv pip install '.[graphviz]'
38
38
 
39
39
  ## CLI
40
40
 
41
- The package exposes two console scripts:
41
+ The package exposes the `nkparser` console script:
42
42
 
43
43
  ```bash
44
44
  uv run nkparser --help
45
- uv run nkparse --help
46
45
  ```
47
46
 
48
47
  You can also run it as a module:
@@ -57,11 +56,45 @@ uv run python -m nkparser --help
57
56
  uv run nkparser info tests/fixtures/minimal.nk
58
57
  uv run nkparser validate tests/fixtures/malformed_unclosed.nk
59
58
  uv run nkparser tree tests/fixtures/complex_groups.nk --knobs
59
+ uv run nkparser tree tests/fixtures/complex_groups.nk --knobs --format json
60
+ uv run nkparser show tests/fixtures/minimal.nk --format json
60
61
  uv run nkparser nodes tests/fixtures/minimal.nk --class Grade
61
62
  uv run nkparser dot tests/fixtures/minimal.nk -o graph.dot
62
63
  uv run nkparser dot tests/fixtures/minimal.nk -o graph.dot --render --dot-command /opt/homebrew/bin/dot
64
+ uv run nkparser diff v012.nk v013.nk --ignore xpos,ypos,selected
63
65
  ```
64
66
 
67
+ `nkparser diff` prints one line per change and exits 0 when the scripts match, 1 when they differ:
68
+
69
+ ```text
70
+ - Merge1 (Merge2)
71
+ + Blur2 (Blur)
72
+ ~ Grade1 (Grade) white: 1.2 -> 1.4
73
+ ~ Merge1 (Merge2) inputs: ['Grade1', 'Read1'] -> ['Grade1', None]
74
+ ```
75
+
76
+ Add `--format json` to get the raw dict from `diff_scripts`.
77
+
78
+ ## Use with git
79
+
80
+ `nkparser git-diff` is a git external diff driver: `git diff` then shows node changes for `.nk` files instead of raw text.
81
+
82
+ Add to `.gitattributes` in the repository:
83
+
84
+ ```text
85
+ *.nk diff=nk
86
+ ```
87
+
88
+ Register the driver (once per repository, or add `--global`):
89
+
90
+ ```bash
91
+ git config diff.nk.command "nkparser git-diff --ignore xpos,ypos,selected"
92
+ ```
93
+
94
+ `nkparser` must be on `PATH` for git. Drop `--ignore` to also see node moves. To see the raw text diff for one command, run `git diff --no-ext-diff`.
95
+
96
+ The driver always exits 0, because git stops the whole diff when an external driver exits non-zero. Added and deleted files show every node as `+` or `-`.
97
+
65
98
  ## Development
66
99
 
67
100
  Sync the dev environment:
@@ -24,11 +24,10 @@ uv pip install '.[graphviz]'
24
24
 
25
25
  ## CLI
26
26
 
27
- The package exposes two console scripts:
27
+ The package exposes the `nkparser` console script:
28
28
 
29
29
  ```bash
30
30
  uv run nkparser --help
31
- uv run nkparse --help
32
31
  ```
33
32
 
34
33
  You can also run it as a module:
@@ -43,11 +42,45 @@ uv run python -m nkparser --help
43
42
  uv run nkparser info tests/fixtures/minimal.nk
44
43
  uv run nkparser validate tests/fixtures/malformed_unclosed.nk
45
44
  uv run nkparser tree tests/fixtures/complex_groups.nk --knobs
45
+ uv run nkparser tree tests/fixtures/complex_groups.nk --knobs --format json
46
+ uv run nkparser show tests/fixtures/minimal.nk --format json
46
47
  uv run nkparser nodes tests/fixtures/minimal.nk --class Grade
47
48
  uv run nkparser dot tests/fixtures/minimal.nk -o graph.dot
48
49
  uv run nkparser dot tests/fixtures/minimal.nk -o graph.dot --render --dot-command /opt/homebrew/bin/dot
50
+ uv run nkparser diff v012.nk v013.nk --ignore xpos,ypos,selected
49
51
  ```
50
52
 
53
+ `nkparser diff` prints one line per change and exits 0 when the scripts match, 1 when they differ:
54
+
55
+ ```text
56
+ - Merge1 (Merge2)
57
+ + Blur2 (Blur)
58
+ ~ Grade1 (Grade) white: 1.2 -> 1.4
59
+ ~ Merge1 (Merge2) inputs: ['Grade1', 'Read1'] -> ['Grade1', None]
60
+ ```
61
+
62
+ Add `--format json` to get the raw dict from `diff_scripts`.
63
+
64
+ ## Use with git
65
+
66
+ `nkparser git-diff` is a git external diff driver: `git diff` then shows node changes for `.nk` files instead of raw text.
67
+
68
+ Add to `.gitattributes` in the repository:
69
+
70
+ ```text
71
+ *.nk diff=nk
72
+ ```
73
+
74
+ Register the driver (once per repository, or add `--global`):
75
+
76
+ ```bash
77
+ git config diff.nk.command "nkparser git-diff --ignore xpos,ypos,selected"
78
+ ```
79
+
80
+ `nkparser` must be on `PATH` for git. Drop `--ignore` to also see node moves. To see the raw text diff for one command, run `git diff --no-ext-diff`.
81
+
82
+ The driver always exits 0, because git stops the whole diff when an external driver exits non-zero. Added and deleted files show every node as `+` or `-`.
83
+
51
84
  ## Development
52
85
 
53
86
  Sync the dev environment:
@@ -30,6 +30,10 @@ Quick start::
30
30
 
31
31
  from __future__ import annotations
32
32
 
33
+ from importlib.metadata import version
34
+
35
+ from .diff import diff_scripts
36
+ from .graph import graph_json
33
37
  from .query import NodeQuery
34
38
  from .errors import (LexError, ParseError, NkParserError, ValidationError,
35
39
  SerializationError)
@@ -38,7 +42,7 @@ from .models import (Knob, Node, Script, GroupNode, KnobValue, Diagnostic,
38
42
  VariableAssignment)
39
43
  from .visualization import TextTree, DotExporter
40
44
 
41
- __version__ = "0.1.0"
45
+ __version__ = version("nkparser")
42
46
 
43
47
  __all__ = [
44
48
  # Core model
@@ -60,6 +64,8 @@ __all__ = [
60
64
  "SerializationError",
61
65
  # Query
62
66
  "NodeQuery",
67
+ "diff_scripts",
68
+ "graph_json",
63
69
  # Visualization
64
70
  "TextTree",
65
71
  "DotExporter",
@@ -182,31 +182,20 @@ class ScriptBuilder:
182
182
  knobs = [self._build_knob(rk) for rk in raw.knobs]
183
183
 
184
184
  if raw.is_group:
185
- # Build children, simulating stack within the group context.
186
- # Groups have their own isolated stack; we save and restore.
187
- saved_stack = self._execution_stack
188
- self._execution_stack = []
189
- children: list[Node] = []
185
+ # A group has its own stack. Its nodes and set/push ops go to the
186
+ # group, not the script, so swap in fresh lists while building them.
187
+ saved = self._execution_stack, self._script.nodes, self._script._ordered_statements
188
+ self._execution_stack, self._script.nodes, self._script._ordered_statements = [], [], []
190
189
  for child_stmt in raw.children:
191
190
  self._process_statement(child_stmt)
192
- # Collect nodes that were appended to self._script.nodes
193
- # from this group's children processing — we need to move
194
- # them into the group's children list instead.
195
- # Any nodes added to script.nodes during group processing are
196
- # actually children — move the last N nodes.
197
- n_children = len(raw.children)
198
- group_children = self._script.nodes[-n_children:]
199
- del self._script.nodes[-n_children:]
200
- # Also remove their ordered statements
201
- # (re-add them nested under the group in serializer)
202
- del self._script._ordered_statements[-n_children:]
203
- children = group_children
204
- self._execution_stack = saved_stack
191
+ children, ordered = self._script.nodes, self._script._ordered_statements
192
+ self._execution_stack, self._script.nodes, self._script._ordered_statements = saved
205
193
  node: Node = GroupNode(
206
194
  class_name=raw.node_class,
207
195
  knobs=knobs,
208
196
  children=children,
209
197
  is_unclosed=raw.is_unclosed,
198
+ _ordered_statements=ordered,
210
199
  source_line=raw.source_line,
211
200
  source_end_line=raw.source_end_line,
212
201
  )
@@ -8,6 +8,9 @@ tree Print a hierarchical text tree of the node graph.
8
8
  dot Export the node graph to a Graphviz DOT file.
9
9
  nodes List all nodes, optionally filtered by class or name.
10
10
  show Dump the raw (or modified) .nk text — useful for debugging.
11
+ diff List nodes added, removed and changed between two .nk files.
12
+ git-diff Git external diff driver for .nk files.
13
+ graph Print the node graph as JSON (versioned, for editor previews).
11
14
 
12
15
  Usage examples
13
16
  --------------
@@ -22,6 +25,7 @@ Usage examples
22
25
 
23
26
  from __future__ import annotations
24
27
 
28
+ import os
25
29
  import sys
26
30
  import csv
27
31
  import io
@@ -31,7 +35,9 @@ from typing import Any
31
35
  from pathlib import Path
32
36
 
33
37
  from . import __version__
34
- from .models import Node, Script, DiagnosticSeverity
38
+ from .diff import diff_scripts
39
+ from .graph import graph_json
40
+ from .models import Node, Script, GroupNode, DiagnosticSeverity
35
41
  from .visualization import TextTree, DotExporter
36
42
 
37
43
  # ---------------------------------------------------------------------------
@@ -43,7 +49,7 @@ def _load(path: str) -> Script:
43
49
  p = Path(path)
44
50
  if not p.exists():
45
51
  print(f"error: file not found: {path}", file=sys.stderr)
46
- sys.exit(1)
52
+ sys.exit(2)
47
53
  if p.suffix.lower() != ".nk":
48
54
  print(
49
55
  f"warning: file does not have .nk extension: {path}", file=sys.stderr)
@@ -160,8 +166,30 @@ def cmd_validate(args: argparse.Namespace) -> int:
160
166
  return _exit_code(script)
161
167
 
162
168
 
169
+ def _tree_node(node: Node, show_knobs: bool, depth: int, max_depth: int) -> dict[str, Any]:
170
+ entry: dict[str, Any] = {
171
+ "class": node.class_name,
172
+ "name": node.name,
173
+ "inputs": [(n.name or n.class_name) if n else None for n in node.inputs],
174
+ }
175
+ if show_knobs and depth < max_depth:
176
+ entry["knobs"] = {k.name: _cap(k.value.raw) for k in node.knobs
177
+ if k.name not in ("name", "xpos", "ypos")}
178
+ if isinstance(node, GroupNode) and depth < max_depth:
179
+ entry["children"] = [_tree_node(c, show_knobs, depth + 1, max_depth)
180
+ for c in node.children]
181
+ return entry
182
+
183
+
163
184
  def cmd_tree(args: argparse.Namespace) -> int:
164
185
  script = _load(args.file)
186
+ if getattr(args, "format", "text") == "json":
187
+ print(json.dumps({
188
+ "file": args.file,
189
+ "version": script.nuke_version,
190
+ "nodes": [_tree_node(n, args.knobs, 0, args.depth) for n in script.nodes],
191
+ }, indent=2))
192
+ return _exit_code(script)
165
193
  output = TextTree(script).render(
166
194
  show_knobs=args.knobs,
167
195
  max_depth=args.depth,
@@ -240,43 +268,19 @@ def cmd_nodes(args: argparse.Namespace) -> int:
240
268
  )
241
269
  col_w[col] = min(_MAX_W, max(len(col), max_val))
242
270
 
243
- if getattr(args, "format", "text") == "json":
244
- def _node_dict(node: Node) -> dict[str, Any]:
245
- d: dict[str, Any] = {
246
- "class": node.class_name,
247
- "name": node.name,
248
- "xpos": int(node.xpos) if node.xpos is not None else None,
249
- "ypos": int(node.ypos) if node.ypos is not None else None,
250
- }
251
- if extra_cols:
252
- d["knobs"] = {c: node.get(c)
253
- for c in extra_cols if node.knob(c)}
254
- return d
271
+ knobs_arg = extra_cols if extra_cols else None
255
272
 
273
+ if getattr(args, "format", "text") == "json":
256
274
  out: dict[str, Any] = {
257
275
  "file": args.file,
258
- "nodes": [_node_dict(n) for n in nodes],
276
+ "nodes": [n.to_dict(knobs=knobs_arg) for n in nodes],
259
277
  "count": len(nodes),
260
278
  }
261
279
  print(json.dumps(out, indent=2))
262
280
  return _exit_code(script)
263
281
 
264
282
  if getattr(args, "format", "text") == "csv":
265
- buf = io.StringIO()
266
- headers = ["class", "name", "xpos", "ypos"] + extra_cols
267
- writer = csv.DictWriter(buf, fieldnames=headers)
268
- writer.writeheader()
269
- for node in nodes:
270
- row: dict[str, Any] = {
271
- "class": node.class_name,
272
- "name": node.name,
273
- "xpos": int(node.xpos) if node.xpos is not None else "",
274
- "ypos": int(node.ypos) if node.ypos is not None else "",
275
- }
276
- for c in extra_cols:
277
- row[c] = node.get(c)
278
- writer.writerow(row)
279
- print(buf.getvalue(), end="")
283
+ print(script.to_csv(nodes=nodes, knobs=knobs_arg), end="")
280
284
  return _exit_code(script)
281
285
 
282
286
  parts = [
@@ -308,10 +312,80 @@ def cmd_nodes(args: argparse.Namespace) -> int:
308
312
 
309
313
  def cmd_show(args: argparse.Namespace) -> int:
310
314
  script = _load(args.file)
315
+ if getattr(args, "format", "text") == "json":
316
+ print(json.dumps({"file": args.file, "nk": script.to_nk()}, indent=2))
317
+ return _exit_code(script)
311
318
  print(script.to_nk(), end="")
312
319
  return _exit_code(script)
313
320
 
314
321
 
322
+ _MAX_VALUE = 1000 # same cap as nuke_graph: one Roto curves knob can be 300,000 characters
323
+
324
+
325
+ def _cap(value: str | None) -> str | None:
326
+ if value is None or len(value) <= _MAX_VALUE:
327
+ return value
328
+ return f"<{len(value)} chars, cut>"
329
+
330
+
331
+ def _one_line(value: str | None) -> str | None:
332
+ # multi-line knob values (curves, repeated addUserKnob) would break one line per change
333
+ return value.replace("\n", "\\n") if value is not None else None
334
+
335
+
336
+ def _print_diff(old: Script, new: Script, ignore: str | None, fmt: str) -> bool:
337
+ """Print the diff of two scripts and return True when they differ."""
338
+ skip = [k.strip() for k in (ignore or "").split(",") if k.strip()]
339
+ result = diff_scripts(old, new, ignore=skip)
340
+ for entry in result["changed"]:
341
+ for pair in entry.get("knobs", {}).values():
342
+ pair[:] = [_cap(v) for v in pair]
343
+
344
+ if fmt == "json":
345
+ print(json.dumps(result))
346
+ else:
347
+ for n in result["removed"]:
348
+ print(f"- {n['name']} ({n['class']})")
349
+ for n in result["added"]:
350
+ print(f"+ {n['name']} ({n['class']})")
351
+ for n in result["changed"]:
352
+ label = f"~ {n['name']} ({n['class']})"
353
+ if "inputs" in n:
354
+ before, after = n["inputs"]
355
+ print(f"{label} inputs: {before} -> {after}")
356
+ for knob, (before, after) in n.get("knobs", {}).items():
357
+ print(f"{label} {knob}: {_one_line(before)} -> {_one_line(after)}")
358
+
359
+ return any(result.values())
360
+
361
+
362
+ def cmd_diff(args: argparse.Namespace) -> int:
363
+ """Exit 0 when the scripts match, 1 when they differ (like diff(1))."""
364
+ return 1 if _print_diff(_load(args.old), _load(args.new), args.ignore, args.format) else 0
365
+
366
+
367
+ def _load_git_side(path: str) -> Script:
368
+ # git passes /dev/null for the missing side of an added or deleted file
369
+ return Script.from_string("") if path == os.devnull else Script.from_file(path)
370
+
371
+
372
+ def cmd_git_diff(args: argparse.Namespace) -> int:
373
+ """Git external diff driver: path old-file old-hex old-mode new-file new-hex new-mode.
374
+
375
+ Always exits 0: git stops the whole diff when an external driver exits non-zero.
376
+ """
377
+ print(f"nkparser diff a/{args.path} b/{args.path}")
378
+ _print_diff(_load_git_side(args.old_file), _load_git_side(args.new_file),
379
+ args.ignore, args.format)
380
+ return 0
381
+
382
+
383
+ def cmd_graph(args: argparse.Namespace) -> int:
384
+ script = _load(args.file)
385
+ print(json.dumps(graph_json(script, file=args.file), indent=args.indent))
386
+ return _exit_code(script)
387
+
388
+
315
389
  # ---------------------------------------------------------------------------
316
390
  # Argument parser
317
391
  # ---------------------------------------------------------------------------
@@ -336,6 +410,8 @@ examples:
336
410
  nkparse nodes comp.nk --format csv
337
411
  nkparse validate comp.nk --format csv
338
412
  nkparse show comp.nk
413
+ nkparse diff v012.nk v013.nk --ignore xpos,ypos,selected
414
+ nkparse graph comp.nk --indent 2
339
415
  """,
340
416
  )
341
417
  parser.add_argument("--version", action="version",
@@ -367,6 +443,9 @@ examples:
367
443
  p_tree.add_argument(
368
444
  "--depth", "-d", type=int, default=99, metavar="N", help="Maximum tree depth (default: 99)"
369
445
  )
446
+ p_tree.add_argument(
447
+ "--format", choices=["text", "json"], default="text", help="Output format (default: text)"
448
+ )
370
449
 
371
450
  # dot
372
451
  p_dot = sub.add_parser(
@@ -422,6 +501,43 @@ examples:
422
501
  p_show = sub.add_parser(
423
502
  "show", help="Print the serialized .nk text (round-trip output)")
424
503
  p_show.add_argument("file", metavar="FILE", help=".nk file")
504
+ p_show.add_argument(
505
+ "--format", choices=["text", "json"], default="text", help="Output format (default: text)"
506
+ )
507
+
508
+ # diff
509
+ p_diff = sub.add_parser(
510
+ "diff", help="List nodes added, removed and changed between two files")
511
+ p_diff.add_argument("old", metavar="OLD", help="original .nk file")
512
+ p_diff.add_argument("new", metavar="NEW", help="changed .nk file")
513
+ p_diff.add_argument(
514
+ "--ignore", metavar="KNOBS", help="Comma-separated knobs to skip, e.g. xpos,ypos,selected"
515
+ )
516
+ p_diff.add_argument(
517
+ "--format", choices=["text", "json"], default="text", help="Output format (default: text)"
518
+ )
519
+
520
+ # git-diff
521
+ p_git = sub.add_parser(
522
+ "git-diff", help="Git external diff driver (set as diff.<driver>.command)")
523
+ for name in ("path", "old_file", "old_hex", "old_mode", "new_file", "new_hex", "new_mode"):
524
+ p_git.add_argument(name)
525
+ # git adds the new path and rename info for renamed files
526
+ p_git.add_argument("rename", nargs="*", help=argparse.SUPPRESS)
527
+ p_git.add_argument(
528
+ "--ignore", metavar="KNOBS", help="Comma-separated knobs to skip, e.g. xpos,ypos,selected"
529
+ )
530
+ p_git.add_argument(
531
+ "--format", choices=["text", "json"], default="text", help="Output format (default: text)"
532
+ )
533
+
534
+ # graph
535
+ p_graph = sub.add_parser(
536
+ "graph", help="Print the node graph as JSON for editor previews")
537
+ p_graph.add_argument("file", metavar="FILE", help=".nk file")
538
+ p_graph.add_argument(
539
+ "--indent", type=int, metavar="N", help="Indent JSON by N spaces (default: compact)"
540
+ )
425
541
 
426
542
  return parser
427
543
 
@@ -442,6 +558,9 @@ def main() -> None:
442
558
  "dot": cmd_dot,
443
559
  "nodes": cmd_nodes,
444
560
  "show": cmd_show,
561
+ "diff": cmd_diff,
562
+ "git-diff": cmd_git_diff,
563
+ "graph": cmd_graph,
445
564
  }
446
565
 
447
566
  fn = dispatch.get(args.command)
@@ -0,0 +1,79 @@
1
+ """Compare two parsed scripts node by node.
2
+
3
+ Nodes match by full name (``Group1.Blur1``). A node without a name uses its
4
+ class name, so ``Root`` matches ``Root``.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Any, Iterator, Optional, Iterable
10
+
11
+ from .models import Node, Script, GroupNode
12
+
13
+
14
+ def _walk(nodes: list[Node], prefix: str = "") -> Iterator[tuple[str, Node]]:
15
+ for node in nodes:
16
+ full = prefix + (node.name or node.class_name)
17
+ yield full, node
18
+ if isinstance(node, GroupNode):
19
+ yield from _walk(node.children, full + ".")
20
+
21
+
22
+ def _index(script: Script) -> dict[str, Node]:
23
+ index: dict[str, Node] = {}
24
+ for full, node in _walk(script.nodes):
25
+ key, n = full, 2
26
+ while key in index: # duplicate names: keep both, in file order
27
+ key, n = f"{full}#{n}", n + 1
28
+ index[key] = node
29
+ return index
30
+
31
+
32
+ def _knobs(node: Node, ignore: frozenset[str]) -> dict[str, str]:
33
+ values: dict[str, list[str]] = {}
34
+ for knob in node.knobs:
35
+ if knob.name not in ignore:
36
+ values.setdefault(knob.name, []).append(knob.value.raw)
37
+ # repeated knobs (addUserKnob) compare as one ordered value
38
+ return {name: "\n".join(raws) for name, raws in values.items()}
39
+
40
+
41
+ def _inputs(node: Node) -> list[Optional[str]]:
42
+ return [i.name if i is not None else None for i in node.inputs]
43
+
44
+
45
+ def diff_scripts(a: Script, b: Script, ignore: Iterable[str] = ()) -> dict[str, Any]:
46
+ """Return the nodes added, removed and changed from ``a`` to ``b``.
47
+
48
+ ``ignore`` lists knob names to skip, for example ``xpos`` and ``ypos``.
49
+ Each changed node lists only what differs, as ``[old, new]`` pairs; a
50
+ knob missing on one side shows as ``None``.
51
+ """
52
+ skip = frozenset(ignore)
53
+ old, new = _index(a), _index(b)
54
+
55
+ def same(name: str) -> bool:
56
+ # a node of another class under the same name is a replacement
57
+ return name in old and name in new and old[name].class_name == new[name].class_name
58
+
59
+ changed: list[dict[str, Any]] = []
60
+ for name, after in new.items():
61
+ if not same(name):
62
+ continue
63
+ before = old[name]
64
+ entry: dict[str, Any] = {"name": name, "class": after.class_name}
65
+ if _inputs(before) != _inputs(after):
66
+ entry["inputs"] = [_inputs(before), _inputs(after)]
67
+ kb, ka = _knobs(before, skip), _knobs(after, skip)
68
+ knobs = {k: [kb.get(k), ka.get(k)]
69
+ for k in sorted(kb.keys() | ka.keys()) if kb.get(k) != ka.get(k)}
70
+ if knobs:
71
+ entry["knobs"] = knobs
72
+ if len(entry) > 2:
73
+ changed.append(entry)
74
+
75
+ return {
76
+ "added": [{"name": n, "class": new[n].class_name} for n in new if not same(n)],
77
+ "removed": [{"name": n, "class": old[n].class_name} for n in old if not same(n)],
78
+ "changed": changed,
79
+ }
@@ -0,0 +1,74 @@
1
+ """Describe a parsed script's node graph as JSON for external viewers.
2
+
3
+ The Nuke-Tools VS Code extension reads this output, so its shape is a
4
+ contract: bump ``GRAPH_VERSION`` on any change that breaks a reader.
5
+ Node ids use the same full dotted names as ``diff_scripts``.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Any, Optional
11
+
12
+ from .diff import _index
13
+ from .models import Node, Script, GroupNode
14
+
15
+ GRAPH_VERSION = 1
16
+
17
+
18
+ def _int(node: Node, name: str) -> Optional[int]:
19
+ knob = node.knob(name)
20
+ value = knob.number_value if knob else None
21
+ return int(value) if value is not None else None
22
+
23
+
24
+ def _flag(node: Node, name: str) -> bool:
25
+ knob = node.knob(name)
26
+ return knob is not None and knob.bool_value is True
27
+
28
+
29
+ def _color(node: Node) -> Optional[str]:
30
+ """Return tile_color (0xRRGGBBAA, hex or decimal) as ``#rrggbbaa``."""
31
+ try:
32
+ value = int(node.get_string("tile_color"), 0)
33
+ except ValueError:
34
+ return None
35
+ # 0 means "use the class default color" in Nuke
36
+ return f"#{value:08x}" if 0 < value <= 0xFFFFFFFF else None
37
+
38
+
39
+ def graph_json(script: Script, file: Optional[str] = None) -> dict[str, Any]:
40
+ """Return the node graph of ``script`` as a version 1 graph dict.
41
+
42
+ ``file`` is copied to the output as is. The Root node is left out: it
43
+ holds script settings and has no place in the node graph.
44
+ """
45
+ index = _index(script)
46
+ # keyed by id(): GroupNode is a dataclass with eq, so it is unhashable
47
+ ids = {id(node): key for key, node in index.items()}
48
+ parents = {id(child): key for key, node in index.items()
49
+ if isinstance(node, GroupNode) for child in node.children}
50
+
51
+ nodes: list[dict[str, Any]] = []
52
+ for node_id, node in index.items():
53
+ if node.class_name == "Root":
54
+ continue
55
+ label = node.knob("label")
56
+ entry: dict[str, Any] = {
57
+ "id": node_id,
58
+ "name": node.name,
59
+ "class": node.class_name,
60
+ "parent": parents.get(id(node)),
61
+ "x": _int(node, "xpos"),
62
+ "y": _int(node, "ypos"),
63
+ "color": _color(node),
64
+ "label": node.get_string("label") if label else None,
65
+ "disabled": _flag(node, "disable"),
66
+ "hide_input": _flag(node, "hide_input"),
67
+ "inputs": [ids.get(id(i)) if i is not None else None for i in node.inputs],
68
+ "line": node.source_line,
69
+ }
70
+ if node.class_name == "BackdropNode":
71
+ entry["backdrop"] = {"w": _int(node, "bdwidth"), "h": _int(node, "bdheight")}
72
+ nodes.append(entry)
73
+
74
+ return {"version": GRAPH_VERSION, "file": file, "nodes": nodes}
@@ -216,6 +216,29 @@ class Node:
216
216
 
217
217
  return Serializer._serialize_node(self)
218
218
 
219
+ def to_dict(self, knobs: Optional[list[str]] = None) -> dict:
220
+ """Return a dict representation of this node.
221
+
222
+ Parameters
223
+ ----------
224
+ knobs:
225
+ ``None`` — omit extra knobs (default).
226
+ ``["*"]`` — include all knobs as a nested dict.
227
+ ``[...]`` — include only the named knobs.
228
+ """
229
+ d: dict = {
230
+ "class": self.class_name,
231
+ "name": self.name,
232
+ "xpos": int(self.xpos) if self.xpos is not None else None,
233
+ "ypos": int(self.ypos) if self.ypos is not None else None,
234
+ }
235
+ if knobs is not None:
236
+ cols = (
237
+ [k.name for k in self.knobs] if knobs == ["*"] else knobs
238
+ )
239
+ d["knobs"] = {c: self.get(c) for c in cols if self.knob(c)}
240
+ return d
241
+
219
242
  def __repr__(self) -> str:
220
243
  return f"<Node {self.class_name!r} name={self.name!r}>"
221
244
 
@@ -239,6 +262,8 @@ class GroupNode(Node):
239
262
  # by the builder; also includes nested GroupNodes).
240
263
  children: list[Node] = field(default_factory=list)
241
264
  is_unclosed: bool = False # True if end_group was missing (parse error)
265
+ # children plus set/push/add_layer ops in file order, for the serializer
266
+ _ordered_statements: list[object] = field(default_factory=list, repr=False)
242
267
 
243
268
  def iter_nodes(self, recursive: bool = True) -> Iterator[Node]:
244
269
  """Yield all descendant Nodes depth-first."""
@@ -398,6 +423,77 @@ class Script:
398
423
  with open(path, "w", encoding="utf-8") as fh:
399
424
  fh.write(self.to_nk())
400
425
 
426
+ def to_json(
427
+ self,
428
+ nodes: Optional[list[Node]] = None,
429
+ knobs: Optional[list[str]] = None,
430
+ ) -> str:
431
+ """Return a JSON array string of nodes.
432
+
433
+ Parameters
434
+ ----------
435
+ nodes:
436
+ Subset of nodes to include; defaults to ``all_nodes()``.
437
+ knobs:
438
+ ``None`` — omit extra knobs (default).
439
+ ``["*"]`` — include all knobs per node as a nested dict.
440
+ ``[...]`` — include only the named knobs.
441
+ """
442
+ import json
443
+
444
+ target = nodes if nodes is not None else list(self.all_nodes())
445
+ return json.dumps([n.to_dict(knobs=knobs) for n in target], indent=2)
446
+
447
+ def to_csv(
448
+ self,
449
+ nodes: Optional[list[Node]] = None,
450
+ knobs: Optional[list[str]] = None,
451
+ ) -> str:
452
+ """Return a CSV string of nodes.
453
+
454
+ Parameters
455
+ ----------
456
+ nodes:
457
+ Subset of nodes to include; defaults to ``all_nodes()``.
458
+ knobs:
459
+ ``None`` — only class/name/xpos/ypos columns (default).
460
+ ``["*"]`` — add a column for every knob found across all nodes.
461
+ ``[...]`` — add columns for the named knobs only.
462
+ """
463
+ import csv
464
+ import io
465
+
466
+ _FIXED = {"name", "xpos", "ypos"}
467
+ target = nodes if nodes is not None else list(self.all_nodes())
468
+
469
+ extra_cols: list[str] = []
470
+ if knobs is not None:
471
+ if knobs == ["*"]:
472
+ seen: dict[str, None] = {}
473
+ for node in target:
474
+ for k in node.knobs:
475
+ if k.name not in _FIXED and k.name not in seen:
476
+ seen[k.name] = None
477
+ extra_cols = list(seen)
478
+ else:
479
+ extra_cols = knobs
480
+
481
+ buf = io.StringIO()
482
+ headers = ["class", "name", "xpos", "ypos"] + extra_cols
483
+ writer = csv.DictWriter(buf, fieldnames=headers)
484
+ writer.writeheader()
485
+ for node in target:
486
+ row: dict = {
487
+ "class": node.class_name,
488
+ "name": node.name,
489
+ "xpos": int(node.xpos) if node.xpos is not None else "",
490
+ "ypos": int(node.ypos) if node.ypos is not None else "",
491
+ }
492
+ for c in extra_cols:
493
+ row[c] = node.get(c)
494
+ writer.writerow(row)
495
+ return buf.getvalue()
496
+
401
497
  # ------------------------------------------------------------------
402
498
  # Navigation
403
499
  # ------------------------------------------------------------------
@@ -10,7 +10,8 @@ Design notes:
10
10
  - Error recovery uses per-node checkpoints: when parsing a node body fails, the
11
11
  parser skips forward to the next top-level closing '}' and resumes, emitting
12
12
  a ParseError diagnostic for the broken node.
13
- - Groups (Group { ... end_group }) are handled recursively via _parse_group().
13
+ - Groups: knobs sit inside ``Group { }``; child statements follow the closing
14
+ brace up to ``end_group``, as Nuke writes them. Nested groups recurse.
14
15
  """
15
16
 
16
17
  from __future__ import annotations
@@ -70,6 +71,30 @@ RawStatement = RawNode | RawSetOp | RawPushOp | RawAddLayer
70
71
  _STACK_RE = re.compile(r"\[stack\s+(\d+)\]")
71
72
 
72
73
 
74
+ def _scan(text: str, depth: int, in_string: bool) -> tuple[int, bool]:
75
+ """Return brace depth and open-string state after ``text``.
76
+
77
+ Same rules as ``Lexer._read_brace_block``: braces inside a double-quoted
78
+ string do not count, and a backslash escapes the next character in a string.
79
+ """
80
+ i = 0
81
+ while i < len(text):
82
+ ch = text[i]
83
+ if in_string:
84
+ if ch == "\\":
85
+ i += 1
86
+ elif ch == '"':
87
+ in_string = False
88
+ elif ch == '"':
89
+ in_string = True
90
+ elif ch == "{":
91
+ depth += 1
92
+ elif ch == "}":
93
+ depth -= 1
94
+ i += 1
95
+ return depth, in_string
96
+
97
+
73
98
  # ---------------------------------------------------------------------------
74
99
  # Parser
75
100
  # ---------------------------------------------------------------------------
@@ -176,6 +201,10 @@ class Parser:
176
201
  return self._parse_push()
177
202
  if word == "add_layer":
178
203
  return self._parse_add_layer()
204
+ if word == "end_group":
205
+ self.errors.append(ParseError("end_group without a Group", tok.line, tok.col))
206
+ self._consume()
207
+ return None
179
208
 
180
209
  # Anything else should be a node class followed by {
181
210
  return self._parse_node()
@@ -261,22 +290,8 @@ class Parser:
261
290
  body_tok = self._consume() # BRACE_BLOCK token for the node body
262
291
  end_line = body_tok.end_line
263
292
 
264
- # Parse the brace block's inner text for knob lines.
265
- # Groups additionally contain child statements between their knobs and end_group.
266
- if is_group:
267
- knobs, children, is_unclosed = self._parse_group_body(
268
- body_tok.value[1:-1], line)
269
- return RawNode(
270
- node_class=node_class,
271
- knobs=knobs,
272
- children=children,
273
- is_group=True,
274
- is_unclosed=is_unclosed,
275
- source_line=line,
276
- source_end_line=end_line,
277
- )
278
- else:
279
- knobs = self._parse_node_body(body_tok.value[1:-1], line)
293
+ knobs = self._parse_node_body(body_tok.value[1:-1], line)
294
+ if not is_group:
280
295
  return RawNode(
281
296
  node_class=node_class,
282
297
  knobs=knobs,
@@ -284,6 +299,32 @@ class Parser:
284
299
  source_end_line=end_line,
285
300
  )
286
301
 
302
+ # Nuke writes a Group's children after its closing brace, up to end_group.
303
+ children: list[RawStatement] = []
304
+ is_unclosed = True
305
+ while True:
306
+ self._skip_newlines()
307
+ if self._at_eof():
308
+ break
309
+ tok = self._peek()
310
+ if tok.kind == TokenKind.WORD and tok.value == "end_group":
311
+ self._consume()
312
+ end_line = tok.line
313
+ is_unclosed = False
314
+ break
315
+ stmt = self._parse_statement()
316
+ if stmt is not None:
317
+ children.append(stmt)
318
+ return RawNode(
319
+ node_class=node_class,
320
+ knobs=knobs,
321
+ children=children,
322
+ is_group=True,
323
+ is_unclosed=is_unclosed,
324
+ source_line=line,
325
+ source_end_line=end_line,
326
+ )
327
+
287
328
  # ------------------------------------------------------------------
288
329
  # Node body parsing (knob lines inside a brace block)
289
330
  # ------------------------------------------------------------------
@@ -298,18 +339,24 @@ class Parser:
298
339
 
299
340
  while i < len(lines):
300
341
  raw_line = lines[i]
301
- stripped = raw_line.strip()
342
+ start_line = current_line
302
343
  i += 1
303
344
  current_line += 1
304
345
 
305
- if not stripped:
346
+ if not raw_line.strip():
306
347
  continue
307
348
 
349
+ # A knob value can span lines ({curve ...}, multi-line strings):
350
+ # keep joining lines until its braces and quotes close.
351
+ depth, in_string = _scan(raw_line, 0, False)
352
+ while (depth > 0 or in_string) and i < len(lines):
353
+ raw_line += "\n" + lines[i]
354
+ depth, in_string = _scan(lines[i], depth, in_string)
355
+ i += 1
356
+ current_line += 1
357
+
308
358
  # A knob line is: <name> <value>
309
- # Value may be a brace block that spans multiple lines — but since
310
- # the lexer already collected the full brace block into a single
311
- # BRACE_BLOCK token, within the node body text the braces are
312
- # already balanced inline.
359
+ stripped = raw_line.strip()
313
360
  parts = stripped.split(None, 1)
314
361
  if len(parts) == 0:
315
362
  continue
@@ -319,113 +366,13 @@ class Parser:
319
366
  RawKnob(
320
367
  name=knob_name,
321
368
  raw_value=raw_value,
322
- source_line=current_line - 1,
369
+ source_line=start_line,
323
370
  raw_line=raw_line,
324
371
  )
325
372
  )
326
373
 
327
374
  return knobs
328
375
 
329
- def _parse_group_body(
330
- self, body_text: str, base_line: int
331
- ) -> tuple[list[RawKnob], list[RawStatement], bool]:
332
- """Parse the interior of a Group { ... end_group } block.
333
-
334
- Returns (knobs, children, is_unclosed).
335
- """
336
- # Re-tokenise the inner body so we can use the same parser logic.
337
- from .lexer import \
338
- Lexer # local import to avoid circular at module load
339
-
340
- inner_lexer = Lexer(body_text)
341
- inner_tokens = inner_lexer.tokenize()
342
- # Adjust line numbers by base_line offset
343
- adjusted: list[Token] = []
344
- for t in inner_tokens:
345
- adjusted.append(
346
- Token(
347
- kind=t.kind,
348
- value=t.value,
349
- line=t.line + base_line,
350
- col=t.col,
351
- end_line=t.end_line + base_line,
352
- end_col=t.end_col,
353
- )
354
- )
355
-
356
- inner_parser = Parser(adjusted)
357
- knobs: list[RawKnob] = []
358
- children: list[RawStatement] = []
359
- is_unclosed = True
360
-
361
- inner_parser._skip_newlines()
362
-
363
- # First, parse leading knob lines (before any child nodes / end_group)
364
- # Knobs appear before child nodes in Group bodies.
365
- while not inner_parser._at_eof():
366
- inner_parser._skip_newlines()
367
- if inner_parser._at_eof():
368
- break
369
- tok = inner_parser._peek()
370
- if tok.kind != TokenKind.WORD:
371
- break
372
- if tok.value == "end_group":
373
- inner_parser._consume()
374
- is_unclosed = False
375
- break
376
-
377
- # Peek ahead: if next meaningful token after word is BRACE_BLOCK,
378
- # this is a child node; otherwise it's a knob line.
379
- next_idx = inner_parser._pos + 1
380
- while next_idx < len(inner_parser._tokens) and inner_parser._tokens[next_idx].kind in (
381
- TokenKind.NEWLINE,
382
- ):
383
- next_idx += 1
384
- next_tok = (
385
- inner_parser._tokens[next_idx]
386
- if next_idx < len(inner_parser._tokens)
387
- else inner_parser._tokens[-1]
388
- )
389
-
390
- if next_tok.kind == TokenKind.BRACE_BLOCK and tok.value not in (
391
- "set",
392
- "push",
393
- "add_layer",
394
- ):
395
- # Child node or nested group
396
- stmt = inner_parser._parse_statement()
397
- if stmt is not None:
398
- children.append(stmt)
399
- elif tok.value in ("set", "push", "add_layer"):
400
- stmt = inner_parser._parse_statement()
401
- if stmt is not None:
402
- children.append(stmt)
403
- else:
404
- # Knob line — consume the rest of the logical line
405
- knob_tok = inner_parser._consume()
406
- parts = knob_tok.value.split(
407
- None, 1) # shouldn't really happen
408
- knob_name = parts[0]
409
- raw_value = ""
410
-
411
- # Value tokens follow on same logical line
412
- val_parts: list[str] = []
413
- while not inner_parser._at_newline_or_eof():
414
- val_parts.append(inner_parser._consume().value)
415
- raw_value = " ".join(val_parts)
416
-
417
- knobs.append(
418
- RawKnob(
419
- name=knob_name,
420
- raw_value=raw_value,
421
- source_line=knob_tok.line,
422
- raw_line=f" {knob_name} {raw_value}",
423
- )
424
- )
425
-
426
- self.errors.extend(inner_parser.errors)
427
- return knobs, children, is_unclosed
428
-
429
376
  # ------------------------------------------------------------------
430
377
  # Token stream helpers
431
378
  # ------------------------------------------------------------------
@@ -48,25 +48,34 @@ class Serializer:
48
48
 
49
49
  # Body — replay ordered statements to preserve set/push interleaving
50
50
  for stmt in self._script._ordered_statements:
51
- if isinstance(stmt, Node):
52
- parts.append(self._serialize_node(stmt))
53
- elif isinstance(stmt, RawSetOp):
54
- parts.append(f"set {stmt.name} [stack {stmt.stack_index}]")
55
- elif isinstance(stmt, RawPushOp):
56
- parts.append(f"push ${stmt.ref}")
57
- elif isinstance(stmt, RawAddLayer):
58
- parts.append(f"add_layer {{{stmt.declaration}}}")
51
+ parts.append(self._serialize_statement(stmt, 0))
59
52
 
60
53
  return "\n".join(parts) + "\n"
61
54
 
62
55
  @staticmethod
63
- def _serialize_node(node: Node) -> str:
64
- lines: list[str] = [f"{node.class_name} {{"]
56
+ def _serialize_statement(stmt: object, depth: int) -> str:
57
+ # Nuke indents group contents one space per nesting level
58
+ indent = " " * depth
59
+ if isinstance(stmt, Node):
60
+ return Serializer._serialize_node(stmt, depth)
61
+ if isinstance(stmt, RawSetOp):
62
+ return f"{indent}set {stmt.name} [stack {stmt.stack_index}]"
63
+ if isinstance(stmt, RawPushOp):
64
+ return f"{indent}push ${stmt.ref}"
65
+ if isinstance(stmt, RawAddLayer):
66
+ return f"{indent}add_layer {{{stmt.declaration}}}"
67
+ raise TypeError(f"cannot serialize {stmt!r}")
68
+
69
+ @staticmethod
70
+ def _serialize_node(node: Node, depth: int = 0) -> str:
71
+ indent = " " * depth
72
+ lines: list[str] = [f"{indent}{node.class_name} {{"]
65
73
  for knob in node.knobs:
66
74
  lines.append(knob.raw_line)
75
+ lines.append(f"{indent}}}")
67
76
  if isinstance(node, GroupNode):
68
- for child in node.children:
69
- lines.append(Serializer._serialize_node(child))
70
- lines.append("end_group")
71
- lines.append("}")
77
+ # Nuke writes children after the Group's closing brace, up to end_group
78
+ for stmt in node._ordered_statements or node.children:
79
+ lines.append(Serializer._serialize_statement(stmt, depth + 1))
80
+ lines.append(f"{indent}end_group")
72
81
  return "\n".join(lines)
@@ -16,7 +16,7 @@ Diagnostic codes emitted:
16
16
 
17
17
  from __future__ import annotations
18
18
 
19
- from .models import Script, GroupNode, Diagnostic, DiagnosticSeverity
19
+ from .models import Node, Script, GroupNode, Diagnostic, DiagnosticSeverity
20
20
 
21
21
 
22
22
  class Validator:
@@ -59,20 +59,25 @@ class Validator:
59
59
  )
60
60
 
61
61
  def _check_duplicate_names(self) -> None:
62
- seen: dict[str, int] = {}
63
- for node in self._script.all_nodes():
64
- n = node.name
65
- if not n:
66
- continue
67
- if n in seen:
68
- self._emit(
69
- DiagnosticSeverity.WARNING,
70
- f"Duplicate node name {n!r} (first at line {seen[n]})",
71
- "duplicate-name",
72
- node.source_line,
73
- )
74
- else:
75
- seen[n] = node.source_line
62
+ # Nuke names are unique per group: Input1 may exist in every group
63
+ scopes: list[list[Node]] = [self._script.nodes]
64
+ while scopes:
65
+ seen: dict[str, int] = {}
66
+ for node in scopes.pop():
67
+ if isinstance(node, GroupNode):
68
+ scopes.append(node.children)
69
+ n = node.name
70
+ if not n:
71
+ continue
72
+ if n in seen:
73
+ self._emit(
74
+ DiagnosticSeverity.WARNING,
75
+ f"Duplicate node name {n!r} (first at line {seen[n]})",
76
+ "duplicate-name",
77
+ node.source_line,
78
+ )
79
+ else:
80
+ seen[n] = node.source_line
76
81
 
77
82
  def _check_orphaned_sets(self) -> None:
78
83
  pushed_names = {ref.name for ref in self._script._variable_refs}
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "nkparser"
3
- version = "0.2.0"
3
+ version = "0.4.0"
4
4
  description = "Parse, query, and serialize Foundry Nuke .nk script files"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
@@ -9,7 +9,7 @@ authors = [
9
9
  ]
10
10
 
11
11
  [tool.hatch.build.targets.sdist]
12
- exclude = ["sample", "tests", "out", ".uv-cache", "todo.md"]
12
+ exclude = ["sample", "tests", "out", "other", "docs", ".ropeproject", ".claude", ".uv-cache", "todo.md"]
13
13
 
14
14
  [project.scripts]
15
15
  nkparser = "nkparser.cli:main"
@@ -134,7 +134,7 @@ name = "exceptiongroup"
134
134
  version = "1.3.1"
135
135
  source = { registry = "https://pypi.org/simple" }
136
136
  dependencies = [
137
- { name = "typing-extensions", marker = "python_full_version < '3.13'" },
137
+ { name = "typing-extensions" },
138
138
  ]
139
139
  sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
140
140
  wheels = [
@@ -301,7 +301,7 @@ wheels = [
301
301
 
302
302
  [[package]]
303
303
  name = "nkparser"
304
- version = "0.2.0"
304
+ version = "0.4.0"
305
305
  source = { editable = "." }
306
306
 
307
307
  [package.optional-dependencies]
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes