nodebpy 520.0.1__tar.gz → 520.1.0__tar.gz

{nodebpy-520.0.1 → nodebpy-520.1.0}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.3
 Name: nodebpy
-Version: 520.0.1
+Version: 520.1.0
 Summary: Build nodes trees in Blender more elegantly with code
 Author: Brady Johnston
 Author-email: Brady Johnston <brady.johnston@me.com>
 License: GPL-3.0-or-later
 Requires-Dist: bpy==5.2.* ; extra == 'bpy'
+Requires-Dist: ruff>=0.14.11 ; extra == 'format'
 Requires-Dist: networkx>=3.6.1 ; extra == 'networkx'
 Requires-Python: >=3.13
 Provides-Extra: bpy
+Provides-Extra: format
 Provides-Extra: networkx
 Description-Content-Type: text/markdown
 

{nodebpy-520.0.1 → nodebpy-520.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nodebpy"
-version = "520.0.1"
+version = "520.1.0"
 description = "Build nodes trees in Blender more elegantly with code"
 readme = "README.md"
 authors = [
@@ -19,6 +19,10 @@ networkx = [
 bpy = [
     "bpy==5.2.*",
 ]
+# Used by `to_python(format=True)` to tidy generated source via `ruff format`.
+format = [
+    "ruff>=0.14.11",
+]
 
 [build-system]
 requires = ["uv_build>=0.8.15,<0.9.0"]

{nodebpy-520.0.1 → nodebpy-520.1.0}/src/nodebpy/__init__.py

@@ -1,7 +1,5 @@
-from . import diagram, nodes
-from .builder import (
-    TreeBuilder,
-)
+from . import export, nodes
+from .builder import TreeBuilder
 from .nodes import compositor, geometry, shader
 
 __all__ = [
@@ -9,6 +7,6 @@ __all__ = [
     "compositor",
     "geometry",
     "shader",
-    "diagram",
+    "export",
     "TreeBuilder",
 ]

{nodebpy-520.0.1 → nodebpy-520.1.0}/src/nodebpy/builder/__init__.py

@@ -1,5 +1,6 @@
 from ._utils import SocketError, denormalize_name, normalize_name
 from .accessor import SocketAccessor
+from .items import Item, ItemsMixin
 from .mixins import LinkingMixin, OperatorMixin
 from .node import (
     BaseNode,
@@ -75,6 +76,8 @@ __all__ = [
     "OperatorMixin",
     "LinkingMixin",
     "DynamicInputsMixin",
+    "Item",
+    "ItemsMixin",
     # Node groups
     "NodeGroupBuilder",
     "CustomCompositorGroup",

{nodebpy-520.0.1 → nodebpy-520.1.0}/src/nodebpy/builder/_utils.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
-from typing import Any, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 import bpy
 from bpy.types import NodeSocket
 
+if TYPE_CHECKING:
+    from ..types import SOCKET_TYPES
+
 
 class SocketError(Exception):
     """Raised when a socket operation fails."""
@@ -49,6 +52,12 @@ def _allow_innactive_sockets(node: bpy.types.Node) -> bool:
         "ShaderNodeMixShader",
         # "ShaderNodeMix",
         "GeometryNodeSwitch",
+        # Group inputs that are only used behind an internal switch poll as
+        # inactive until the group is evaluated — including the input we are
+        # about to link, which would itself activate the socket.
+        "GeometryNodeGroup",
+        "ShaderNodeGroup",
+        "CompositorNodeGroup",
     )
 
 
@@ -62,7 +71,7 @@ def _resolve_promotion(
 
     Returns (dominant_socket, effective_other, effective_reverse).
     """
-    other_type = getattr(other, "type", None)
+    other_type = _output_socket_type(other)
     self_prec = _TYPE_PRECEDENCE.get(self_socket.type, 1)
     other_prec = _TYPE_PRECEDENCE.get(other_type, -1) if other_type is not None else -1
 
@@ -89,3 +98,17 @@ class _SocketLike(Protocol):
     """Protocol for objects that wrap a single Blender NodeSocket and expose ``.socket``."""
 
     socket: NodeSocket
+
+
+def _output_socket_type(value: Any) -> "SOCKET_TYPES | None":
+    """The Blender socket ``type`` of *value*'s default output socket.
+
+    Resolves a raw ``NodeSocket`` or any socket/node wrapper to the type string
+    Blender uses (e.g. ``"VECTOR"``, ``"VALUE"``). Returns ``None`` for plain
+    Python values (ints, floats, tuples) that carry no socket type.
+    """
+    if isinstance(value, NodeSocket):
+        return value.type  # type: ignore[return-value]
+    if isinstance(value, (_SocketLike, _NodeLike)):
+        return value._default_output_socket.type  # type: ignore[return-value]
+    return None

{nodebpy-520.0.1 → nodebpy-520.1.0}/src/nodebpy/builder/accessor.py

@@ -48,6 +48,7 @@ class SocketAccessor:
         if isinstance(key, int):
             return key
         ids = [s.identifier for s in self._collection]
+        names = [s.name for s in self._collection]
         denorm = denormalize_name(key)
         for candidate in (key, denorm):
             if candidate in ids:
@@ -56,16 +57,27 @@ class SocketAccessor:
         normalized_ids = [normalize_name(id) for id in ids]
         if key in normalized_ids:
             return normalized_ids.index(key)
-        names = [s.name for s in self._collection]
-        for key in (key, denorm):
-            if key in names:
-                if names.count(key) > 1:
+        for candidate in (key, denorm):
+            if candidate in names:
+                if names.count(candidate) > 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."
+                        f"{self._direction.title()} name '{candidate}' is ambiguous "
+                        f"on {self._node.bl_idname} (appears {names.count(candidate)} "
+                        f"times). Use the socket identifier instead."
                     )
-                return names.index(key)
+                return names.index(candidate)
+        # Normalized name match: 'flip_and_cyclic' matches name 'Flip and Cyclic'
+        # (denormalize_name can't recover the original capitalisation of small
+        # connector words like "and"/"to").
+        normalized_names = [normalize_name(n) for n in names]
+        if key in normalized_names:
+            if normalized_names.count(key) > 1:
+                raise RuntimeError(
+                    f"{self._direction.title()} name '{key}' is ambiguous on "
+                    f"{self._node.bl_idname} (appears {normalized_names.count(key)} "
+                    f"times). Use the socket identifier instead."
+                )
+            return normalized_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))}"

nodebpy-520.1.0/src/nodebpy/builder/items.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping, cast
+
+from bpy.types import Node, NodeSocket
+from mathutils import Euler
+
+from ..types import _is_default_value
+from ._registry import _wrap_socket
+from ._utils import _SocketLike
+from .node import DynamicInputsMixin
+from .socket import Socket
+
+if TYPE_CHECKING:
+    from ..types import InputLinkable
+    from .tree import TreeBuilder
+
+
+def _infer_value_type(value: Any) -> str | None:
+    """Item ``socket_type`` for a plain default value, or None."""
+    match value:
+        case bool():
+            return "BOOLEAN"
+        case int():
+            return "INT"
+        case float():
+            return "FLOAT"
+        case str():
+            return "STRING"
+        case tuple() | list():
+            return "VECTOR"
+        case Euler():
+            return "ROTATION"
+        case _:
+            return None
+
+
+class Item:
+    """Handle for one item of an items-driven node.
+
+    Names the item's socket *roles* rather than socket plumbing: ``input``
+    is the node's input socket for the item, ``output`` the matching
+    output socket.
+
+    Holds the item's collection index rather than the bpy item itself —
+    bpy collection item references are invalidated when the collection
+    grows.
+    """
+
+    def __init__(self, owner: ItemsMixin, item: Any):
+        self._owner = owner
+        self._index = next(
+            i for i, candidate in enumerate(self._collection) if candidate == item
+        )
+
+    @property
+    def _collection(self):
+        return self._owner._items
+
+    @property
+    def _item(self):
+        return self._collection[self._index]
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.name!r}, {self.socket_type!r})"
+
+    @property
+    def name(self) -> str:
+        return self._item.name
+
+    @property
+    def socket_type(self) -> str:
+        # some collections (capture_items, grid_items) call this data_type
+        item = self._item
+        return getattr(item, "socket_type", None) or item.data_type
+
+    @property
+    def input(self) -> Socket:
+        """The node's input socket for this item."""
+        return _wrap_socket(self._owner._item_socket(self._item))
+
+    @property
+    def output(self) -> Socket:
+        """The node's output socket for this item."""
+        return _wrap_socket(self._owner._item_socket(self._item, output=True))
+
+
+class ItemsMixin(DynamicInputsMixin):
+    """Socket machinery for nodes whose sockets are driven by a bpy item
+    collection (``capture_items``, ``bake_items``, ``format_items``, ...).
+
+    Subclasses declare class attributes instead of overriding methods:
+
+    - ``_items_collection``: name of the collection on ``_items_node``
+    - ``_socket_data_types``: socket types considered when inferring an
+      item's type from a source socket
+    - ``_type_map``: socket type -> item ``socket_type`` renames
+      (e.g. ``VALUE`` -> ``FLOAT``)
+
+    Must come *before* ``BaseNode`` in the bases so that
+    ``_find_best_socket_pair`` (the ``>>``-implicit-add behaviour) takes
+    precedence over ``LinkingMixin``'s.
+    """
+
+    _items_collection: str
+
+    if TYPE_CHECKING:
+        node: Node
+        tree: TreeBuilder
+
+        def _establish_links(self, **kwargs: Any) -> None: ...
+
+    @property
+    def _items_node(self) -> Node:
+        """Node owning the items collection.
+
+        Zone input nodes override this to return ``paired_output``, where
+        the shared collection lives.
+        """
+        return self.node
+
+    @property
+    def _items(self):
+        return getattr(self._items_node, self._items_collection)
+
+    def _new_item(self, name: str, type: str):
+        """Create a new collection item.
+
+        Override to adapt collections whose ``.new()`` signature differs
+        from ``(socket_type, name)``.
+        """
+        return self._items.new(socket_type=type, name=name)
+
+    def _item_socket(self, item, *, output: bool = False) -> NodeSocket:
+        """The node socket belonging to ``item``."""
+        sockets = self.node.outputs if output else self.node.inputs
+        matches = [s for s in sockets if s.name == item.name]
+        if len(matches) == 1:
+            return matches[0]
+        # Name collides — e.g. a capture item named "Selection" alongside the
+        # built-in CaptureAttribute "Selection" socket. Item sockets are the
+        # trailing N sockets (one per collection item), so resolve by the
+        # item's position in the collection instead.
+        items = list(self._items)
+        idx = next(i for i, it in enumerate(items) if it == item)
+        real = [s for s in sockets if not s.identifier.startswith("__extend__")]
+        return real[len(real) - len(items) + idx]
+
+    def _add_socket(self, name: str, type: str) -> NodeSocket:
+        return self._item_socket(self._new_item(name, type))
+
+    def _resolve_capture(
+        self,
+        value: InputLinkable,
+        *,
+        name: str | None,
+        types: tuple[str, ...] | None = None,
+    ) -> tuple[NodeSocket, str, str]:
+        """Resolve the source socket, item type and item name for a capture."""
+        accessor = getattr(value, "o", None)
+        sources = (
+            [cast("NodeSocket", value)] if accessor is None else accessor._available
+        )
+        socket_source, type = self._match_compatible_data(sources, types)
+        if type in self._type_map:
+            type = self._type_map[type]
+        if name is None:
+            default_socket = getattr(value, "_default_output_socket", None)
+            name = socket_source.name if default_socket is None else default_socket.name
+        if isinstance(socket_source, _SocketLike):
+            socket_source = socket_source.socket
+        return socket_source, type, name
+
+    def _declared_item_type(self, value: Any) -> str | None:
+        """The item ``socket_type`` if ``value`` is a socket-type string
+        (e.g. ``"FLOAT"``) valid for this node, else ``None``."""
+        if not isinstance(value, str):
+            return None
+        if value in self._socket_data_types:
+            return self._type_map.get(value, value)
+        if value in {self._type_map.get(t, t) for t in self._socket_data_types}:
+            return value
+        return None
+
+    def _add_unlinked_input(self, name: str, value: Any) -> bool:
+        """Items may also be declared with a plain default value
+        (``items={"label": "hello"}``) — the item type is inferred from
+        the Python type and the value becomes the socket default."""
+        if super()._add_unlinked_input(name, value):
+            return True
+        type = _infer_value_type(value)
+        if type is None:
+            return False
+        socket = self._add_socket(
+            name=name, type=self._declared_item_type(type) or type
+        )
+        socket.default_value = value  # ty: ignore[unresolved-attribute]
+        return True
+
+    def capture(self, value: InputLinkable, *, name: str | None = None) -> Socket:
+        """Add an item linked from ``value`` and return its output socket.
+
+        The item is auto-named after the source socket unless ``name`` is
+        given.
+        """
+        source, type, name = self._resolve_capture(value, name=name)
+        item = self._new_item(name, type)
+        self.tree.link(source, self._item_socket(item))
+        return _wrap_socket(self._item_socket(item, output=True))
+
+    def add_item(
+        self, name: str, value: Any = None, *, type: str | None = None
+    ) -> Item:
+        """Add a single item and return its handle.
+
+        ``value`` may be a linkable (linked to the item's input) or a plain
+        default value; otherwise ``type`` (a socket-type string such as
+        ``"FLOAT"``) declares the item unlinked.
+        """
+        if value is not None and not _is_default_value(value):
+            source, inferred, _ = self._resolve_capture(value, name=name)
+            item = self._new_item(name, type or inferred)
+            self.tree.link(source, self._item_socket(item))
+            return Item(self, item)
+        if type is None:
+            type = _infer_value_type(value)
+        if type is None:
+            raise TypeError(f"item {name!r} requires a value or an explicit type=")
+        item = self._new_item(name, self._declared_item_type(type) or type)
+        if value is not None:
+            self._item_socket(item).default_value = value  # ty: ignore[unresolved-attribute]
+        return Item(self, item)
+
+    def add_items(self, items: Mapping[str, InputLinkable | str]) -> dict[str, Item]:
+        """Add an item per mapping entry and return their handles by name.
+
+        Values may be linkables (linked to the new item's input) or
+        socket-type strings such as ``"FLOAT"`` (declare an unlinked item).
+        """
+        handles = {}
+        for key, value in items.items():
+            type = self._declared_item_type(value)
+            if type is not None:
+                handles[key] = self.add_item(key, type=type)
+            else:
+                handles[key] = self.add_item(key, cast("InputLinkable", value))
+        return handles

{nodebpy-520.0.1 → nodebpy-520.1.0}/src/nodebpy/builder/mixins.py

@@ -330,6 +330,16 @@ class LinkingMixin:
         if possible_combos:
             return sorted(possible_combos, key=lambda x: x[0])[0][1]
 
+        # A node with a virtual ``__extend__`` input (Viewer, …) accepts any
+        # source: linking to it makes Blender create a typed socket. Fall back
+        # to it when nothing else matched, pairing with the source's first
+        # available output.
+        extend = next(
+            (i for i in inputs if i.identifier.startswith("__extend__")), None
+        )
+        if extend is not None and outputs:
+            return extend, outputs[0]
+
         src_name = getattr(getattr(source, "node", None), "name", repr(source))
         tgt_name = getattr(getattr(target, "node", None), "name", repr(target))
         raise SocketError(