nodebpy 0.11.1__tar.gz → 0.12.0__tar.gz

{nodebpy-0.11.1 → nodebpy-0.12.0}/PKG-INFO

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

{nodebpy-0.11.1 → nodebpy-0.12.0}/pyproject.toml

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

nodebpy-0.12.0/src/nodebpy/__init__.py

@@ -0,0 +1,23 @@
+from . import diagram, nodes, sockets
+from .builder import (
+    CustomCompositorGroup,
+    CustomGeometryGroup,
+    CustomShaderGroup,
+    NodeGroupBuilder,
+    TreeBuilder,
+)
+from .nodes import compositor, geometry, shader
+
+__all__ = [
+    "nodes",
+    "compositor",
+    "geometry",
+    "shader",
+    "sockets",
+    "diagram",
+    "TreeBuilder",
+    "NodeGroupBuilder",
+    "GeometryNodeGroup",
+    "ShaderNodeGroup",
+    "CompositorNodeGroup",
+]

{nodebpy-0.11.1 → nodebpy-0.12.0}/src/nodebpy/builder/__init__.py

@@ -27,7 +27,14 @@ from .interface import (
     SocketVector,
 )
 from .mixins import LinkingMixin, OperatorMixin
-from .node import BaseNode, DynamicInputsMixin, NodeGroupBuilder
+from .node import (
+    BaseNode,
+    CustomCompositorGroup,
+    CustomGeometryGroup,
+    CustomShaderGroup,
+    DynamicInputsMixin,
+    NodeGroupBuilder,
+)
 from .socket import (
     BooleanSocket,
     BundleSocket,
@@ -82,6 +89,9 @@ __all__ = [
     "DynamicInputsMixin",
     # Node groups
     "NodeGroupBuilder",
+    "GeometryNodeGroup",
+    "ShaderNodeGroup",
+    "CompositorNodeGroup",
     # Type-specific socket classes (runtime)
     "FloatSocket",
     "VectorSocket",

{nodebpy-0.11.1 → nodebpy-0.12.0}/src/nodebpy/builder/_utils.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Protocol, runtime_checkable
 
 import bpy
 from bpy.types import NodeSocket
@@ -73,9 +73,15 @@ def _resolve_promotion(
     return self_socket, other, reverse
 
 
-class _NodeLike:
-    """Marker base for objects that wrap a Blender node (have .node, .inputs, .outputs)."""
+@runtime_checkable
+class _NodeLike(Protocol):
+    """Protocol for objects that wrap a Blender node and expose an ``outputs`` accessor."""
 
+    outputs: Any  # SocketAccessor at runtime; typed as Any to avoid circular import
 
-class _SocketLike:
-    """Marker base for objects that wrap a single Blender NodeSocket (have .socket)."""
+
+@runtime_checkable
+class _SocketLike(Protocol):
+    """Protocol for objects that wrap a single Blender NodeSocket and expose ``.socket``."""
+
+    socket: NodeSocket

{nodebpy-0.11.1 → nodebpy-0.12.0}/src/nodebpy/builder/node.py

@@ -1,19 +1,44 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Iterable, Literal, Self
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Iterable,
+    Literal,
+    Protocol,
+    Self,
+    TypeVar,
+    cast,
+)
 
 import bpy
-from bpy.types import Node, NodeSocket
-
-from ..types import SOCKET_COMPATIBILITY, SOCKET_TYPES, InputAny, InputLinkable
+from bpy.types import (
+    CompositorNodeTree,
+    GeometryNodeTree,
+    Node,
+    NodeSocket,
+    ShaderNodeTree,
+)
+
+from ..types import SOCKET_COMPATIBILITY, SOCKET_TYPES, InputAny
 from ._utils import SocketError, _NodeLike, _SocketLike
 from .accessor import SocketAccessor
 from .mixins import LinkingMixin, OperatorMixin
 from .tree import TreeBuilder
 
+_T = TypeVar("_T", bound=bpy.types.NodeTree)
+
 if TYPE_CHECKING:
-    pass
+
+    class _DynamicTarget(Protocol):
+        """Structural type for a node that supports dynamic socket addition."""
+
+        def _add_inputs(self, *args: Any, **kwargs: Any) -> dict[str, NodeSocket]: ...
+
+        @property
+        def inputs(self) -> SocketAccessor: ...
 
 
 class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
@@ -86,7 +111,9 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
                     assert link.to_node
                     if link.to_node.bl_idname == cls._bl_idname:
                         return cls._from_node(link.to_node)
-            return cls(socket)
+            node = cls()
+            node.tree.link(socket, node.inputs._best_match(socket.type))
+            return node
         else:
             if socket.links:
                 for link in socket.links:
@@ -98,8 +125,9 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
             node >> socket
             return node
 
-    def _set_input_default_value(self, input, value):
+    def _set_input_default_value(self, input: NodeSocket, value: Any) -> None:
         """Set the default value for an input socket, handling type conversions."""
+        assert hasattr(input, "default_value")
         if (
             hasattr(input, "type")
             and input.type == "VECTOR"
@@ -115,7 +143,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
             if value is None or (
                 "GridPrune" in self._bl_idname
                 and name == "Threshold"
-                and self.node.data_type == "BOOLEAN"
+                and getattr(self.node, "data_type", None) == "BOOLEAN"
             ):
                 continue
             if isinstance(value, Node):
@@ -128,7 +156,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
                 continue
 
             elif isinstance(value, _SocketLike):
-                self._link_from(value, name)
+                self._link_from(value.socket, name)
             elif isinstance(value, NodeSocket):
                 self._link_from(value, name)
             elif isinstance(value, _NodeLike):
@@ -165,7 +193,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
         return SocketAccessor(self.node.inputs, "input")
 
 
-class DynamicInputsMixin:
+class DynamicInputsMixin(ABC):
     _socket_data_types: tuple[str, ...]
     _type_map: dict[str, str] = {}
 
@@ -192,10 +220,14 @@ class DynamicInputsMixin:
         try:
             return super()._find_best_socket_pair(source, target)  # type: ignore
         except SocketError:
-            target_name, source_socket = list(target._add_inputs(source).items())[0]
-            return (source_socket, target.inputs[target_name].socket)
+            dyn = cast("_DynamicTarget", target)
+            target_name, source_socket = list(dyn._add_inputs(source).items())[0]
+            return (source_socket, dyn.inputs[target_name].socket)
 
-    def _add_inputs(self, *args, **kwargs) -> dict[str, InputLinkable]:
+    @abstractmethod
+    def _add_socket(self, name: str, *args: Any, **kwargs: Any) -> NodeSocket: ...
+
+    def _add_inputs(self, *args, **kwargs) -> dict[str, NodeSocket]:
         """Dictionary with {new_socket.name: from_linkable} for link creation"""
         new_sockets = {}
         items = {}
@@ -212,14 +244,15 @@ class DynamicInputsMixin:
         return new_sockets
 
 
-class NodeGroupBuilder(BaseNode, ABC):
+class NodeGroupBuilder(BaseNode, ABC, Generic[_T]):
     """Base class for custom node groups.
 
     Subclasses implement :meth:`_build_group` with the node-graph logic.
+    Subclass one of the editor-specific variants: :class:`GeometryNodeGroup`,
+    :class:`ShaderNodeGroup`, or :class:`CompositorNodeGroup`.
     """
 
     _name: str
-    _bl_idname = "GeometryNodeGroup"
     _warning_propagation: Literal["ALL", "ERRORS_AND_WARNINGS", "ERRORS", "NONE"] = (
         "ALL"
     )
@@ -234,27 +267,92 @@ class NodeGroupBuilder(BaseNode, ABC):
         "TEXTURE",
         "VECTOR",
     ] = "NONE"
-    node: bpy.types.GeometryNodeGroup
 
     def __init__(self, **kwargs):
         super().__init__()
-        self.node.node_tree = self._get_or_create_group()
+        self._setup_node_group()
         self.node.show_options = False
-        self.node.warning_propagation = self._warning_propagation
         self._establish_links(**kwargs)
 
-    def _get_or_create_group(self) -> bpy.types.GeometryNodeTree:
-        name = self._name
-        if name in bpy.data.node_groups:
-            return bpy.data.node_groups[name]
+    @abstractmethod
+    def _setup_node_group(self) -> None:
+        """Set ``self.node.node_tree`` and any node-type-specific properties.
+
+        Called by ``__init__`` after the node is created but before links are
+        established. Concrete subclasses have a narrowed ``self.node`` type,
+        so the ``node_tree`` assignment is type-safe here rather than in the
+        base class where ``self.node`` is only ``bpy.types.Node``.
+        """
+        ...
+
+    @abstractmethod
+    def _build_group(self, tree: TreeBuilder) -> None:
+        """Build the node group internals and interface."""
+
+    def _get_or_create_tree(self) -> _T:
+        existing = bpy.data.node_groups[self._name]
+        if existing.bl_idname == self.tree.tree.bl_idname:
+            return cast(_T, existing)
+        raise TypeError(
+            f"Node group '{self._name}' already exists as "
+            f"{type(existing).__name__}, not {self._bl_idname}. "
+            f"Use a unique _name for this group."
+        )
+
+
+class CustomGeometryGroup(NodeGroupBuilder[GeometryNodeTree]):
+    """Node group in a Geometry Nodes tree."""
+
+    _bl_idname = "GeometryNodeGroup"
+    node: bpy.types.GeometryNodeGroup
+
+    def _setup_node_group(self) -> None:
+        self.node.node_tree = self._get_or_create_group()
+        self.node.warning_propagation = self._warning_propagation
 
-        with TreeBuilder(name) as tree:
-            self._build_group(tree)
+    def _get_or_create_group(self) -> GeometryNodeTree:
+        try:
+            return self._get_or_create_tree()
+        except KeyError:
+            with TreeBuilder.geometry(self._name) as tree:
+                self._build_group(tree)
             tree.tree.color_tag = self._color_tag
+            return tree.tree
 
-        return tree.tree
 
-    @classmethod
-    @abstractmethod
-    def _build_group(cls, tree: TreeBuilder) -> None:
-        """Code that builds the node group internals and interface"""
+class CustomShaderGroup(NodeGroupBuilder[ShaderNodeTree]):
+    """Node group in a Shader (Material) node tree."""
+
+    _bl_idname = "ShaderNodeGroup"
+    node: bpy.types.ShaderNodeGroup
+
+    def _setup_node_group(self) -> None:
+        self.node.node_tree = self._get_or_create_group()
+
+    def _get_or_create_group(self) -> ShaderNodeTree:
+        try:
+            return self._get_or_create_tree()
+        except KeyError:
+            with TreeBuilder.shader(self._name) as tree:
+                self._build_group(tree)
+            tree.tree.color_tag = self._color_tag
+            return tree.tree
+
+
+class CustomCompositorGroup(NodeGroupBuilder[CompositorNodeTree]):
+    """Node group in a Compositor node tree."""
+
+    _bl_idname = "CompositorNodeGroup"
+    node: bpy.types.CompositorNodeGroup
+
+    def _setup_node_group(self) -> None:
+        self.node.node_tree = self._get_or_create_group()
+
+    def _get_or_create_group(self) -> CompositorNodeTree:
+        try:
+            return self._get_or_create_tree()
+        except KeyError:
+            with TreeBuilder.compositor(self._name) as tree:
+                self._build_group(tree)
+            tree.tree.color_tag = self._color_tag
+            return tree.tree

{nodebpy-0.11.1 → nodebpy-0.12.0}/src/nodebpy/builder/tree.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, Self
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, Self, TypeVar, cast
 
 import bpy
 from bpy.types import (
@@ -623,12 +623,16 @@ class OutputInterfaceContext(DirectionalContext):
     _direction = "OUTPUT"
 
 
-class TreeBuilder:
+_TreeT = TypeVar("_TreeT", bound=NodeTree)
+
+
+class TreeBuilder(Generic[_TreeT]):
     """Builder for creating Blender node trees with a clean Python API.
 
     Supports geometry, shader, and compositor node trees.
     """
 
+    tree: _TreeT
     _tree_contexts: ClassVar["list[TreeBuilder]"] = []
     _frame_contexts: ClassVar["list[NodeFrame]"] = []
 
@@ -645,9 +649,9 @@ class TreeBuilder:
         ignore_visibility: bool = False,
     ):
         if isinstance(tree, str):
-            self.tree = bpy.data.node_groups.new(tree, tree_type)
+            self.tree = bpy.data.node_groups.new(tree, tree_type)  # type: ignore[assignment]
         else:
-            self.tree = tree
+            self.tree = tree  # type: ignore[assignment]
 
         self._menu_defaults: dict[str, str] = {}
         self.inputs = InputInterfaceContext(self)
@@ -665,14 +669,17 @@ class TreeBuilder:
         collapse: bool = False,
         arrange: Literal["sugiyama", "simple"] | None = "sugiyama",
         fake_user: bool = False,
-    ) -> "TreeBuilder":
+    ) -> "TreeBuilder[GeometryNodeTree]":
         """Create a geometry node tree."""
-        return cls(
-            name,
-            tree_type="GeometryNodeTree",
-            collapse=collapse,
-            arrange=arrange,
-            fake_user=fake_user,
+        return cast(
+            "TreeBuilder[GeometryNodeTree]",
+            cls(
+                name,
+                tree_type="GeometryNodeTree",
+                collapse=collapse,
+                arrange=arrange,
+                fake_user=fake_user,
+            ),
         )
 
     @classmethod
@@ -683,14 +690,17 @@ class TreeBuilder:
         collapse: bool = False,
         arrange: Literal["sugiyama", "simple"] | None = "sugiyama",
         fake_user: bool = False,
-    ) -> "TreeBuilder":
+    ) -> "TreeBuilder[ShaderNodeTree]":
         """Create a shader node tree."""
-        return cls(
-            name,
-            tree_type="ShaderNodeTree",
-            collapse=collapse,
-            arrange=arrange,
-            fake_user=fake_user,
+        return cast(
+            "TreeBuilder[ShaderNodeTree]",
+            cls(
+                name,
+                tree_type="ShaderNodeTree",
+                collapse=collapse,
+                arrange=arrange,
+                fake_user=fake_user,
+            ),
         )
 
     @classmethod
@@ -701,14 +711,17 @@ class TreeBuilder:
         collapse: bool = False,
         arrange: Literal["sugiyama", "simple"] | None = "sugiyama",
         fake_user: bool = False,
-    ) -> "TreeBuilder":
+    ) -> "TreeBuilder[CompositorNodeTree]":
         """Create a compositor node tree."""
-        return cls(
-            name,
-            tree_type="CompositorNodeTree",
-            collapse=collapse,
-            arrange=arrange,
-            fake_user=fake_user,
+        return cast(
+            "TreeBuilder[CompositorNodeTree]",
+            cls(
+                name,
+                tree_type="CompositorNodeTree",
+                collapse=collapse,
+                arrange=arrange,
+                fake_user=fake_user,
+            ),
         )
 
     @property

{nodebpy-0.11.1 → nodebpy-0.12.0}/src/nodebpy/nodes/geometry/groups.py

@@ -5,8 +5,8 @@ from nodebpy.nodes.compositor import CombineXYZ
 from nodebpy.types import InputInteger, InputVector
 
 from ...builder import (
+    CustomGeometryGroup,
     IntegerSocket,
-    NodeGroupBuilder,
     RotationSocket,
     SocketAccessor,
     VectorSocket,
@@ -25,7 +25,7 @@ from . import (
 )
 
 
-class OtherVertex(NodeGroupBuilder):
+class OtherVertex(CustomGeometryGroup):
     """
     Given a vertex and an edge number from that vertex, returns the other
     vertex of that edge.
@@ -58,8 +58,7 @@ class OtherVertex(NodeGroupBuilder):
         kwargs = {"Vertex Index": vertex_index, "Edge Number": edge_number}
         super().__init__(**kwargs)
 
-    @classmethod
-    def _build_group(cls, tree):
+    def _build_group(self, tree: TreeBuilder):
         vertex_index = tree.inputs.integer("Vertex Index", default_input="INDEX")
         edge_number = tree.inputs.integer("Edge Number")
 
@@ -72,7 +71,7 @@ class OtherVertex(NodeGroupBuilder):
         _ = switch >> tree.outputs.integer("Other Vertex")
 
 
-class OffsetVector(NodeGroupBuilder):
+class OffsetVector(CustomGeometryGroup):
     """
     Evaluate a given vector field at an offset to the current ``Index``.
     """
@@ -108,8 +107,7 @@ class OffsetVector(NodeGroupBuilder):
     ):
         super().__init__(index=index, vector=vector, offset=offset)
 
-    @classmethod
-    def _build_group(cls, tree):
+    def _build_group(self, tree: TreeBuilder):
         index = tree.inputs.integer("Index", default_input="INDEX")
         vector = tree.inputs.vector("Vector", default_input="POSITION")
         offset = tree.inputs.integer("Offset")
@@ -119,7 +117,7 @@ class OffsetVector(NodeGroupBuilder):
         _ = value >> tree.outputs.vector("Vector")
 
 
-class PrincipalComponents(NodeGroupBuilder):
+class PrincipalComponents(CustomGeometryGroup):
     """
     Compute PCA on a given vector field.
     """

nodebpy-0.11.1/src/nodebpy/__init__.py

@@ -1,14 +0,0 @@
-from . import nodes, diagram, sockets
-from .builder import TreeBuilder, NodeGroupBuilder
-from .nodes import compositor, geometry, shader
-
-__all__ = [
-    "nodes",
-    "compositor",
-    "geometry",
-    "shader",
-    "sockets",
-    "diagram",
-    "TreeBuilder",
-    "NodeGroupBuilder",
-]