nodebpy 520.35.1__tar.gz → 520.37.0__tar.gz

{nodebpy-520.35.1 → nodebpy-520.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nodebpy
-Version: 520.35.1
+Version: 520.37.0
 Summary: Build nodes trees in Blender more elegantly with code
 Author: Brady Johnston
 Author-email: Brady Johnston <brady.johnston@me.com>
@@ -60,6 +60,22 @@ with g.tree("AnotherTree", collapse=True, is_modifier=True) as tree:
 - 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()`.
 
+## Agent skill
+
+nodebpy ships an [Agent Skill](https://agentskills.io) that teaches AI coding agents to
+write, check and port node trees with it. Install it into any skills-aware agent
+(Claude Code, Codex, Cursor, Copilot, OpenCode and others) from the repository:
+
+```sh
+npx skills add BradyAJohnston/nodebpy
+```
+
+Claude Code can also take it as a plugin (`/plugin marketplace add BradyAJohnston/nodebpy`,
+then `/plugin install nodebpy@nodebpy`), and the installed package carries the same
+skill, matched to its version: `nodebpy skill install` copies it into `~/.claude/skills`
+and `nodebpy skill path` prints where it is. `nodebpy lookup search|show|socket` is the
+lookup the skill uses to find classes, sockets and options.
+
 ## Documentation
 
 Guides and the full node reference live at [bradyajohnston.github.io/nodebpy](https://bradyajohnston.github.io/nodebpy):

{nodebpy-520.35.1 → nodebpy-520.37.0}/README.md

@@ -43,6 +43,22 @@ with g.tree("AnotherTree", collapse=True, is_modifier=True) as tree:
 - 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()`.
 
+## Agent skill
+
+nodebpy ships an [Agent Skill](https://agentskills.io) that teaches AI coding agents to
+write, check and port node trees with it. Install it into any skills-aware agent
+(Claude Code, Codex, Cursor, Copilot, OpenCode and others) from the repository:
+
+```sh
+npx skills add BradyAJohnston/nodebpy
+```
+
+Claude Code can also take it as a plugin (`/plugin marketplace add BradyAJohnston/nodebpy`,
+then `/plugin install nodebpy@nodebpy`), and the installed package carries the same
+skill, matched to its version: `nodebpy skill install` copies it into `~/.claude/skills`
+and `nodebpy skill path` prints where it is. `nodebpy lookup search|show|socket` is the
+lookup the skill uses to find classes, sockets and options.
+
 ## Documentation
 
 Guides and the full node reference live at [bradyajohnston.github.io/nodebpy](https://bradyajohnston.github.io/nodebpy):

{nodebpy-520.35.1 → nodebpy-520.37.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nodebpy"
-version = "520.35.1"
+version = "520.37.0"
 description = "Build nodes trees in Blender more elegantly with code"
 readme = "README.md"
 authors = [
@@ -65,6 +65,10 @@ not-subscriptable = "ignore"
 invalid-assignment = "ignore"
 invalid-argument-type = "ignore"
 
+[tool.ruff]
+# The agent skill's Markdown keeps its examples compact and aligned by hand.
+extend-exclude = ["src/nodebpy/skills", "skills"]
+
 [tool.ruff.lint]
 ignore = ["SIM117", "RUF059"]
 

nodebpy-520.37.0/src/nodebpy/_lookup.py

@@ -0,0 +1,215 @@
+"""``nodebpy lookup``: find node classes and show their API compactly.
+
+``search <term>`` matches the term (case-insensitive, words may be separated
+by anything) against class names, Blender ``bl_idname``s and the first
+docstring line. ``show <ClassName>`` prints the constructor parameters, enum
+options, class-method variants and output sockets without the long Union
+types ``inspect.signature`` prints. ``socket [Type]`` lists the methods and
+properties on a socket type (what ``node.o.<name>`` or
+``tree.inputs.<type>(...)`` returns), or the socket types themselves.
+"""
+
+from __future__ import annotations
+
+import argparse
+import inspect
+import re
+import typing
+from collections.abc import Iterator
+
+_PREFIX = {"geometry": "g", "shader": "s", "compositor": "c"}
+
+
+def _modules() -> dict[str, object]:
+    import nodebpy  # noqa: F401  # before bpy: the project's own copy wins
+    from nodebpy import compositor, geometry, shader
+
+    return {"geometry": geometry, "shader": shader, "compositor": compositor}
+
+
+def _classes(module) -> Iterator[tuple[str, type]]:
+    for name in dir(module):
+        obj = getattr(module, name)
+        if name[0].isupper() and inspect.isclass(obj) and hasattr(obj, "_bl_idname"):
+            yield name, obj
+
+
+def _summary(cls) -> str:
+    doc = inspect.getdoc(cls) or ""
+    return doc.strip().splitlines()[0] if doc.strip() else ""
+
+
+def search(term: str, trees: list[str]) -> list[str]:
+    words = re.split(r"[\s_]+", term.strip())
+    pattern = re.compile(".*".join(re.escape(w) for w in words), re.IGNORECASE)
+    modules = _modules()
+    lines = []
+    for tree in trees:
+        for name, cls in _classes(modules[tree]):
+            idname = getattr(cls, "_bl_idname", "")
+            summary = _summary(cls)
+            if (
+                pattern.search(name)
+                or pattern.search(idname)
+                or pattern.search(summary)
+            ):
+                lines.append(f"{_PREFIX[tree]}.{name:32} {idname:40} {summary[:70]}")
+    return lines or [f"no node class matches {term!r}"]
+
+
+def _short_type(annotation) -> str:
+    if typing.get_origin(annotation) is typing.Literal:
+        return " | ".join(repr(a) for a in typing.get_args(annotation))
+    text = str(annotation)
+    match = re.search(r"ForwardRef\('(\w+Socket)'\)", text)
+    return match.group(1) if match else text.replace("typing.", "")[:40]
+
+
+def _signature_lines(fn, names_only: bool = False) -> list[str]:
+    """One entry per parameter, with a ``*`` marker before keyword-only ones."""
+    try:
+        sig = inspect.signature(fn)
+    except (TypeError, ValueError):  # pragma: no cover - C-implemented callables
+        return []
+    hints: dict = {}
+    if not names_only:
+        try:
+            hints = typing.get_type_hints(fn)
+        except Exception:  # noqa: BLE001 - forward references that do not resolve
+            hints = {}
+    entries, keyword_only = [], False
+    for param in sig.parameters.values():
+        if param.name == "self":
+            continue
+        if param.kind is param.KEYWORD_ONLY and not keyword_only:
+            entries.append("*")
+            keyword_only = True
+        if param.kind in (param.VAR_KEYWORD, param.VAR_POSITIONAL):
+            entries.append(
+                f"{'**' if param.kind is param.VAR_KEYWORD else '*'}{param.name}"
+            )
+            continue
+        if names_only:
+            entries.append(param.name)
+            continue
+        default = "" if param.default is param.empty else f" = {param.default!r}"
+        kind = _short_type(hints.get(param.name, param.annotation))
+        entries.append(f"{param.name}: {kind}{default}")
+    return entries
+
+
+def show(name: str, trees: list[str]) -> list[str]:
+    modules = _modules()
+    for tree in trees:
+        cls = getattr(modules[tree], name, None)
+        if cls is None:
+            continue
+        lines = [
+            f"{tree}.{name}  ({getattr(cls, '_bl_idname', '?')})",
+            f"  {_summary(cls)}",
+            "",
+            "  constructor:",
+        ]
+        for entry in _signature_lines(cls.__init__):
+            lines.append(
+                "    * (keyword-only properties)" if entry == "*" else f"    {entry}"
+            )
+        methods, factories = [], {}
+        for attr in sorted(dir(cls)):
+            if attr.startswith("_") or not attr.islower():
+                continue
+            static = inspect.getattr_static(cls, attr, None)
+            if isinstance(static, classmethod) and attr != "create_group":
+                methods.append(attr)
+            elif not isinstance(static, (property, staticmethod)) and not callable(
+                static
+            ):
+                # factory objects: g.Compare.float.less_than(), g.StoreNamedAttribute.point.float()
+                subs = tuple(s for s in dir(static) if not s.startswith("_"))
+                if subs:
+                    factories.setdefault(subs, []).append(attr)
+        if methods:
+            lines.append("")
+            lines.append("  variants:")
+            for m in methods:
+                params = ", ".join(_signature_lines(getattr(cls, m), names_only=True))
+                lines.append(f"    {name}.{m}({params})")
+        for subs, attrs in factories.items():
+            left = attrs[0] if len(attrs) == 1 else "{" + ",".join(attrs) + "}"
+            lines.append("")
+            lines.append(f"  variants: {name}.{left}.{{{','.join(subs)}}}()")
+        doc = inspect.getdoc(cls) or ""
+        outputs = doc.split("Outputs\n-------", 1)
+        if len(outputs) == 2:
+            names = [
+                ln.strip() for ln in outputs[1].splitlines() if ln.startswith("o.")
+            ]
+            lines.append("")
+            lines.append("  outputs: " + ", ".join(names))
+        return lines
+    return [f"no class {name!r}; try: nodebpy lookup search {name}"]
+
+
+def socket(kind: str | None) -> list[str]:
+    from nodebpy.builder import socket as sockets
+
+    base = set(dir(sockets.Socket))
+    classes = {
+        n.removesuffix("Socket"): c
+        for n, c in vars(sockets).items()
+        if inspect.isclass(c)
+        and n.endswith("Socket")
+        and n not in ("Socket", "BaseSocket")
+    }
+    if not kind:
+        return ["socket types: " + ", ".join(sorted(classes))]
+    wanted = kind.lower().removesuffix("socket")
+    key = next((k for k in classes if k.lower() == wanted), None)
+    if key is None:
+        return [f"no socket type {kind!r}; types: {', '.join(sorted(classes))}"]
+    cls = classes[key]
+    lines = [f"{key}Socket"]
+    for attr in sorted(set(dir(cls)) - base):
+        if attr.startswith("_"):
+            continue
+        static = inspect.getattr_static(cls, attr, None)
+        doc = (inspect.getdoc(static) or "").strip().splitlines()
+        first = doc[0] if doc else ""
+        if isinstance(static, property):
+            lines.append(f"  .{attr:22} {first[:80]}")
+        elif callable(static) or isinstance(static, (classmethod, staticmethod)):
+            params = _signature_lines(getattr(cls, attr), names_only=True)
+            lines.append(f"  .{attr}({', '.join(params)})".ljust(40) + f" {first[:70]}")
+        else:  # pragma: no cover - a plain factory object on a socket class
+            subs = [x for x in dir(static) if not x.startswith("_")]
+            lines.append(f"  .{attr}.{{{','.join(subs)}}}()"[:110])
+    return lines
+
+
+def add_parser(sub) -> None:
+    parser = sub.add_parser(
+        "lookup",
+        help="Find node classes and show their API: search, show, socket.",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("what", choices=["search", "show", "socket"])
+    parser.add_argument(
+        "term", nargs="?", help="search term, class name or socket type"
+    )
+    parser.add_argument(
+        "--tree", choices=list(_PREFIX), default=None, help="limit to one tree type"
+    )
+
+
+def run(args: argparse.Namespace) -> None:
+    trees = [args.tree] if args.tree else list(_PREFIX)
+    if args.what == "socket":
+        lines = socket(args.term)
+    elif not args.term:
+        raise SystemExit(f"nodebpy lookup {args.what} needs a term")
+    elif args.what == "search":
+        lines = search(args.term, trees)
+    else:
+        lines = show(args.term, trees)
+    print("\n".join(lines))

nodebpy-520.37.0/src/nodebpy/_skill.py

@@ -0,0 +1,53 @@
+"""``nodebpy skill``: the agent skill bundled with the package.
+
+The skill (``nodebpy/skills/nodebpy/SKILL.md`` and its references) teaches
+AI coding agents to write node trees with the installed nodebpy, so it
+always matches the installed version. ``path`` prints its directory;
+``install`` copies it into an agent's skills directory (Claude Code's
+``~/.claude/skills`` by default). Other agents are covered by
+``npx skills add BradyAJohnston/nodebpy``, which reads the same folder from
+the repository.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+from pathlib import Path
+
+SKILL_DIR = Path(__file__).parent / "skills" / "nodebpy"
+
+
+def install(target: Path) -> Path:
+    """Copy the skill into ``target`` (a skills directory), replacing an
+    existing ``nodebpy`` skill there, and return the installed directory."""
+    destination = Path(target).expanduser() / SKILL_DIR.name
+    if destination.exists():
+        shutil.rmtree(destination)
+    shutil.copytree(
+        SKILL_DIR, destination, ignore=shutil.ignore_patterns("__pycache__")
+    )
+    return destination
+
+
+def add_parser(sub) -> None:
+    parser = sub.add_parser(
+        "skill",
+        help="Locate or install the bundled agent skill.",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("what", choices=["path", "install"])
+    parser.add_argument(
+        "--to",
+        type=Path,
+        default=Path("~/.claude/skills"),
+        help="skills directory to install into (default: ~/.claude/skills)",
+    )
+
+
+def run(args: argparse.Namespace) -> None:
+    if args.what == "path":
+        print(SKILL_DIR)
+    else:
+        print(f"installed {install(args.to)}")

{nodebpy-520.35.1 → nodebpy-520.37.0}/src/nodebpy/assets/_library.py

@@ -1773,6 +1773,10 @@ def _parse_args(argv: list[str] | None = None):
         ),
     )
     sub = parser.add_subparsers(dest="command", required=True)
+    from nodebpy import _lookup, _skill
+
+    _lookup.add_parser(sub)
+    _skill.add_parser(sub)
 
     dump = sub.add_parser(
         "dump",
@@ -2020,7 +2024,7 @@ def _parse_args(argv: list[str] | None = None):
     )
 
     args = parser.parse_args(argv)
-    if args.command not in ("plot", "textconv"):
+    if args.command not in ("plot", "textconv", "lookup", "skill"):
         # Fill positionals and flags from the nearest pyproject's
         # [tool.nodebpy.assets] table; explicit arguments always win.
         apply_config(args)
@@ -2073,9 +2077,17 @@ def _build_command(args) -> None:
 
 def main(argv: list[str] | None = None) -> None:  # pragma: no cover - CLI wrapper
     """CLI entry point for the ``dump``, ``build``, ``ensure``, ``check``,
-    ``plot`` and ``textconv`` subcommands."""
+    ``plot``, ``textconv``, ``lookup`` and ``skill`` subcommands."""
     args = _parse_args(argv)
-    if args.command == "dump":
+    if args.command == "lookup":
+        from nodebpy import _lookup
+
+        _lookup.run(args)
+    elif args.command == "skill":
+        from nodebpy import _skill
+
+        _skill.run(args)
+    elif args.command == "dump":
         _dump_command(args)
     elif args.command == "ensure":
         if is_stale(args.blend, args.source, args.resources, stamp_options(args)):

{nodebpy-520.35.1 → nodebpy-520.37.0}/src/nodebpy/builder/__init__.py

@@ -81,6 +81,7 @@ from .tree import (
     PanelContext,
     SocketContext,
     TreeBuilder,
+    WorldBuilder,
     default_split_inputs,
 )
 
@@ -157,6 +158,7 @@ __all__ = [
     "VectorSocket",
     "VectorSocketGrid",
     "VectorSocketList",
+    "WorldBuilder",
     "arrange",
     "asset_group_base",
     "build_from_source",

nodebpy-520.37.0/src/nodebpy/builder/_combine.py

@@ -0,0 +1,80 @@
+"""Feed a vector, rotation or color input from a tuple that holds sockets.
+
+``g.Cube(size=(1, 1, height))`` can't store ``height`` in the socket's
+default, since it is only known when the tree runs, so the tuple is built into
+a Combine XYZ (or Combine Color) node whose output is linked in instead.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from bpy.types import NodeSocket
+
+from ._infer import _source_socket
+from ._utils import SocketError
+
+if TYPE_CHECKING:
+    from .tree import TreeBuilder
+
+
+def _show(values: list[Any]) -> str:
+    """The tuple as written, with sockets named by their node."""
+    parts = []
+    for v in values:
+        socket = _source_socket(v)
+        node = getattr(socket, "node", None)
+        parts.append(f"{node.name}'s {socket.name}" if socket and node else repr(v))
+    return f"({', '.join(parts)})"
+
+
+def holds_sockets(value: Any) -> bool:
+    """Whether ``value`` is a tuple or list with a socket or node in it."""
+    return isinstance(value, (tuple, list)) and any(
+        _source_socket(v) is not None for v in value
+    )
+
+
+def link_combined(tree: TreeBuilder[Any], socket: NodeSocket, value: Any) -> None:
+    """Link a Combine XYZ / Combine Color built from ``value`` into ``socket``."""
+    from ..nodes import compositor, geometry, shader
+
+    nodes: Any = {"ShaderNodeTree": shader, "CompositorNodeTree": compositor}.get(
+        tree.tree.bl_idname, geometry
+    )
+    values = list(value)
+    if socket.type in ("VECTOR", "ROTATION"):
+        # a 2D vector socket takes (x, y); an Euler rotation is converted
+        size = len(getattr(socket, "default_value", ())) or 3
+        if socket.type == "ROTATION" or size not in (2, 3):
+            size = 3
+        if len(values) != size:
+            raise SocketError(
+                f"'{socket.name}' takes {size} components, not {len(values)}: "
+                f"{_show(values)}."
+            )
+        combined = nodes.CombineXYZ(*values)
+    elif socket.type == "RGBA":
+        if len(values) not in (3, 4):
+            raise SocketError(
+                f"'{socket.name}' takes a color of 3 or 4 components, not "
+                f"{len(values)}: {_show(values)}."
+            )
+        red, green, blue, *alpha = values
+        kwargs: dict[str, Any] = {"red": red, "green": green, "blue": blue}
+        if alpha and "alpha" in nodes.CombineColor.__init__.__code__.co_varnames:
+            kwargs["alpha"] = alpha[0]
+        elif alpha and not (isinstance(alpha[0], (int, float)) and alpha[0] == 1):
+            # shader colors carry no alpha through links (and ``==`` on a
+            # socket would build a Compare node rather than test it)
+            raise SocketError(
+                f"Shader colors have no alpha to set from {_show(alpha)[1:-1]}; "
+                f"pass (red, green, blue) to '{socket.name}'."
+            )
+        combined = nodes.CombineColor(**kwargs)
+    else:
+        raise SocketError(
+            f"'{socket.name}' is a {socket.type} input, which a tuple of sockets "
+            "can't feed."
+        )
+    tree.link(combined._default_output_socket, socket)

nodebpy-520.37.0/src/nodebpy/builder/_infer.py

@@ -0,0 +1,139 @@
+"""Pick a multi-type node's data type from the values it is given.
+
+Switch, Index Switch and Menu Switch need their type set before anything is
+linked. Left at the default (Float), a node passed in links whichever of its
+outputs converts to a float, so ``g.Switch(cond, g.Cube(), g.UVSphere())``
+silently switches between the two UV Maps instead of the meshes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, cast
+
+from bpy.types import Node, NodeSocket
+
+from ._utils import SocketError
+
+# the data_type / input_type spelling of a socket type, where they differ
+_DATA_TYPE = {"VALUE": "FLOAT"}
+
+
+def _source_socket(value: Any) -> NodeSocket | None:
+    """The socket ``value`` would link from, or ``None`` for a plain value."""
+    if value is None or value is ...:
+        return None
+    if isinstance(value, NodeSocket):
+        return value
+    if isinstance(value, Node):
+        return next((s for s in value.outputs if s.enabled), None)
+    socket = getattr(value, "socket", None)
+    if isinstance(socket, NodeSocket):
+        return socket
+    try:
+        # nodes and item handles link from their default output
+        default = getattr(value, "_default_output_socket", None)
+    except (IndexError, ValueError, AttributeError):
+        return None
+    return default if isinstance(default, NodeSocket) else None
+
+
+def _literal_type(value: Any) -> str | None:
+    if isinstance(value, bool):
+        return "BOOLEAN"
+    if isinstance(value, int):
+        return "INT"
+    if isinstance(value, float):
+        return "FLOAT"
+    if isinstance(value, str):
+        return "STRING"
+    if isinstance(value, (tuple, list)) and all(
+        isinstance(v, (int, float)) for v in value
+    ):
+        return {3: "VECTOR", 4: "RGBA"}.get(len(value))
+    return None
+
+
+def _describe(socket: NodeSocket) -> str:
+    return f"{getattr(socket.node, 'name', '?')}'s {socket.name}"
+
+
+def infer_node_type(
+    node: Node, prop: str, values: Iterable[Any], *, default: str = "FLOAT"
+) -> str:
+    """``prop``'s value for ``node`` switching between ``values``, set on it.
+
+    The types a switch takes depend on the tree (Integer Vector only in the
+    compositor), which only the node itself knows, so the inferred type is
+    tried on the node and the error lists the ones it accepts.
+    """
+    name = cast(Any, node.bl_rna).name
+    data_type = infer_data_type(name, values, keyword=prop, default=default)
+    try:
+        setattr(node, prop, data_type)
+    except TypeError:
+        raise SocketError(
+            f"{name} can't switch {data_type} values in this tree; it takes "
+            f"{', '.join(_accepted(node, prop))}."
+        ) from None
+    return data_type
+
+
+def _accepted(node: Node, prop: str) -> list[str]:
+    """The values of ``prop`` that ``node`` accepts where it is."""
+    current = getattr(node, prop)
+    accepted = []
+    for item in cast(Any, node.bl_rna).properties[prop].enum_items:
+        try:
+            setattr(node, prop, item.identifier)
+        except TypeError:
+            continue
+        accepted.append(item.identifier)
+    setattr(node, prop, current)
+    return accepted
+
+
+def infer_data_type(
+    node_name: str,
+    values: Iterable[Any],
+    *,
+    keyword: str,
+    default: str = "FLOAT",
+) -> str:
+    """The data type for a node switching between ``values``.
+
+    Sockets and nodes decide it: each links from one socket, and they must all
+    agree. Plain Python values only decide when nothing is linked (``1`` and
+    ``2.5`` together make a float). Raises :class:`SocketError` when the linked
+    values disagree.
+    """
+    values = list(values)
+    sources = [s for s in (_source_socket(v) for v in values) if s is not None]
+
+    if not sources:
+        literals = {t for t in map(_literal_type, values) if t is not None}
+        if literals <= {"INT", "FLOAT"} and len(literals) == 2:
+            literals = {"FLOAT"}
+        return literals.pop() if len(literals) == 1 else default
+
+    found: dict[str, list[str]] = {}
+    for socket in sources:
+        data_type = _DATA_TYPE.get(socket.type, socket.type)
+        found.setdefault(data_type, []).append(_describe(socket))
+    if len(found) > 1:
+        listing = "; ".join(
+            f"{data_type} from {', '.join(names)}" for data_type, names in found.items()
+        )
+        raise SocketError(
+            f"Can't tell which type of {node_name} to build: the values are "
+            f"{listing}. Use a typed variant (e.g. "
+            f"{node_name.replace(' ', '')}.{_variant(next(iter(found)))}(...)) "
+            f"or pass {keyword}=."
+        )
+    (data_type,) = found
+    return data_type
+
+
+def _variant(data_type: str) -> str:
+    """The class-method name for a data type (``RGBA`` is ``color``)."""
+    return {"RGBA": "color", "INT": "integer"}.get(data_type, data_type.lower())