nodebpy 0.12.0__tar.gz → 0.14.0__tar.gz

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

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

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

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

nodebpy-0.14.0/src/nodebpy/__init__.py

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

nodebpy-0.14.0/src/nodebpy/builder/__init__.py

@@ -0,0 +1,86 @@
+from ._utils import SocketError, denormalize_name, normalize_name
+from .accessor import SocketAccessor
+from .mixins import LinkingMixin, OperatorMixin
+from .node import (
+    BaseNode,
+    CustomCompositorGroup,
+    CustomGeometryGroup,
+    CustomShaderGroup,
+    DynamicInputsMixin,
+    NodeGroupBuilder,
+)
+from .socket import (
+    BooleanSocket,
+    BundleSocket,
+    ClosureSocket,
+    CollectionSocket,
+    ColorSocket,
+    FloatSocket,
+    FontSocket,
+    GeometrySocket,
+    ImageSocket,
+    IntegerSocket,
+    MaterialSocket,
+    MatrixSocket,
+    MenuSocket,
+    ObjectSocket,
+    RotationSocket,
+    ShaderSocket,
+    Socket,
+    StringSocket,
+    VectorSocket,
+)
+from .tree import (
+    InputInterfaceContext,
+    MaterialBuilder,
+    OutputInterfaceContext,
+    PanelContext,
+    SocketContext,
+    TreeBuilder,
+)
+
+__all__ = [
+    # Core
+    "TreeBuilder",
+    "MaterialBuilder",
+    "BaseNode",
+    "Socket",
+    "SocketAccessor",
+    # Mixins
+    "OperatorMixin",
+    "LinkingMixin",
+    "DynamicInputsMixin",
+    # Node groups
+    "NodeGroupBuilder",
+    "CustomCompositorGroup",
+    "CustomGeometryGroup",
+    "CustomShaderGroup",
+    # Runtime socket types
+    "FloatSocket",
+    "VectorSocket",
+    "ColorSocket",
+    "IntegerSocket",
+    "BooleanSocket",
+    "RotationSocket",
+    "MatrixSocket",
+    "StringSocket",
+    "MenuSocket",
+    "GeometrySocket",
+    "ObjectSocket",
+    "FontSocket",
+    "MaterialSocket",
+    "ImageSocket",
+    "CollectionSocket",
+    "BundleSocket",
+    "ClosureSocket",
+    "ShaderSocket",
+    # Tree context
+    "SocketContext",
+    "PanelContext",
+    "InputInterfaceContext",
+    "OutputInterfaceContext",
+    # Utilities
+    "SocketError",
+    "normalize_name",
+    "denormalize_name",
+]

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

@@ -67,7 +67,10 @@ def _resolve_promotion(
 
     if other_prec > self_prec:
         # Other side is dominant — swap so the linker wraps the vector/higher socket
-        other_socket = other._default_output_socket
+        if isinstance(other, NodeSocket):
+            other_socket = other
+        else:
+            other_socket = other._default_output_socket
         return other_socket, self_socket, not reverse
 
     return self_socket, other, reverse

{nodebpy-0.12.0 → nodebpy-0.14.0}/src/nodebpy/builder/accessor.py

@@ -28,7 +28,7 @@ class SocketAccessor:
 
     def __init__(
         self,
-        collection: bpy.types.NodeInputs | bpy.types.NodeOutputs,
+        collection: bpy.types.NodeInputs | bpy.types.NodeOutputs | list[NodeSocket],
         direction: Literal["input", "output"],
     ):
         self._direction = direction
@@ -190,8 +190,7 @@ class SocketAccessor:
         return len(self._items())
 
     def __iter__(self):
-        """Iterate over socket names (enables ``**node.outputs`` unpacking)."""
-        return iter(self._keys())
+        return iter(self._values())
 
     def __getattr__(self, name: str) -> "Socket":
         """Dynamic socket access by normalised attribute name.

{nodebpy-0.12.0 → nodebpy-0.14.0}/src/nodebpy/builder/mixins.py

@@ -11,10 +11,11 @@ from ._utils import SocketError, _resolve_promotion, _SocketLike
 _RShiftT = TypeVar("_RShiftT")
 
 if TYPE_CHECKING:
-    from ..nodes.geometry import Compare, Math
+    from ..nodes.geometry import Compare, Math, MultiplyMatrices, TransformPoint
     from ..types import InputLinkable
     from .node import BaseNode
-    from .socket import Socket
+    from .socket import MatrixSocket, Socket
+    from .tree import TreeBuilder
 
 
 class OperatorMixin:
@@ -100,9 +101,12 @@ class OperatorMixin:
         )
 
     def _apply_compare_operation(self, other: Any, operation: str) -> "Math":
-        return _get_socket_linker(self._default_output_socket)._dispatch_compare(  # type: ignore[attr-defined]
-            other, operation
+        socket, other, _ = _resolve_promotion(
+            self._default_output_socket,  # type: ignore[attr-defined]
+            other,
+            False,
         )
+        return _get_socket_linker(socket)._dispatch_compare(other, operation)
 
     def __lt__(self, other: Any) -> "Compare":
         return self._apply_compare_operation(other, "less_than")
@@ -157,46 +161,46 @@ class OperatorMixin:
         return BooleanMath.l_not(self)
 
     @staticmethod
-    def _cast_to_matrix(value):
+    def _cast_to_matrix(value) -> MatrixSocket:
         from ..nodes.geometry.converter import CombineMatrix
 
         if hasattr(value, "shape") and value.shape == (4, 4):
-            return CombineMatrix(*value.ravel())
+            return CombineMatrix(*value.ravel()).o.matrix
         else:
             return value
 
-    def __matmul__(self, other: Any):
+    def __matmul__(self, other: Any) -> "MultiplyMatrices | TransformPoint":
         from ..nodes.geometry.converter import MultiplyMatrices, TransformPoint
 
         other = self._cast_to_matrix(other)
-        socket = self._default_output_socket  # type: ignore[attr-defined]
-        other_type = getattr(other, "type", None)
+        socket = self._default_output_socket
 
-        if socket.type == "MATRIX" and other_type == "VECTOR":
+        if socket.type == "MATRIX" and other.type == "VECTOR":
             return TransformPoint(other, socket)
 
-        return MultiplyMatrices(self, other)
+        return MultiplyMatrices(socket, other)
 
-    def __rmatmul__(self, other: Any):
+    def __rmatmul__(self, other: Any) -> "MultiplyMatrices | TransformPoint":
         from ..nodes.geometry.converter import MultiplyMatrices, TransformPoint
 
         other = self._cast_to_matrix(other)
-        socket = self._default_output_socket  # type: ignore[attr-defined]
-        other_type = getattr(other, "type", None)
+        socket = self._default_output_socket
 
-        if socket.type == "VECTOR" and other_type == "MATRIX":
+        if socket.type == "VECTOR" and getattr(other, "type", None) == "MATRIX":
             return TransformPoint(socket, other)
 
-        return MultiplyMatrices(other, self)
+        return MultiplyMatrices(other, socket)
 
 
 class LinkingMixin:
     """Node/socket linking logic: ``>>``, ``_link``, best-socket matching.
 
-    Requires ``tree``, ``inputs``, ``outputs``, ``_default_output_socket``,
+    Requires ``tree``, ``i``, ``o``, ``_default_output_socket``,
     and ``_default_input_socket`` on the concrete class.
     """
 
+    tree: "TreeBuilder"
+
     def _source_socket(self, node: "InputLinkable | Socket | NodeSocket") -> NodeSocket:
         assert node
         if isinstance(node, NodeSocket):
@@ -221,21 +225,45 @@ class LinkingMixin:
         target: "BaseNode | Socket | NodeSocket | EllipsisType | LinkingMixin",
     ) -> tuple[NodeSocket, NodeSocket]:
         """Find the best compatible pair of sockets between two nodes/sockets."""
-        from ..types import SOCKET_COMPATIBILITY
+        from ..builder.node import BaseNode
+        from ..builder.socket import Socket
+        from ..types import PREFER_FIRST_SOCKET, SOCKET_COMPATIBILITY
 
         possible_combos = []
-        if hasattr(source, "outputs"):
-            outputs = source.outputs._available  # type: ignore[union-attr]
+        if isinstance(source, BaseNode):
+            outputs = source.o._available
         elif isinstance(source, NodeSocket):
             outputs = [source]
+        elif isinstance(source, Socket):
+            outputs = [source.socket]
         else:
             raise TypeError(f"Cannot get outputs from {type(source)}")
 
-        if hasattr(target, "inputs"):
-            inputs = target.inputs._available  # type: ignore[union-attr]
+        if isinstance(target, BaseNode):
+            inputs = target.i._available
         else:
             inputs = [target]
 
+        # NodeReroute adapts its type to whatever is linked — skip type matching
+        if getattr(getattr(target, "node", None), "bl_idname", None) == "NodeReroute":
+            if outputs and inputs:
+                return inputs[0], outputs[0]
+
+        # Try first available input first — if the output type matches it exactly,
+        # or is a "preferred" implicit conversion (e.g. float→color, vector→color),
+        # use the first socket rather than searching for a better-typed later one.
+        # This keeps float→Image working in the compositor instead of drifting to
+        # a float Factor socket that scores higher on raw compatibility.
+        # Pairs not in PREFER_FIRST_SOCKET (e.g. VALUE→BOOLEAN, VECTOR→ROTATION)
+        # fall through to the ranked search below.
+        if inputs:
+            first_input = inputs[0]
+            for output in outputs:
+                if first_input.type == output.type:
+                    return first_input, output
+                if (output.type, first_input.type) in PREFER_FIRST_SOCKET:
+                    return first_input, output
+
         for output in outputs:
             compat_sockets = SOCKET_COMPATIBILITY.get(output.type, ())
             for input in inputs:
@@ -261,7 +289,7 @@ class LinkingMixin:
     ) -> NodeLink:
         source_socket = self._source_socket(source)
         target_socket = self._target_socket(target)
-        return self.tree.link(source_socket, target_socket)  # type: ignore[attr-defined]
+        return self.tree.link(source_socket, target_socket)
 
     def _link_from(
         self,
@@ -270,9 +298,9 @@ class LinkingMixin:
     ):
         if isinstance(input, str):
             try:
-                self._link(source, self.node.inputs[input])  # type: ignore[attr-defined]
+                self._link(source, self.node.inputs[input])
             except KeyError:
-                self._link(source, self.node.inputs[self.inputs._index(input)])  # type: ignore[attr-defined]
+                self._link(source, self.node.inputs[self.i._index(input)])
         else:
             self._link(source, input)
 
@@ -296,8 +324,8 @@ class LinkingMixin:
             try:
                 target = other.node.inputs[name]
             except KeyError:
-                target = other.node.inputs[other.inputs._index(name)]
-            source = self.outputs._best_match(target.type)
+                target = other.node.inputs[other.i._index(name)]
+            source = self.o._best_match(target.type) if hasattr(self, "o") else self
         else:
             try:
                 source, target = self._find_best_socket_pair(self, other)

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

@@ -15,10 +15,13 @@ from typing import (
 
 import bpy
 from bpy.types import (
+    CompositorNodeGroup,
     CompositorNodeTree,
+    GeometryNodeGroup,
     GeometryNodeTree,
     Node,
     NodeSocket,
+    ShaderNodeGroup,
     ShaderNodeTree,
 )
 
@@ -38,7 +41,7 @@ if TYPE_CHECKING:
         def _add_inputs(self, *args: Any, **kwargs: Any) -> dict[str, NodeSocket]: ...
 
         @property
-        def inputs(self) -> SocketAccessor: ...
+        def i(self) -> SocketAccessor: ...
 
 
 class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
@@ -50,7 +53,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
     _default_output_id: str | None = None
     _placeholder_inputs: list[str]
 
-    def __init__(self, node: bpy.types.Node | None = None):
+    def __init__(self, node: Node | None = None):
         tree = (
             TreeBuilder._tree_contexts[-1] if len(TreeBuilder._tree_contexts) else None
         )
@@ -81,13 +84,13 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
     @property
     def _default_input_socket(self) -> NodeSocket:
         if self._default_input_id is not None:
-            return self.node.inputs[self.inputs._index(self._default_input_id)]
+            return self.node.inputs[self.i._index(self._default_input_id)]
         return self.node.inputs[0]
 
     @property
     def _default_output_socket(self) -> NodeSocket:
         if self._default_output_id is not None:
-            return self.node.outputs[self.outputs._index(self._default_output_id)]
+            return self.node.outputs[self.o._index(self._default_output_id)]
 
         counter = 0
         socket = self.node.outputs[counter]
@@ -97,7 +100,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
         return socket
 
     @classmethod
-    def _from_node(cls, node: bpy.types.Node) -> Self:
+    def _from_node(cls, node: Node) -> Self:
         builder = cls()
         builder.tree.nodes.remove(builder.node)
         builder.node = node
@@ -112,7 +115,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
                     if link.to_node.bl_idname == cls._bl_idname:
                         return cls._from_node(link.to_node)
             node = cls()
-            node.tree.link(socket, node.inputs._best_match(socket.type))
+            node.tree.link(socket, node.i._best_match(socket.type))
             return node
         else:
             if socket.links:
@@ -160,9 +163,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
             elif isinstance(value, NodeSocket):
                 self._link_from(value, name)
             elif isinstance(value, _NodeLike):
-                self._link_from(
-                    value.outputs._best_match(self.inputs._get(name).type), name
-                )
+                self._link_from(value.o._best_match(self.i._get(name).type), name)
             else:
                 if name in input_ids:
                     input = self.node.inputs[input_ids.index(name)]
@@ -174,14 +175,6 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
                         input = self.node.inputs[name.replace("_", " ").title()]
                     self._set_input_default_value(input, value)
 
-    @property
-    def outputs(self) -> SocketAccessor:
-        return SocketAccessor(self.node.outputs, "output")
-
-    @property
-    def inputs(self) -> SocketAccessor:
-        return SocketAccessor(self.node.inputs, "input")
-
     @property
     def o(self) -> SocketAccessor:
         """Output socket accessor. Subclasses narrow the return type via TYPE_CHECKING."""
@@ -222,7 +215,7 @@ class DynamicInputsMixin(ABC):
         except SocketError:
             dyn = cast("_DynamicTarget", target)
             target_name, source_socket = list(dyn._add_inputs(source).items())[0]
-            return (source_socket, dyn.inputs[target_name].socket)
+            return (source_socket, dyn.i[target_name].socket)
 
     @abstractmethod
     def _add_socket(self, name: str, *args: Any, **kwargs: Any) -> NodeSocket: ...
@@ -235,7 +228,9 @@ class DynamicInputsMixin(ABC):
             items[arg._default_output_socket.name] = arg
         items.update(kwargs)
         for key, source in items.items():
-            socket_source, type = self._match_compatible_data(source.outputs._available)
+            socket_source, type = self._match_compatible_data(
+                source.o._available if hasattr(source, "o") else [source]
+            )
             if type in self._type_map:
                 type = self._type_map[type]
             socket = self._add_socket(name=key, type=type)
@@ -274,6 +269,12 @@ class NodeGroupBuilder(BaseNode, ABC, Generic[_T]):
         self.node.show_options = False
         self._establish_links(**kwargs)
 
+    @property
+    @abstractmethod
+    def node_tree(self) -> _T:
+        """The internal node tree for this group node."""
+        ...
+
     @abstractmethod
     def _setup_node_group(self) -> None:
         """Set ``self.node.node_tree`` and any node-type-specific properties.
@@ -304,7 +305,12 @@ class CustomGeometryGroup(NodeGroupBuilder[GeometryNodeTree]):
     """Node group in a Geometry Nodes tree."""
 
     _bl_idname = "GeometryNodeGroup"
-    node: bpy.types.GeometryNodeGroup
+    node: GeometryNodeGroup
+
+    @property
+    def node_tree(self) -> GeometryNodeTree:
+        assert self.node.node_tree is not None
+        return self.node.node_tree
 
     def _setup_node_group(self) -> None:
         self.node.node_tree = self._get_or_create_group()
@@ -324,7 +330,12 @@ class CustomShaderGroup(NodeGroupBuilder[ShaderNodeTree]):
     """Node group in a Shader (Material) node tree."""
 
     _bl_idname = "ShaderNodeGroup"
-    node: bpy.types.ShaderNodeGroup
+    node: ShaderNodeGroup
+
+    @property
+    def node_tree(self) -> ShaderNodeTree:
+        assert self.node.node_tree is not None
+        return self.node.node_tree
 
     def _setup_node_group(self) -> None:
         self.node.node_tree = self._get_or_create_group()
@@ -343,7 +354,12 @@ class CustomCompositorGroup(NodeGroupBuilder[CompositorNodeTree]):
     """Node group in a Compositor node tree."""
 
     _bl_idname = "CompositorNodeGroup"
-    node: bpy.types.CompositorNodeGroup
+    node: CompositorNodeGroup
+
+    @property
+    def node_tree(self) -> CompositorNodeTree:
+        assert self.node.node_tree is not None
+        return self.node.node_tree
 
     def _setup_node_group(self) -> None:
         self.node.node_tree = self._get_or_create_group()