nkparser 0.1.0__py3-none-any.whl

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.
nkparser/models.py ADDED
@@ -0,0 +1,526 @@
1
+ """Data model for Nuke .nk script files.
2
+
3
+ Public classes:
4
+ KnobValueKind — enum tag for knob value representation
5
+ KnobValue — tagged value holding verbatim raw text
6
+ Knob — a single knob (property) on a node
7
+ Node — a Nuke node with knobs and connectivity
8
+ GroupNode — a Group node containing child nodes/statements
9
+ VariableAssignment — a 'set X [stack 0]' operation
10
+ VariableReference — a 'push $X' operation
11
+ DiagnosticSeverity — enum for diagnostic level
12
+ Diagnostic — a single validation or parse diagnostic message
13
+ Script — the root object for a parsed .nk file
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import os
19
+ import re
20
+ from enum import Enum, auto
21
+ from typing import TYPE_CHECKING, Iterator, Optional
22
+ from dataclasses import field, dataclass
23
+
24
+ if TYPE_CHECKING:
25
+ from .query import NodeQuery
26
+
27
+
28
+ # ---------------------------------------------------------------------------
29
+ # Knob value model
30
+ # ---------------------------------------------------------------------------
31
+
32
+
33
+ class KnobValueKind(Enum):
34
+ BARE = auto() # xpos -409, inputs 2, true/false
35
+ QUOTED = auto() # "some string"
36
+ BRACE_EXPR = auto() # {{sin(frame/5)}} — double-brace TCL expression
37
+ BRACE_BLOCK = auto() # {1 0.5434 0 1} — vector / multiline data block
38
+ BRACKET = auto() # [stack 0] — bracket expression (rare as knob value)
39
+
40
+
41
+ @dataclass
42
+ class KnobValue:
43
+ # verbatim source text (used for round-trip)
44
+ raw: str
45
+ kind: KnobValueKind
46
+ interpreted: Optional[str] = None # lazily computed unescaped/parsed form
47
+
48
+ @classmethod
49
+ def classify(cls, raw: str) -> "KnobValue":
50
+ """Create a KnobValue with automatically determined kind."""
51
+ if raw.startswith('"'):
52
+ return cls(raw=raw, kind=KnobValueKind.QUOTED)
53
+ if raw.startswith("{{") and raw.endswith("}}"):
54
+ return cls(raw=raw, kind=KnobValueKind.BRACE_EXPR)
55
+ if raw.startswith("{"):
56
+ return cls(raw=raw, kind=KnobValueKind.BRACE_BLOCK)
57
+ if raw.startswith("["):
58
+ return cls(raw=raw, kind=KnobValueKind.BRACKET)
59
+ return cls(raw=raw, kind=KnobValueKind.BARE)
60
+
61
+ def as_string(self) -> Optional[str]:
62
+ """Return unquoted string content if QUOTED, else None."""
63
+ if self.kind != KnobValueKind.QUOTED:
64
+ return None
65
+ s = self.raw
66
+ if s.startswith('"') and s.endswith('"') and len(s) >= 2:
67
+ # Unescape standard backslash sequences
68
+ return s[1:-1].replace('\\"', '"').replace("\\n", "\n").replace("\\t", "\t")
69
+ return s
70
+
71
+ def as_number(self) -> Optional[float]:
72
+ """Return float if value is a bare numeric literal, else None."""
73
+ if self.kind != KnobValueKind.BARE:
74
+ return None
75
+ try:
76
+ return float(self.raw)
77
+ except ValueError:
78
+ return None
79
+
80
+ def as_bool(self) -> Optional[bool]:
81
+ """Return bool if value is 'true' or 'false', else None."""
82
+ if self.kind == KnobValueKind.BARE:
83
+ if self.raw == "true":
84
+ return True
85
+ if self.raw == "false":
86
+ return False
87
+ return None
88
+
89
+
90
+ # ---------------------------------------------------------------------------
91
+ # Knob
92
+ # ---------------------------------------------------------------------------
93
+
94
+
95
+ @dataclass
96
+ class Knob:
97
+ name: str
98
+ value: KnobValue
99
+ source_line: int = 0
100
+ # verbatim source line(s) — used for round-trip serialization
101
+ raw_line: str = ""
102
+ # set when value is mutated
103
+ _dirty: bool = field(default=False, repr=False)
104
+
105
+ def set_value(self, raw: str) -> None:
106
+ """Update the knob value and mark for re-serialization."""
107
+ self.value = KnobValue.classify(raw)
108
+ self.raw_line = f" {self.name} {raw}"
109
+ self._dirty = True
110
+
111
+ def is_user_knob(self) -> bool:
112
+ return self.name == "addUserKnob"
113
+
114
+ @property
115
+ def string_value(self) -> Optional[str]:
116
+ return self.value.as_string()
117
+
118
+ @property
119
+ def number_value(self) -> Optional[float]:
120
+ return self.value.as_number()
121
+
122
+ @property
123
+ def bool_value(self) -> Optional[bool]:
124
+ return self.value.as_bool()
125
+
126
+
127
+ # ---------------------------------------------------------------------------
128
+ # Node
129
+ # ---------------------------------------------------------------------------
130
+
131
+
132
+ @dataclass
133
+ class Node:
134
+ node_class: str
135
+ knobs: list[Knob] = field(default_factory=list)
136
+ source_line: int = 0
137
+ source_end_line: int = 0
138
+
139
+ # Populated by the builder — not part of the serialized form
140
+ _inputs: list[Optional["Node"]] = field(default_factory=list, repr=False)
141
+ _script_ref: Optional["Script"] = field(default=None, repr=False)
142
+
143
+ # ------------------------------------------------------------------
144
+ # Knob accessors
145
+ # ------------------------------------------------------------------
146
+
147
+ def knob(self, name: str) -> Optional[Knob]:
148
+ """Return the first Knob with the given name, or None."""
149
+ return next((k for k in self.knobs if k.name == name), None)
150
+
151
+ def knobs_named(self, name: str) -> list[Knob]:
152
+ """Return all knobs with the given name."""
153
+ return [k for k in self.knobs if k.name == name]
154
+
155
+ def get(self, name: str, default: str = "") -> str:
156
+ """Return the raw value of the first knob with the given name, or default."""
157
+ k = self.knob(name)
158
+ return default if k is None else k.value.raw
159
+
160
+ def get_string(self, name: str, default: str = "") -> str:
161
+ """Return unquoted string value of knob, or default."""
162
+ k = self.knob(name)
163
+ if k is None:
164
+ return default
165
+ s = k.string_value
166
+ return s if s is not None else k.value.raw
167
+
168
+ def set(self, name: str, raw_value: str) -> None:
169
+ """Set a knob value by name. Creates the knob if it doesn't exist."""
170
+ k = self.knob(name)
171
+ if k is not None:
172
+ k.set_value(raw_value)
173
+ else:
174
+ new_knob = Knob(
175
+ name=name,
176
+ value=KnobValue.classify(raw_value),
177
+ raw_line=f" {name} {raw_value}",
178
+ _dirty=True,
179
+ )
180
+ self.knobs.append(new_knob)
181
+
182
+ # ------------------------------------------------------------------
183
+ # Properties
184
+ # ------------------------------------------------------------------
185
+
186
+ @property
187
+ def name(self) -> str:
188
+ """Value of the 'name' knob (the node's unique identifier in Nuke)."""
189
+ k = self.knob("name")
190
+ if k is None:
191
+ return ""
192
+ s = k.string_value
193
+ return s if s is not None else k.value.raw
194
+
195
+ @property
196
+ def inputs(self) -> list[Optional["Node"]]:
197
+ return self._inputs
198
+
199
+ @property
200
+ def xpos(self) -> Optional[float]:
201
+ x = self.knob("xpos")
202
+ return x.number_value if x else None
203
+
204
+ @property
205
+ def ypos(self) -> Optional[float]:
206
+ y = self.knob("ypos")
207
+ return y.number_value if y else None
208
+
209
+ # ------------------------------------------------------------------
210
+ # Serialization
211
+ # ------------------------------------------------------------------
212
+
213
+ def to_nk(self) -> str:
214
+ """Serialize this node to .nk text."""
215
+ from .serializer import Serializer # avoid circular at import time
216
+
217
+ return Serializer._serialize_node(self)
218
+
219
+ def __repr__(self) -> str:
220
+ return f"<Node {self.node_class!r} name={self.name!r}>"
221
+
222
+ def __hash__(self) -> int:
223
+ return id(self)
224
+
225
+ def __eq__(self, other: object) -> bool:
226
+ return self is other
227
+
228
+
229
+ # ---------------------------------------------------------------------------
230
+ # GroupNode
231
+ # ---------------------------------------------------------------------------
232
+
233
+
234
+ @dataclass
235
+ class GroupNode(Node):
236
+ """A Group { ... end_group } block containing child nodes and statements."""
237
+
238
+ # Children are the inner statements (RawStatement converted to Node instances
239
+ # by the builder; also includes nested GroupNodes).
240
+ children: list[Node] = field(default_factory=list)
241
+ is_unclosed: bool = False # True if end_group was missing (parse error)
242
+
243
+ def iter_nodes(self, recursive: bool = True) -> Iterator[Node]:
244
+ """Yield all descendant Nodes depth-first."""
245
+ for child in self.children:
246
+ yield child
247
+ if recursive and isinstance(child, GroupNode):
248
+ yield from child.iter_nodes(recursive=True)
249
+
250
+ def __repr__(self) -> str:
251
+ return f"<GroupNode {self.node_class!r} name={self.name!r} children={len(self.children)}>"
252
+
253
+
254
+ # ---------------------------------------------------------------------------
255
+ # Variable operations (retained for validation and round-trip)
256
+ # ---------------------------------------------------------------------------
257
+
258
+
259
+ @dataclass
260
+ class VariableAssignment:
261
+ """Represents: set Na154c800 [stack 0]"""
262
+
263
+ name: str
264
+ stack_index: int
265
+ source_line: int
266
+
267
+
268
+ @dataclass
269
+ class VariableReference:
270
+ """Represents: push $Na154cc00"""
271
+
272
+ name: str
273
+ source_line: int
274
+ resolved: Optional[Node] = None # populated by the builder
275
+
276
+
277
+ # ---------------------------------------------------------------------------
278
+ # Diagnostics
279
+ # ---------------------------------------------------------------------------
280
+
281
+
282
+ class DiagnosticSeverity(Enum):
283
+ ERROR = "error"
284
+ WARNING = "warning"
285
+ INFO = "info"
286
+
287
+
288
+ @dataclass
289
+ class Diagnostic:
290
+ severity: DiagnosticSeverity
291
+ message: str
292
+ code: str # e.g. "unresolved-variable", "unclosed-group", "duplicate-name"
293
+ line: int
294
+ col: int = 0
295
+
296
+ def __str__(self) -> str:
297
+ return f"[{self.severity.value.upper()}] {self.code}: {self.message} (line {self.line})"
298
+
299
+
300
+ # ---------------------------------------------------------------------------
301
+ # Script — the root object
302
+ # ---------------------------------------------------------------------------
303
+
304
+ # Type alias for any statement stored alongside nodes in the ordered sequence
305
+ from .parser import (RawSetOp, RawPushOp, # noqa: E402 (after dataclass defs)
306
+ RawAddLayer)
307
+
308
+
309
+ @dataclass
310
+ class Script:
311
+ """The root object for a parsed Nuke .nk file.
312
+
313
+ Typical usage::
314
+
315
+ script = Script.from_file("comp.nk")
316
+ for node in script.all_nodes():
317
+ print(node)
318
+ reads = script.query().of_class("Read").all()
319
+ script.write("comp_modified.nk")
320
+ """
321
+
322
+ # Header metadata
323
+ shebang: Optional[str] = None
324
+ nuke_version: Optional[str] = None
325
+ window_layout_xml: Optional[str] = None
326
+
327
+ # Top-level nodes in document order
328
+ nodes: list[Node] = field(default_factory=list)
329
+
330
+ # Layer declarations in document order
331
+ add_layer_declarations: list[str] = field(default_factory=list)
332
+
333
+ # Variable tracking for validation (populated by builder)
334
+ _variables: dict[str, VariableAssignment] = field(
335
+ default_factory=dict, repr=False)
336
+ _variable_refs: list[VariableReference] = field(
337
+ default_factory=list, repr=False)
338
+
339
+ # Ordered list of all top-level statements (nodes + set/push/add_layer ops)
340
+ # needed for round-trip serialization preserving exact ordering.
341
+ _ordered_statements: list[object] = field(default_factory=list, repr=False)
342
+
343
+ # Validation diagnostics
344
+ diagnostics: list[Diagnostic] = field(default_factory=list, repr=False)
345
+
346
+ # ------------------------------------------------------------------
347
+ # I/O class methods
348
+ # ------------------------------------------------------------------
349
+
350
+ @classmethod
351
+ def from_file(cls, path: str | os.PathLike[str]) -> "Script":
352
+ """Parse a .nk file and return a Script.
353
+
354
+ Raises ParseError on fatal failures. Non-fatal issues are appended to
355
+ ``script.diagnostics``.
356
+ """
357
+ text = open(path, encoding="utf-8", errors="replace").read()
358
+ return cls.from_string(text)
359
+
360
+ @classmethod
361
+ def from_string(cls, text: str) -> "Script":
362
+ """Parse a .nk script from an in-memory string."""
363
+ from .lexer import Lexer
364
+ from .parser import Parser
365
+ from .builder import ScriptBuilder
366
+ from .validator import Validator
367
+
368
+ lexer = Lexer(text)
369
+ tokens = lexer.tokenize()
370
+ parser = Parser(tokens)
371
+ header, statements = parser.parse()
372
+ script = ScriptBuilder().build(header, statements)
373
+
374
+ # Absorb any lex/parse errors as diagnostics
375
+
376
+ for err in lexer.errors:
377
+ script.diagnostics.append(
378
+ Diagnostic(DiagnosticSeverity.ERROR, str(
379
+ err), "lex-error", err.line, err.col)
380
+ )
381
+ for err in parser.errors:
382
+ script.diagnostics.append(
383
+ Diagnostic(DiagnosticSeverity.ERROR, str(
384
+ err), "parse-error", err.line, err.col)
385
+ )
386
+
387
+ Validator(script).validate()
388
+ return script
389
+
390
+ def to_nk(self) -> str:
391
+ """Serialize the entire script back to .nk text."""
392
+ from .serializer import Serializer
393
+
394
+ return Serializer(self).serialize()
395
+
396
+ def write(self, path: str | os.PathLike[str]) -> None:
397
+ """Write the serialized script to a file."""
398
+ with open(path, "w", encoding="utf-8") as fh:
399
+ fh.write(self.to_nk())
400
+
401
+ # ------------------------------------------------------------------
402
+ # Navigation
403
+ # ------------------------------------------------------------------
404
+
405
+ def all_nodes(self, recursive: bool = True) -> Iterator[Node]:
406
+ """Yield every Node in the script.
407
+
408
+ If recursive=True, descends into GroupNode children.
409
+ """
410
+ for node in self.nodes:
411
+ yield node
412
+ if recursive and isinstance(node, GroupNode):
413
+ yield from node.iter_nodes(recursive=True)
414
+
415
+ def find(
416
+ self,
417
+ name: Optional[str] = None,
418
+ *,
419
+ attr: Optional[str] = None,
420
+ value: Optional[str] = None,
421
+ ) -> Optional[Node]:
422
+ """Return the first matching node.
423
+
424
+ Modes:
425
+ find("Grade1") — exact name match (backward compat)
426
+ find(value=r".+comp") — any knob value matches regex
427
+ find(attr="label", value=r"comp") — specific knob value matches regex
428
+ find(attr="label") — first node that has that knob
429
+ """
430
+ if name is not None:
431
+ for node in self.all_nodes():
432
+ if node.name == name:
433
+ return node
434
+ return None
435
+
436
+ rx = re.compile(value) if value is not None else None
437
+ for node in self.all_nodes():
438
+ if attr is not None:
439
+ k = node.knob(attr)
440
+ if k is None:
441
+ continue
442
+ if rx is None or rx.search(k.value.raw):
443
+ return node
444
+ else:
445
+ if rx is None:
446
+ return node
447
+ for k in node.knobs:
448
+ if rx.search(k.value.raw):
449
+ return node
450
+ break
451
+ return None
452
+
453
+ def find_all(
454
+ self,
455
+ node_class: Optional[str] = None,
456
+ name_pattern: Optional[str] = None,
457
+ *,
458
+ attr: Optional[str] = None,
459
+ value: Optional[str] = None,
460
+ ) -> list[Node]:
461
+ """Filter nodes by class, name regex, and/or knob attr/value regex.
462
+
463
+ Parameters
464
+ ----------
465
+ node_class: keep only nodes of this class
466
+ name_pattern: regex matched against the node name
467
+ attr: keep only nodes that have this knob name
468
+ value: regex matched against the knob's raw value
469
+ (all knobs when attr is None, specific knob otherwise)
470
+ """
471
+ name_rx = re.compile(name_pattern) if name_pattern else None
472
+ val_rx = re.compile(value) if value is not None else None
473
+ results: list[Node] = []
474
+ for node in self.all_nodes():
475
+ if node_class is not None and node.node_class != node_class:
476
+ continue
477
+ if name_rx is not None and not name_rx.search(node.name):
478
+ continue
479
+ if attr is not None or val_rx is not None:
480
+ if attr is not None:
481
+ k = node.knob(attr)
482
+ if k is None:
483
+ continue
484
+ if val_rx is not None and not val_rx.search(k.value.raw):
485
+ continue
486
+ else:
487
+ # val_rx without attr: any knob must match
488
+ if val_rx is not None and not any(
489
+ val_rx.search(k.value.raw) for k in node.knobs
490
+ ):
491
+ continue
492
+ results.append(node)
493
+ return results
494
+
495
+ def root(self) -> Optional[Node]:
496
+ """Return the Root node, or None."""
497
+ for node in self.nodes:
498
+ if node.node_class == "Root":
499
+ return node
500
+ return None
501
+
502
+ def query(self) -> "NodeQuery":
503
+ """Return a NodeQuery over all nodes in the script."""
504
+ from .query import NodeQuery
505
+
506
+ return NodeQuery(self.all_nodes())
507
+
508
+ # ------------------------------------------------------------------
509
+ # Diagnostic helpers
510
+ # ------------------------------------------------------------------
511
+
512
+ @property
513
+ def has_errors(self) -> bool:
514
+ return any(d.severity == DiagnosticSeverity.ERROR for d in self.diagnostics)
515
+
516
+ def errors(self) -> list[Diagnostic]:
517
+ return [d for d in self.diagnostics if d.severity == DiagnosticSeverity.ERROR]
518
+
519
+ def warnings(self) -> list[Diagnostic]:
520
+ return [d for d in self.diagnostics if d.severity == DiagnosticSeverity.WARNING]
521
+
522
+ def __repr__(self) -> str:
523
+ return (
524
+ f"<Script version={self.nuke_version!r} "
525
+ f"nodes={len(self.nodes)} diagnostics={len(self.diagnostics)}>"
526
+ )