add methods_description and extend export and exportstream decorators

to allow driver-provided help text for exported methods.
Map od methods and their descriptions is added to GetReport to save on RPC calls.

Author: michalskrivanek

packages/jumpstarter/jumpstarter/client/base.py

@@ -36,6 +36,9 @@ class DriverClient(AsyncDriverClient):
     description: str | None = None
     """Driver description from GetReport(), used for CLI help text"""
 
+    methods_description: dict[str, str] = field(default_factory=dict)
+    """Map of method names to their help descriptions from GetReport()"""
+
     def call(self, method, *args):
         """
         Invoke driver call

packages/jumpstarter/jumpstarter/client/client.py

@@ -60,6 +60,7 @@ async def client_from_channel(
             stack=stack.enter_context(ExitStack()),
             children={reports[k].labels["jumpstarter.dev/name"]: clients[k] for k in topo[index]},
             description=getattr(report, 'description', None) or None,
+            methods_description=getattr(report, 'methods_description', {}) or {},
         )
 
         clients[index] = client

packages/jumpstarter/jumpstarter/driver/base.py

@@ -23,6 +23,7 @@
 
 from .decorators import (
     MARKER_DRIVERCALL,
+    MARKER_HELP,
     MARKER_MAGIC,
     MARKER_STREAMCALL,
     MARKER_STREAMING_DRIVERCALL,
@@ -75,6 +76,9 @@ class Driver(
     description: str | None = None
     """Custom description for the driver (shown in CLI help)"""
 
+    methods_description: dict[str, str] = field(default_factory=dict, init=False)
+    """Map of method names to their help descriptions"""
+
     log_level: str = "INFO"
     logger: logging.Logger = field(init=False)
 
@@ -85,6 +89,23 @@ def __post_init__(self):
         self.logger = logging.getLogger(self.__class__.__name__)
         self.logger.setLevel(self.log_level)
 
+        # Collect help texts from decorated methods
+        self._collect_methods_description()
+
+    def _collect_methods_description(self):
+        """Collect help texts from @export and @exportstream decorated methods"""
+        for name in dir(self):
+            if name.startswith('_'):
+                continue
+
+            try:
+                method = getattr(self, name)
+                if callable(method) and hasattr(method, MARKER_HELP):
+                    help_text = getattr(method, MARKER_HELP)
+                    self.methods_description[name] = help_text
+            except Exception:
+                continue
+
     def close(self):
         for child in self.children.values():
             child.close()
@@ -210,6 +231,7 @@ def report(self, *, root=None, parent=None, name=None):
             | ({"jumpstarter.dev/client": self.client()})
             | ({"jumpstarter.dev/name": name} if name else {}),
             description=self.description or None,
+            methods_description=self.methods_description or {},
         )
 
     def enumerate(self, *, root=None, parent=None, name=None):

packages/jumpstarter/jumpstarter/driver/decorators.py

@@ -1,28 +1,33 @@
 from inspect import isasyncgenfunction, iscoroutinefunction, isfunction, isgeneratorfunction
-from typing import Final
+from typing import Callable, Final
 
 MARKER_MAGIC: Final[str] = "07c9b9cc"
 MARKER_DRIVERCALL: Final[str] = "marker_drivercall"
 MARKER_STREAMCALL: Final[str] = "marker_streamcall"
 MARKER_STREAMING_DRIVERCALL: Final[str] = "marker_streamingdrivercall"
+MARKER_HELP: Final[str] = "marker_help"
 
 
-def export(func):
-    """
-    Decorator for exporting method as driver call
-    """
-    if isasyncgenfunction(func) or isgeneratorfunction(func):
-        setattr(func, MARKER_STREAMING_DRIVERCALL, MARKER_MAGIC)
-    elif iscoroutinefunction(func) or isfunction(func):
-        setattr(func, MARKER_DRIVERCALL, MARKER_MAGIC)
-    else:
-        raise ValueError(f"unsupported exported function {func}")
-    return func
+def export(func: Callable | None = None, *, help: str | None = None) -> Callable:
+    """Decorator for exporting method as driver call"""
+    def decorator(f: Callable) -> Callable:
+        if isasyncgenfunction(f) or isgeneratorfunction(f):
+            setattr(f, MARKER_STREAMING_DRIVERCALL, MARKER_MAGIC)
+        elif iscoroutinefunction(f) or isfunction(f):
+            setattr(f, MARKER_DRIVERCALL, MARKER_MAGIC)
+        else:
+            raise ValueError(f"unsupported exported function {f}")
+        if help is not None:
+            setattr(f, MARKER_HELP, help)
+        return f
+    return decorator(func) if func else decorator
 
 
-def exportstream(func):
-    """
-    Decorator for exporting method as stream
-    """
-    setattr(func, MARKER_STREAMCALL, MARKER_MAGIC)
-    return func
+def exportstream(func: Callable | None = None, *, help: str | None = None) -> Callable:
+    """Decorator for exporting method as stream"""
+    def decorator(f: Callable) -> Callable:
+        setattr(f, MARKER_STREAMCALL, MARKER_MAGIC)
+        if help is not None:
+            setattr(f, MARKER_HELP, help)
+        return f
+    return decorator(func) if func else decorator