nodebpy 0.10.1__tar.gz → 0.11.0__tar.gz

nodebpy-0.11.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.3
+Name: nodebpy
+Version: 0.11.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.1.0 ; extra == 'bpy'
+Requires-Dist: networkx>=3.6.1 ; extra == 'networkx'
+Requires-Python: >=3.13
+Provides-Extra: bpy
+Provides-Extra: networkx
+Description-Content-Type: text/markdown
+
+# nodebpy
+
+[![Run
+Tests](https://github.com/BradyAJohnston/nodebpy/actions/workflows/tests.yml/badge.svg)](https://github.com/BradyAJohnston/nodebpy/actions/workflows/tests.yml)
+[![](https://codecov.io/gh/BradyAJohnston/nodebpy/graph/badge.svg?token=buThDQZUED)](https://codecov.io/gh/BradyAJohnston/nodebpy)
+
+A package to build node trees in blender more elegantly with python code. Geometry Nodes, Shader Nodes and Compositor nodes are all fully supported. Look at the [documentation](https://bradyajohnston.github.io/nodebpy) for more examples.
+
+## Creating Nodes With Code
+
+> A text-based version of nodes should bring the convenience of writing code with IDE auto-completion, type hinting, with overall compactness and readability, while staying as close as possible to what building a node tree via the GUI feels like.
+
+```python
+from nodebpy import geometry as g
+
+with g.tree("AnotherTree", collapse=True) as tree:
+    rotation = (
+        g.RandomValue.vector(min=-1, seed=2)
+        >> g.AlignRotationToVector()
+        >> g.RotateRotation(rotate_by=g.AxisAngleToRotation(angle=0.3))
+    )
+
+    _ = (
+        tree.inputs.integer("Count", 10)
+        >> g.Points(position=g.RandomValue.vector(min=-1))
+        >> g.InstanceOnPoints(instance=g.Cube(), rotation=rotation)
+        >> g.SetPosition(
+            position=g.Position() * 2.0 + (0, 0.2, 0.3),
+            offset=(0, 0, 0.1),
+        )
+        >> g.RealizeInstances()
+        >> g.InstanceOnPoints(g.Cube(), instance=...)
+        >> tree.outputs.geometry("Instances")
+    )
+```
+
+![](docs/images/paste-1.png)
+
+Nodes are created by instantiating their classes. The node tree they are added to is determined by the context the code is executed in (while inside `with g.tree():`). The interface for the node tree is created with `tree.inputs` and `tree.inputs`, adding the sockets and returning the input or output socket for linking with other nodes.
+
+Nodes are linked by overloading the `>>` operator, to link from the previous node on the left to the input on the right. Suitable socket pairs are automatically selected or explicitly supplied.
+
+The layout / arrangement of the node tree is not important to Blender's evaluation of it - but an automatic layout algorithm is potentially applied upon exiting the node tree context.
+
+### `nodebpy` and the `>>` operator
+
+In `nodebpy` we use the `>>` operator to link from one node or socket into another.
+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
+# vector output will be linked into the first vector input (position)
+g.Vector() >> g.SetPosition()
+# vector output will be linked into the offset input
+g.Vector() >> g.SetPosition(offset=...)
+g.SetPosition(offset=g.Vector())
+```
+
+The `>>` operator will always look for the _most_ compatible sockets first (matching data types) before looking for other compatible but not identical socket data types to link.
+If a compatible match can't be found an error _will_ be thrown.
+
+### Contexts
+
+What node tree or node tree interface we are currently editing is determined based on contexts.
+Instantiating a node class outside of a tree context will throw an error. The easiest way to enter and exit a tree context is to use the `with` statement.
+
+Each time you instantiate a node class, a new node will be created and added to the current tree.
+If these nodes are given as arguments to other nodes or used with the `>>` operator, they will be automatically linked to the appropriate sockets.
+
+## Nodes
+
+Documentation for all of the nodes can be found in the [API Reference](https://bradyajohnston.github.io/nodebpy/reference/). This is mostly built automatically from the existing Blender node classes.
+
+Every node has all of it's input sockets and enum options exposed as arguments to the class constructor. Input sockets are prefixed with `.i.*` and output sockets are prefixed with `.o.*`. Properties that aren't exposed as sockets are available as class properties. Many properties are also available as class methods for convenience when constructing.
+
+The basic math operators also automatically add relevant nodes with their operations and values set.
+
+```py
+# operation is exposed as a property
+math = g.Math(1.0, 2.0, operation='ADD')
+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
+# the 3.0 + 2.0 is evaluated as regular python code first,
+# so the result with be a Math.add(g.Value(1.0), 5.0)
+math = g.Value(1.0) 3.0 + 2.0
+
+# these are equivalent, the g.Math.multiply is automatically added
+g.Value(1.0) * 2
+g.Math.multiply(g.Value(1.0), 2.0)
+```
+
+# Design Considerations
+
+The top priority of `nodebpy` has been type hinting and IDE auto-complete.
+Typical tooling that supports autoring regular python code should also support the authoring of node trees.
+Much like [`databpy`](https://github.com/BradyAJohnston/databpy), this started as an internal tool used inside of [`molecularnodes`](https://github.com/BradyAJohnston/molecularnodes) but has since been broken out into it's own separate project.
+This projects is robustly typed and tested, with the intent that it can be used internally for multiple other add-ons and projects.
+
+- Node classes are named after nodes 'Random Value' -> `RandomValue()`
+- Node 'subtypes' and methods should be accessible via dot (`.`) for easier IDE auto-complete and authoring:
+  - `RandomValue(data_type="FLOAT_VECTOR")` -> `RandomValue.vector()`
+- Node properties are available on the top level, with inputs and outputs available behind `.i.*` and `.o.*` accessors
+- Inputs and outputs from a node are prefixed with `i.*` and `o.*`:
+  - `AccumulateField().o.total` returns the output `Total` socket
+  - `AccumulateField().i.value` returns the input `Value` socket
+
+## Building
+
+Most of the code for classes are generated automatically with the `generate.py` script.
+Some nodes are manually specified in the `src/nodebpy/nodes/geometry/manual.py` if they require special handling.
+
+Run the build & format script as such:
+
+```bash
+uv run generate.py && uvx ruff format && uvx ruff check --fix
+```
+
+## Other Projects
+
+There are several other notable projects which have also attempted interfacing with node trees via code. They mostly fit into two categories of either storing & retrieving node trees via code (`.json` or the `bpy` API), or authoring of node trees with custom API and syntax. This project mostly fits in to the latter category.
+
+
+
+### Storing node trees as code:
+Converting node trees to the python API calls or `.json` is great to have a robust storage method, but this approach falls down in human authorability / readability. These projects are great for storage but less useful when wanting to write / generate node trees froms scratch.
+
+  - [NodeToPython](https://github.com/BrendanParmer/NodeToPython)
+  - [TreeClipper](https://github.com/Algebraic-UG/tree_clipper) (used by this project for running tests & snapshots)
+
+### Authoring node trees with code:
+Two previous projects have made similar approaches to authoring node trees. `geometry-script` also auto-generated most of it's type hinting, code and docs. It uses the approach of method chaining with the `.` operator, but obfuscates some of the non-linear way of building node trees.
+
+The other project `geonodes` uses a similar context system for creating and authoring node trees, but doesn't use the same method of exposing each individual node as it's own class that `nodebpy` does.
+
+I personally found both of their APIs to _not quite_ fit how I wanted to work, leading to the creation of `nodebpy`.
+In comparison, this project is also the only one that is also distributed on `PyPi` and insallable via `pip` for easier use in other projects.
+
+  - [geometry-script](https://github.com/carson-katri/geometry-script),
+  - [geonodes](https://github.com/al1brn/geonodes)

nodebpy-0.11.0/README.md

@@ -0,0 +1,143 @@
+# nodebpy
+
+[![Run
+Tests](https://github.com/BradyAJohnston/nodebpy/actions/workflows/tests.yml/badge.svg)](https://github.com/BradyAJohnston/nodebpy/actions/workflows/tests.yml)
+[![](https://codecov.io/gh/BradyAJohnston/nodebpy/graph/badge.svg?token=buThDQZUED)](https://codecov.io/gh/BradyAJohnston/nodebpy)
+
+A package to build node trees in blender more elegantly with python code. Geometry Nodes, Shader Nodes and Compositor nodes are all fully supported. Look at the [documentation](https://bradyajohnston.github.io/nodebpy) for more examples.
+
+## Creating Nodes With Code
+
+> A text-based version of nodes should bring the convenience of writing code with IDE auto-completion, type hinting, with overall compactness and readability, while staying as close as possible to what building a node tree via the GUI feels like.
+
+```python
+from nodebpy import geometry as g
+
+with g.tree("AnotherTree", collapse=True) as tree:
+    rotation = (
+        g.RandomValue.vector(min=-1, seed=2)
+        >> g.AlignRotationToVector()
+        >> g.RotateRotation(rotate_by=g.AxisAngleToRotation(angle=0.3))
+    )
+
+    _ = (
+        tree.inputs.integer("Count", 10)
+        >> g.Points(position=g.RandomValue.vector(min=-1))
+        >> g.InstanceOnPoints(instance=g.Cube(), rotation=rotation)
+        >> g.SetPosition(
+            position=g.Position() * 2.0 + (0, 0.2, 0.3),
+            offset=(0, 0, 0.1),
+        )
+        >> g.RealizeInstances()
+        >> g.InstanceOnPoints(g.Cube(), instance=...)
+        >> tree.outputs.geometry("Instances")
+    )
+```
+
+![](docs/images/paste-1.png)
+
+Nodes are created by instantiating their classes. The node tree they are added to is determined by the context the code is executed in (while inside `with g.tree():`). The interface for the node tree is created with `tree.inputs` and `tree.inputs`, adding the sockets and returning the input or output socket for linking with other nodes.
+
+Nodes are linked by overloading the `>>` operator, to link from the previous node on the left to the input on the right. Suitable socket pairs are automatically selected or explicitly supplied.
+
+The layout / arrangement of the node tree is not important to Blender's evaluation of it - but an automatic layout algorithm is potentially applied upon exiting the node tree context.
+
+### `nodebpy` and the `>>` operator
+
+In `nodebpy` we use the `>>` operator to link from one node or socket into another.
+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
+# vector output will be linked into the first vector input (position)
+g.Vector() >> g.SetPosition()
+# vector output will be linked into the offset input
+g.Vector() >> g.SetPosition(offset=...)
+g.SetPosition(offset=g.Vector())
+```
+
+The `>>` operator will always look for the _most_ compatible sockets first (matching data types) before looking for other compatible but not identical socket data types to link.
+If a compatible match can't be found an error _will_ be thrown.
+
+### Contexts
+
+What node tree or node tree interface we are currently editing is determined based on contexts.
+Instantiating a node class outside of a tree context will throw an error. The easiest way to enter and exit a tree context is to use the `with` statement.
+
+Each time you instantiate a node class, a new node will be created and added to the current tree.
+If these nodes are given as arguments to other nodes or used with the `>>` operator, they will be automatically linked to the appropriate sockets.
+
+## Nodes
+
+Documentation for all of the nodes can be found in the [API Reference](https://bradyajohnston.github.io/nodebpy/reference/). This is mostly built automatically from the existing Blender node classes.
+
+Every node has all of it's input sockets and enum options exposed as arguments to the class constructor. Input sockets are prefixed with `.i.*` and output sockets are prefixed with `.o.*`. Properties that aren't exposed as sockets are available as class properties. Many properties are also available as class methods for convenience when constructing.
+
+The basic math operators also automatically add relevant nodes with their operations and values set.
+
+```py
+# operation is exposed as a property
+math = g.Math(1.0, 2.0, operation='ADD')
+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
+# the 3.0 + 2.0 is evaluated as regular python code first,
+# so the result with be a Math.add(g.Value(1.0), 5.0)
+math = g.Value(1.0) 3.0 + 2.0
+
+# these are equivalent, the g.Math.multiply is automatically added
+g.Value(1.0) * 2
+g.Math.multiply(g.Value(1.0), 2.0)
+```
+
+# Design Considerations
+
+The top priority of `nodebpy` has been type hinting and IDE auto-complete.
+Typical tooling that supports autoring regular python code should also support the authoring of node trees.
+Much like [`databpy`](https://github.com/BradyAJohnston/databpy), this started as an internal tool used inside of [`molecularnodes`](https://github.com/BradyAJohnston/molecularnodes) but has since been broken out into it's own separate project.
+This projects is robustly typed and tested, with the intent that it can be used internally for multiple other add-ons and projects.
+
+- Node classes are named after nodes 'Random Value' -> `RandomValue()`
+- Node 'subtypes' and methods should be accessible via dot (`.`) for easier IDE auto-complete and authoring:
+  - `RandomValue(data_type="FLOAT_VECTOR")` -> `RandomValue.vector()`
+- Node properties are available on the top level, with inputs and outputs available behind `.i.*` and `.o.*` accessors
+- Inputs and outputs from a node are prefixed with `i.*` and `o.*`:
+  - `AccumulateField().o.total` returns the output `Total` socket
+  - `AccumulateField().i.value` returns the input `Value` socket
+
+## Building
+
+Most of the code for classes are generated automatically with the `generate.py` script.
+Some nodes are manually specified in the `src/nodebpy/nodes/geometry/manual.py` if they require special handling.
+
+Run the build & format script as such:
+
+```bash
+uv run generate.py && uvx ruff format && uvx ruff check --fix
+```
+
+## Other Projects
+
+There are several other notable projects which have also attempted interfacing with node trees via code. They mostly fit into two categories of either storing & retrieving node trees via code (`.json` or the `bpy` API), or authoring of node trees with custom API and syntax. This project mostly fits in to the latter category.
+
+
+
+### Storing node trees as code:
+Converting node trees to the python API calls or `.json` is great to have a robust storage method, but this approach falls down in human authorability / readability. These projects are great for storage but less useful when wanting to write / generate node trees froms scratch.
+
+  - [NodeToPython](https://github.com/BrendanParmer/NodeToPython)
+  - [TreeClipper](https://github.com/Algebraic-UG/tree_clipper) (used by this project for running tests & snapshots)
+
+### Authoring node trees with code:
+Two previous projects have made similar approaches to authoring node trees. `geometry-script` also auto-generated most of it's type hinting, code and docs. It uses the approach of method chaining with the `.` operator, but obfuscates some of the non-linear way of building node trees.
+
+The other project `geonodes` uses a similar context system for creating and authoring node trees, but doesn't use the same method of exposing each individual node as it's own class that `nodebpy` does.
+
+I personally found both of their APIs to _not quite_ fit how I wanted to work, leading to the creation of `nodebpy`.
+In comparison, this project is also the only one that is also distributed on `PyPi` and insallable via `pip` for easier use in other projects.
+
+  - [geometry-script](https://github.com/carson-katri/geometry-script),
+  - [geonodes](https://github.com/al1brn/geonodes)

{nodebpy-0.10.1 → nodebpy-0.11.0}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "nodebpy"
-version = "0.10.1"
+version = "0.11.0"
 description = "Build nodes trees in Blender more elegantly with code"
 readme = "README.md"
 authors = [
     { name = "Brady Johnston", email = "brady.johnston@me.com" }
 ]
-requires-python = ">=3.11"
-dependencies = []
+requires-python = ">=3.13"
+license = { text = "GPL-3.0-or-later" }
 
 [project.scripts]
 nodebpy = "nodebpy:main"
@@ -17,7 +17,7 @@ networkx = [
     "networkx>=3.6.1",
 ]
 bpy = [
-    "bpy>=5.0.1",
+    "bpy>=5.1.0",
 ]
 
 [build-system]
@@ -28,12 +28,11 @@ build-backend = "uv_build"
 dev = [
     "ipython>=8.0.0",
     "networkx>=3.6.1",
-    "numpy<2.0",
     "fake-bpy-module>=20260113",
     "jsondiff>=2.2.1",
     "pytest>=9.0.2",
     "pytest-cov>=7.0.0",
-    "quarto-cli>=1.8.26",
+    "quarto-cli>=1.9",
     "quartodoc>=0.11.1",
     "ruff>=0.14.11",
     "syrupy>=5.0.0",

{nodebpy-0.10.1 → nodebpy-0.11.0}/src/nodebpy/__init__.py

@@ -1,4 +1,4 @@
-from . import nodes, screenshot, sockets
+from . import nodes, diagram, sockets
 from .builder import TreeBuilder, NodeGroupBuilder
 from .nodes import compositor, geometry, shader
 
@@ -8,7 +8,7 @@ __all__ = [
     "geometry",
     "shader",
     "sockets",
-    "screenshot",
+    "diagram",
     "TreeBuilder",
     "NodeGroupBuilder",
 ]

{nodebpy-0.10.1 → nodebpy-0.11.0}/src/nodebpy/builder/__init__.py

@@ -35,6 +35,7 @@ from .socket import (
     CollectionSocket,
     ColorSocket,
     FloatSocket,
+    FontSocket,
     GeometrySocket,
     ImageSocket,
     IntegerSocket,
@@ -93,6 +94,7 @@ __all__ = [
     "MenuSocket",
     "GeometrySocket",
     "ObjectSocket",
+    "FontSocket",
     "MaterialSocket",
     "ImageSocket",
     "CollectionSocket",
@@ -120,6 +122,7 @@ __all__ = [
     "SocketMenu",
     "SocketObject",
     "SocketGeometry",
+    "SocketFont",
     "SocketCollection",
     "SocketImage",
     "SocketMaterial",

{nodebpy-0.10.1 → nodebpy-0.11.0}/src/nodebpy/builder/accessor.py

@@ -1,12 +1,17 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Literal, overload
 
 import bpy
 from bpy.types import NodeSocket
 
 from ._registry import _get_socket_linker
-from ._utils import SocketError, _allow_innactive_sockets, denormalize_name
+from ._utils import (
+    SocketError,
+    _allow_innactive_sockets,
+    denormalize_name,
+    normalize_name,
+)
 
 if TYPE_CHECKING:
     from .socket import Socket
@@ -43,6 +48,10 @@ class SocketAccessor:
         for candidate in (key, denorm):
             if candidate in ids:
                 return ids.index(candidate)
+        # Normalized identifier match: 'value_001' matches identifier 'Value_001'
+        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:
@@ -58,11 +67,24 @@ class SocketAccessor:
             f"{self._node.bl_idname}. Available sockets (id: name): {list(zip(ids, names))}"
         )
 
-    def _get(self, key: str | int) -> "Socket":
+    @overload
+    def _get(self, key: slice) -> "list[Socket]": ...
+    @overload
+    def _get(self, key: str | int) -> "Socket": ...
+    def _get(self, key: str | int | slice) -> "Socket | list[Socket]":
         """Get a Socket for a socket by identifier, name, or index."""
+        if isinstance(key, slice):
+            return [
+                _get_socket_linker(self._collection[i])
+                for i in range(*key.indices(len(self._collection)))
+            ]
         return _get_socket_linker(self._collection[self._index(key)])
 
-    def __getitem__(self, key: str | int) -> "Socket":
+    @overload
+    def __getitem__(self, key: slice) -> "list[Socket]": ...
+    @overload
+    def __getitem__(self, key: str | int) -> "Socket": ...
+    def __getitem__(self, key: str | int | slice) -> "Socket | list[Socket]":
         """Access by identifier, name, or integer index."""
         return self._get(key)
 

{nodebpy-0.10.1 → nodebpy-0.11.0}/src/nodebpy/builder/mixins.py

@@ -1,14 +1,17 @@
 from __future__ import annotations
 
 from types import EllipsisType
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, TypeVar
 
 from bpy.types import NodeLink, NodeSocket
 
 from ._registry import _get_socket_linker
 from ._utils import SocketError, _resolve_promotion, _SocketLike
 
+_RShiftT = TypeVar("_RShiftT")
+
 if TYPE_CHECKING:
+    from ..nodes.geometry import Compare, Math
     from ..types import InputLinkable
     from .node import BaseNode
     from .socket import Socket
@@ -26,7 +29,7 @@ class OperatorMixin:
 
     def _apply_math_operation(
         self, other: Any, operation: str, reverse: bool = False
-    ) -> "BaseNode":
+    ) -> "Math":
         socket, other, reverse = _resolve_promotion(
             self._default_output_socket,
             other,
@@ -34,43 +37,43 @@ class OperatorMixin:
         )
         return _get_socket_linker(socket)._dispatch_math(other, operation, reverse)
 
-    def __mul__(self, other: Any) -> "BaseNode":
+    def __mul__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "multiply")
 
-    def __rmul__(self, other: Any) -> "BaseNode":
+    def __rmul__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "multiply", reverse=True)
 
-    def __truediv__(self, other: Any) -> "BaseNode":
+    def __truediv__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "divide")
 
-    def __rtruediv__(self, other: Any) -> "BaseNode":
+    def __rtruediv__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "divide", reverse=True)
 
-    def __add__(self, other: Any) -> "BaseNode":
+    def __add__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "add")
 
-    def __radd__(self, other: Any) -> "BaseNode":
+    def __radd__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "add", reverse=True)
 
-    def __sub__(self, other: Any) -> "BaseNode":
+    def __sub__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "subtract")
 
-    def __rsub__(self, other: Any) -> "BaseNode":
+    def __rsub__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "subtract", reverse=True)
 
-    def __pow__(self, other: Any) -> "BaseNode":
+    def __pow__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "power")
 
-    def __rpow__(self, other: Any) -> "BaseNode":
+    def __rpow__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "power", reverse=True)
 
-    def __mod__(self, other: Any) -> "BaseNode":
+    def __mod__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "modulo")
 
-    def __rmod__(self, other: Any) -> "BaseNode":
+    def __rmod__(self, other: Any) -> "Math":
         return self._apply_math_operation(other, "modulo", reverse=True)
 
-    def __floordiv__(self, other: Any) -> "BaseNode":
+    def __floordiv__(self, other: Any) -> "Math":
         socket, other, reverse = _resolve_promotion(
             self._default_output_socket,
             other,
@@ -78,7 +81,7 @@ class OperatorMixin:
         )
         return _get_socket_linker(socket)._dispatch_floordiv(other, reverse)
 
-    def __rfloordiv__(self, other: Any) -> "BaseNode":
+    def __rfloordiv__(self, other: Any) -> "Math":
         socket, other, reverse = _resolve_promotion(
             self._default_output_socket,
             other,
@@ -86,37 +89,37 @@ class OperatorMixin:
         )
         return _get_socket_linker(socket)._dispatch_floordiv(other, reverse)
 
-    def __neg__(self) -> "BaseNode":
+    def __neg__(self) -> "Math":
         return _get_socket_linker(self._default_output_socket)._dispatch_unary(  # type: ignore[attr-defined]
             "negate"
         )
 
-    def __abs__(self) -> "BaseNode":
+    def __abs__(self) -> "Math":
         return _get_socket_linker(self._default_output_socket)._dispatch_unary(  # type: ignore[attr-defined]
             "absolute"
         )
 
-    def _apply_compare_operation(self, other: Any, operation: str) -> "BaseNode":
+    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
         )
 
-    def __lt__(self, other: Any) -> "BaseNode":
+    def __lt__(self, other: Any) -> "Compare":
         return self._apply_compare_operation(other, "less_than")
 
-    def __gt__(self, other: Any) -> "BaseNode":
+    def __gt__(self, other: Any) -> "Compare":
         return self._apply_compare_operation(other, "greater_than")
 
-    def __le__(self, other: Any) -> "BaseNode":
+    def __le__(self, other: Any) -> "Compare":
         return self._apply_compare_operation(other, "less_equal")
 
-    def __ge__(self, other: Any) -> "BaseNode":
+    def __ge__(self, other: Any) -> "Compare":
         return self._apply_compare_operation(other, "greater_equal")
 
-    def __eq__(self, other: Any) -> "BaseNode":  # type: ignore[override]
+    def __eq__(self, other: Any) -> "Compare":  # type: ignore[override]
         return self._apply_compare_operation(other, "equal")
 
-    def __ne__(self, other: Any) -> "BaseNode":  # type: ignore[override]
+    def __ne__(self, other: Any) -> "Compare":  # type: ignore[override]
         return self._apply_compare_operation(other, "not_equal")
 
     def _apply_boolean_operation(self, other: Any, operation: str):

{nodebpy-0.10.1 → nodebpy-0.11.0}/src/nodebpy/builder/node.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Iterable, Literal
+from typing import TYPE_CHECKING, Iterable, Literal, Self
 
 import bpy
 from bpy.types import Node, NodeSocket
@@ -25,7 +25,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
     _default_output_id: str | None = None
     _placeholder_inputs: list[str]
 
-    def __init__(self):
+    def __init__(self, node: bpy.types.Node | None = None):
         tree = (
             TreeBuilder._tree_contexts[-1] if len(TreeBuilder._tree_contexts) else None
         )
@@ -39,7 +39,7 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
 
         self._tree = tree
         self._placeholder_inputs = []
-        self.node: bpy.types.Node = self._tree.add(self.__class__._bl_idname)
+        self.node = node if node else self._tree.add(self.__class__._bl_idname)
 
     @property
     def tree(self) -> TreeBuilder:
@@ -71,6 +71,33 @@ class BaseNode(_NodeLike, OperatorMixin, LinkingMixin):
             socket = self.node.outputs[counter]
         return socket
 
+    @classmethod
+    def _from_node(cls, node: bpy.types.Node) -> Self:
+        builder = cls()
+        builder.tree.nodes.remove(builder.node)
+        builder.node = node
+        return builder
+
+    @classmethod
+    def _find_or_create_linked(cls, socket: NodeSocket) -> Self:
+        if socket.is_output:
+            if socket.links:
+                for link in socket.links:
+                    assert link.to_node
+                    if link.to_node.bl_idname == cls._bl_idname:
+                        return cls._from_node(link.to_node)
+            return cls(socket)
+        else:
+            if socket.links:
+                for link in socket.links:
+                    assert link.from_node
+                    if link.from_node.bl_idname == cls._bl_idname:
+                        return cls._from_node(link.from_node)
+
+            node = cls()
+            node >> socket
+            return node
+
     def _set_input_default_value(self, input, value):
         """Set the default value for an input socket, handling type conversions."""
         if (