nodebpy 520.2.0__tar.gz → 520.4.0__tar.gz

{nodebpy-520.2.0 → nodebpy-520.4.0}/PKG-INFO

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

{nodebpy-520.2.0 → nodebpy-520.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nodebpy"
-version = "520.2.0"
+version = "520.4.0"
 description = "Build nodes trees in Blender more elegantly with code"
 readme = "README.md"
 authors = [
@@ -42,5 +42,5 @@ dev = [
     "syrupy>=5.0.0",
     "pytest-xdist>=3.8.0",
     "griffe<2.0.0",
-    "ty>=0.0.35",
+    "ty==0.0.51",
 ]

{nodebpy-520.2.0 → nodebpy-520.4.0}/src/nodebpy/__init__.py

@@ -1,4 +1,4 @@
-from . import export, nodes
+from . import builder, export, nodes, types
 from .builder import TreeBuilder
 from .nodes import compositor, geometry, shader
 
@@ -8,5 +8,7 @@ __all__ = [
     "geometry",
     "shader",
     "export",
+    "types",
+    "builder",
     "TreeBuilder",
 ]

nodebpy-520.4.0/src/nodebpy/assets/__main__.py

@@ -0,0 +1,113 @@
+"""Regenerate the bundled-essentials asset APIs.
+
+``python -m nodebpy.assets`` introspects Blender's bundled node-group asset
+libraries and writes typed classes to ``nodebpy/nodes/{geometry,shader,
+compositor}/assets.py``, where ``python -m gen`` re-exports them so they are
+available alongside the built-in nodes (e.g. ``g.SmoothByAngle()``). Run *before*
+``python -m gen`` and through the ruff/ty post-processing (see the Makefile).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from ..builder import BundledLibrary, PackageLibrary
+from ._codegen import generate_asset_api
+
+# Bundled libraries shipped with Blender, grouped by output module. Each library
+# holds node groups of a single tree type.
+_ESSENTIALS: dict[str, tuple[str, ...]] = {
+    "geometry": (
+        "geometry_nodes_essentials.blend",
+        "geometry_nodes_dynamics_assets.blend",
+        "procedural_hair_node_assets.blend",
+        "principal_components.blend",
+    ),
+    "shader": ("shading_nodes_essentials.blend",),
+    "compositor": ("compositing_nodes_essentials.blend",),
+}
+
+
+def generate_essentials(
+    nodes_dir: Path, nodebpy_pkg: str = ".."
+) -> dict[str, list[str]]:
+    """Generate the bundled-essentials asset modules into
+    ``<nodes_dir>/<tree>/assets.py``; returns the class names written per tree
+    (libraries not present in this Blender install are skipped)."""
+    written: dict[str, list[str]] = {}
+    for tree, filenames in _ESSENTIALS.items():
+        libraries = [
+            BundledLibrary(f)
+            for f in filenames
+            if os.path.exists(BundledLibrary(f).path())
+        ]
+        if not libraries:  # pragma: no cover - depends on the Blender install
+            print(f"  {tree}: no bundled libraries present, skipping")
+            continue
+        names = generate_asset_api(
+            libraries,
+            Path(nodes_dir) / tree / "assets.py",
+            nodebpy_pkg=nodebpy_pkg,
+        )
+        written[tree] = names
+        print(f"  nodes/{tree}/assets.py: {len(names)} asset classes")
+    return written
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--blend-file",
+        "-b",
+        type=Path,
+        help="Optional custom .blend asset library to generate from.",
+    )
+    parser.add_argument(
+        "--output",
+        "--output-dir",
+        "-o",
+        dest="output",
+        type=Path,
+        help="Path of the assets.py module to write.",
+    )
+    parser.add_argument(
+        "--nodebpy-pkg",
+        default="nodebpy",
+        help=(
+            "Import anchor for nodebpy in the generated module. Defaults to the "
+            "absolute 'nodebpy'. When nodebpy is vendored inside another package, "
+            "pass the path that reaches it relative to the generated module's "
+            "package — e.g. '..lib.nodebpy'."
+        ),
+    )
+    return parser.parse_args()
+
+
+def main() -> None:  # pragma: no cover - CLI wrapper
+    args = parse_args()
+    output = (
+        args.output
+        if args.output
+        else Path(__file__).parent.parent / "nodes" / "custom" / "assets.py"
+    )
+
+    if args.blend_file is not None:
+        # PackageLibrary resolves ``relative`` against the generated module's
+        # directory (``__file__``), so express the .blend relative to the output
+        # module — not the CWD the command happened to run from.
+        blend = args.blend_file.resolve()
+        relative = Path(os.path.relpath(blend, output.resolve().parent)).as_posix()
+        generate_asset_api(
+            [PackageLibrary(str(output), relative)],
+            output,
+            nodebpy_pkg=args.nodebpy_pkg,
+        )
+        return
+
+    generate_essentials(Path(__file__).parent.parent / "nodes")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

{nodebpy-520.2.0 → nodebpy-520.4.0}/src/nodebpy/assets/_codegen.py

@@ -144,7 +144,7 @@ def _introspect(library: AssetLibrary, names: set[str] | None) -> list[_AssetCla
     path = library.path()
     library_source = _library_source(library)
 
-    with bpy.data.libraries.load(path, link=False, assets_only=True) as (src, _):
+    with bpy.data.libraries.load(path, link=False, assets_only=True) as (src, _):  # ty: ignore[invalid-context-manager]
         available = list(src.node_groups)
     wanted = [n for n in available if names is None or n in names]
 
@@ -155,7 +155,7 @@ def _introspect(library: AssetLibrary, names: set[str] | None) -> list[_AssetCla
         # compositor "Combine Spherical" both exist) and we'd introspect the
         # wrong one. Blender renames the appended copy on a clash; that's fine,
         # we only read its interface (the emitted _asset_name uses the original).
-        with bpy.data.libraries.load(path, link=False, assets_only=True) as (
+        with bpy.data.libraries.load(path, link=False, assets_only=True) as (  # ty: ignore[invalid-context-manager]
             src,
             dst,
         ):
@@ -170,7 +170,7 @@ def _introspect(library: AssetLibrary, names: set[str] | None) -> list[_AssetCla
                 "CompositorNodeTree": "CompositorNodeGroup",
             }[group.bl_idname]
             node = host.nodes.new(node_type)
-            node.node_tree = group
+            node.node_tree = group  # ty: ignore[unresolved-attribute]
             classes.append(
                 _AssetClass(
                     class_name=_class_name(name),
@@ -194,7 +194,11 @@ def _library_source(library: AssetLibrary) -> str:
     from ..builder import PackageLibrary
 
     if isinstance(library, PackageLibrary):
-        return f"PackageLibrary(__file__, {library.relative!r})"
+        # Emit a plain forward-slash string literal (never ``PosixPath(...)``),
+        # so the generated module imports cleanly and stays cross-platform even
+        # when ``relative`` was passed as a ``Path``.
+        relative = Path(library.relative).as_posix()
+        return f"PackageLibrary(__file__, {relative!r})"
     raise TypeError(f"Cannot serialise asset library: {library!r}")
 
 
@@ -245,7 +249,7 @@ def _render_class(cls: _AssetClass) -> str:
 '''
 
 
-def _render_module(classes: list[_AssetClass]) -> str:
+def _render_module(classes: list[_AssetClass], nodebpy_pkg: str = "nodebpy") -> str:
     socket_classes = sorted(
         {s.socket_class for c in classes for s in c.inputs + c.outputs}
     )
@@ -268,8 +272,8 @@ def _render_module(classes: list[_AssetClass]) -> str:
         "# Auto-generated by nodebpy.assets.generate_asset_api — do not edit manually.",
         "from typing import TYPE_CHECKING",
         "",
-        f"from nodebpy.builder import (\n    {',\n    '.join(builder_imports)},\n)",
-        f"from nodebpy.types import (\n    {',\n    '.join(input_types)},\n)"
+        f"from {nodebpy_pkg}.builder import (\n    {',\n    '.join(builder_imports)},\n)",
+        f"from {nodebpy_pkg}.types import (\n    {',\n    '.join(input_types)},\n)"
         if input_types
         else "",
     ]
@@ -288,6 +292,7 @@ def generate_asset_api(
     output_path: str | Path,
     *,
     names: set[str] | None = None,
+    nodebpy_pkg: str = "nodebpy",
 ) -> list[str]:
     """Generate typed asset classes for ``libraries`` into ``output_path``.
 
@@ -302,6 +307,12 @@ def generate_asset_api(
         The ``.py`` file to write.
     names:
         Restrict generation to these asset (node-group) names; defaults to all.
+    nodebpy_pkg:
+        Import anchor for nodebpy in the generated module. Defaults to the
+        absolute ``"nodebpy"``. When nodebpy is vendored inside another package,
+        pass the path that reaches it *relative to the generated module's
+        package* — e.g. ``"..vendor.nodebpy"`` — so the emitted imports stay
+        relative to the install/vendor location.
 
     Returns the list of generated class names.
     """
@@ -314,5 +325,7 @@ def generate_asset_api(
 
     output_path = Path(output_path)
     output_path.parent.mkdir(parents=True, exist_ok=True)
-    output_path.write_text(_render_module(classes), encoding="utf-8")
+    output_path.write_text(
+        _render_module(classes, nodebpy_pkg=nodebpy_pkg), encoding="utf-8"
+    )
     return [c.class_name for c in classes]

{nodebpy-520.2.0 → nodebpy-520.4.0}/src/nodebpy/builder/_utils.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import keyword
+import re
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 import bpy
@@ -34,9 +36,21 @@ GEO_NODE_NAMES = (
 )
 
 
+_NON_IDENTIFIER = re.compile(r"[^0-9a-z]+")
+
+
 def normalize_name(name: str) -> str:
-    """Convert 'Geometry' or 'My Socket' to 'geometry' or 'my_socket'."""
-    return name.lower().replace(" ", "_").replace("é", "e")
+    """Convert 'Geometry' or 'My Socket' to a valid lower-case Python identifier
+    ('geometry', 'my_socket'). Spaces, punctuation and other non-identifier
+    characters (e.g. the '⟂'/'(' in 'BA⟂(BC)') collapse to underscores so the
+    result is always usable as an attribute or parameter name."""
+    text = name.lower().replace("é", "e")
+    cleaned = _NON_IDENTIFIER.sub("_", text).strip("_")
+    if cleaned and cleaned[0].isdigit():
+        cleaned = "_" + cleaned
+    if keyword.iskeyword(cleaned):
+        cleaned += "_"
+    return cleaned or "_"
 
 
 def denormalize_name(attr_name: str) -> str:

{nodebpy-520.2.0 → nodebpy-520.4.0}/src/nodebpy/builder/asset.py

@@ -93,7 +93,7 @@ class _AssetGroupMixin:
         path = cls._library.path()
         if not os.path.exists(path):
             raise FileNotFoundError(f"Asset library not found: {path}")
-        with bpy.data.libraries.load(path, link=False, assets_only=True) as (src, dst):
+        with bpy.data.libraries.load(path, link=False, assets_only=True) as (src, dst):  # ty: ignore[invalid-context-manager]
             if cls._asset_name not in src.node_groups:
                 raise KeyError(f"Node group {cls._asset_name!r} not found in {path}")
             dst.node_groups = [cls._asset_name]

{nodebpy-520.2.0 → nodebpy-520.4.0}/src/nodebpy/builder/mixins.py

@@ -367,7 +367,11 @@ class LinkingMixin:
         else:
             self._link(source, input)
 
-    def __rshift__(self, other: _RShiftT) -> _RShiftT:
+    @overload
+    def __rshift__(self, other: None) -> Self: ...
+    @overload
+    def __rshift__(self, other: _RShiftT) -> _RShiftT: ...
+    def __rshift__(self, other: _RShiftT | None) -> _RShiftT | Self:
         """Chain nodes using >> operator. Links output to input.
 
         Usage:
@@ -377,8 +381,14 @@ class LinkingMixin:
         If the target node has an ellipsis placeholder (...), links to that specific input.
         Otherwise, finds the best compatible socket pair based on type compatibility.
 
-        Returns the right-hand node to enable continued chaining.
+        Returns the right-hand node to enable continued chaining. A ``None``
+        target is a no-op passthrough — nothing is linked and ``self`` is
+        returned so an optional node can be conditionally skipped::
+
+            src >> SetPosition() >> (Transform() if trans else None) >> out
         """
+        if other is None:
+            return self
         if isinstance(other, _SocketLike):
             source = self._default_output_socket
             target = other.socket

{nodebpy-520.2.0 → nodebpy-520.4.0}/src/nodebpy/builder/socket.py

@@ -472,7 +472,9 @@ class _FloatGridOperatorMixin(Socket):
         """Generate a mesh on the "surface" of a volume grid."""
         from ..nodes.geometry import GridToMesh
 
-        return GridToMesh(self.socket).o.mesh
+        return GridToMesh(
+            self.socket, threshold=threshold, adaptivity=adaptivity
+        ).o.mesh
 
 
 class _VectorGridOperatorMixin(Socket):
@@ -675,7 +677,6 @@ class _AccumulateField(_EvaluateField[_T]):
     def _accumulate(
         self, output: Literal["leading", "trailing", "total"], group_index: InputInteger
     ) -> "_T":
-
         from ..nodes.geometry import AccumulateField
 
         node = getattr(
@@ -1504,16 +1505,91 @@ class _FloatMixin(BaseSocket, Generic[_IntegerResult]):
 
         return Clamp.min_max(self.socket, min, max).o.result  # ty: ignore[invalid-return-type]
 
+    def min(self, value: InputFloat = 0.0) -> Self:
+        """Create Math with operation 'Minimum'. The minimum from self and value"""
+        self._assert_output("min")
+        return self._math.minimum(self.socket, value).o.value  # ty: ignore[invalid-return-type]
+
+    def max(self, value: InputFloat = 1.0) -> Self:
+        """Create Math with operation 'Maximum'. The maximum from self and value"""
+        self._assert_output("max")
+        return self._math.maximum(self.socket, value).o.value  # ty: ignore[invalid-return-type]
+
+    def sin(self) -> Self:
+        "Create a Math node with operation 'Sine'. The sine of self"
+        self._assert_output("sin")
+        return self._math.sine(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def cos(self) -> Self:
+        "Create a Math node with operation 'Cosine'. The cosine of self"
+        self._assert_output("cos")
+        return self._math.cosine(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def tan(self) -> Self:
+        "Create a Math node with operation 'Tangent'. The tangent of self"
+        self._assert_output("tan")
+        return self._math.tangent(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def asin(self) -> Self:
+        "Create a Math node with operation 'ArcSine'. The arcsine of self"
+        self._assert_output("asin")
+        return self._math.arcsine(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def acos(self) -> Self:
+        "Create a Math node with operation 'ArcCosine'. The arccosine of self"
+        self._assert_output("acos")
+        return self._math.arccosine(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def atan(self) -> Self:
+        "Create a Math node with operation 'ArcTangent'. The arctangent of self"
+        self._assert_output("atan")
+        return self._math.arctangent(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def sinh(self) -> Self:
+        "Create a Math node with operation 'Hyperbolic Sine'. The hyperbolic sine of self"
+        self._assert_output("sinh")
+        return self._math.hyperbolic_sine(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def cosh(self) -> Self:
+        "Create a Math node with operation 'Hyperbolic Cosine'. The hyperbolic cosine of self"
+        self._assert_output("cosh")
+        return self._math.hyperbolic_cosine(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def tanh(self) -> Self:
+        "Create a Math node with operation 'Hyperbolic Tangent'. The hyperbolic tangent of self"
+        self._assert_output("tanh")
+        return self._math.hyperbolic_tangent(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def exp(self) -> Self:
+        "Create a Math node with operation 'Exponent'. The exponent of self"
+        self._assert_output("exp")
+        return self._math.exponent(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def snap(self, increment: InputFloat = 0.5) -> Self:
+        "Create a Math node with operation 'Snap'. The snap of self"
+        self._assert_output("snap")
+        return self._math.snap(self.socket, increment).o.value  # ty: ignore[invalid-return-type]
+
+    def atan2(self, value: InputFloat = 0.5) -> Self:
+        "Create a Math node with operation 'ArcTan2'. The arctangent of self"
+        self._assert_output("atan2")
+        return self._math.arctan2(self.socket, value).o.value  # ty: ignore[invalid-return-type]
+
     def sqrt(self) -> Self:
         """Return the square root of this value."""
         self._assert_output("sqrt")
         return self._math.square_root(self.socket).o.value  # ty: ignore[invalid-return-type]
 
-    def power(self, exponent: InputFloat) -> Self:
+    def power(self, exponent: InputFloat = 2.0) -> Self:
         """Raise this value to *exponent*."""
         self._assert_output("power")
         return self._math.power(self.socket, exponent).o.value  # ty: ignore[invalid-return-type]
 
+    def log(self, base: InputFloat = 2.0) -> Self:
+        """Return the logarithm of this value to *base*."""
+        self._assert_output("log")
+        return self._math.logarithm(self.socket, base).o.value  # ty: ignore[invalid-return-type]
+
     def floor(self) -> Self:
         """Round down to the nearest integer."""
         self._assert_output("floor")
@@ -1524,23 +1600,48 @@ class _FloatMixin(BaseSocket, Generic[_IntegerResult]):
         self._assert_output("ceil")
         return self._math.ceil(self.socket).o.value  # ty: ignore[invalid-return-type]
 
+    def truncate(self) -> Self:
+        """The integer part of of the value, removing fractional digits"""
+        self._assert_output("truncate")
+        return self._math.truncate(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def fraction(self) -> Self:
+        """The fractional part of the vlaue"""
+        self._assert_output("fraction")
+        return self._math.fraction(self.socket).o.value  # ty: ignore[invalid-return-type]
+
     def round(self) -> Self:
         """Round to the nearest integer."""
         self._assert_output("round")
         return self._math.round(self.socket).o.value  # ty: ignore[invalid-return-type]
 
+    def ping_pong(self, value: InputFloat = 1.0) -> Self:
+        """Input ping-pongs between 0 and *value*."""
+        self._assert_output("ping_pong")
+        return self._math.ping_pong(self.socket, value).o.value  # ty: ignore[invalid-return-type]
+
     def modulo(self, divisor: InputFloat) -> Self:
         """Floored modulo — remainder after dividing by *divisor*, always non-negative."""
         self._assert_output("modulo")
         return self._math.floored_modulo(self.socket, divisor).o.value  # ty: ignore[invalid-return-type]
 
-    def wrap(self, min: InputFloat, max: InputFloat) -> Self:
+    def abs(self) -> Self:
+        """Absolute value of the input"""
+        self._assert_output("abs")
+        return self._math.absolute(self.socket).o.value  # ty: ignore[invalid-return-type]
+
+    def wrap(self, min: InputFloat = 0.0, max: InputFloat = 1.0) -> Self:
         """Wrap the value into the *[min, max]* range, repeating cyclically."""
         self._assert_output("wrap")
         # the wrap method has different order of arguments with max being first
         # compared to other nodes that are defined.
         return self._math.wrap(self.socket, value_001=max, value_002=min).o.value  # ty: ignore[invalid-return-type]
 
+    def mul_add(self, multiplier: InputFloat = 0.5, addend: InputFloat = 0.5) -> Self:
+        """Multiply and then add a value. More efficient as it is a single CPU instruction."""
+        self._assert_output("mul_add")
+        return self._math.multiply_add(self.socket, multiplier, addend).o.value  # ty: ignore[invalid-return-type]
+
     def to_radians(self) -> Self:
         """Convert degrees to radians."""
         self._assert_output("to_radians")
@@ -1602,6 +1703,16 @@ class _IntegerMixin(BaseSocket, Generic[_FloatResult]):
         self._assert_output("negate")
         return self._imath.negate(self.socket).o.value  # ty: ignore[invalid-return-type]
 
+    def mul_add(self, multiplier: InputInteger = 0, addend: InputInteger = 0) -> Self:
+        "Multiply and then add a value. More efficient as it is a single CPU instruction."
+        self._assert_output("mul_add")
+        return self._imath.multiply_add(self.socket, multiplier, addend).o.value  # ty: ignore[invalid-return-type]
+
+    def power(self, exponent: InputInteger = 2) -> Self:
+        """Raise this value to *exponent*."""
+        self._assert_output("power")
+        return self._imath.power(self.socket, exponent).o.value  # ty: ignore[invalid-return-type]
+
     @staticmethod
     def _is_integer_socket(value: Any) -> bool:
         socket = getattr(

{nodebpy-520.2.0 → nodebpy-520.4.0}/src/nodebpy/builder/tree.py

@@ -629,7 +629,7 @@ class TreeBuilder(Generic[_TreeT]):
         ignore_visibility: bool = False,
     ):
         if isinstance(tree, str):
-            self.tree = bpy.data.node_groups.new(tree, tree_type)  # type: ignore[assignment]
+            self.tree = bpy.data.node_groups.new(tree, tree_type)  # ty: ignore[invalid-assignment]
         else:
             self.tree = tree  # type: ignore
 
@@ -725,6 +725,7 @@ class TreeBuilder(Generic[_TreeT]):
         keep_reroutes: bool = False,
         top_level: Literal["with", "class"] = "with",
         format: bool = True,
+        nodebpy_pkg: str = "nodebpy",
     ) -> str:
         """Generate Python source that recreates this tree using nodebpy.
 
@@ -741,6 +742,7 @@ class TreeBuilder(Generic[_TreeT]):
             keep_reroutes=keep_reroutes,
             top_level=top_level,
             format=format,
+            nodebpy_pkg=nodebpy_pkg,
         )
 
     def to_mermaid(self, fenced: bool = True) -> str: