nodebpy 520.26.0__tar.gz → 520.28.0__tar.gz

{nodebpy-520.26.0 → nodebpy-520.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nodebpy
-Version: 520.26.0
+Version: 520.28.0
 Summary: Build nodes trees in Blender more elegantly with code
 Author: Brady Johnston
 Author-email: Brady Johnston <brady.johnston@me.com>

{nodebpy-520.26.0 → nodebpy-520.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nodebpy"
-version = "520.26.0"
+version = "520.28.0"
 description = "Build nodes trees in Blender more elegantly with code"
 readme = "README.md"
 authors = [

{nodebpy-520.26.0 → nodebpy-520.28.0}/src/nodebpy/__init__.py

@@ -1,4 +1,4 @@
-from . import builder, export, nodes, types
+from . import builder, export, live, nodes, types
 from .builder import (
     ArrangeMethod,
     SimpleOptions,
@@ -22,6 +22,7 @@ __all__ = [
     "default_sugiyama_options",
     "export",
     "geometry",
+    "live",
     "nodes",
     "shader",
     "types",

{nodebpy-520.26.0 → nodebpy-520.28.0}/src/nodebpy/assets/__main__.py

@@ -90,8 +90,11 @@ def parse_args(
         ),
         epilog=(
             "subcommands:\n"
-            "  dump <blend> <output-dir>    dump every node-group asset in a "
+            "  dump <blend> <output-dir> [--names ...]\n"
+            "                               dump every node-group asset in a "
             ".blend to per-asset .py source files\n"
+            "                               (or only those matching --names, "
+            "wildcards supported)\n"
             "  build <source-dir> <blend>   rebuild the .blend asset library "
             "from dumped .py source files\n"
             "  ensure <source-dir> <blend>  rebuild only when the .blend or "

{nodebpy-520.26.0 → nodebpy-520.28.0}/src/nodebpy/assets/_library.py

@@ -467,7 +467,7 @@ def dump_library(
     blend_path: str | Path,
     output_dir: str | Path,
     *,
-    names: set[str] | None = None,
+    names: Iterable[str] | None = None,
     nodebpy_pkg: str = "nodebpy",
     snapshot_positions: bool = False,
     keep_reroutes: bool = False,
@@ -511,11 +511,20 @@ def dump_library(
     output_dir:
         Directory to write the per-asset modules into (created if needed).
     names:
-        Restrict the dump to these asset (node-group or material) names;
-        defaults to all. A full dump first clears the managed subdirectories
-        (``geometry``/``shader``/``compositor``/``materials``) so files from
-        renamed or deleted assets don't linger; a filtered dump leaves the
-        other assets' files in place.
+        Restrict the dump to the assets (node groups or materials) matching
+        these exact names or :mod:`fnmatch` wildcard patterns (``"Style *"``);
+        defaults to all. A pattern matching nothing raises. Meant for quick
+        iteration on a few assets: only the selected assets' modules are
+        regenerated, plus the ``_shared`` helper and ``materials/`` modules
+        they depend on — byte-identical to what a full dump writes for them,
+        because the whole library is still appended to decide what is shared
+        (a helper also used by an unselected asset stays in ``_shared``;
+        an unselected nested asset stays imported from its own module).
+        Edits to unselected assets are not picked up; a full dump (or the
+        ``check`` subcommand) catches those. A full dump first clears the
+        managed subdirectories (``geometry``/``shader``/``compositor``/
+        ``materials``) so files from renamed or deleted assets don't linger;
+        a filtered dump leaves the other assets' files in place.
     nodebpy_pkg:
         Import anchor for nodebpy in the generated sources, as for
         :func:`nodebpy.export.to_python`.
@@ -572,13 +581,18 @@ def dump_library(
         else (output_dir, blend_path)
     )
 
-    # Append every wanted asset in one load, so groups shared between assets
-    # (including assets nested in other assets) arrive as single trees and the
-    # sharing structure can be read off the session directly. Dependencies of
-    # other kinds (materials, images, …) come along too; everything appended
-    # is cleaned back out afterwards. The pre-append checks run inside the
-    # load context (the load itself happens on exit, with nothing selected
-    # when a check raises), so the .blend is opened only once.
+    # Append every asset in one load — even for a filtered dump — so groups
+    # shared between assets (including assets nested in other assets) arrive
+    # as single trees and the sharing structure can be read off the session
+    # directly: whether a helper is embedded or goes to _shared/ depends on
+    # how many assets reach it, and an asset outside the selection counts
+    # just the same. Appending is cheap next to code generation, which only
+    # runs for the selected roots. Dependencies of other kinds (materials,
+    # images, …) come along too; everything appended is cleaned back out
+    # afterwards. The pre-append checks run inside the load context (the
+    # load itself happens on exit, with nothing selected when a check
+    # raises), so the .blend is opened only once.
+    patterns = list(names) if names is not None else None
     before = {
         coll: set(getattr(bpy.data, coll).keys()) for coll in _CLEANUP_COLLECTIONS
     }
@@ -589,25 +603,28 @@ def dump_library(
         # assets_only exposes exactly the asset-marked materials: they are
         # dump roots alongside the node-group assets.
         available_materials = list(src.materials)
-        wanted = [n for n in available if names is None or n in names]
-        wanted_materials = [
-            n for n in available_materials if names is None or n in names
-        ]
-        if names is not None and (
-            missing := names - set(wanted) - set(wanted_materials)
-        ):
-            raise KeyError(f"Assets not found in {blend_path}: {sorted(missing)}")
-        clashes = sorted(n for n in wanted if n in bpy.data.node_groups)
+        selected: set[str] | None = None
+        if patterns is not None:
+            roots = available + available_materials
+            selected = {
+                n for n in roots if any(fnmatch.fnmatchcase(n, p) for p in patterns)
+            }
+            unmatched = [
+                p for p in patterns if not any(fnmatch.fnmatchcase(n, p) for n in roots)
+            ]
+            if unmatched:
+                raise KeyError(f"No assets in {blend_path} match: {unmatched}")
+        clashes = sorted(n for n in available if n in bpy.data.node_groups)
         if clashes:
             raise RuntimeError(
                 f"Node groups already exist in this session: {clashes}. "
                 "Appending would rename them and corrupt the dumped sources — "
                 "dump from a fresh session (e.g. python -m nodebpy.assets dump)."
             )
-        dst.node_groups = list(wanted)
+        dst.node_groups = list(available)
         # A same-named material already in the session renames the appended
         # one — caught by the post-append renamed-datablock guard below.
-        dst.materials = list(wanted_materials)
+        dst.materials = list(available_materials)
     added = {
         coll: [db for db in getattr(bpy.data, coll) if db.name not in before[coll]]
         for coll in _CLEANUP_COLLECTIONS
@@ -641,11 +658,12 @@ def dump_library(
             format=format,
             library_blend=anchor_blend.resolve() if typed_api else None,
             anchor_dir=anchor_dir.resolve(),
+            roots=selected,
             # A full dump owns the managed subdirectories: clear stale modules
             # from assets since renamed or deleted, so the next build_library
             # doesn't silently resurrect them. A filtered dump (names=...)
             # leaves the other assets' files alone.
-            clean_stale=names is None,
+            clean_stale=selected is None,
         )
     finally:
         for coll in _CLEANUP_COLLECTIONS:
@@ -699,6 +717,7 @@ def _dump_appended(
     format: bool,
     library_blend: Path | None = None,
     anchor_dir: Path | None = None,
+    roots: set[str] | None = None,
     clean_stale: bool = False,
 ) -> dict[str, Path]:
     """Partition the appended groups (and material roots and referenced
@@ -713,7 +732,11 @@ def _dump_appended(
     typed API — see ``dump_library(typed_api=...)`` — and ``anchor_dir``
     (default: ``output_dir``) is the directory the ``PackageLibrary``
     relative paths are computed against — see
-    ``dump_library(library_anchor=...)``. ``clean_stale`` removes
+    ``dump_library(library_anchor=...)``. ``roots`` restricts the modules
+    written to those assets (node-group or material names) plus the shared
+    helpers and materials they depend on — the partition itself is always
+    computed over every appended asset, so a filtered dump writes exactly
+    what a full one would for those modules. ``clean_stale`` removes
     modules under the managed subdirectories that this dump did not write
     (hand-written ``__init__.py`` files are kept, as ever).
     """
@@ -820,6 +843,24 @@ def _dump_appended(
     # and group calls to any of them use the typed parameter names.
     typed_groups = external if library_blend is not None else set()
 
+    # The modules this dump writes. A filtered dump writes the selected roots
+    # plus the modules they depend on that no other asset owns: the _shared
+    # helpers in their closures, the materials their footers record and those
+    # materials' shared helpers. Unselected assets — nested in a selected one
+    # or not — keep their own modules untouched and are imported as usual.
+    if roots is None:
+        write_assets = list(asset_trees)
+        write_materials = set(material_trees)
+    else:
+        write_assets = [t for t in asset_trees if t.name in roots]
+        write_materials = {k for k, m in material_trees.items() if m in roots}
+        for tree in write_assets:
+            for mat_name in module_dependencies(tree.name).get("materials", ()):
+                if (key := f"material:{mat_name}") in material_trees:
+                    write_materials.add(key)
+    write_roots = {t.name for t in write_assets} | write_materials
+    write_shared = shared & set().union(*(closures[r] for r in write_roots))
+
     def write_module(key: str, module: str, *, kind: str) -> Path:
         group = trees[key]
         # Emitted here: the tree itself plus, for roots, its private helpers.
@@ -876,13 +917,13 @@ def _dump_appended(
         return path
 
     written: dict[str, Path] = {}
-    for tree in asset_trees:
+    for tree in write_assets:
         written[tree.name] = write_module(tree.name, modules[tree.name], kind="asset")
     all_written = set(written.values())
-    for name in sorted(shared):
+    for name in sorted(write_shared):
         all_written.add(write_module(name, modules[name], kind="shared"))
     asset_material_names = set(asset_materials)
-    for key in sorted(material_trees):
+    for key in sorted(write_materials):
         path = write_module(key, modules[key], kind="material")
         all_written.add(path)
         # Material roots are assets the caller asked for, so they belong in
@@ -895,12 +936,14 @@ def _dump_appended(
     if library_blend is not None:
         # Typed API: each tree directory re-exports its asset classes, so
         # ``from <pkg>.<tree_dir> import <Class>`` (or an aliased module
-        # import) works like the old single-file API.
+        # import) works like the old single-file API. A filtered dump only
+        # exports modules that exist on disk (a full dump wrote them all).
         for dirname in set(_TREE_DIRS.values()):
             exports = sorted(
                 (modules[t.name].split("/")[1], class_names[t.name])
                 for t in asset_trees
                 if modules[t.name].startswith(f"{dirname}/")
+                and (output_dir / f"{modules[t.name]}.py").is_file()
             )
             if exports:
                 _write_dir_exports(output_dir / dirname, exports)
@@ -1674,7 +1717,15 @@ def _parse_args(argv: list[str] | None = None):
     dump.add_argument(
         "--names",
         nargs="+",
-        help="Only dump these asset (node-group or material) names (default: all).",
+        metavar="NAME",
+        help=(
+            "Only dump the assets (node groups or materials) matching these "
+            "names; fnmatch wildcards supported ('Style *', quoted to keep the "
+            "shell from expanding them). Default: all. The _shared helpers "
+            "and materials the selection depends on are written too, and the "
+            "other assets' files are left untouched — for quick iteration on "
+            "a few assets; a full dump (or 'check') catches edits elsewhere."
+        ),
     )
     _add_dump_flags(dump)
     dump.add_argument(
@@ -1856,7 +1907,7 @@ def _dump_command(args) -> None:
     written = dump_library(
         args.blend,
         args.output,
-        names=set(args.names) if args.names else None,
+        names=args.names or None,
         nodebpy_pkg=args.nodebpy_pkg,
         snapshot_positions=args.snapshot_positions,
         keep_reroutes=args.keep_reroutes,

{nodebpy-520.26.0 → nodebpy-520.28.0}/src/nodebpy/builder/tree.py

@@ -1108,11 +1108,28 @@ class TreeBuilder[TreeT: NodeTree]:
         fake_user: bool = False,
         ignore_visibility: bool = False,
         split_inputs: bool | None = None,
+        clear: bool = False,
     ):
+        # ``clear`` rebuilds in place: the tree is emptied (nodes, links and
+        # interface) before the body runs, keeping the datablock so modifiers,
+        # group nodes and pinned editors that reference it stay attached. With
+        # a name, an existing group of that name and tree type is reused
+        # instead of creating a ``Name.001`` duplicate; a group of another
+        # tree type is left alone and a new one is created as usual.
+        # Tree-level properties (description, color_tag, is_tool, fake user,
+        # ...) are kept: only the contents are rebuilt.
         if isinstance(tree, str):
-            self.tree = bpy.data.node_groups.new(tree, tree_type)  # ty: ignore[invalid-assignment]
+            existing = bpy.data.node_groups.get(tree) if clear else None
+            if existing is not None and existing.bl_idname == tree_type:
+                self.tree = existing
+            else:
+                self.tree = bpy.data.node_groups.new(tree, tree_type)  # ty: ignore[invalid-assignment]
         else:
             self.tree = tree  # type: ignore
+        if clear:
+            assert self.tree.interface is not None
+            self.tree.nodes.clear()
+            self.tree.interface.clear()
 
         self._menu_defaults: list[_MenuDefault] = []
         self._exited = False
@@ -1133,6 +1150,7 @@ class TreeBuilder[TreeT: NodeTree]:
         arrange: ArrangeMethod = "sugiyama",
         fake_user: bool = False,
         split_inputs: bool | None = None,
+        clear: bool = False,
     ) -> TreeBuilder[GeometryNodeTree]:
         """Create a geometry node tree."""
         return cast(
@@ -1144,6 +1162,7 @@ class TreeBuilder[TreeT: NodeTree]:
                 arrange=arrange,
                 fake_user=fake_user,
                 split_inputs=split_inputs,
+                clear=clear,
             ),
         )
 
@@ -1156,6 +1175,7 @@ class TreeBuilder[TreeT: NodeTree]:
         arrange: ArrangeMethod = "sugiyama",
         fake_user: bool = False,
         split_inputs: bool | None = None,
+        clear: bool = False,
     ) -> TreeBuilder[ShaderNodeTree]:
         """Create a shader node tree."""
         return cast(
@@ -1167,6 +1187,7 @@ class TreeBuilder[TreeT: NodeTree]:
                 arrange=arrange,
                 fake_user=fake_user,
                 split_inputs=split_inputs,
+                clear=clear,
             ),
         )
 
@@ -1179,6 +1200,7 @@ class TreeBuilder[TreeT: NodeTree]:
         arrange: ArrangeMethod = "sugiyama",
         fake_user: bool = False,
         split_inputs: bool | None = None,
+        clear: bool = False,
     ) -> TreeBuilder[CompositorNodeTree]:
         """Create a compositor node tree."""
         return cast(
@@ -1190,6 +1212,7 @@ class TreeBuilder[TreeT: NodeTree]:
                 arrange=arrange,
                 fake_user=fake_user,
                 split_inputs=split_inputs,
+                clear=clear,
             ),
         )
 
@@ -1215,6 +1238,7 @@ class TreeBuilder[TreeT: NodeTree]:
         top_level: Literal["with", "class"] = "with",
         format: bool = True,
         nodebpy_pkg: str = "nodebpy",
+        in_place: bool = False,
     ) -> str:
         """Generate Python source that recreates this tree using nodebpy.
 
@@ -1232,6 +1256,7 @@ class TreeBuilder[TreeT: NodeTree]:
             top_level=top_level,
             format=format,
             nodebpy_pkg=nodebpy_pkg,
+            in_place=in_place,
         )
 
     def to_mermaid(self, fenced: bool = True) -> str:

{nodebpy-520.26.0 → nodebpy-520.28.0}/src/nodebpy/export/codegen.py

@@ -3724,6 +3724,7 @@ def to_python(
     external_groups: Collection[str] | None = None,
     typed_groups: Collection[str] | None = None,
     root_interface: GroupInterface | None = None,
+    in_place: bool = False,
 ) -> str:
     """Generate Python code that recreates the given node tree using nodebpy.
 
@@ -3794,6 +3795,17 @@ def to_python(
         Typed-interface parts (docstring, class attributes, accessors and
         ``__init__``) spliced into the top-level tree's class in ``class``
         mode, ahead of ``_build_group``.
+    in_place: bool
+        If True, the ``with`` header is emitted as
+        ``with g.tree("Name", clear=True) as tree:`` so running the source
+        rebuilds the exported tree in place — the same datablock, emptied
+        first — instead of creating a ``Name.001`` copy, keeping modifiers,
+        group nodes and pinned editors attached across re-runs. Only the
+        top-level tree is rebuilt this way: nested groups are emitted as
+        ``Custom*Group`` classes whose ``create_group()`` reuses an existing
+        tree of the same name, so edits to them only take effect through
+        :func:`nodebpy.live.run_source`. Ignored with ``top_level="class"``
+        (a class is rebuilt by ``run_source``, not by a header).
 
     Returns
     -------
@@ -3876,6 +3888,8 @@ def to_python(
         # for either option.
         if snapshot_positions or keep_reroutes:
             ctor_args.append("arrange=None")
+        if in_place:
+            ctor_args.append("clear=True")
         lines.append(f"with {constructor}({', '.join(ctor_args)}) as tree:")
         lines.extend(_assemble_tree_body(emission))
 

nodebpy-520.28.0/src/nodebpy/live.py

@@ -0,0 +1,361 @@
+"""Re-run nodebpy source safely inside a live Blender session.
+
+A live editor (a Text block, a file on disk) re-executes its code on every
+change. Three things make a naive ``exec`` unpleasant, and :func:`run_source`
+handles all of them:
+
+- ``Custom*Group.create_group()`` reuses an existing group of the same
+  ``_name`` rather than rebuilding it, so re-running edited class code would
+  silently hand back the previous build. Existing groups the code claims are
+  renamed out of the way first (:func:`stash_groups`), then their users are
+  remapped onto the rebuilt trees and the old ones removed
+  (:meth:`GroupStash.replace`); on failure the old names are put back
+  (:meth:`GroupStash.restore`).
+- Rebuilding a tree's interface regenerates its socket identifiers, which is
+  what Geometry Nodes modifiers key their input values on, so the values
+  would be lost. :func:`preserve_modifier_inputs` snapshots them by socket
+  name and reapplies them afterwards.
+- The tree the run produced has to be found among whatever the code did:
+  the ``tree`` variable of the ``with g.tree(...) as tree:`` form, the newest
+  top-level group it created, or the last group class it defined.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable, Iterator
+from contextlib import contextmanager, suppress
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+import bpy
+
+from .builder import TreeBuilder
+
+__all__ = [
+    "GroupStash",
+    "RunResult",
+    "group_names_in_source",
+    "preserve_modifier_inputs",
+    "run_source",
+    "stash_groups",
+]
+
+
+def group_names_in_source(code: str) -> set[str]:
+    """Literal ``_name`` values assigned in class bodies of ``code``.
+
+    Parsed with :mod:`ast`; both ``_name = "..."`` and ``_name: str = "..."``
+    count. Returns an empty set on a :class:`SyntaxError` (``exec`` reports
+    it).
+    """
+    try:
+        module = ast.parse(code)
+    except SyntaxError:
+        return set()
+    names: set[str] = set()
+    for node in ast.walk(module):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        for stmt in node.body:
+            if isinstance(stmt, ast.Assign):
+                targets, value = stmt.targets, stmt.value
+            elif isinstance(stmt, ast.AnnAssign) and stmt.value is not None:
+                targets, value = [stmt.target], stmt.value
+            else:
+                continue
+            if not (isinstance(value, ast.Constant) and isinstance(value.value, str)):
+                continue
+            if any(isinstance(t, ast.Name) and t.id == "_name" for t in targets):
+                names.add(value.value)
+    return names
+
+
+@dataclass
+class GroupStash:
+    """Existing node groups renamed out of the way before a run.
+
+    Maps each original name to the old tree, now named ``<name>.stale``.
+    """
+
+    stashed: dict[str, bpy.types.NodeTree] = field(default_factory=dict)
+
+    def restore(self) -> None:
+        """Failure path: remove any partial build under an original name and
+        give the old trees their names back. Empties the stash, so calling
+        it (or :meth:`replace`) again is a no-op."""
+        for name, old in self.stashed.items():
+            leftover = bpy.data.node_groups.get(name)
+            if leftover is not None and leftover != old:
+                bpy.data.node_groups.remove(leftover)
+            old.name = name
+        self.stashed.clear()
+
+    def replace(self) -> None:
+        """Success path: for each name, if the run created a new tree of the
+        same type under it, point the old tree's users (group nodes,
+        modifiers, pinned editors) at the new one and remove the old;
+        otherwise the old tree keeps its original name. Empties the stash,
+        so calling it (or :meth:`restore`) again is a no-op."""
+        for name, old in self.stashed.items():
+            new = bpy.data.node_groups.get(name)
+            if new is not None and new != old and new.bl_idname == old.bl_idname:
+                old.user_remap(new)
+                bpy.data.node_groups.remove(old)
+            else:
+                old.name = name
+        self.stashed.clear()
+
+
+def stash_groups(names: Iterable[str]) -> GroupStash:
+    """Rename each existing ``bpy.data.node_groups[name]`` to ``"<name>.stale"``
+    and return the :class:`GroupStash` that undoes or completes the move.
+
+    A group linked from a library (an appended asset) cannot be renamed and
+    is left in place, so ``create_group()`` reuses it as usual.
+    """
+    stash = GroupStash()
+    for name in names:
+        if name in stash.stashed:
+            continue
+        existing = bpy.data.node_groups.get(name)
+        if existing is not None and existing.library is None:
+            existing.name = f"{name}.stale"
+            stash.stashed[name] = existing
+    return stash
+
+
+def _copy_value(value: Any) -> Any:
+    # Vector / colour values come back as bpy_prop_array views into the
+    # modifier's storage, which the rebuild replaces; keep a plain tuple.
+    if hasattr(value, "__len__") and not isinstance(value, (str, bytes, bpy.types.ID)):
+        return tuple(value)
+    return value
+
+
+def _input_sockets(
+    tree: bpy.types.NodeTree,
+) -> dict[str, bpy.types.NodeTreeInterfaceSocket]:
+    """Interface input sockets by name (first wins on duplicate names)."""
+    sockets: dict[str, bpy.types.NodeTreeInterfaceSocket] = {}
+    assert tree.interface is not None
+    for item in tree.interface.items_tree:
+        if item.item_type != "SOCKET":
+            continue
+        assert isinstance(item, bpy.types.NodeTreeInterfaceSocket)
+        if item.in_out == "INPUT" and item.name not in sockets:
+            sockets[item.name] = item
+    return sockets
+
+
+def _modifier_inputs(modifier: bpy.types.NodesModifier) -> Any:
+    """``modifier.properties.inputs``: one RNA property per interface input,
+    named by socket identifier, each wrapping the stored ``value`` (Blender
+    5.x; the type stubs predate it)."""
+    properties = cast("Any", modifier.properties)
+    return properties.inputs
+
+
+def _nodes_modifiers(pointers: set[int]) -> Iterator[bpy.types.NodesModifier]:
+    for obj in bpy.data.objects:
+        for modifier in obj.modifiers:
+            if not isinstance(modifier, bpy.types.NodesModifier):
+                continue
+            group = modifier.node_group
+            if group is not None and group.as_pointer() in pointers:
+                yield modifier
+
+
+# Per-input state a modifier stores besides ``value``: whether the input
+# reads a named attribute instead (``type`` is ``VALUE`` or ``ATTRIBUTE``)
+# and which one.
+_INPUT_ATTRS = ("value", "type", "attribute_name")
+
+
+@dataclass
+class _InputState:
+    socket_type: str
+    attrs: dict[str, Any]
+
+
+@contextmanager
+def preserve_modifier_inputs(trees: Iterable[bpy.types.NodeTree]) -> Iterator[None]:
+    """Keep Geometry Nodes modifier input values across an interface rebuild.
+
+    Snapshots the input state of every Geometry Nodes modifier (on any
+    object) whose ``node_group`` is one of ``trees``, keyed by interface
+    socket *name*: the value, and whether the input reads a named attribute
+    instead (``type`` and ``attribute_name``). On exit — also when the body
+    raised, so a failed in-place rebuild keeps the values of the sockets it
+    did build — each entry whose socket name still exists on the modifier's
+    (possibly rebuilt, possibly remapped) tree is reapplied; sockets whose
+    type changed are skipped, as is anything that fails to apply — the
+    reapply step never raises.
+    """
+    pointers = {tree.as_pointer() for tree in trees}
+    snapshot: list[tuple[bpy.types.NodesModifier, dict[str, _InputState]]] = []
+    for modifier in _nodes_modifiers(pointers):
+        assert modifier.node_group is not None
+        inputs = _modifier_inputs(modifier)
+        values: dict[str, _InputState] = {}
+        for name, socket in _input_sockets(modifier.node_group).items():
+            wrapper = getattr(inputs, socket.identifier, None)
+            if wrapper is None or not hasattr(wrapper, "value"):
+                continue  # a geometry socket, or one with no stored value
+            attrs = {
+                attr: _copy_value(getattr(wrapper, attr))
+                for attr in _INPUT_ATTRS
+                if hasattr(wrapper, attr)
+            }
+            values[name] = _InputState(socket.socket_type, attrs)
+        snapshot.append((modifier, values))
+
+    try:
+        yield
+    finally:
+        for modifier, values in snapshot:
+            # A modifier the run removed, a tree it freed, ...: never raise.
+            with suppress(Exception):
+                _reapply_inputs(modifier, values)
+
+
+def _reapply_inputs(
+    modifier: bpy.types.NodesModifier, values: dict[str, _InputState]
+) -> None:
+    group = modifier.node_group
+    if group is None:
+        return
+    inputs = _modifier_inputs(modifier)
+    sockets = _input_sockets(group)
+    for name, state in values.items():
+        socket = sockets.get(name)
+        if socket is None or socket.socket_type != state.socket_type:
+            continue
+        wrapper = getattr(inputs, socket.identifier, None)
+        if wrapper is None or not hasattr(wrapper, "value"):
+            continue
+        for attr, value in state.attrs.items():
+            with suppress(Exception):  # best effort, per attribute
+                setattr(wrapper, attr, value)
+
+
+@dataclass
+class RunResult:
+    """What :func:`run_source` produced."""
+
+    tree: bpy.types.NodeTree | None
+    """The tree the run produced, or ``None`` if it made no tree."""
+    created: list[bpy.types.NodeTree]
+    """Every node group that exists after the run and did not before."""
+    namespace: dict[str, Any]
+    """The globals the code ran in."""
+
+
+def _is_group_class(value: Any, module_name: str | None) -> bool:
+    return (
+        isinstance(value, type)
+        and getattr(value, "__module__", None) == module_name
+        and callable(getattr(value, "create_group", None))
+        and bool(getattr(value, "_name", None))
+        and bool(getattr(value, "_tree_idname", None))
+    )
+
+
+def _produced_tree(
+    namespace: dict[str, Any], before: set[int], prior: Any
+) -> bpy.types.NodeTree | None:
+    """The tree a run produced: the ``tree`` variable's, else the newest
+    top-level group created, else the last group class defined (built now).
+
+    ``before`` holds the ``session_uid`` of every group that existed before
+    the run; ``prior`` is whatever ``tree`` was bound to before it (a value
+    the caller's namespace carried over from an earlier run), which does not
+    count as produced by this one."""
+    bound = namespace.get("tree")
+    if bound is not prior:
+        if isinstance(bound, TreeBuilder):
+            return bound.tree
+        if isinstance(bound, bpy.types.NodeTree):
+            return bound
+
+    new_groups = [g for g in bpy.data.node_groups if g.session_uid not in before]
+    if new_groups:
+        nested = {
+            sub.as_pointer()
+            for group in new_groups
+            for node in group.nodes
+            if (sub := getattr(node, "node_tree", None)) is not None
+        }
+        top_level = [g for g in new_groups if g.as_pointer() not in nested]
+        # bpy.data.node_groups is sorted by name; session_uid counts up with
+        # creation, so it picks the group the code made last.
+        return max(top_level or new_groups, key=lambda g: g.session_uid)
+
+    module_name = namespace.get("__name__")
+    for value in reversed(list(namespace.values())):
+        if _is_group_class(value, module_name):
+            tree = value.create_group()
+            if isinstance(tree, bpy.types.NodeTree):
+                return tree
+    return None
+
+
+def run_source(
+    code: str,
+    *,
+    filename: str = "<nodebpy>",
+    namespace: dict[str, Any] | None = None,
+) -> RunResult:
+    """Execute nodebpy source for a live re-run.
+
+    Existing groups the code's classes claim by ``_name`` are stashed so
+    ``create_group()`` builds fresh, Geometry Nodes modifier input values on
+    every pre-existing tree are preserved across the rebuild, and the
+    stashed trees' users are remapped onto the new builds afterwards. On any
+    exception the stash is restored and the exception re-raised unchanged;
+    ``filename`` is what its traceback names. Nothing is printed or captured.
+
+    Parameters
+    ----------
+    code
+        The source to run.
+    filename
+        Filename for the compiled code, so tracebacks point at the caller's
+        Text block or file.
+    namespace
+        Extra globals merged over the defaults (``__name__``, ``__file__``
+        and ``bpy``). A ``tree`` it carries over from an earlier run's
+        :attr:`RunResult.namespace` is not mistaken for this run's tree.
+
+    A run that fails partway through a ``with g.tree(..., clear=True)`` body
+    leaves that tree half built (the class form is atomic: the old build is
+    restored). Groups the failed run created under other names are left
+    behind as well.
+    """
+    stash = stash_groups(group_names_in_source(code))
+    before = {group.session_uid for group in bpy.data.node_groups}
+    globals_: dict[str, Any] = {
+        "__name__": "__nodebpy_live__",
+        "__file__": filename,
+        "bpy": bpy,
+    }
+    if namespace:
+        globals_.update(namespace)
+    prior = globals_.get("tree")
+
+    existing = list(bpy.data.node_groups)
+    with preserve_modifier_inputs(existing):
+        try:
+            exec(compile(code, filename, "exec"), globals_)  # noqa: S102
+            # Resolved before the stash is replaced: building a defined-only
+            # class must not find the old tree back under its name.
+            tree = _produced_tree(globals_, before, prior)
+        except BaseException:
+            stash.restore()
+            raise
+        # Inside the preserve context: remapping a modifier onto the rebuilt
+        # tree resets its inputs just like an in-place rebuild does.
+        stash.replace()
+
+    created = [g for g in bpy.data.node_groups if g.session_uid not in before]
+    return RunResult(tree=tree, created=created, namespace=globals_)

{nodebpy-520.26.0 → nodebpy-520.28.0}/src/nodebpy/nodes/compositor/manual.py

@@ -42,9 +42,10 @@ def tree(
     collapse: bool = False,
     arrange: ArrangeMethod = "sugiyama",
     fake_user: bool = False,
+    clear: bool = False,
 ) -> TreeBuilder[CompositorNodeTree]:
     return TreeBuilder.compositor(
-        name, collapse=collapse, arrange=arrange, fake_user=fake_user
+        name, collapse=collapse, arrange=arrange, fake_user=fake_user, clear=clear
     )
 
 

{nodebpy-520.26.0 → nodebpy-520.28.0}/src/nodebpy/nodes/geometry/manual.py

@@ -152,8 +152,9 @@ def tree(
     *,
     collapse: bool = False,
     arrange: ArrangeMethod = "sugiyama",
+    clear: bool = False,
 ) -> TreeBuilder[GeometryNodeTree]:
-    return TreeBuilder.geometry(name, collapse=collapse, arrange=arrange)
+    return TreeBuilder.geometry(name, collapse=collapse, arrange=arrange, clear=clear)
 
 
 _ColorRampColorInterpolations = Literal[

{nodebpy-520.26.0 → nodebpy-520.28.0}/src/nodebpy/nodes/shader/manual.py

@@ -52,9 +52,10 @@ def tree(
     collapse: bool = False,
     arrange: ArrangeMethod = "sugiyama",
     fake_user: bool = False,
+    clear: bool = False,
 ) -> TreeBuilder[ShaderNodeTree]:
     return TreeBuilder.shader(
-        name, collapse=collapse, arrange=arrange, fake_user=fake_user
+        name, collapse=collapse, arrange=arrange, fake_user=fake_user, clear=clear
     )