nodebpy 520.37.0__tar.gz → 520.39.0__tar.gz

{nodebpy-520.37.0 → nodebpy-520.39.0}/PKG-INFO

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

{nodebpy-520.37.0 → nodebpy-520.39.0}/pyproject.toml

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

{nodebpy-520.37.0 → nodebpy-520.39.0}/src/nodebpy/__init__.py

@@ -5,6 +5,7 @@ from .builder import (
     SugiyamaOptions,
     TreeBuilder,
     arrange,
+    default_keep_edits,
     default_split_inputs,
     default_sugiyama_options,
 )
@@ -20,6 +21,7 @@ __all__ = [
     "arrange",
     "builder",
     "compositor",
+    "default_keep_edits",
     "default_split_inputs",
     "default_sugiyama_options",
     "export",

{nodebpy-520.37.0 → nodebpy-520.39.0}/src/nodebpy/builder/__init__.py

@@ -5,7 +5,7 @@ from ..layout import (
     arrange,
     default_sugiyama_options,
 )
-from ._utils import SocketError, denormalize_name, normalize_name
+from ._utils import InvalidLinkWarning, SocketError, denormalize_name, normalize_name
 from .accessor import SocketAccessor
 from .asset import (
     AssetCompositorGroup,
@@ -82,6 +82,7 @@ from .tree import (
     SocketContext,
     TreeBuilder,
     WorldBuilder,
+    default_keep_edits,
     default_split_inputs,
 )
 
@@ -123,6 +124,7 @@ __all__ = [
     "IntegerSocketGrid",
     "IntegerSocketList",
     "IntegerVectorSocket",
+    "InvalidLinkWarning",
     "Item",
     "ItemsMixin",
     "LinkingMixin",
@@ -162,6 +164,7 @@ __all__ = [
     "arrange",
     "asset_group_base",
     "build_from_source",
+    "default_keep_edits",
     "default_split_inputs",
     "default_sugiyama_options",
     "denormalize_name",

{nodebpy-520.37.0 → nodebpy-520.39.0}/src/nodebpy/builder/_utils.py

@@ -20,6 +20,10 @@ class SocketError(Exception):
     """Raised when a socket operation fails."""
 
 
+class InvalidLinkWarning(UserWarning):
+    """Emitted when a built tree holds links Blender can't evaluate."""
+
+
 _ENUM_NOT_FOUND = re.compile(
     r'enum "(?P<value>[^"]*)" not found in \((?P<options>.*)\)'
 )

{nodebpy-520.37.0 → nodebpy-520.39.0}/src/nodebpy/builder/socket.py

@@ -15,6 +15,7 @@ Organization (top to bottom):
 
 from __future__ import annotations
 
+import math
 from collections.abc import Iterable, Iterator, Mapping
 from typing import (
     TYPE_CHECKING,
@@ -1958,8 +1959,9 @@ class _FloatMixin[IntegerResult: (IntegerSocket, IntegerSocketGrid, IntegerSocke
         self._assert_output("power")
         return self._math.power(self.socket, exponent).o.value  # ty: ignore[invalid-return-type]
 
-    def log(self, base: InputFloat = 2.0) -> Self:
-        """Return the logarithm of this value to *base*."""
+    def log(self, base: InputFloat = math.e) -> Self:
+        """Return the logarithm of this value to *base*, the natural logarithm
+        by default (as ``math.log``)."""
         self._assert_output("log")
         return self._math.logarithm(self.socket, base).o.value  # ty: ignore[invalid-return-type]
 

{nodebpy-520.37.0 → nodebpy-520.39.0}/src/nodebpy/builder/tree.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
+import warnings
 from collections import Counter
-from collections.abc import Iterator
+from collections.abc import Collection, Iterator
 from contextlib import AbstractContextManager, contextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, ClassVar, Literal, Self, TypeVar, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, Self, TypeVar, cast
 
 import bpy
 from bpy.types import (
@@ -22,6 +23,7 @@ from bpy.types import (
 
 from ..layout import ArrangeMethod
 from ..layout import arrange as _arrange_nodes
+from ..layout import keep as _keep
 from ..types import (
     SOCKET_COMPATIBILITY,
     Default,
@@ -33,6 +35,7 @@ from ..types import (
     _SocketShapeStructureType,
 )
 from ._utils import (
+    InvalidLinkWarning,
     SocketError,
     _allow_innactive_sockets,
     enum_value_error,
@@ -62,6 +65,9 @@ from .socket import (
     VectorSocket,
 )
 
+if TYPE_CHECKING:
+    from ..live import NodeAnimation
+
 _SocketT = TypeVar("_SocketT", bound=Socket)
 
 # What TreeBuilder's split_inputs=None resolves to; see `default_split_inputs`.
@@ -86,6 +92,41 @@ def default_split_inputs(split: bool = True) -> Iterator[None]:
         _DEFAULT_SPLIT_INPUTS.reset(token)
 
 
+# What TreeBuilder's keep_edits=None resolves to; see `default_keep_edits`.
+_DEFAULT_KEEP_EDITS: ContextVar[bool] = ContextVar(
+    "nodebpy_default_keep_edits", default=False
+)
+
+
+@contextmanager
+def default_keep_edits(keep: bool = True) -> Iterator[None]:
+    """Scope in which every ``TreeBuilder`` left at its default
+    ``keep_edits`` keeps the layout edits made to the tree it rebuilds with
+    ``clear=True`` (see :class:`TreeBuilder`). :func:`nodebpy.live.run_source`
+    runs its code in this scope.
+    """
+    token = _DEFAULT_KEEP_EDITS.set(keep)
+    try:
+        yield
+    finally:
+        _DEFAULT_KEEP_EDITS.reset(token)
+
+
+# Whether every TreeBuilder records what it built (see nodebpy.live.stamp_build),
+# not only the clear=True rebuilds; run_source sets it for the group classes
+# it rebuilds. Recording costs a pass over the nodes, so other builds skip it.
+_RECORD_BUILDS: ContextVar[bool] = ContextVar("nodebpy_record_builds", default=False)
+
+
+@contextmanager
+def _record_builds() -> Iterator[None]:
+    token = _RECORD_BUILDS.set(True)
+    try:
+        yield
+    finally:
+        _RECORD_BUILDS.reset(token)
+
+
 # The interface ``default_input`` values Blender actually accepts at runtime,
 # per socket type (the RNA enum lists every option on every type, but
 # assignment validates a per-type subset — union across tree types here).
@@ -1138,6 +1179,7 @@ class TreeBuilder[TreeT: NodeTree]:
         ignore_visibility: bool = False,
         split_inputs: bool | None = None,
         clear: bool = False,
+        keep_edits: bool | None = None,
         is_modifier: bool | None = None,
         is_tool: bool | None = None,
     ):
@@ -1154,6 +1196,10 @@ class TreeBuilder[TreeT: NodeTree]:
         # interface gives its sockets new identifiers, which is what
         # Geometry Nodes modifiers key their input values by, so those values
         # are snapshotted by socket name here and reapplied on exit.
+        # ``keep_edits`` (default: see default_keep_edits) carries the layout
+        # edits made to the tree since it was last arranged (moved, resized,
+        # collapsed, framed or relabelled nodes) over to the rebuild, onto
+        # the nodes that match; see nodebpy.layout.keep.
         if isinstance(tree, str):
             existing = bpy.data.node_groups.get(tree) if clear else None
             if existing is not None and existing.bl_idname == tree_type:
@@ -1163,12 +1209,33 @@ class TreeBuilder[TreeT: NodeTree]:
         else:
             self.tree = tree  # type: ignore
         self._preserved_inputs: AbstractContextManager[None] | None = None
+        self._kept_edits: _keep.Edits | None = None
+        if keep_edits is None:
+            keep_edits = _DEFAULT_KEEP_EDITS.get()
+        if clear and keep_edits and arrange is not None:
+            self._kept_edits = _keep.record(self.tree)
+        self._animation: NodeAnimation | None = None
+        self._unedited_users: list[NodeTree] = []
+        self._record = clear or _RECORD_BUILDS.get()
         if clear:
-            from ..live import preserve_modifier_inputs
+            from ..live import (
+                NodeAnimation,
+                keep_edited,
+                preserve_modifier_inputs,
+                unedited_users,
+                was_edited,
+            )
 
+            self._unedited_users = unedited_users(self.tree)
+            if was_edited(self.tree):
+                copy = self.tree.copy()
+                assert copy is not None
+                keep_edited(copy, self.tree.name)
             assert self.tree.interface is not None
             self._preserved_inputs = preserve_modifier_inputs([self.tree])
             self._preserved_inputs.__enter__()
+            # Removing the nodes would delete their keyframes and drivers.
+            self._animation = NodeAnimation(self.tree)
             self.tree.nodes.clear()
             self.tree.interface.clear()
 
@@ -1197,6 +1264,7 @@ class TreeBuilder[TreeT: NodeTree]:
         fake_user: bool = False,
         split_inputs: bool | None = None,
         clear: bool = False,
+        keep_edits: bool | None = None,
         is_modifier: bool | None = None,
         is_tool: bool | None = None,
     ) -> TreeBuilder[GeometryNodeTree]:
@@ -1215,6 +1283,7 @@ class TreeBuilder[TreeT: NodeTree]:
                 fake_user=fake_user,
                 split_inputs=split_inputs,
                 clear=clear,
+                keep_edits=keep_edits,
                 is_modifier=is_modifier,
                 is_tool=is_tool,
             ),
@@ -1230,6 +1299,7 @@ class TreeBuilder[TreeT: NodeTree]:
         fake_user: bool = False,
         split_inputs: bool | None = None,
         clear: bool = False,
+        keep_edits: bool | None = None,
     ) -> TreeBuilder[ShaderNodeTree]:
         """Create a shader node tree."""
         return cast(
@@ -1242,6 +1312,7 @@ class TreeBuilder[TreeT: NodeTree]:
                 fake_user=fake_user,
                 split_inputs=split_inputs,
                 clear=clear,
+                keep_edits=keep_edits,
             ),
         )
 
@@ -1255,6 +1326,7 @@ class TreeBuilder[TreeT: NodeTree]:
         fake_user: bool = False,
         split_inputs: bool | None = None,
         clear: bool = False,
+        keep_edits: bool | None = None,
         scene: bool = False,
     ) -> TreeBuilder[CompositorNodeTree]:
         """Create a compositor node tree; ``scene=True`` also makes it the
@@ -1269,6 +1341,7 @@ class TreeBuilder[TreeT: NodeTree]:
                 fake_user=fake_user,
                 split_inputs=split_inputs,
                 clear=clear,
+                keep_edits=keep_edits,
             ),
         )
         if scene:
@@ -1318,6 +1391,8 @@ class TreeBuilder[TreeT: NodeTree]:
         format: bool = True,
         nodebpy_pkg: str = "nodebpy",
         in_place: bool = False,
+        groups: Literal["inline", "reference"] = "inline",
+        group_modules: Collection[str] | None = None,
     ) -> str:
         """Generate Python source that recreates this tree using nodebpy.
 
@@ -1336,6 +1411,8 @@ class TreeBuilder[TreeT: NodeTree]:
             format=format,
             nodebpy_pkg=nodebpy_pkg,
             in_place=in_place,
+            groups=groups,
+            group_modules=group_modules,
         )
 
     def to_mermaid(self, fenced: bool = True) -> str:
@@ -1415,16 +1492,82 @@ class TreeBuilder[TreeT: NodeTree]:
             self.split_group_inputs()
         if self._arrange is not None:
             self.arrange()
+            if self._kept_edits is not None:
+                _keep.restore(self._kept_edits, self.tree)
+        self._kept_edits = None
+        if self._animation is not None:
+            self._animation.restore()
+            self._animation = None
         self._apply_input_defaults()
         if self._preserved_inputs is not None:
             self._preserved_inputs.__exit__(None, None, None)
             self._preserved_inputs = None
+        self._warn_invalid_links()
+        if self._record:
+            from ..live import stamp_build
+
+            stamp_build(self.tree)
+            for user in self._unedited_users:
+                stamp_build(user)
+            self._unedited_users = []
         # Interface-menu defaults assigned from here on can't wait for a
         # context exit that already happened — apply them immediately
         # (see MenuSocket.default_value).
         self._exited = True
         self.deactivate_tree()
 
+    def invalid_links(self) -> list[bpy.types.NodeLink]:
+        """Links Blender can't evaluate, drawn red in the node editor: most
+        often a field reaching an input that takes a single value, such as a
+        Repeat Zone's Iterations or Points' Count. Muted links and links to
+        sockets the node's settings hide or grey out aren't evaluated, so they
+        aren't reported."""
+
+        def evaluated(socket: NodeSocket | None) -> bool:
+            return (
+                socket is not None
+                and not socket.is_unavailable
+                and not socket.is_inactive
+            )
+
+        return [
+            link
+            for link in self.tree.links
+            if not link.is_valid
+            and not link.is_muted
+            and not link.is_hidden
+            and evaluated(link.from_socket)
+            and evaluated(link.to_socket)
+        ]
+
+    def _warn_invalid_links(self) -> None:
+        invalid = self.invalid_links()
+        if not invalid:
+            return
+        lines = []
+        for link in invalid:
+            source, target = link.from_socket, link.to_socket
+            assert source is not None and target is not None
+            assert link.from_node is not None and link.to_node is not None
+            line = (
+                f"  {link.from_node.name}.{source.name} -> "
+                f"{link.to_node.name}.{target.name}"
+            )
+            # Blender draws inputs that only take a single value as a line.
+            if (
+                target.display_shape == "LINE"
+                and source.inferred_structure_type == "FIELD"
+            ):
+                line += f" ('{target.name}' takes a single value, not a field)"
+            lines.append(line)
+        count = "1 link" if len(invalid) == 1 else f"{len(invalid)} links"
+        warnings.warn(
+            f"Blender can't evaluate {count} in '{self.tree.name}':\n"
+            + "\n".join(lines),
+            InvalidLinkWarning,
+            stacklevel=3,
+        )
+
     def _apply_input_defaults(self) -> None:
         if not self._menu_defaults:
             return
@@ -1880,12 +2023,14 @@ class MaterialBuilder(TreeBuilder[ShaderNodeTree]):
         fake_user: bool = False,
         ignore_visibility: bool = False,
         clear: bool = False,
+        keep_edits: bool | None = None,
     ):
         # With ``clear`` an existing material of that name is rebuilt in place
         # (objects keep it assigned) instead of creating ``Name.001``. A new
         # material starts with Blender's default Principled BSDF and Material
         # Output nodes, which are removed so the body builds from empty.
         material = bpy.data.materials.get(name) if clear else None
+        reused = material is not None
         if material is None:
             material = bpy.data.materials.new(name)
         assert material is not None
@@ -1899,6 +2044,7 @@ class MaterialBuilder(TreeBuilder[ShaderNodeTree]):
             fake_user=fake_user,
             ignore_visibility=ignore_visibility,
             clear=True,
+            keep_edits=keep_edits if reused else False,
         )
 
 
@@ -1915,12 +2061,14 @@ class WorldBuilder(TreeBuilder[ShaderNodeTree]):
         fake_user: bool = False,
         ignore_visibility: bool = False,
         clear: bool = False,
+        keep_edits: bool | None = None,
         scene: bool = False,
     ):
         # With ``clear`` an existing world of that name is rebuilt in place (a
         # scene using it keeps it). A new world's default Background and World
         # Output nodes are removed so the body builds from empty.
         world = bpy.data.worlds.get(name) if clear else None
+        reused = world is not None
         if world is None:
             world = bpy.data.worlds.new(name)
         assert world is not None and world.node_tree is not None
@@ -1933,6 +2081,7 @@ class WorldBuilder(TreeBuilder[ShaderNodeTree]):
             fake_user=fake_user,
             ignore_visibility=ignore_visibility,
             clear=True,
+            keep_edits=keep_edits if reused else False,
         )
         if scene:
             active = bpy.context.scene

nodebpy-520.39.0/src/nodebpy/export/_groups.py

@@ -0,0 +1,168 @@
+"""Group classes that exist in Python already, for
+``to_python(groups="reference")``.
+
+A tree can use a group that a loaded class builds or links: one of Blender's
+bundled assets (``g.Array``), one of nodebpy's own groups, a class from a
+generated asset module or one the live script defines. Codegen can then call
+that class instead of writing the group out again.
+
+A tree belongs to a class when:
+
+- an asset class linked it: the tree is linked from the class's library under
+  the asset's name;
+- it was appended from that library (the asset browser's default), which
+  leaves a weak reference to the file and the asset's name;
+- it is a local tree with the name the class gives its tree, which is the tree
+  the class reuses when it runs. A tree changed by hand since nodebpy built
+  it in this session is not matched, so the edits are written out.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import os
+import pkgutil
+import sys
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+import bpy
+
+from ..builder._utils import typed_param_names
+from ..builder.asset import BundledLibrary, _AssetGroupMixin
+from ..builder.node import NodeGroupBuilder
+
+# Modules a script's own classes live in: run_source runs code as
+# __nodebpy_live__, Blender runs scripts and Text blocks as __main__.
+SCRIPT_MODULES = frozenset({"__main__", "__nodebpy_live__"})
+
+# Modules holding nodebpy's own group classes, which nothing else imports.
+_BUILTIN_MODULES = ("nodebpy.nodes.geometry.groups",)
+
+
+@dataclass(frozen=True)
+class Reference:
+    """How codegen calls the class that builds a group node's tree."""
+
+    cls: type[NodeGroupBuilder]
+    params: dict[str, str] | None
+    """Socket identifier → ``__init__`` parameter for a typed class, or
+    ``None`` to pass inputs by socket name."""
+
+
+def import_modules(names: Iterable[str]) -> None:
+    """Import each module, and every submodule of a package, so the group
+    classes they define can be found."""
+    for name in names:
+        module = importlib.import_module(name)
+        if hasattr(module, "__path__"):
+            for info in pkgutil.walk_packages(module.__path__, f"{name}."):
+                importlib.import_module(info.name)
+
+
+def configured_modules(start: str | Path | None = None) -> list[str]:
+    """The package holding the dumped sources that ``[tool.nodebpy.assets]``
+    names in the nearest ``pyproject.toml``, if it can be imported from a
+    ``sys.path`` entry."""
+    from ..assets._pipeline import load_config
+
+    table, root = load_config(start)
+    source = table.get("source")
+    if not source or root is None:
+        return []
+    path = (root / source).resolve()
+    names = []
+    for entry in sys.path:
+        try:
+            parts = path.relative_to(Path(entry or ".").resolve()).parts
+        except ValueError:
+            continue
+        if parts and all(part.isidentifier() for part in parts):
+            names.append(".".join(parts))
+    return [min(names, key=len)] if names else []
+
+
+def _subclasses[T](cls: type[T]) -> Iterator[type[T]]:
+    for sub in cls.__subclasses__():
+        yield sub
+        yield from _subclasses(sub)
+
+
+def _group_classes() -> list[type[NodeGroupBuilder]]:
+    import_modules(_BUILTIN_MODULES)
+    return [
+        cls
+        for cls in dict.fromkeys(_subclasses(NodeGroupBuilder))
+        if not inspect.isabstract(cls)
+        and (getattr(cls, "_asset_name", None) or getattr(cls, "_name", None))
+    ]
+
+
+def _path(path: str) -> str:
+    return os.path.normcase(os.path.realpath(bpy.path.abspath(path)))
+
+
+def _from_library(cls: type[_AssetGroupMixin], path: str) -> bool:
+    library = cls._library
+    if isinstance(library, BundledLibrary):
+        # Blender installs differ, the bundled file names don't.
+        return os.path.basename(bpy.path.abspath(path)) == library.filename
+    return _path(path) == _path(library.path())
+
+
+def _builds(cls: type[NodeGroupBuilder], tree: bpy.types.NodeTree) -> bool:
+    if cls._tree_idname != tree.bl_idname:
+        return False
+    if issubclass(cls, _AssetGroupMixin):
+        name = cls._asset_name
+        if tree.library is not None:
+            return tree.name == name and _from_library(cls, tree.library.filepath)
+        weak = tree.library_weak_reference
+        if weak is not None:
+            return weak.id_name[2:] == name and _from_library(cls, weak.filepath)
+        return tree.name == name
+    # A class choosing its tree's name per instance can't be matched by name.
+    return (
+        tree.library is None
+        and cls._group_name is NodeGroupBuilder._group_name
+        and tree.name == getattr(cls, "_name", None)
+    )
+
+
+def find_class(tree: bpy.types.NodeTree) -> type[NodeGroupBuilder] | None:
+    """The loaded class that builds or links *tree*, the latest defined when
+    several do (a live script defines its classes again on every run)."""
+    from ..live import was_edited
+
+    if tree.library is None and was_edited(tree):
+        return None
+    found = [cls for cls in _group_classes() if _builds(cls, tree)]
+    return found[-1] if found else None
+
+
+def reference(node: bpy.types.Node) -> Reference | None:
+    """How to call the class that builds *node*'s group, or ``None`` when no
+    loaded class does or its ``__init__`` can't take the node's inputs."""
+    tree = getattr(node, "node_tree", None)
+    cls = find_class(tree) if tree is not None else None
+    if cls is None:
+        return None
+    if cls.__init__ is NodeGroupBuilder.__init__:
+        return Reference(cls, None)
+    parameters = list(inspect.signature(cls.__init__).parameters.values())[1:]
+    named = {
+        p.name: p
+        for p in parameters
+        if p.kind in (p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY)
+    }
+    if not named and any(p.kind is p.VAR_KEYWORD for p in parameters):
+        # ``__init__(self, **kwargs)`` passes socket names through.
+        return Reference(cls, None)
+    params = typed_param_names(node.inputs)
+    if not set(params.values()) <= named.keys() or any(
+        p.default is p.empty for p in named.values()
+    ):
+        return None
+    return Reference(cls, params)