nodebpy 520.29.0__tar.gz → 520.30.1__tar.gz

{nodebpy-520.29.0 → nodebpy-520.30.1}/PKG-INFO

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

{nodebpy-520.29.0 → nodebpy-520.30.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nodebpy"
-version = "520.29.0"
+version = "520.30.1"
 description = "Build nodes trees in Blender more elegantly with code"
 readme = "README.md"
 authors = [
@@ -9,9 +9,6 @@ authors = [
 requires-python = ">=3.13"
 license = { text = "GPL-3.0-or-later" }
 
-[project.scripts]
-nodebpy = "nodebpy:main"
-
 [project.optional-dependencies]
 networkx = [
     "networkx>=3.6.1",

{nodebpy-520.29.0 → nodebpy-520.30.1}/src/nodebpy/__init__.py

@@ -9,9 +9,11 @@ from .builder import (
     default_sugiyama_options,
 )
 from .nodes import compositor, geometry, shader
+from .types import Default
 
 __all__ = [
     "ArrangeMethod",
+    "Default",
     "SimpleOptions",
     "SugiyamaOptions",
     "TreeBuilder",

{nodebpy-520.29.0 → nodebpy-520.30.1}/src/nodebpy/assets/_codegen.py

@@ -24,6 +24,7 @@ import bpy
 from ..builder import AssetLibrary, BundledLibrary, asset_group_base
 from ..builder._utils import normalize_name, typed_param_names
 from ..export.codegen import GroupInterface, _fmt
+from ..types import Default
 
 # bl_socket_type substring → (Socket accessor class, Input* parameter type).
 # Order matters: more specific keys (IntVector before Int) come first.
@@ -143,12 +144,29 @@ class _Socket:
     attr: str  # normalized accessor/param name
     description: str = ""  # interface tooltip, if the asset author set one
     menu_items: tuple[str, ...] = ()  # menu sockets only: the selectable items
+    fallback: str = ""  # what an unconnected input reads, for the docstring
+    modifier_attribute: str = ""  # attribute a modifier input defaults to reading
 
     @property
     def doc(self) -> str:
         """Documentation line for this socket — its tooltip, else its name."""
         return _clean_doc(self.description or self.name)
 
+    @property
+    def param_doc(self) -> str:
+        """The parameter's documentation line: the tooltip plus, for an input
+        with a fallback, what it reads when nothing is connected, and for one
+        with a default attribute, what a modifier input reads by default."""
+        doc = self.doc
+        if self.fallback:
+            doc = f"{doc.rstrip('.')}. When unconnected: {self.fallback}"
+        if self.modifier_attribute:
+            doc = (
+                f"{doc.rstrip('.')}. As a modifier input, reads the "
+                f'"{self.modifier_attribute}" attribute by default.'
+            )
+        return doc
+
     @property
     def param_type(self) -> str:
         """Type hint for the ``__init__`` parameter.
@@ -179,13 +197,22 @@ def _collect(
     sockets,
     descriptions: dict[str, str] | None = None,
     menus: bool = False,
+    fallbacks: dict[str, Default] | None = None,
+    modifier_attributes: dict[str, str] | None = None,
 ) -> list[_Socket]:
     """Introspect ``sockets`` into records.
 
     ``menus`` resolves menu sockets to their items — only worth doing for the
-    group's *inputs*, whose parameters are typed from them.
+    group's *inputs*, whose parameters are typed from them. ``fallbacks`` maps
+    an input's identifier to what it reads when unconnected (the interface's
+    ``default_input`` field); such a parameter defaults to the matching
+    ``Default`` member instead of a stored value. ``modifier_attributes``
+    maps an input to its default attribute name, which only a Geometry Nodes
+    modifier uses, so it is documented but does not change the default.
     """
     descriptions = descriptions or {}
+    fallbacks = fallbacks or {}
+    modifier_attributes = modifier_attributes or {}
     # Keep inactive sockets: socket-usage inference deactivates inputs that the
     # current node options (e.g. a menu selection) leave unused, but a caller
     # may set those options differently, so the API must expose every input.
@@ -202,21 +229,58 @@ def _collect(
         attr = (
             norm_name if name_counts[norm_name] == 1 else normalize_name(s.identifier)
         )
+        fallback = fallbacks.get(s.identifier)
         out.append(
             _Socket(
                 name=s.name,
                 identifier=s.identifier,
                 socket_class=socket_class,
                 input_type=input_type,
-                default=_format_default(s),
+                default=repr(fallback) if fallback else _format_default(s),
                 attr=attr,
                 description=descriptions.get(s.identifier, ""),
                 menu_items=menu_items,
+                fallback=fallback.description if fallback else "",
+                modifier_attribute=modifier_attributes.get(s.identifier, ""),
             )
         )
     return out
 
 
+def _interface_fallbacks(group) -> dict[str, Default]:
+    """What each group input reads when unconnected, by socket identifier.
+
+    An interface input with a ``default_input`` other than ``VALUE`` reads an
+    implicit field or context value instead of its stored default, whether
+    the group is a modifier or a node in another tree. Other inputs are left
+    out.
+    """
+    fallbacks: dict[str, Default] = {}
+    for item in group.interface.items_tree:
+        if item.item_type != "SOCKET" or item.in_out != "INPUT":
+            continue
+        default_input = getattr(item, "default_input", "VALUE")
+        if default_input != "VALUE":
+            fallbacks[item.identifier] = Default(default_input)
+    return fallbacks
+
+
+def _interface_modifier_attributes(group) -> dict[str, str]:
+    """Each group input's default attribute name, by socket identifier.
+
+    Blender only applies it when the group is a Geometry Nodes modifier (the
+    input starts in attribute mode reading that name); as a node inside
+    another tree the input still uses its stored value.
+    """
+    return {
+        item.identifier: item.default_attribute_name
+        for item in group.interface.items_tree
+        if item.item_type == "SOCKET"
+        and item.in_out == "INPUT"
+        and getattr(item, "default_attribute_name", "")
+    }
+
+
 def _introspect_group(group, name: str, library_source: str) -> _AssetClass:
     """Introspect the node group ``group`` (a ``bpy.types.NodeTree``) into an
     :class:`_AssetClass` record by instantiating it on a throwaway host node.
@@ -253,7 +317,13 @@ def _introspect_group(group, name: str, library_source: str) -> _AssetClass:
             description=(group.description or name).strip(),
             library_source=library_source,
             tree_idname=group.bl_idname,
-            inputs=_collect(node.inputs, descriptions, menus=True),
+            inputs=_collect(
+                node.inputs,
+                descriptions,
+                menus=True,
+                fallbacks=_interface_fallbacks(group),
+                modifier_attributes=_interface_modifier_attributes(group),
+            ),
             outputs=_collect(node.outputs, descriptions),
         )
     finally:
@@ -320,7 +390,7 @@ def _class_docstring(cls: _AssetClass) -> str:
     if cls.inputs:
         lines += ["Parameters", "----------"]
         for s in cls.inputs:
-            lines += [f"{s.attr} : {s.param_type}", f"    {s.doc}"]
+            lines += [f"{s.attr} : {s.param_type}", f"    {s.param_doc}"]
         lines.append("")
         lines += ["Inputs", "------"]
         for s in cls.inputs:
@@ -369,7 +439,7 @@ def _render_class(cls: _AssetClass, docstrings: bool = False) -> str:
         @property
         def o(self) -> _Outputs: ...
 
-    def __init__{signature}:
+    def __init__{signature}{" -> None" if signature == "(self)" else ""}:
         super().__init__(**{{{key_args}}})
 """
 
@@ -428,7 +498,8 @@ def interface_parts(
         args.append("**{" + ", ".join(keyed) + "}")
     if pairs:
         args.append("_named_links=[" + ", ".join(pairs) + "]")
-    init = f"    def __init__{signature}:\n        super().__init__({', '.join(args)})"
+    init_return = " -> None" if signature == "(self)" else ""
+    init = f"    def __init__{signature}{init_return}:\n        super().__init__({', '.join(args)})"
 
     type_checking = (
         "    if TYPE_CHECKING:\n"
@@ -469,6 +540,8 @@ def interface_parts(
     ]
     if any("math." in s.default for s in cls.inputs):
         import_lines.insert(0, "import math")
+    if any(s.default.startswith("Default.") for s in cls.inputs):
+        input_types.insert(0, "Default")  # sorts before the Input* names
     if input_types:
         import_lines.append(f"from {nodebpy_pkg}.types import {', '.join(input_types)}")
 
@@ -489,6 +562,8 @@ def _render_module(
         {s.socket_class for c in classes for s in c.inputs + c.outputs}
     )
     input_types = sorted({s.input_type for c in classes for s in c.inputs})
+    if any(s.default.startswith("Default.") for c in classes for s in c.inputs):
+        input_types.insert(0, "Default")
     bases = sorted({asset_group_base(c.tree_idname).__name__ for c in classes})
     libraries = sorted(
         {

{nodebpy-520.29.0 → nodebpy-520.30.1}/src/nodebpy/builder/_utils.py

@@ -178,9 +178,10 @@ def _resolve_promotion(
 
 @runtime_checkable
 class _NodeLike(Protocol):
-    """Protocol for objects that wrap a Blender node and expose an ``outputs`` accessor."""
+    """Protocol for objects that wrap a Blender node and expose an ``o`` output accessor."""
 
-    outputs: Any  # SocketAccessor at runtime; typed as Any to avoid circular import
+    @property
+    def o(self) -> Any: ...  # SocketAccessor at runtime; Any avoids a circular import
 
 
 @runtime_checkable

{nodebpy-520.29.0 → nodebpy-520.30.1}/src/nodebpy/builder/asset.py

@@ -111,7 +111,7 @@ class _AssetGroupMixin:
         return cls._build_group is not _AssetGroupMixin._build_group
 
     @classmethod
-    def create_group(cls):
+    def create_group(cls) -> Any:
         """Append the named asset group from the library and return its tree,
         reusing a previously-appended group of the same name and tree type.
 

{nodebpy-520.29.0 → nodebpy-520.30.1}/src/nodebpy/builder/items.py

@@ -200,7 +200,7 @@ class ItemsMixin(DynamicInputsMixin):
 
     if TYPE_CHECKING:
         node: Node
-        tree: TreeBuilder
+        tree: TreeBuilder[Any]
 
         def _establish_links(self, **kwargs: Any) -> None: ...
 

{nodebpy-520.29.0 → nodebpy-520.30.1}/src/nodebpy/builder/layout.py

@@ -39,7 +39,9 @@ def _is_layoutable(node: bpy.types.Node) -> bool:
 
 def build_dependency_graph(
     tree: bpy.types.NodeTree,
-) -> tuple[dict[bpy.types.Node, set[bpy.types.Node]], Counter]:
+) -> tuple[
+    dict[bpy.types.Node, set[bpy.types.Node]], Counter[bpy.types.NodeSocket | None]
+]:
     """Build a graph of node dependencies and count input connections.
 
     Only layoutable nodes (excluding frames and reroutes) are included.
@@ -48,7 +50,7 @@ def build_dependency_graph(
     dependency_graph: dict[bpy.types.Node, set[bpy.types.Node]] = {
         node: set() for node in layoutable
     }
-    socket_input_connection_count: Counter = Counter()
+    socket_input_connection_count: Counter[bpy.types.NodeSocket | None] = Counter()
 
     for link in tree.links:
         if link.from_node in layoutable and link.to_node in layoutable:
@@ -181,7 +183,7 @@ def _socket_visible(socket: bpy.types.NodeSocket) -> bool:
 
 def _is_expanded_vector(
     socket: bpy.types.NodeSocket,
-    socket_input_connection_count: Counter | None,
+    socket_input_connection_count: Counter[bpy.types.NodeSocket | None] | None,
 ) -> bool:
     """Whether an input draws the expanded 3-component vector widget: an
     unlinked vector whose value is shown (``hide_value`` sockets, such as
@@ -266,7 +268,7 @@ def _interface_panels(node: bpy.types.Node) -> tuple[list[Any], dict[int, bool]]
 
 def node_rows(
     node: bpy.types.Node,
-    socket_input_connection_count: Counter | None = None,
+    socket_input_connection_count: Counter[bpy.types.NodeSocket | None] | None = None,
 ) -> list[NodeRow]:
     """The rows Blender draws below an expanded node's header, top to bottom.
 
@@ -376,7 +378,7 @@ def node_rows(
 def _rows_from_order(
     node: bpy.types.Node,
     order: tuple[tuple, ...],
-    socket_input_connection_count: Counter | None,
+    socket_input_connection_count: Counter[bpy.types.NodeSocket | None] | None,
 ) -> list[NodeRow]:
     """Rows of a node drawn from its declaration (see ``_socket_order``)."""
     rows: list[NodeRow] = []
@@ -584,7 +586,7 @@ def _rows_from_order(
 
 def calculate_node_dimensions(
     node: bpy.types.Node,
-    socket_input_connection_count: Counter | None = None,
+    socket_input_connection_count: Counter[bpy.types.NodeSocket | None] | None = None,
     interface_scale: float = 1.0,
 ) -> tuple[float, float]:
     """Calculate the visual dimensions of a node.
@@ -744,7 +746,7 @@ def _reduce_crossings(
 
 def position_nodes_in_columns(
     columns: list[list[bpy.types.Node]],
-    connection_counts: Counter,
+    connection_counts: Counter[bpy.types.NodeSocket | None],
     spacing: tuple[float, float] = (50, 25),
 ) -> None:
     """Position nodes column-by-column with the given spacing.

{nodebpy-520.29.0 → nodebpy-520.30.1}/src/nodebpy/builder/mixins.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, Any, Self, TypeVar, cast, overload
 
 from bpy.types import NodeLink, NodeSocket
 
+from ..types import Default
 from ._registry import _wrap_socket
 from ._utils import SocketError, _resolve_promotion, _SocketLike
 
@@ -12,13 +13,13 @@ _RShiftT = TypeVar("_RShiftT")
 
 if TYPE_CHECKING:
     from ..nodes.geometry import CombineTransform
+    from ..nodes.geometry.converter import BooleanMath
     from ..types import InputLinkable
     from .accessor import SocketAccessor
     from .node import BaseNode
     from .socket import (
         BooleanSocket,
         FloatSocket,
-        IntegerSocket,
         MatrixSocket,
         Position,
         Socket,
@@ -44,74 +45,65 @@ class OperatorMixin:
 
     def _apply_math_operation(
         self, other: Any, operation: str, reverse: bool = False
-    ) -> FloatSocket | VectorSocket | IntegerSocket:
+    ) -> Socket:
         socket, other, reverse = _resolve_promotion(
             self._default_output_socket,
             other,
             reverse,
         )
-        return cast(
-            "FloatSocket | VectorSocket | IntegerSocket",
-            _wrap_socket(socket)._dispatch_math(other, operation, reverse),
-        )
+        return _wrap_socket(socket)._dispatch_math(other, operation, reverse)
 
-    def __mul__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __mul__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "multiply")
 
-    def __rmul__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __rmul__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "multiply", reverse=True)
 
-    def __truediv__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __truediv__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "divide")
 
-    def __rtruediv__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __rtruediv__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "divide", reverse=True)
 
-    def __add__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __add__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "add")
 
-    def __radd__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __radd__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "add", reverse=True)
 
-    def __sub__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __sub__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "subtract")
 
-    def __rsub__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __rsub__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "subtract", reverse=True)
 
-    def __pow__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __pow__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "power")
 
-    def __rpow__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __rpow__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "power", reverse=True)
 
-    def __mod__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __mod__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "modulo")
 
-    def __rmod__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __rmod__(self, other: Any) -> Socket:
         return self._apply_math_operation(other, "modulo", reverse=True)
 
-    def __floordiv__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __floordiv__(self, other: Any) -> Socket:
         socket, other, reverse = _resolve_promotion(
             self._default_output_socket,
             other,
             False,
         )
-        return cast(
-            "FloatSocket | VectorSocket | IntegerSocket",
-            _wrap_socket(socket)._dispatch_floordiv(other, reverse),
-        )
+        return _wrap_socket(socket)._dispatch_floordiv(other, reverse)
 
-    def __rfloordiv__(self, other: Any) -> FloatSocket | VectorSocket | IntegerSocket:
+    def __rfloordiv__(self, other: Any) -> Socket:
         socket, other, reverse = _resolve_promotion(
             self._default_output_socket,
             other,
             True,
         )
-        return cast(
-            "FloatSocket | VectorSocket | IntegerSocket",
-            _wrap_socket(socket)._dispatch_floordiv(other, reverse),
-        )
+        return _wrap_socket(socket)._dispatch_floordiv(other, reverse)
 
     def __matmul__(
         self, other: Position | CombineTransform | VectorSocket | MatrixSocket
@@ -143,36 +135,11 @@ class OperatorMixin:
 
         return MultiplyMatrices(other, self).o.matrix  # ty: ignore[invalid-argument-type]
 
-    def __neg__(self) -> FloatSocket | VectorSocket | IntegerSocket:
-        return cast(
-            "FloatSocket | VectorSocket | IntegerSocket",
-            _wrap_socket(self._default_output_socket)._dispatch_unary("negate"),
-        )
-
-    def __abs__(self) -> FloatSocket | VectorSocket | IntegerSocket:
-        return cast(
-            "FloatSocket | VectorSocket | IntegerSocket",
-            _wrap_socket(self._default_output_socket)._dispatch_unary("absolute"),
-        )
-
-    if TYPE_CHECKING:
+    def __neg__(self) -> Socket:
+        return _wrap_socket(self._default_output_socket)._dispatch_unary("negate")
 
-        def __mul__(self, other: Any) -> Self: ...
-        def __rmul__(self, other: Any) -> Self: ...
-        def __truediv__(self, other: Any) -> Self: ...
-        def __rtruediv__(self, other: Any) -> Self: ...
-        def __add__(self, other: Any) -> Self: ...
-        def __radd__(self, other: Any) -> Self: ...
-        def __sub__(self, other: Any) -> Self: ...
-        def __rsub__(self, other: Any) -> Self: ...
-        def __pow__(self, other: Any) -> Self: ...
-        def __rpow__(self, other: Any) -> Self: ...
-        def __mod__(self, other: Any) -> Self: ...
-        def __rmod__(self, other: Any) -> Self: ...
-        def __floordiv__(self, other: Any) -> Self: ...
-        def __rfloordiv__(self, other: Any) -> Self: ...
-        def __neg__(self) -> Self: ...
-        def __abs__(self) -> Self: ...
+    def __abs__(self) -> Socket:
+        return _wrap_socket(self._default_output_socket)._dispatch_unary("absolute")
 
     def _apply_compare_operation(
         self, other: Any, operation: str
@@ -202,36 +169,36 @@ class OperatorMixin:
     def __ne__(self, other: object) -> FloatSocket | BooleanSocket:  # type: ignore
         return self._apply_compare_operation(other, "not_equal")
 
-    def _apply_boolean_operation(self, other: Any, operation: str):
+    def _apply_boolean_operation(self, other: Any, operation: str) -> BooleanMath:
         from ..nodes.geometry.converter import BooleanMath
 
         return getattr(BooleanMath, operation)(self, other)
 
-    def __and__(self, other: Any):
+    def __and__(self, other: Any) -> BooleanMath | Socket:
         return self._apply_boolean_operation(other, "l_and")
 
-    def __rand__(self, other: Any):
+    def __rand__(self, other: Any) -> BooleanMath | Socket:
         from ..nodes.geometry.converter import BooleanMath
 
         return BooleanMath.l_and(other, cast(Any, self))
 
-    def __or__(self, other: Any):
+    def __or__(self, other: Any) -> BooleanMath | Socket:
         return self._apply_boolean_operation(other, "l_or")
 
-    def __ror__(self, other: Any):
+    def __ror__(self, other: Any) -> BooleanMath | Socket:
         from ..nodes.geometry.converter import BooleanMath
 
         return BooleanMath.l_or(other, cast(Any, self))
 
-    def __xor__(self, other: Any):
+    def __xor__(self, other: Any) -> BooleanMath | Socket:
         return self._apply_boolean_operation(other, "not_equal")
 
-    def __rxor__(self, other: Any):
+    def __rxor__(self, other: Any) -> BooleanMath | Socket:
         from ..nodes.geometry.converter import BooleanMath
 
         return BooleanMath.not_equal(other, cast(Any, self))
 
-    def __invert__(self):
+    def __invert__(self) -> BooleanMath | Socket:
         from ..nodes.geometry.converter import BooleanMath
 
         return BooleanMath.l_not(cast(Any, self))
@@ -244,7 +211,7 @@ class LinkingMixin:
     and ``_default_input_socket`` on the concrete class.
     """
 
-    tree: TreeBuilder
+    tree: TreeBuilder[Any]
 
     if TYPE_CHECKING:
         import bpy
@@ -262,6 +229,8 @@ class LinkingMixin:
 
     def _source_socket(self, node: InputLinkable | Socket | NodeSocket) -> NodeSocket:
         assert node is not None
+        if isinstance(node, Default):
+            raise TypeError(f"{node} marks an input's fallback, it cannot be linked")
         if isinstance(node, NodeSocket):
             return node
         elif hasattr(node, "_default_output_socket"):
@@ -271,6 +240,8 @@ class LinkingMixin:
 
     def _target_socket(self, node: InputLinkable | Socket | NodeSocket) -> NodeSocket:
         assert node is not None
+        if isinstance(node, Default):
+            raise TypeError(f"{node} marks an input's fallback, it cannot be linked")
         if isinstance(node, NodeSocket):
             return node
         elif hasattr(node, "_default_input_socket"):

{nodebpy-520.29.0 → nodebpy-520.30.1}/src/nodebpy/builder/node.py

@@ -25,7 +25,7 @@ from bpy.types import (
     ShaderNodeTree,
 )
 
-from ..types import SOCKET_COMPATIBILITY, InputAny
+from ..types import SOCKET_COMPATIBILITY, Default, InputAny
 from ._utils import SocketError, _NodeLike, _SocketLike
 from .accessor import SocketAccessor
 from .mixins import LinkingMixin, OperatorMixin
@@ -91,7 +91,8 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
     """Base class for all node wrappers."""
 
     _bl_idname: str
-    _tree: TreeBuilder
+    _tree: TreeBuilder[Any]
+    node: Node
     _default_input_id: str | None = None
     _default_output_id: str | None = None
     _placeholder_inputs: list[str]
@@ -113,7 +114,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
         self.node = node if node else self._tree.add(self.__class__._bl_idname)
 
     @property
-    def tree(self) -> TreeBuilder:
+    def tree(self) -> TreeBuilder[Any]:
         """The `TreeBuilder` instance this node belongs to and is being built within."""
         return self._tree
 
@@ -207,6 +208,11 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
         lets callers address one of several same-named sockets unambiguously.
         """
         named = isinstance(target, str)
+        # A ``Default`` member stands for the socket's own fallback (an implicit
+        # field or context value Blender reads when nothing is linked): nothing to
+        # set or link, the same as ``None``.
+        if isinstance(value, Default):
+            return
         # TODO: don't like these manual overrides for particular nodes, but best I can do for now
         if value is None or (
             named
@@ -231,7 +237,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
             self._link_from(value, target)
         elif isinstance(value, _NodeLike):
             target_type = target.type if not named else self.i._get(target).type
-            self._link_from(value.o._best_match(target_type), target)  # type: ignore
+            self._link_from(value.o._best_match(target_type), target)
         else:
             # TODO: explicitly skipping the sockets for BooleanMath as they are default false,
             # but this needs to be a more generic solution for sockets which aren't available
@@ -422,7 +428,7 @@ class NodeGroupBuilder[T: bpy.types.NodeTree](BaseNode, ABC):
     # fresh tree's defaults belong here; codegen fills it when exporting.
     _tree_properties: ClassVar[dict[str, Any]] = {}
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs: Any):
         super().__init__()
         self._setup_node_group()
         self.node.show_options = False