nodebpy 520.0.1__tar.gz → 520.2.0__tar.gz

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

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

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

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

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

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

nodebpy-520.2.0/src/nodebpy/assets/__init__.py

@@ -0,0 +1,17 @@
+"""Typed APIs for node-group assets.
+
+``generate_asset_api`` builds typed :class:`~nodebpy.builder.AssetNodeGroup`
+classes for the node groups in a ``.blend`` asset library. The bundled-essentials
+APIs generated for nodebpy itself live alongside this module as
+``nodebpy.assets.geometry`` / ``.shader`` / ``.compositor``.
+"""
+
+from ..builder import AssetLibrary, BundledLibrary, PackageLibrary
+from ._codegen import generate_asset_api
+
+__all__ = [
+    "generate_asset_api",
+    "AssetLibrary",
+    "BundledLibrary",
+    "PackageLibrary",
+]

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

@@ -0,0 +1,57 @@
+"""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 os
+from pathlib import Path
+
+from ..builder import BundledLibrary
+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) -> 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")
+        written[tree] = names
+        print(f"  nodes/{tree}/assets.py: {len(names)} asset classes")
+    return written
+
+
+def main() -> None:  # pragma: no cover - CLI wrapper over generate_essentials
+    generate_essentials(Path(__file__).parent.parent / "nodes")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

nodebpy-520.2.0/src/nodebpy/assets/_codegen.py

@@ -0,0 +1,318 @@
+"""Generate typed ``nodebpy`` API classes for node-group assets.
+
+Given one or more asset ``.blend`` libraries, :func:`generate_asset_api` appends
+each node group, introspects its interface, and writes a Python module of typed
+:class:`~nodebpy.builder.AssetNodeGroup` subclasses — so an asset reads and
+type-checks like any other node. The emitted classes append the asset at runtime
+rather than rebuilding it.
+
+This is a *shipped*, reusable tool: other projects call it on their own asset
+libraries (via :class:`~nodebpy.builder.PackageLibrary`) to generate APIs for
+their assets.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import bpy
+
+from ..builder import AssetLibrary, BundledLibrary, asset_group_base
+from ..builder._utils import normalize_name
+
+# bl_socket_type substring → (Socket accessor class, Input* parameter type).
+# Order matters: more specific keys (IntVector before Int) come first.
+_SOCKET_TYPES: dict[str, tuple[str, str]] = {
+    "NodeSocketFloat": ("FloatSocket", "InputFloat"),
+    "NodeSocketIntVector": ("IntegerVectorSocket", "InputIntegerVector"),
+    "NodeSocketInt": ("IntegerSocket", "InputInteger"),
+    "NodeSocketBool": ("BooleanSocket", "InputBoolean"),
+    "NodeSocketVector": ("VectorSocket", "InputVector"),
+    "NodeSocketColor": ("ColorSocket", "InputColor"),
+    "NodeSocketRotation": ("RotationSocket", "InputRotation"),
+    "NodeSocketMatrix": ("MatrixSocket", "InputMatrix"),
+    "NodeSocketString": ("StringSocket", "InputString"),
+    "NodeSocketMenu": ("MenuSocket", "InputMenu"),
+    "NodeSocketGeometry": ("GeometrySocket", "InputGeometry"),
+    "NodeSocketObject": ("ObjectSocket", "InputObject"),
+    "NodeSocketMaterial": ("MaterialSocket", "InputMaterial"),
+    "NodeSocketImage": ("ImageSocket", "InputImage"),
+    "NodeSocketCollection": ("CollectionSocket", "InputCollection"),
+    "NodeSocketBundle": ("BundleSocket", "InputBundle"),
+    "NodeSocketClosure": ("ClosureSocket", "InputClosure"),
+    "NodeSocketShader": ("ShaderSocket", "InputShader"),
+    "NodeSocketFont": ("FontSocket", "InputFont"),
+    "NodeSocketSound": ("SoundSocket", "InputSound"),
+    "NodeSocketVirtual": ("Socket", "InputLinkable"),
+}
+
+
+def _socket_types(bl_socket_type: str) -> tuple[str, str]:
+    for key, value in _SOCKET_TYPES.items():
+        if key in bl_socket_type:
+            return value
+    return ("Socket", "InputLinkable")
+
+
+def _class_name(name: str) -> str:
+    """A valid, readable Python class name for an asset group display name."""
+    cleaned = "".join(c if c.isalnum() or c.isspace() else " " for c in name)
+    parts = cleaned.split()
+    cleaned = "".join(p[:1].upper() + p[1:] for p in parts)
+    if cleaned and cleaned[0].isdigit():
+        cleaned = "_" + cleaned
+    return cleaned or "AssetGroup"
+
+
+def _format_default(socket: bpy.types.NodeSocket) -> str:
+    """Source for a socket's scalar default value, or ``None``.
+
+    Only plain scalars are emitted as parameter defaults. Vector/colour/matrix
+    defaults vary in arity (2D UVs, 3D vectors, 4-component colours) and don't
+    always fit the parameter's ``Input*`` type, so they're left as ``None`` —
+    the appended group keeps its own socket default regardless.
+    """
+    value = getattr(socket, "default_value", None)
+    if isinstance(value, bool):
+        return str(value)
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return str(round(value, 6))
+    if isinstance(value, str):
+        return repr(value)
+    return "None"
+
+
+@dataclass
+class _Socket:
+    name: str
+    identifier: str
+    socket_class: str  # e.g. "GeometrySocket"
+    input_type: str  # e.g. "InputGeometry"
+    default: str  # source for the default value
+    attr: str  # normalized accessor/param name
+
+
+@dataclass
+class _AssetClass:
+    class_name: str
+    asset_name: str
+    description: str
+    library_source: str
+    tree_idname: str
+    inputs: list[_Socket]
+    outputs: list[_Socket]
+
+
+def _collect(sockets) -> list[_Socket]:
+    raw = [
+        s
+        for s in sockets
+        if s.identifier != "__extend__" and not getattr(s, "is_inactive", False)
+    ]
+    # The accessor resolves attribute names by identifier first, then name, so a
+    # group socket's readable name works as the attr/param when it's unambiguous;
+    # fall back to the opaque-but-unique identifier only on a name collision.
+    name_counts = Counter(normalize_name(s.name) for s in raw)
+    out: list[_Socket] = []
+    for s in raw:
+        socket_class, input_type = _socket_types(type(s).__name__)
+        norm_name = normalize_name(s.name)
+        attr = (
+            norm_name if name_counts[norm_name] == 1 else normalize_name(s.identifier)
+        )
+        out.append(
+            _Socket(
+                name=s.name,
+                identifier=s.identifier,
+                socket_class=socket_class,
+                input_type=input_type,
+                default=_format_default(s),
+                attr=attr,
+            )
+        )
+    return out
+
+
+def _introspect(library: AssetLibrary, names: set[str] | None) -> list[_AssetClass]:
+    """Append each requested group from the library and introspect its
+    interface into :class:`_AssetClass` records."""
+    path = library.path()
+    library_source = _library_source(library)
+
+    with bpy.data.libraries.load(path, link=False, assets_only=True) as (src, _):
+        available = list(src.node_groups)
+    wanted = [n for n in available if names is None or n in names]
+
+    classes: list[_AssetClass] = []
+    for name in wanted:
+        # Always append from *this* library — never reuse a same-named group by
+        # global lookup, since names collide across tree types (a geometry and a
+        # 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 (
+            src,
+            dst,
+        ):
+            dst.node_groups = [name]
+        group = dst.node_groups[0]
+
+        host = bpy.data.node_groups.new("_introspect_host", group.bl_idname)
+        try:
+            node_type = {
+                "GeometryNodeTree": "GeometryNodeGroup",
+                "ShaderNodeTree": "ShaderNodeGroup",
+                "CompositorNodeTree": "CompositorNodeGroup",
+            }[group.bl_idname]
+            node = host.nodes.new(node_type)
+            node.node_tree = group
+            classes.append(
+                _AssetClass(
+                    class_name=_class_name(name),
+                    asset_name=name,
+                    description=(group.description or name).strip(),
+                    library_source=library_source,
+                    tree_idname=group.bl_idname,
+                    inputs=_collect(node.inputs),
+                    outputs=_collect(node.outputs),
+                )
+            )
+        finally:
+            bpy.data.node_groups.remove(host)
+    return classes
+
+
+def _library_source(library: AssetLibrary) -> str:
+    """Source expression that reconstructs ``library`` in the generated module."""
+    if isinstance(library, BundledLibrary):
+        return f"BundledLibrary({library.filename!r})"
+    from ..builder import PackageLibrary
+
+    if isinstance(library, PackageLibrary):
+        return f"PackageLibrary(__file__, {library.relative!r})"
+    raise TypeError(f"Cannot serialise asset library: {library!r}")
+
+
+def _accessor(sockets: list[_Socket], kind: str) -> str:
+    if not sockets:
+        return f"    class {kind}(SocketAccessor):\n        pass"
+    lines = [f"    class {kind}(SocketAccessor):"]
+    for s in sockets:
+        lines.append(f"        {s.attr}: {s.socket_class}")
+        doc = s.name
+        if doc and doc != s.attr:
+            lines.append(f'        """{doc}"""')
+    return "\n".join(lines)
+
+
+def _render_class(cls: _AssetClass) -> str:
+    base = asset_group_base(cls.tree_idname).__name__
+    inputs_cls = _accessor(cls.inputs, "_Inputs")
+    outputs_cls = _accessor(cls.outputs, "_Outputs")
+
+    params = [f"{s.attr}: {s.input_type} = {s.default}" for s in cls.inputs]
+    signature = (
+        "(\n        self,\n        " + ",\n        ".join(params) + ",\n    )"
+        if params
+        else "(self)"
+    )
+    key_args = ", ".join(f'"{s.identifier}": {s.attr}' for s in cls.inputs)
+
+    return f'''class {cls.class_name}({base}):
+    """{cls.description}"""
+
+    _name = {cls.asset_name!r}
+    _asset_name = {cls.asset_name!r}
+    _library = {cls.library_source}
+
+{inputs_cls}
+
+{outputs_cls}
+
+    if TYPE_CHECKING:
+        @property
+        def i(self) -> _Inputs: ...
+        @property
+        def o(self) -> _Outputs: ...
+
+    def __init__{signature}:
+        super().__init__(**{{{key_args}}})
+'''
+
+
+def _render_module(classes: list[_AssetClass]) -> str:
+    socket_classes = sorted(
+        {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})
+    bases = sorted({asset_group_base(c.tree_idname).__name__ for c in classes})
+    libraries = sorted(
+        {
+            "BundledLibrary"
+            if c.library_source.startswith("BundledLibrary")
+            else "PackageLibrary"
+            for c in classes
+        }
+    )
+
+    builder_imports = sorted(
+        set(bases) | set(libraries) | {"SocketAccessor"} | set(socket_classes)
+    )
+
+    lines = [
+        "# 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)"
+        if input_types
+        else "",
+    ]
+    header = "\n".join(line for line in lines if line) + "\n\n\n"
+    ordered = sorted(classes, key=lambda c: c.class_name)
+    body = "\n\n".join(_render_class(c) for c in ordered)
+    all_names = ",\n    ".join(f'"{c.class_name}"' for c in ordered)
+    footer = (
+        f"\n\n__all__ = (\n    {all_names},\n)\n" if ordered else "\n__all__ = ()\n"
+    )
+    return header + body + footer
+
+
+def generate_asset_api(
+    libraries: AssetLibrary | Sequence[AssetLibrary],
+    output_path: str | Path,
+    *,
+    names: set[str] | None = None,
+) -> list[str]:
+    """Generate typed asset classes for ``libraries`` into ``output_path``.
+
+    Parameters
+    ----------
+    libraries:
+        One or more :class:`~nodebpy.builder.AssetLibrary` instances
+        (:class:`~nodebpy.builder.BundledLibrary` for Blender's bundled assets,
+        :class:`~nodebpy.builder.PackageLibrary` for a ``.blend`` shipped inside
+        your own package).
+    output_path:
+        The ``.py`` file to write.
+    names:
+        Restrict generation to these asset (node-group) names; defaults to all.
+
+    Returns the list of generated class names.
+    """
+    if isinstance(libraries, AssetLibrary):
+        libraries = [libraries]
+
+    classes: list[_AssetClass] = []
+    for library in libraries:
+        classes.extend(_introspect(library, names))
+
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(_render_module(classes), encoding="utf-8")
+    return [c.class_name for c in classes]

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

@@ -1,5 +1,15 @@
 from ._utils import SocketError, denormalize_name, normalize_name
 from .accessor import SocketAccessor
+from .asset import (
+    AssetCompositorGroup,
+    AssetGeometryGroup,
+    AssetLibrary,
+    AssetShaderGroup,
+    BundledLibrary,
+    PackageLibrary,
+    asset_group_base,
+)
+from .items import Item, ItemsMixin
 from .mixins import LinkingMixin, OperatorMixin
 from .node import (
     BaseNode,
@@ -75,12 +85,21 @@ __all__ = [
     "OperatorMixin",
     "LinkingMixin",
     "DynamicInputsMixin",
+    "Item",
+    "ItemsMixin",
     # Node groups
     "NodeGroupBuilder",
     "CustomCompositorGroup",
     "CustomGeometryGroup",
     "CustomShaderGroup",
-    "CustomShaderGroup",
+    # Asset-backed node groups
+    "AssetLibrary",
+    "BundledLibrary",
+    "PackageLibrary",
+    "AssetGeometryGroup",
+    "AssetShaderGroup",
+    "AssetCompositorGroup",
+    "asset_group_base",
     # Runtime socket types
     "FloatSocket",
     "FloatSocketGrid",

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

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

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

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