nodebpy 0.9.1__tar.gz → 0.10.0__tar.gz

{nodebpy-0.9.1 → nodebpy-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nodebpy
-Version: 0.9.1
+Version: 0.10.0
 Summary: Build nodes trees in Blender more elegantly with code
 Author: Brady Johnston
 Author-email: Brady Johnston <brady.johnston@me.com>
@@ -46,7 +46,6 @@ In `nodebpy` we use the `>>` operator to link from one node or socket into anoth
 This should feel and behave much like the <kbd>Alt</kbd> + <kbd>Right Click</kbd> drag between nodes in [Node Wrangler](https://docs.blender.org/manual/en/latest/addons/node/node_wrangler.html). It will use some smart logic to match the most compatible sockets between the nodes, but if you ever want to be explicit you do so. The input and output sockets of a node are accessible as properties via the `i_*` and `o_*` prefixes, or you can use the `...` placeholder to specify the particular input to be user, or pass in the previous node as a named argument.
 
 ```py
-g.Vector() >> g.SetPosition().i_offset
 g.Vector() >> g.SetPosition(offset=...)
 g.SetPosition(offset=g.Vector())
 ```
@@ -75,14 +74,9 @@ with TreeBuilder("MyTree") as tree:
 The node tree below creates a integer input and geometry output to the node group. We create a `rotation` variable that can be used later on as an argument, then construct a longer chain of nodes being created and linked together. The nodes are added and linked as each node is instantiated. After we exit the tree context, the nodes are automatically arranged.
 
 ``` python
-from nodebpy import TreeBuilder, geometry as g, sockets as s
-
-with TreeBuilder("AnotherTree", collapse=True) as tree:
-    with tree.inputs:
-        count = s.SocketInt("Count", 10)
-    with tree.outputs:
-        instances = s.SocketGeometry("Instances")
+from nodebpy import geometry as g
 
+with g.tree("AnotherTree", collapse=True) as tree:
     rotation = (
         g.RandomValue.vector(min=-1, seed=2)
         >> g.AlignRotationToVector()
@@ -90,7 +84,7 @@ with TreeBuilder("AnotherTree", collapse=True) as tree:
     )
 
     _ = (
-        count
+        tree.inputs.integer("Count", 10)
         >> g.Points(position=g.RandomValue.vector(min=-1))
         >> g.InstanceOnPoints(instance=g.Cube(), rotation=rotation)
         >> g.SetPosition(
@@ -99,7 +93,7 @@ with TreeBuilder("AnotherTree", collapse=True) as tree:
         )
         >> g.RealizeInstances()
         >> g.InstanceOnPoints(g.Cube(), instance=...)
-        >> instances
+        >> tree.outputs.geometry("Instances")
     )
 ```
 
@@ -120,7 +114,9 @@ math.operation = "SUBTRACT"
 
 # operation can be chose as a class method
 math = g.Math.subtract(1.0, 2.0)
+math = g.Value(1.0) - 2.0
 math = g.Math.add(1.0, 2.0)
+math = g.Value(1.0) + 2.0
 
 # these are equivalent, the g.Math.multiply is automatically added
 g.Value(1.0) * 2

{nodebpy-0.9.1 → nodebpy-0.10.0}/README.md

@@ -33,7 +33,6 @@ In `nodebpy` we use the `>>` operator to link from one node or socket into anoth
 This should feel and behave much like the <kbd>Alt</kbd> + <kbd>Right Click</kbd> drag between nodes in [Node Wrangler](https://docs.blender.org/manual/en/latest/addons/node/node_wrangler.html). It will use some smart logic to match the most compatible sockets between the nodes, but if you ever want to be explicit you do so. The input and output sockets of a node are accessible as properties via the `i_*` and `o_*` prefixes, or you can use the `...` placeholder to specify the particular input to be user, or pass in the previous node as a named argument.
 
 ```py
-g.Vector() >> g.SetPosition().i_offset
 g.Vector() >> g.SetPosition(offset=...)
 g.SetPosition(offset=g.Vector())
 ```
@@ -62,14 +61,9 @@ with TreeBuilder("MyTree") as tree:
 The node tree below creates a integer input and geometry output to the node group. We create a `rotation` variable that can be used later on as an argument, then construct a longer chain of nodes being created and linked together. The nodes are added and linked as each node is instantiated. After we exit the tree context, the nodes are automatically arranged.
 
 ``` python
-from nodebpy import TreeBuilder, geometry as g, sockets as s
-
-with TreeBuilder("AnotherTree", collapse=True) as tree:
-    with tree.inputs:
-        count = s.SocketInt("Count", 10)
-    with tree.outputs:
-        instances = s.SocketGeometry("Instances")
+from nodebpy import geometry as g
 
+with g.tree("AnotherTree", collapse=True) as tree:
     rotation = (
         g.RandomValue.vector(min=-1, seed=2)
         >> g.AlignRotationToVector()
@@ -77,7 +71,7 @@ with TreeBuilder("AnotherTree", collapse=True) as tree:
     )
 
     _ = (
-        count
+        tree.inputs.integer("Count", 10)
         >> g.Points(position=g.RandomValue.vector(min=-1))
         >> g.InstanceOnPoints(instance=g.Cube(), rotation=rotation)
         >> g.SetPosition(
@@ -86,7 +80,7 @@ with TreeBuilder("AnotherTree", collapse=True) as tree:
         )
         >> g.RealizeInstances()
         >> g.InstanceOnPoints(g.Cube(), instance=...)
-        >> instances
+        >> tree.outputs.geometry("Instances")
     )
 ```
 
@@ -107,7 +101,9 @@ math.operation = "SUBTRACT"
 
 # operation can be chose as a class method
 math = g.Math.subtract(1.0, 2.0)
+math = g.Value(1.0) - 2.0
 math = g.Math.add(1.0, 2.0)
+math = g.Value(1.0) + 2.0
 
 # these are equivalent, the g.Math.multiply is automatically added
 g.Value(1.0) * 2

{nodebpy-0.9.1 → nodebpy-0.10.0}/pyproject.toml

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

{nodebpy-0.9.1 → nodebpy-0.10.0}/src/nodebpy/__init__.py

@@ -1,7 +1,6 @@
 from . import nodes, screenshot, sockets
-from .builder import TreeBuilder
+from .builder import TreeBuilder, NodeGroupBuilder
 from .nodes import compositor, geometry, shader
-from .screenshot import generate_mermaid_diagram, save_mermaid_diagram
 
 __all__ = [
     "nodes",
@@ -11,6 +10,5 @@ __all__ = [
     "sockets",
     "screenshot",
     "TreeBuilder",
-    "generate_mermaid_diagram",
-    "save_mermaid_diagram",
+    "NodeGroupBuilder",
 ]

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

@@ -0,0 +1,142 @@
+"""nodebpy.builder — node tree construction API.
+
+Public names are re-exported here. Old names (NodeBuilder, SocketLinker,
+SocketBase) are kept as aliases for backward compatibility.
+"""
+
+from ._utils import SocketError, denormalize_name, normalize_name
+from .accessor import SocketAccessor
+from .interface import (
+    InterfaceSocket,
+    SocketBoolean,
+    SocketBundle,
+    SocketClosure,
+    SocketCollection,
+    SocketColor,
+    SocketFloat,
+    SocketGeometry,
+    SocketImage,
+    SocketInteger,
+    SocketMaterial,
+    SocketMatrix,
+    SocketMenu,
+    SocketObject,
+    SocketRotation,
+    SocketShader,
+    SocketString,
+    SocketVector,
+)
+from .mixins import LinkingMixin, OperatorMixin
+from .node import BaseNode, DynamicInputsMixin, NodeGroupBuilder
+from .socket import (
+    BooleanSocket,
+    BundleSocket,
+    ClosureSocket,
+    CollectionSocket,
+    ColorSocket,
+    FloatSocket,
+    GeometrySocket,
+    ImageSocket,
+    IntegerSocket,
+    MaterialSocket,
+    MatrixSocket,
+    MenuSocket,
+    ObjectSocket,
+    RotationSocket,
+    ShaderSocket,
+    Socket,
+    StringSocket,
+    VectorSocket,
+    _BooleanMixin,
+    _ColorMixin,
+    _IntegerMixin,
+    _MatrixMixin,
+    _RotationMixin,
+    _VectorMixin,
+)
+from .tree import (
+    InputInterfaceContext,
+    MaterialBuilder,
+    OutputInterfaceContext,
+    PanelContext,
+    SocketContext,
+    TreeBuilder,
+)
+
+# Backward-compatible aliases for hand-written code that uses the old names.
+NodeBuilder = BaseNode
+SocketLinker = Socket
+SocketBase = InterfaceSocket
+
+__all__ = [
+    # Core
+    "TreeBuilder",
+    "MaterialBuilder",
+    "BaseNode",
+    "Socket",
+    "SocketAccessor",
+    # Mixins
+    "OperatorMixin",
+    "LinkingMixin",
+    "DynamicInputsMixin",
+    # Node groups
+    "NodeGroupBuilder",
+    # Type-specific socket classes (runtime)
+    "FloatSocket",
+    "VectorSocket",
+    "ColorSocket",
+    "IntegerSocket",
+    "BooleanSocket",
+    "RotationSocket",
+    "MatrixSocket",
+    "StringSocket",
+    "MenuSocket",
+    "GeometrySocket",
+    "ObjectSocket",
+    "MaterialSocket",
+    "ImageSocket",
+    "CollectionSocket",
+    "BundleSocket",
+    "ClosureSocket",
+    "ShaderSocket",
+    # Type-specific behaviour mixins
+    "_VectorMixin",
+    "_ColorMixin",
+    "_IntegerMixin",
+    "_BooleanMixin",
+    "_RotationMixin",
+    "_MatrixMixin",
+    # Interface socket base
+    "InterfaceSocket",
+    # Interface socket types
+    "SocketFloat",
+    "SocketInteger",
+    "SocketBoolean",
+    "SocketVector",
+    "SocketColor",
+    "SocketRotation",
+    "SocketMatrix",
+    "SocketString",
+    "SocketMenu",
+    "SocketObject",
+    "SocketGeometry",
+    "SocketCollection",
+    "SocketImage",
+    "SocketMaterial",
+    "SocketBundle",
+    "SocketClosure",
+    "SocketShader",
+    # Tree context helpers
+    "SocketContext",
+    "PanelContext",
+    "InputInterfaceContext",
+    "OutputInterfaceContext",
+    # Utilities
+    "SocketError",
+    "normalize_name",
+    "denormalize_name",
+    # Backward-compatible aliases
+    "NodeBuilder",
+    "SocketLinker",
+    "SocketBase",
+]

nodebpy-0.10.0/src/nodebpy/builder/_registry.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from bpy.types import NodeSocket
+
+if TYPE_CHECKING:
+    from .socket import Socket
+
+_SOCKET_LINKER_REGISTRY: dict[str, "type[Socket]"] = {}
+
+
+def _get_socket_linker(socket: NodeSocket) -> "Socket":
+    for key, cls in _SOCKET_LINKER_REGISTRY.items():
+        if key in socket.bl_idname:
+            return cls(socket)
+    from .socket import Socket
+
+    return Socket(socket)

nodebpy-0.10.0/src/nodebpy/builder/_utils.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any
+
+import bpy
+from bpy.types import NodeSocket
+
+
+class SocketError(Exception):
+    """Raised when a socket operation fails."""
+
+
+# Type precedence for mixed-type operator dispatch (higher = dominant).
+_TYPE_PRECEDENCE: dict[str, int] = {
+    "INT": 0,
+    "VALUE": 1,
+    "FLOAT": 1,
+    "VECTOR": 2,
+}
+
+GEO_NODE_NAMES = (
+    f"GeometryNode{name}"
+    for name in (
+        "SetPosition",
+        "TransformGeometry",
+        "GroupInput",
+        "GroupOutput",
+        "MeshToPoints",
+        "PointsToVertices",
+    )
+)
+
+
+def normalize_name(name: str) -> str:
+    """Convert 'Geometry' or 'My Socket' to 'geometry' or 'my_socket'."""
+    return name.lower().replace(" ", "_").replace("é", "e")
+
+
+def denormalize_name(attr_name: str) -> str:
+    """Convert 'geometry' or 'my_socket' to 'Geometry' or 'My Socket'."""
+    return attr_name.replace("_", " ").title()
+
+
+def _allow_innactive_sockets(node: bpy.types.Node) -> bool:
+    """Returns True if we should allow inactive sockets to be linked for this node type"""
+    return node.bl_idname in (
+        "GeometryNodeIndexSwitch",
+        "GeometryNodeMenuSwitch",
+        "ShaderNodeMixShader",
+        "GeometryNodeSwitch",
+    )
+
+
+def _resolve_promotion(
+    self_socket: NodeSocket, other: Any, reverse: bool
+) -> "tuple[NodeSocket, Any, bool]":
+    """Determine the dominant socket for operator dispatch.
+
+    When both operands have a socket type, the higher-precedence type wins.
+    If `other` is dominant, the operands are swapped and `reverse` is flipped.
+
+    Returns (dominant_socket, effective_other, effective_reverse).
+    """
+    other_type = getattr(other, "type", None)
+    self_prec = _TYPE_PRECEDENCE.get(self_socket.type, 1)
+    other_prec = _TYPE_PRECEDENCE.get(other_type, -1)  # type: ignore[arg-type]
+
+    if other_prec > self_prec:
+        # Other side is dominant — swap so the linker wraps the vector/higher socket
+        other_socket = other._default_output_socket
+        return other_socket, self_socket, not reverse
+
+    return self_socket, other, reverse
+
+
+class _NodeLike:
+    """Marker base for objects that wrap a Blender node (have .node, .inputs, .outputs)."""
+
+
+class _SocketLike:
+    """Marker base for objects that wrap a single Blender NodeSocket (have .socket)."""

nodebpy-0.10.0/src/nodebpy/builder/accessor.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+import bpy
+from bpy.types import NodeSocket
+
+from ._registry import _get_socket_linker
+from ._utils import SocketError, _allow_innactive_sockets, denormalize_name
+
+if TYPE_CHECKING:
+    from .socket import Socket
+
+
+class SocketAccessor:
+    """Unified accessor for a node's input or output socket collection.
+
+    Supports identifier/name lookup, dict-style ``[]`` access, availability
+    filtering, and type-compatible matching — replacing the former pairs of
+    ``_input_idx``/``_output_idx``, ``_input``/``_output``,
+    ``_available_inputs``/``_available_outputs``, and ``_best_output_socket``.
+    """
+
+    def __init__(
+        self,
+        collection: bpy.types.NodeInputs | bpy.types.NodeOutputs,
+        direction: Literal["input", "output"],
+    ):
+        self._direction = direction
+        self._collection = collection
+
+    def _index(self, key: str | int) -> int:
+        """Find socket index by identifier, falling back to name.
+
+        Tries identifier match first. If no identifier matches, falls back to
+        name lookup — but raises if the name is duplicated (ambiguous).
+        Integer keys are returned directly.
+        """
+        if isinstance(key, int):
+            return key
+        ids = [s.identifier for s in self._collection]
+        denorm = denormalize_name(key)
+        for candidate in (key, denorm):
+            if candidate in ids:
+                return ids.index(candidate)
+        names = [s.name for s in self._collection]
+        for key in (key, denorm):
+            if key in names:
+                if names.count(key) > 1:
+                    raise RuntimeError(
+                        f"{self._direction.title()} name '{key}' is ambiguous on "
+                        f"{self._node.bl_idname} (appears {names.count(key)} times). "
+                        f"Use the socket identifier instead."
+                    )
+                return names.index(key)
+        raise RuntimeError(
+            f"{self._direction.title()} '{key}' not found on "
+            f"{self._node.bl_idname}. Available sockets (id: name): {list(zip(ids, names))}"
+        )
+
+    def _get(self, key: str | int) -> "Socket":
+        """Get a Socket for a socket by identifier, name, or index."""
+        return _get_socket_linker(self._collection[self._index(key)])
+
+    def __getitem__(self, key: str | int) -> "Socket":
+        """Access by identifier, name, or integer index."""
+        return self._get(key)
+
+    @property
+    def _node(self) -> bpy.types.Node:
+        """The node this accessor is associated with."""
+        if isinstance(self._collection, list):
+            return self._collection[0].node
+        # bpy NodeInputs/NodeOutputs.id_data returns the NodeTree (top-level ID),
+        # not the Node. Retrieve the node via the first socket instead.
+        for s in self._collection:
+            return s.node
+        return self._collection.data  # empty collection fallback
+
+    @property
+    def _ignore_visibility(self) -> bool:
+        """Whether to ignore socket visibility when selecting available sockets.
+
+        Only affects ``available`` / ``best_match`` (the auto-linking heuristics).
+        ``values()`` / ``items()`` always respect node-level visibility so that
+        iteration over a node's sockets stays predictable regardless of context.
+        Returns False when called outside a tree context (e.g. from a bare
+        Socket that was created outside a ``with tree:`` block).
+        """
+        from .tree import TreeBuilder
+
+        if not TreeBuilder._tree_contexts:
+            return False
+        return TreeBuilder._tree_contexts[-1].ignore_visibility
+
+    def _visible_sockets(self) -> list[NodeSocket]:
+        """Sockets that should appear in iteration (values/items/keys).
+
+        Uses the per-node allowlist (``_allow_innactive_sockets``) rather than
+        the tree-level ``ignore_visibility`` flag — enumeration should always
+        reflect what is meaningfully present on the node, not the linking context.
+        """
+        if self._direction == "input":
+            return [
+                s
+                for s in self._collection
+                if _allow_innactive_sockets(self._node)
+                or (not s.is_inactive and s.is_icon_visible)
+            ]
+        return [s for s in self._collection if s.is_icon_visible]
+
+    @property
+    def _available(self) -> list[NodeSocket]:
+        """Sockets eligible for automatic linking.
+
+        Respects ``ignore_visibility`` on the active ``TreeBuilder`` context, so
+        nodes with normally-hidden sockets can still be auto-linked when that flag
+        is set (e.g. during ``test_add_all_nodes``).
+        """
+        if self._direction == "input":
+            return [
+                s
+                for s in self._collection
+                if (
+                    self._ignore_visibility or (not s.is_inactive and s.is_icon_visible)
+                )
+                and (not s.links or s.is_multi_input)
+            ]
+        return [
+            s for s in self._collection if self._ignore_visibility or s.is_icon_visible
+        ]
+
+    def _best_match(self, socket_type: str) -> NodeSocket:
+        """Find the best compatible socket for the given type."""
+        from ..types import SOCKET_COMPATIBILITY
+
+        compatible = SOCKET_COMPATIBILITY.get(socket_type, ())
+        possible = [s for s in self._available if s.type in compatible]
+        if possible:
+            possible.sort(key=lambda x: compatible.index(x.type))
+            return possible[0]
+        raise SocketError(
+            f"No compatible {self._direction} socket found for type "
+            f"{socket_type} on {self._node.name}"
+        )
+
+    def _values(self) -> "list[Socket]":
+        """All visible sockets as Sockets.
+
+        Uses node-level visibility rules regardless of ``ignore_visibility`` —
+        see ``_visible_sockets`` for rationale.
+        """
+        return [_get_socket_linker(s) for s in self._visible_sockets()]
+
+    def _items(self) -> "list[tuple[str, Socket]]":
+        """All visible sockets as (name, Socket) pairs.
+
+        Uses node-level visibility rules regardless of ``ignore_visibility`` —
+        see ``_visible_sockets`` for rationale.
+        """
+        return [(s.name, _get_socket_linker(s)) for s in self._visible_sockets()]
+
+    def _keys(self) -> list[str]:
+        """All visible socket names."""
+        return [name for name, _ in self._items()]
+
+    def __len__(self) -> int:
+        return len(self._items())
+
+    def __iter__(self):
+        """Iterate over socket names (enables ``**node.outputs`` unpacking)."""
+        return iter(self._keys())
+
+    def __getattr__(self, name: str) -> "Socket":
+        """Dynamic socket access by normalised attribute name.
+
+        Converts ``node.o.base_color`` to ``self._get("Base Color")``.
+        Raises ``AttributeError`` (not ``RuntimeError``) so that ``hasattr``
+        and ``getattr(..., default)`` behave correctly.
+        """
+        if name.startswith("_"):
+            raise AttributeError(name)
+        try:
+            return self._get(name)
+        except RuntimeError:
+            raise AttributeError(
+                f"Socket '{name}' not found on {self._direction} accessor"
+            )