nodebpy 520.1.0__tar.gz → 520.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nodebpy
-Version: 520.1.0
+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>

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

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

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.1.0 → nodebpy-520.2.0}/src/nodebpy/builder/__init__.py

@@ -1,5 +1,14 @@
 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 (
@@ -83,7 +92,14 @@ __all__ = [
     "CustomCompositorGroup",
     "CustomGeometryGroup",
     "CustomShaderGroup",
-    "CustomShaderGroup",
+    # Asset-backed node groups
+    "AssetLibrary",
+    "BundledLibrary",
+    "PackageLibrary",
+    "AssetGeometryGroup",
+    "AssetShaderGroup",
+    "AssetCompositorGroup",
+    "asset_group_base",
     # Runtime socket types
     "FloatSocket",
     "FloatSocketGrid",

nodebpy-520.2.0/src/nodebpy/builder/asset.py

@@ -0,0 +1,139 @@
+"""Asset-backed node groups.
+
+An :class:`AssetNodeGroup` behaves like a :class:`NodeGroupBuilder`, but instead
+of *building* its inner tree it **appends** a named node group from a ``.blend``
+asset library and points a Group node at it. Subclasses (typically generated by
+:func:`nodebpy.assets.generate_asset_api`) declare the library + asset name and a
+typed interface, so an asset reads and type-checks like any other node.
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+import bpy
+
+from .node import (
+    CustomCompositorGroup,
+    CustomGeometryGroup,
+    CustomShaderGroup,
+)
+
+
+class AssetLibrary(ABC):
+    """Locates a ``.blend`` asset library on disk at runtime."""
+
+    @abstractmethod
+    def path(self) -> str:
+        """Absolute path to the ``.blend`` file."""
+        ...
+
+
+class BundledLibrary(AssetLibrary):
+    """A node-group asset library shipped with Blender itself, under the system
+    datafiles (``…/datafiles/assets/nodes/<filename>``) — e.g. the
+    ``geometry_nodes_essentials.blend`` essentials library."""
+
+    def __init__(self, filename: str):
+        self.filename = filename
+
+    def path(self) -> str:
+        nodes_dir = os.path.join(
+            bpy.utils.system_resource("DATAFILES"),  # ty: ignore[unresolved-attribute]
+            "assets",
+            "nodes",
+        )
+        return os.path.join(nodes_dir, self.filename)
+
+
+class PackageLibrary(AssetLibrary):
+    """A ``.blend`` shipped inside a Python package, located relative to a module
+    file. Pass ``anchor=__file__`` from the generated module and the path to the
+    ``.blend`` relative to it::
+
+        PackageLibrary(__file__, "../data/my_assets.blend")
+    """
+
+    def __init__(self, anchor: str, relative: str):
+        self.anchor = anchor
+        self.relative = relative
+
+    def path(self) -> str:
+        return str((Path(self.anchor).parent / self.relative).resolve())
+
+
+class _AssetGroupMixin:
+    """Mixin that turns a ``Custom*Group`` into an asset-backed group: it appends
+    ``_asset_name`` from ``_library`` (reusing an already-appended group of that
+    name) rather than building the tree."""
+
+    _library: AssetLibrary
+    _asset_name: str
+    _tree_idname: str  # provided by the Custom*Group this is mixed into
+
+    def _build_group(self, tree) -> None:  # pragma: no cover - never called
+        raise NotImplementedError(
+            "Asset groups are appended from a library, not built."
+        )
+
+    @classmethod
+    def create_group(cls):
+        """Append the named asset group from the library and return its tree,
+        reusing a previously-appended group of the same name and tree type.
+
+        The tree-type check matters because asset names collide across editors
+        (a geometry and a compositor "Combine Spherical" both exist); reusing by
+        name alone could hand back a group of the wrong type.
+        """
+        existing = bpy.data.node_groups.get(cls._asset_name)
+        if existing is not None and existing.bl_idname == cls._tree_idname:
+            return existing
+        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):
+            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]
+        return dst.node_groups[0]
+
+
+class AssetGeometryGroup(_AssetGroupMixin, CustomGeometryGroup):
+    """A Geometry Nodes group appended from an asset library."""
+
+
+class AssetShaderGroup(_AssetGroupMixin, CustomShaderGroup):
+    """A Shader node group appended from an asset library."""
+
+
+class AssetCompositorGroup(_AssetGroupMixin, CustomCompositorGroup):
+    """A Compositor node group appended from an asset library."""
+
+
+_ASSET_GROUP_BASE = {
+    "GeometryNodeTree": AssetGeometryGroup,
+    "ShaderNodeTree": AssetShaderGroup,
+    "CompositorNodeTree": AssetCompositorGroup,
+}
+
+
+def asset_group_base(tree_idname: str) -> type:
+    """The ``Asset*Group`` base class for a tree-type bl_idname."""
+    return _ASSET_GROUP_BASE[tree_idname]
+
+
+__all__ = [
+    "AssetLibrary",
+    "BundledLibrary",
+    "PackageLibrary",
+    "AssetNodeGroup",
+    "AssetGeometryGroup",
+    "AssetShaderGroup",
+    "AssetCompositorGroup",
+    "asset_group_base",
+]
+
+# Public alias for the mixin, for type hints / isinstance in generated code.
+AssetNodeGroup = _AssetGroupMixin