nodebpy 520.5.1__tar.gz → 520.6.0__tar.gz

nodebpy-520.6.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.3
+Name: nodebpy
+Version: 520.6.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
+
+[![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)
+
+Build node trees in Blender more elegantly with Python code. Geometry Nodes, Shader Nodes and Compositor nodes are all fully supported, with type hints and IDE auto-completion throughout.
+
+```bash
+pip install nodebpy
+```
+
+> 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)
+
+- Every node is a typed class named after the node it creates — 'Random Value' becomes `g.RandomValue()` — and node subtypes are class methods: `g.RandomValue.vector()`.
+- Trees are built inside a `with g.tree(...):` context; instantiating a node class adds it to the current tree, and the tree's interface is declared with `tree.inputs.*` / `tree.outputs.*`.
+- Nodes are linked with the `>>` operator, which picks the most compatible socket pair automatically (much like Node Wrangler's <kbd>Alt</kbd> + <kbd>Right Click</kbd> drag) — or address sockets explicitly through the `.i.*` / `.o.*` accessors.
+- Python's arithmetic, comparison and boolean operators create the matching `Math` / `VectorMath` / `Compare` / `BooleanMath` nodes: `g.Value(1.0) * 2 + (0, 0, 1)`.
+- Existing node trees — including ones wired up by hand in the GUI — can be exported back to `nodebpy` source with `to_python()`.
+
+## Documentation
+
+Guides and the full node reference live at [bradyajohnston.github.io/nodebpy](https://bradyajohnston.github.io/nodebpy):
+
+- [Writing node trees](https://bradyajohnston.github.io/nodebpy/introduction.html) — adding, linking and organising nodes
+- [Math operators](https://bradyajohnston.github.io/nodebpy/operators.html) — arithmetic, comparison and boolean expressions as nodes
+- [Node API design](https://bradyajohnston.github.io/nodebpy/node-api.html) — sockets, accessors, enum options and class methods
+- [Custom node groups](https://bradyajohnston.github.io/nodebpy/custom-node-groups.html) and [asset node groups](https://bradyajohnston.github.io/nodebpy/assets.html) — reusable groups as Python classes
+- [Nodes to code](https://bradyajohnston.github.io/nodebpy/nodes-to-code.html) — turn existing trees back into `nodebpy` code
+- [Using `nodebpy` in your add-on](https://bradyajohnston.github.io/nodebpy/using.html) — installation, bundling and the Blender-tracking versioning scheme
+- [Comparisons](https://bradyajohnston.github.io/nodebpy/comparisons.html) — how the API relates to [`geometry-script`](https://github.com/carson-katri/geometry-script), [`geonodes`](https://github.com/al1brn/geonodes), [NodeToPython](https://github.com/BrendanParmer/NodeToPython) and [TreeClipper](https://github.com/Algebraic-UG/tree_clipper)
+
+Like [`databpy`](https://github.com/BradyAJohnston/databpy), this project started as an internal tool inside [`molecularnodes`](https://github.com/BradyAJohnston/MolecularNodes) before being broken out into its own robustly typed and tested package.
+
+## Contributing
+
+Development setup, running the tests and regenerating the node classes (most of `src/nodebpy/nodes/` is auto-generated by the `gen/` package) are covered in [CONTRIBUTING.md](CONTRIBUTING.md).

nodebpy-520.6.0/README.md

@@ -0,0 +1,63 @@
+# 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)
+
+Build node trees in Blender more elegantly with Python code. Geometry Nodes, Shader Nodes and Compositor nodes are all fully supported, with type hints and IDE auto-completion throughout.
+
+```bash
+pip install nodebpy
+```
+
+> 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)
+
+- Every node is a typed class named after the node it creates — 'Random Value' becomes `g.RandomValue()` — and node subtypes are class methods: `g.RandomValue.vector()`.
+- Trees are built inside a `with g.tree(...):` context; instantiating a node class adds it to the current tree, and the tree's interface is declared with `tree.inputs.*` / `tree.outputs.*`.
+- Nodes are linked with the `>>` operator, which picks the most compatible socket pair automatically (much like Node Wrangler's <kbd>Alt</kbd> + <kbd>Right Click</kbd> drag) — or address sockets explicitly through the `.i.*` / `.o.*` accessors.
+- Python's arithmetic, comparison and boolean operators create the matching `Math` / `VectorMath` / `Compare` / `BooleanMath` nodes: `g.Value(1.0) * 2 + (0, 0, 1)`.
+- Existing node trees — including ones wired up by hand in the GUI — can be exported back to `nodebpy` source with `to_python()`.
+
+## Documentation
+
+Guides and the full node reference live at [bradyajohnston.github.io/nodebpy](https://bradyajohnston.github.io/nodebpy):
+
+- [Writing node trees](https://bradyajohnston.github.io/nodebpy/introduction.html) — adding, linking and organising nodes
+- [Math operators](https://bradyajohnston.github.io/nodebpy/operators.html) — arithmetic, comparison and boolean expressions as nodes
+- [Node API design](https://bradyajohnston.github.io/nodebpy/node-api.html) — sockets, accessors, enum options and class methods
+- [Custom node groups](https://bradyajohnston.github.io/nodebpy/custom-node-groups.html) and [asset node groups](https://bradyajohnston.github.io/nodebpy/assets.html) — reusable groups as Python classes
+- [Nodes to code](https://bradyajohnston.github.io/nodebpy/nodes-to-code.html) — turn existing trees back into `nodebpy` code
+- [Using `nodebpy` in your add-on](https://bradyajohnston.github.io/nodebpy/using.html) — installation, bundling and the Blender-tracking versioning scheme
+- [Comparisons](https://bradyajohnston.github.io/nodebpy/comparisons.html) — how the API relates to [`geometry-script`](https://github.com/carson-katri/geometry-script), [`geonodes`](https://github.com/al1brn/geonodes), [NodeToPython](https://github.com/BrendanParmer/NodeToPython) and [TreeClipper](https://github.com/Algebraic-UG/tree_clipper)
+
+Like [`databpy`](https://github.com/BradyAJohnston/databpy), this project started as an internal tool inside [`molecularnodes`](https://github.com/BradyAJohnston/MolecularNodes) before being broken out into its own robustly typed and tested package.
+
+## Contributing
+
+Development setup, running the tests and regenerating the node classes (most of `src/nodebpy/nodes/` is auto-generated by the `gen/` package) are covered in [CONTRIBUTING.md](CONTRIBUTING.md).

{nodebpy-520.5.1 → nodebpy-520.6.0}/pyproject.toml

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

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/builder/tree.py

@@ -15,6 +15,7 @@ from bpy.types import (
     ShaderNodeTree,
 )
 
+
 from ..types import (
     SOCKET_COMPATIBILITY,
     FloatInterfaceSubtypes,
@@ -856,7 +857,7 @@ class TreeBuilder(Generic[_TreeT]):
         Mermaid ``_repr_markdown_`` fallback take over.
         """
         try:
-            from ..web_render import to_web_render_html
+            from ..export import to_web_render_html
 
             return to_web_render_html(self)
         except Exception as e:

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/export/__init__.py

@@ -1,7 +1,9 @@
 from .codegen import to_python
 from .diagram import to_mermaid
+from .web_render import to_web_render_html
 
 __all__ = [
     "to_python",
     "to_mermaid",
+    "to_web_render_html",
 ]

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/export/codegen.py

@@ -1389,7 +1389,7 @@ def _non_default_props(node, cls: type) -> dict[str, Any]:
 # (``Compare.float.less_than``). Parsing those bodies at runtime yields a
 # reverse table from node state to factory path, so generated code uses the
 # same idiomatic spellings users write — with no separate table to keep in
-# sync with generate.py. Factories whose bodies are not statically analysable
+# sync with the generator. Factories whose bodies are not statically analysable
 # (positional args, helper indirection, **kwargs) are simply skipped and the
 # node falls back to the plain constructor.
 # ---------------------------------------------------------------------------
@@ -3665,6 +3665,22 @@ def _emit_tree(node_tree, collector: "_GroupCollector") -> "_TreeEmission":
 # ---------------------------------------------------------------------------
 
 
+@register_emitter("ShaderNodeValue")
+def _emit_value(node, ctx: EmitContext) -> Call:
+    """Preserve the Value node's output-backed constructor argument.
+
+    Unlike ordinary node inputs, ``ShaderNodeValue`` stores its editable value
+    directly on its output socket. The generic constructor path only examines
+    input sockets, so a non-zero value needs to be supplied explicitly.
+    """
+    call = ctx.constructor(node)
+    if node.outputs:
+        value = node.outputs[0].default_value
+        if not _eq(value, 0.0):
+            call.args.append(Lit(value))
+    return call
+
+
 _COMPARE_LIFT = {
     "LESS_THAN": "<",
     "GREATER_THAN": ">",

{nodebpy-520.5.1/src/nodebpy → nodebpy-520.6.0/src/nodebpy/export}/web_render.py

@@ -19,7 +19,7 @@ import uuid
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from .builder.tree import TreeBuilder
+    from ..builder.tree import TreeBuilder
 
 #: geonodes-web-render version served from the CDN. A semver range (`"0.3"`)
 #: lets esm.sh serve the latest matching patch, so web-render bug fixes ship to

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/_mixins.py

@@ -1,8 +1,8 @@
 """Hand-written mixins attached to auto-generated node classes.
 
 These hold reusable behaviour that the code generator cannot derive on its own
-(ergonomic flag accessors, items helpers, …). ``generate.py`` wires them onto
-the generated classes via :class:`~generate.NodeCustomization`, so the bulky
+(ergonomic flag accessors, items helpers, …). The ``gen`` package wires them
+onto the generated classes via :class:`~gen.NodeCustomization`, so the bulky
 boilerplate (sockets, docstrings, property accessors) stays generated while the
 bespoke behaviour lives here.
 """

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/__init__.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from .manual import (
     MenuSwitch,

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/color.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING, Literal
 

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/converter.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING, Generic, Literal
 

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/distort.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING, Literal
 

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/filter.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING, Literal
 

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/group.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING
 

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/input.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING, Literal
 

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/interface.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING, Generic, Literal
 

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/matte.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING, Literal
 

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/output.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING
 

{nodebpy-520.5.1 → nodebpy-520.6.0}/src/nodebpy/nodes/compositor/vector.py

@@ -1,4 +1,4 @@
-# Auto-generated by generate.py — do not edit manually.
+# Auto-generated by `python -m gen` — do not edit manually.
 
 from typing import TYPE_CHECKING