feat: Improve BlueapiClient to add plan parameter type hints

src/blueapi/client/client.py

@@ -1,11 +1,10 @@
 import itertools
 import logging
 import time
-from collections.abc import Iterable
+from collections.abc import Iterable, KeysView
 from concurrent.futures import Future
 from contextlib import suppress
 from functools import cached_property
-from itertools import chain
 from pathlib import Path
 from typing import Any, Self
 
@@ -56,6 +55,35 @@
 
 log = logging.getLogger(__name__)
 
+_REPR_MAX_LENGTH = 100
+_REPR_MAX_ARGS_INLINE = 3
+
+
+def _pretty_type(schema: dict[str, Any]) -> str:
+    if "$ref" in schema:
+        return schema["$ref"].split("/")[-1]
+
+    if schema.get("type") == "array":
+        item_schema = schema.get("items", {})
+        inner = _pretty_type(item_schema)
+        return f"list[{inner}]"
+
+    if "anyOf" in schema:
+        return " | ".join(_pretty_type(s) for s in schema["anyOf"])
+
+    json_type = schema.get("type")
+    type_map = {
+        "string": "str",
+        "integer": "int",
+        "boolean": "bool",
+        "number": "float",
+        "object": "dict",
+    }
+    if isinstance(json_type, str):
+        return type_map.get(json_type, json_type.split(".")[-1])
+
+    return "Any"
+
 
 class MissingInstrumentSessionError(Exception):
     pass
@@ -164,7 +192,7 @@ def help_text(self) -> str:
         return self.model.description or f"Plan {self!r}"
 
     @property
-    def properties(self) -> set[str]:
+    def properties(self) -> KeysView[str]:
         return self.model.parameter_schema.get("properties", {}).keys()
 
     @property
@@ -201,10 +229,39 @@ def _build_args(self, *args, **kwargs):
             raise TypeError(f"Missing argument(s) for {missing}")
         return params
 
-    def __repr__(self):
-        opts = [p for p in self.properties if p not in self.required]
-        params = ", ".join(chain(self.required, (f"{opt}=None" for opt in opts)))
-        return f"{self.name}({params})"
+    def __repr__(self) -> str:
+        def _format_arg(name: str, info: dict[str, Any], required: set[str]) -> str:
+            typ = _pretty_type(info)
+
+            is_required = name in required
+            has_default = "default" in info
+            default = info.get("default")
+
+            if is_required:
+                return f"{name}: {typ}"
+
+            # optional with explicit default
+            if has_default:
+                if default is None:
+                    return f"{name}: {typ} | None = None"
+                return f"{name}: {typ} = {repr(default)}"
+
+            # optional with no default
+            return f"{name}: {typ} | None = None"
+
+        props = self.model.parameter_schema.get("properties", {})
+        args = [
+            _format_arg(name, info, set(self.required)) for name, info in props.items()
+        ]
+        single_line = f"{self.name}({', '.join(args)})"
+
+        if len(single_line) <= _REPR_MAX_LENGTH and len(args) <= _REPR_MAX_ARGS_INLINE:
+            return single_line
+
+        indent = "    "
+        # Fall back to multiline if too many arguments or too long.
+        multiline_args = ",\n".join(f"{indent}{arg}" for arg in args)
+        return f"{self.name}(\n{multiline_args}\n)"
 
 
 class BlueapiClient:

src/blueapi/core/context.py

@@ -5,7 +5,7 @@
 from importlib import import_module, metadata
 from inspect import Parameter, isclass, signature
 from types import ModuleType, NoneType, UnionType
-from typing import Any, Generic, TypeVar, Union, get_args, get_origin, get_type_hints
+from typing import Any, TypeVar, Union, get_args, get_origin, get_type_hints
 
 from bluesky.protocols import HasName
 from bluesky.run_engine import RunEngine
@@ -459,14 +459,16 @@ def _type_spec_for_function(
             ):
                 default_factory = self._composite_factory(arg_type)
                 _type = SkipJsonSchema[self._convert_type(arg_type, no_default)]
+                field_info = FieldInfo(default_factory=default_factory)
             else:
-                default_factory = DefaultFactory(para.default)
                 _type = self._convert_type(arg_type, no_default)
-            factory = None if no_default else default_factory
-            new_args[name] = (
-                _type,
-                FieldInfo(default_factory=factory),
-            )
+                if no_default:
+                    field_info = FieldInfo()
+                else:
+                    field_info = FieldInfo(default=para.default)
+
+            new_args[name] = (_type, field_info)
+
         return new_args
 
     def _convert_type(self, typ: Any, no_default: bool = True) -> type:
@@ -517,19 +519,3 @@ def _inject_composite():
             return composite_class(**devices)
 
         return _inject_composite
-
-
-D = TypeVar("D")
-
-
-class DefaultFactory(Generic[D]):
-    _value: D
-
-    def __init__(self, value: D):
-        self._value = value
-
-    def __call__(self) -> D:
-        return self._value
-
-    def __eq__(self, other) -> bool:
-        return other.__class__ == self.__class__ and self._value == other._value

tests/system_tests/plans.json

@@ -20,7 +20,8 @@
                     },
                     "num": {
                         "title": "Num",
-                        "type": "integer"
+                        "type": "integer",
+                        "default": 1
                     },
                     "delay": {
                         "anyOf": [
@@ -34,12 +35,14 @@
                                 "type": "array"
                             }
                         ],
+                        "default": 0.0,
                         "title": "Delay"
                     },
                     "metadata": {
                         "additionalProperties": true,
                         "title": "Metadata",
-                        "type": "object"
+                        "type": "object",
+                        "default": null
                     }
                 },
                 "required": [
@@ -681,7 +684,8 @@
                     "metadata": {
                         "additionalProperties": true,
                         "title": "Metadata",
-                        "type": "object"
+                        "type": "object",
+                        "default": null
                     }
                 },
                 "required": [
@@ -711,11 +715,13 @@
                     },
                     "group": {
                         "title": "Group",
-                        "type": "string"
+                        "type": "string",
+                        "default": null
                     },
                     "wait": {
                         "title": "Wait",
-                        "type": "boolean"
+                        "type": "boolean",
+                        "default": false
                     }
                 },
                 "required": [
@@ -745,11 +751,13 @@
                     },
                     "group": {
                         "title": "Group",
-                        "type": "string"
+                        "type": "string",
+                        "default": null
                     },
                     "wait": {
                         "title": "Wait",
-                        "type": "boolean"
+                        "type": "boolean",
+                        "default": false
                     }
                 },
                 "required": [
@@ -773,7 +781,8 @@
                     },
                     "group": {
                         "title": "Group",
-                        "type": "string"
+                        "type": "string",
+                        "default": null
                     }
                 },
                 "required": [
@@ -796,7 +805,8 @@
                     },
                     "group": {
                         "title": "Group",
-                        "type": "string"
+                        "type": "string",
+                        "default": null
                     }
                 },
                 "required": [
@@ -832,11 +842,13 @@
                 "properties": {
                     "group": {
                         "title": "Group",
-                        "type": "string"
+                        "type": "string",
+                        "default": null
                     },
                     "timeout": {
                         "title": "Timeout",
-                        "type": "number"
+                        "type": "number",
+                        "default": null
                     }
                 },
                 "title": "wait",

tests/unit_tests/client/test_client.py

@@ -806,7 +806,72 @@ def test_plan_fallback_help_text(client):
         ),
         client,
     )
-    assert plan.help_text == "Plan foo(one, two=None)"
+    assert plan.help_text == "Plan foo(one: Any, two: Any | None = None)"
+
+
+def test_plan_multi_parameter_fallback_help_text(client):
+    plan = Plan(
+        "foo",
+        PlanModel(
+            name="foo",
+            schema={
+                "properties": {
+                    "one": {},
+                    "two": {
+                        "anyOf": [{"items": {}, "type": "array"}, {"type": "boolean"}],
+                    },
+                    "three": {"default": 3},
+                    "four": {"default": None},
+                },
+                "required": ["one", "two"],
+            },
+        ),
+        client,
+    )
+    assert (
+        plan.help_text == "Plan foo(\n"
+        "    one: Any,\n"
+        "    two: list[Any] | bool,\n"
+        "    three: Any = 3,\n"
+        "    four: Any | None = None\n"
+        ")"
+    )
+
+
+def test_plan_help_text_with_ref(client):
+    schema = {
+        "$defs": {
+            "Spec": {
+                "properties": {
+                    "foo": {"type": "integer"},
+                    "bar": {"$ref": "#/$defs/InnerSpec"},
+                },
+                "required": ["foo", "bar"],
+            },
+            "InnerSpec": {
+                "properties": {
+                    "x": {"type": "number"},
+                    "y": {"default": 10, "type": "number"},
+                },
+                "required": ["x"],
+            },
+        },
+        "properties": {
+            "spec": {"$ref": "#/$defs/Spec"},
+            "meta": {"type": "string", "default": "abc"},
+        },
+        "required": ["spec"],
+    }
+
+    plan = Plan(
+        "ref_plan",
+        PlanModel(name="ref_plan", schema=schema),
+        client,
+    )
+
+    expected = "Plan ref_plan(spec: Spec, meta: str = 'abc')"
+
+    assert plan.help_text == expected
 
 
 def test_plan_properties(client):