nodebpy 520.8.0__tar.gz → 520.10.0__tar.gz

{nodebpy-520.8.0 → nodebpy-520.10.0}/PKG-INFO

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

{nodebpy-520.8.0 → nodebpy-520.10.0}/pyproject.toml

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

{nodebpy-520.8.0 → nodebpy-520.10.0}/src/nodebpy/assets/__main__.py

@@ -31,7 +31,7 @@ _ESSENTIALS: dict[str, tuple[str, ...]] = {
 
 
 def generate_essentials(
-    nodes_dir: Path, nodebpy_pkg: str = ".."
+    nodes_dir: Path, nodebpy_pkg: str = "..", docstrings: bool = True
 ) -> dict[str, list[str]]:
     """Generate the bundled-essentials asset modules into
     ``<nodes_dir>/<tree>/assets.py``; returns the class names written per tree
@@ -50,6 +50,7 @@ def generate_essentials(
             libraries,
             Path(nodes_dir) / tree / "assets.py",
             nodebpy_pkg=nodebpy_pkg,
+            docstrings=docstrings,
         )
         written[tree] = names
         print(f"  nodes/{tree}/assets.py: {len(names)} asset classes")
@@ -86,6 +87,15 @@ def parse_args() -> argparse.Namespace:
             "package — e.g. '..lib.nodebpy'."
         ),
     )
+    parser.add_argument(
+        "--no-docstrings",
+        dest="docstrings",
+        action="store_false",
+        help=(
+            "Skip the numpy-style class docstrings (description, Parameters, "
+            "Inputs, Outputs) and emit a terser module."
+        ),
+    )
     return parser.parse_args()
 
 
@@ -117,10 +127,13 @@ def main() -> None:  # pragma: no cover - CLI wrapper
             [PackageLibrary(str(output), relative)],
             output,
             nodebpy_pkg=args.nodebpy_pkg,
+            docstrings=args.docstrings,
         )
         return
 
-    generate_essentials(Path(__file__).parent.parent / "nodes")
+    generate_essentials(
+        Path(__file__).parent.parent / "nodes", docstrings=args.docstrings
+    )
 
 
 if __name__ == "__main__":  # pragma: no cover

{nodebpy-520.8.0 → nodebpy-520.10.0}/src/nodebpy/assets/_codegen.py

@@ -95,6 +95,39 @@ def _format_default(socket: bpy.types.NodeSocket) -> str:
     return "None"
 
 
+def _clean_doc(text: str) -> str:
+    """Make ``text`` safe to drop inside a ``\"\"\"…\"\"\"`` docstring."""
+    text = " ".join(text.split())
+    text = text.replace('"""', "'''")
+    return text.rstrip("\\").rstrip()
+
+
+def _quote(text: str) -> str:
+    """``text`` as a double-quoted Python string literal."""
+    return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _menu_items(socket) -> tuple[str, ...]:
+    """The items a menu socket accepts, in order.
+
+    A menu socket's items come from the Menu Switch node that defines them and
+    aren't readable from the socket's RNA enum, but assigning an impossible
+    value makes Blender list them in the ``TypeError`` — the same trick as
+    ``gen.introspect._collect_socket_menu_items`` (duplicated rather than
+    imported, since ``gen`` is a build tool and isn't shipped with the package).
+    """
+    if getattr(socket, "type", "") != "MENU" or not socket.default_value:
+        return ()
+    try:
+        socket.default_value = "X" * 100
+    except TypeError as error:
+        _, _, listed = str(error).partition("not found in ")
+        items = (item.strip("()'\" ") for item in listed.split(", "))
+        return tuple(item for item in items if item)
+    # A menu that accepted the impossible value tells us nothing about its items.
+    return ()
+
+
 @dataclass
 class _Socket:
     name: str
@@ -103,6 +136,27 @@ class _Socket:
     input_type: str  # e.g. "InputGeometry"
     default: str  # source for the default value
     attr: str  # normalized accessor/param name
+    description: str = ""  # interface tooltip, if the asset author set one
+    menu_items: tuple[str, ...] = ()  # menu sockets only: the selectable items
+
+    @property
+    def doc(self) -> str:
+        """Documentation line for this socket — its tooltip, else its name."""
+        return _clean_doc(self.description or self.name)
+
+    @property
+    def param_type(self) -> str:
+        """Type hint for the ``__init__`` parameter.
+
+        A menu socket is narrowed to its own items so editors offer them for
+        completion, while still accepting a linked ``MenuSocket``.
+        """
+        if not self.menu_items:
+            return self.input_type
+        # Double-quoted to match the formatted source (ruff reformats the code
+        # but not the docstring copy of the same annotation).
+        literals = ", ".join(_quote(item) for item in self.menu_items)
+        return f"{self.input_type} | Literal[{literals}]"
 
 
 @dataclass
@@ -116,12 +170,21 @@ class _AssetClass:
     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)
-    ]
+def _collect(
+    sockets,
+    descriptions: dict[str, str] | None = None,
+    menus: bool = False,
+) -> list[_Socket]:
+    """Introspect ``sockets`` into records.
+
+    ``menus`` resolves menu sockets to their items — only worth doing for the
+    group's *inputs*, whose parameters are typed from them.
+    """
+    descriptions = descriptions or {}
+    # Keep inactive sockets: socket-usage inference deactivates inputs that the
+    # current node options (e.g. a menu selection) leave unused, but a caller
+    # may set those options differently, so the API must expose every input.
+    raw = [s for s in sockets if s.identifier != "__extend__"]
     # 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.
@@ -129,6 +192,7 @@ def _collect(sockets) -> list[_Socket]:
     out: list[_Socket] = []
     for s in raw:
         socket_class, input_type = _socket_types(type(s).__name__)
+        menu_items = _menu_items(s) if menus else ()
         norm_name = normalize_name(s.name)
         attr = (
             norm_name if name_counts[norm_name] == 1 else normalize_name(s.identifier)
@@ -141,11 +205,50 @@ def _collect(sockets) -> list[_Socket]:
                 input_type=input_type,
                 default=_format_default(s),
                 attr=attr,
+                description=descriptions.get(s.identifier, ""),
+                menu_items=menu_items,
             )
         )
     return out
 
 
+def _introspect_group(group, name: str, library_source: str) -> _AssetClass:
+    """Introspect the node group ``group`` (a ``bpy.types.NodeTree``) into an
+    :class:`_AssetClass` record by instantiating it on a throwaway host node.
+
+    ``group`` is deliberately unannotated: the stubs type interface items and
+    ``node_groups.new`` too narrowly for the runtime attributes used here.
+    """
+    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  # ty: ignore[unresolved-attribute]
+        # Tooltips live on the tree *interface* items, not on the node's
+        # sockets — collect them by identifier so the generated docstrings
+        # can use the asset author's own wording.
+        descriptions = {
+            item.identifier: item.description or ""
+            for item in group.interface.items_tree
+            if item.item_type == "SOCKET"
+        }
+        return _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, descriptions, menus=True),
+            outputs=_collect(node.outputs, descriptions),
+        )
+    finally:
+        bpy.data.node_groups.remove(host)
+
+
 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."""
@@ -169,29 +272,7 @@ def _introspect(library: AssetLibrary, names: set[str] | None) -> list[_AssetCla
         ):
             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  # ty: ignore[unresolved-attribute]
-            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)
+        classes.append(_introspect_group(group, name, library_source))
     return classes
 
 
@@ -210,24 +291,49 @@ def _library_source(library: AssetLibrary) -> str:
     raise TypeError(f"Cannot serialise asset library: {library!r}")
 
 
-def _accessor(sockets: list[_Socket], kind: str) -> str:
+def _accessor(sockets: list[_Socket], kind: str, docstrings: bool) -> 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
+        doc = s.doc if docstrings else _clean_doc(s.name)
         if doc and doc != s.attr:
             lines.append(f'        """{doc}"""')
     return "\n".join(lines)
 
 
-def _render_class(cls: _AssetClass) -> str:
+def _class_docstring(cls: _AssetClass) -> str:
+    """A numpy-style docstring for ``cls``, matching the built-in node classes."""
+    lines = [_clean_doc(cls.description), ""]
+    if cls.inputs:
+        lines += ["Parameters", "----------"]
+        for s in cls.inputs:
+            lines += [f"{s.attr} : {s.param_type}", f"    {s.doc}"]
+        lines.append("")
+        lines += ["Inputs", "------"]
+        for s in cls.inputs:
+            lines += [f"i.{s.attr} : {s.socket_class}", f"    {s.doc}"]
+        lines.append("")
+    if cls.outputs:
+        lines += ["Outputs", "-------"]
+        for s in cls.outputs:
+            lines += [f"o.{s.attr} : {s.socket_class}", f"    {s.doc}"]
+    # Indent to the class body, leaving blank separator lines truly blank so the
+    # module needs no formatter pass to be clean.
+    body = "\n".join(f"    {line}" if line else "" for line in lines).strip("\n")
+    return f'"""\n{body}\n    """'
+
+
+def _render_class(cls: _AssetClass, docstrings: bool = False) -> str:
     base = asset_group_base(cls.tree_idname).__name__
-    inputs_cls = _accessor(cls.inputs, "_Inputs")
-    outputs_cls = _accessor(cls.outputs, "_Outputs")
+    docstring = (
+        _class_docstring(cls) if docstrings else f'"""{_clean_doc(cls.description)}"""'
+    )
+    inputs_cls = _accessor(cls.inputs, "_Inputs", docstrings)
+    outputs_cls = _accessor(cls.outputs, "_Outputs", docstrings)
 
-    params = [f"{s.attr}: {s.input_type} = {s.default}" for s in cls.inputs]
+    params = [f"{s.attr}: {s.param_type} = {s.default}" for s in cls.inputs]
     signature = (
         "(\n        self,\n        " + ",\n        ".join(params) + ",\n    )"
         if params
@@ -235,8 +341,8 @@ def _render_class(cls: _AssetClass) -> str:
     )
     key_args = ", ".join(f'"{s.identifier}": {s.attr}' for s in cls.inputs)
 
-    return f'''class {cls.class_name}({base}):
-    """{cls.description}"""
+    return f"""class {cls.class_name}({base}):
+    {docstring}
 
     _name = {cls.asset_name!r}
     _asset_name = {cls.asset_name!r}
@@ -254,10 +360,14 @@ def _render_class(cls: _AssetClass) -> str:
 
     def __init__{signature}:
         super().__init__(**{{{key_args}}})
-'''
+"""
 
 
-def _render_module(classes: list[_AssetClass], nodebpy_pkg: str = "nodebpy") -> str:
+def _render_module(
+    classes: list[_AssetClass],
+    nodebpy_pkg: str = "nodebpy",
+    docstrings: bool = False,
+) -> str:
     socket_classes = sorted(
         {s.socket_class for c in classes for s in c.inputs + c.outputs}
     )
@@ -276,9 +386,13 @@ def _render_module(classes: list[_AssetClass], nodebpy_pkg: str = "nodebpy") ->
         set(bases) | set(libraries) | {"SocketAccessor"} | set(socket_classes)
     )
 
+    typing_imports = ["TYPE_CHECKING"]
+    if any(s.menu_items for c in classes for s in c.inputs):
+        typing_imports.append("Literal")
+
     lines = [
         "# Auto-generated by nodebpy.assets.generate_asset_api — do not edit manually.",
-        "from typing import TYPE_CHECKING",
+        f"from typing import {', '.join(typing_imports)}",
         "",
         f"from {nodebpy_pkg}.builder import (\n    {',\n    '.join(builder_imports)},\n)",
         f"from {nodebpy_pkg}.types import (\n    {',\n    '.join(input_types)},\n)"
@@ -287,7 +401,7 @@ def _render_module(classes: list[_AssetClass], nodebpy_pkg: str = "nodebpy") ->
     ]
     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)
+    body = "\n\n".join(_render_class(c, docstrings) 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"
@@ -301,6 +415,7 @@ def generate_asset_api(
     *,
     names: set[str] | None = None,
     nodebpy_pkg: str = "nodebpy",
+    docstrings: bool = True,
 ) -> list[str]:
     """Generate typed asset classes for ``libraries`` into ``output_path``.
 
@@ -321,6 +436,11 @@ def generate_asset_api(
         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.
+    docstrings:
+        Emit numpy-style class docstrings (description, ``Parameters``,
+        ``Inputs``, ``Outputs``) using the asset's own socket tooltips, so
+        editors show documentation alongside the type hints. Defaults to
+        ``True``; pass ``False`` for a terser module.
 
     Returns the list of generated class names.
     """
@@ -334,7 +454,8 @@ 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, nodebpy_pkg=nodebpy_pkg), encoding="utf-8"
+        _render_module(classes, nodebpy_pkg=nodebpy_pkg, docstrings=docstrings),
+        encoding="utf-8",
     )
     return [c.class_name for c in classes]