From 76c7355c46d0320314bfee206ac506f210de61a7 Mon Sep 17 00:00:00 2001 From: marcosf2 Date: Wed, 14 Oct 2026 00:54:15 -0500 Subject: [PATCH 1/3] Adding tests for function type hints --- .../testing/dummy_instruments/generic.py | 81 +++++++++ test/pytest/test_method_annotations.py | 168 ++++++++++++++++++ 2 files changed, 249 insertions(+) create mode 100644 test/pytest/test_method_annotations.py diff --git a/src/instrumentserver/testing/dummy_instruments/generic.py b/src/instrumentserver/testing/dummy_instruments/generic.py index aaecad6..8211563 100644 --- a/src/instrumentserver/testing/dummy_instruments/generic.py +++ b/src/instrumentserver/testing/dummy_instruments/generic.py @@ -242,6 +242,87 @@ def get_numeric_text(self): return "123" +class AnnotatedMethodsInstrument(Instrument): + """Dummy whose public methods use module-level classes as annotations. + + Mirrors drivers like the QDevil QDAC2 (``allocate_trace(...) -> Trace_Context``). + ``inspect.signature`` renders these annotations with their full module path, + which the client has to be able to rebuild when it creates proxy methods. + """ + + def __init__(self, name: str, *args, **kwargs): + super().__init__(name, *args, **kwargs) + + def ask_raw(self, cmd: str) -> str: + """Return a minimal response to identification queries.""" + if cmd.strip().upper().startswith("*IDN"): + return f"dummy,{self.name},0,0" + return "" + + def make_request(self, center_hz: float, span_hz: float) -> SweepRequest: + """Custom class as the return annotation.""" + return SweepRequest(center_hz=center_hz, span_hz=span_hz) + + def request_span(self, request: SweepRequest) -> float: + """Custom class as a parameter annotation.""" + return request.span_hz + + +_NO_VALUE = object() + + +class DefaultValuesInstrument(Instrument): + """Dummy whose public methods have defaults whose ``repr`` is not valid Python. + + ``inspect.signature`` renders these as ```` or + ````, which the client cannot paste into source + when it creates proxy methods. + """ + + def __init__(self, name: str, *args, **kwargs): + super().__init__(name, *args, **kwargs) + + def ask_raw(self, cmd: str) -> str: + """Return a minimal response to identification queries.""" + if cmd.strip().upper().startswith("*IDN"): + return f"dummy,{self.name},0,0" + return "" + + def add(self, a, b=10): + """Plain literal default.""" + return a + b + + def flag_value(self, flag=StatusFlag.EAV): + """Enum member as the default.""" + return int(flag) + + def is_default(self, value=_NO_VALUE): + """Sentinel object as the default.""" + return value is _NO_VALUE + + def scaled(self, x, *, factor=_NO_VALUE): + """Sentinel object as a keyword-only default.""" + if factor is _NO_VALUE: + return x + return x * factor + + def combine(self, a, b=1, c=2): + """Lets a caller skip a middle default.""" + return f"{a},{b},{c}" + + def positional_only(self, a, b=1, /): + """Positional-only parameters with a default.""" + return f"{a},{b}" + + def required_keyword(self, x, *, k): + """Keyword-only parameter without a default.""" + return f"{x},{k}" + + def gather(self, a, b=1, *args, **kwargs): + """Defaults mixed with variadic arguments.""" + return f"{a},{b},{list(args)},{sorted(kwargs.items())}" + + class DummyInstrumentTimeout(Instrument): """A dummy instrument to test timeout situations.""" diff --git a/test/pytest/test_method_annotations.py b/test/pytest/test_method_annotations.py new file mode 100644 index 0000000..472990a --- /dev/null +++ b/test/pytest/test_method_annotations.py @@ -0,0 +1,168 @@ +"""Proxy methods for instrument methods whose signatures are not valid client-side source. + +``inspect.signature`` writes a non-builtin class annotation with its full module +path (e.g. ``-> instrumentserver.testing.dummy_instruments.generic.SweepRequest``), +and defaults with their ``repr`` (e.g. ```` or +````). The client must still be able to build proxy +methods for these, and omitted arguments must fall back to the server's defaults. +""" + +import inspect + +import pytest + +from instrumentserver.testing.dummy_instruments.generic import SweepRequest + +ANNOTATED_INSTRUMENT = ( + "instrumentserver.testing.dummy_instruments.generic.AnnotatedMethodsInstrument" +) + + +def test_proxy_for_instrument_with_custom_class_annotations(cli): + ins = cli.find_or_create_instrument("annotated", ANNOTATED_INSTRUMENT) + + assert "make_request" in ins.functions + assert "request_span" in ins.functions + + +def test_calling_method_with_custom_return_annotation(cli): + ins = cli.find_or_create_instrument("annotated", ANNOTATED_INSTRUMENT) + + request = ins.make_request(5e9, 1e6) + + assert isinstance(request, SweepRequest) + assert request.center_hz == 5e9 + assert request.span_hz == 1e6 + + +def test_calling_method_with_custom_parameter_annotation(cli): + ins = cli.find_or_create_instrument("annotated", ANNOTATED_INSTRUMENT) + + span = ins.request_span(SweepRequest(center_hz=5e9, span_hz=2e6)) + + assert span == 2e6 + + +DEFAULTS_INSTRUMENT = ( + "instrumentserver.testing.dummy_instruments.generic.DefaultValuesInstrument" +) + + +def test_proxy_for_instrument_with_unrepresentable_defaults(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + for name in ["add", "flag_value", "is_default", "scaled"]: + assert name in ins.functions + + +def test_proxy_method_keeps_parameter_names(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert list(inspect.signature(ins.add).parameters) == ["a", "b"] + assert list(inspect.signature(ins.scaled).parameters) == ["x", "factor"] + + +def test_literal_default(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert ins.add(1) == 11 + assert ins.add(1, 2) == 3 + assert ins.add(1, b=5) == 6 + assert ins.add(a=1, b=2) == 3 + + +def test_missing_required_argument_raises(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + with pytest.raises(Exception, match="missing 1 required positional argument: 'a'"): + ins.add() + + +def test_enum_default(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert ins.flag_value() == 4 + assert ins.flag_value(16) == 16 + + +def test_omitted_argument_uses_server_default(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert ins.is_default() is True + assert ins.is_default(None) is False + + +def test_keyword_only_default(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert ins.scaled(3) == 3 + assert ins.scaled(3, factor=2) == 6 + + +def test_skipping_a_middle_default(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert ins.combine(0) == "0,1,2" + assert ins.combine(0, c=5) == "0,1,5" + assert ins.combine(0, 3, 4) == "0,3,4" + + +def test_positional_only_default(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert ins.positional_only(0) == "0,1" + assert ins.positional_only(0, 2) == "0,2" + + +def test_required_keyword_only(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert ins.required_keyword(0, k=3) == "0,3" + + +def _fail_if_server_called(*args, **kwargs): + pytest.fail("call should have been rejected on the client") + + +def test_positional_only_rejects_keyword_on_client(cli, monkeypatch): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + monkeypatch.setattr(ins, "askServer", _fail_if_server_called) + + with pytest.raises(TypeError, match="positional-only"): + ins.positional_only(0, b=2) + + +def test_keyword_only_rejects_positional_on_client(cli, monkeypatch): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + monkeypatch.setattr(ins, "askServer", _fail_if_server_called) + + with pytest.raises(TypeError, match="positional argument"): + ins.required_keyword(0, 3) + + +def test_defaults_with_variadic_arguments(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert ins.gather(0) == "0,1,[],[]" + assert ins.gather(0, 2, 3, 4) == "0,2,[3, 4],[]" + assert ins.gather(0, x=9) == "0,1,[],[('x', 9)]" + + +def test_proxy_signature_shows_server_signature(cli): + """The client GUI uses ``str(inspect.signature(fun))`` as placeholder and tooltip.""" + annotated = cli.find_or_create_instrument("annotated", ANNOTATED_INSTRUMENT) + defaults = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert str(inspect.signature(defaults.add)) == "(a, b=10)" + assert str(inspect.signature(defaults.flag_value)) == "(flag=)" + assert str(inspect.signature(annotated.make_request)) == ( + "(center_hz: float, span_hz: float)" + " -> instrumentserver.testing.dummy_instruments.generic.SweepRequest" + ) + + +def test_proxy_docstring_starts_with_server_signature(cli): + ins = cli.find_or_create_instrument("defaults", DEFAULTS_INSTRUMENT) + + assert ins.add.__doc__.startswith("add(a, b=10)\n\n") + assert "Plain literal default." in ins.add.__doc__ From d5e90991bd6c2e8b1ccc0cfc1c890c57d21c79b4 Mon Sep 17 00:00:00 2001 From: marcosf2 Date: Wed, 14 Oct 2026 12:38:00 -0500 Subject: [PATCH 2/3] Build proxy methods from parameter names and kinds so any server signature works, and leave omitted arguments to the server's defaults --- src/instrumentserver/client/proxy.py | 160 ++++++++++++++++++++++----- 1 file changed, 131 insertions(+), 29 deletions(-) diff --git a/src/instrumentserver/client/proxy.py b/src/instrumentserver/client/proxy.py index 391542c..3f2e525 100644 --- a/src/instrumentserver/client/proxy.py +++ b/src/instrumentserver/client/proxy.py @@ -5,7 +5,6 @@ @author: Chao """ -import collections import inspect import json import logging @@ -15,7 +14,6 @@ from types import MethodType from typing import Any, Callable, Dict, List, Optional, Union -import qcodes as qc import zmq from qcodes import Instrument, Parameter from qcodes.instrument import InstrumentBase @@ -43,10 +41,89 @@ # TODO: enable creation of instruments through yaml files/station configurator. # TODO: support for channel lists # TODO: support for other parameter classes. -# FIXME: need to generally find the imports we need for type annotations! # TODO: convenience function to refresh from server. +class _Missing: + """Default of every proxy method parameter: the caller didn't pass it.""" + + def __repr__(self) -> str: + return "" + + +_MISSING = _Missing() + +# name of the forwarding helper in the generated method's globals; a driver +# parameter won't use it. +_FORWARD_NAME = "__isrv_forward__" + +# the blueprint stores each parameter kind as ``str(kind)``. +_PARAMETER_KINDS = { + str(kind): kind + for kind in ( + inspect.Parameter.POSITIONAL_ONLY, + inspect.Parameter.POSITIONAL_OR_KEYWORD, + inspect.Parameter.VAR_POSITIONAL, + inspect.Parameter.KEYWORD_ONLY, + inspect.Parameter.VAR_KEYWORD, + ) +} +_POSITIONAL_KINDS = ( + inspect.Parameter.POSITIONAL_ONLY, + inspect.Parameter.POSITIONAL_OR_KEYWORD, +) +_VARIADIC_KINDS = (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD) + + +def _defArguments(parameters: List[inspect.Parameter]) -> str: + """Argument list for the generated proxy method: ``self`` first, every + named parameter defaulting to ``_MISSING``, and the ``/`` and ``*`` markers + kept so positional-only and keyword-only behave as on the server.""" + parts = ["self"] + star = False + for i, p in enumerate(parameters): + if p.kind == inspect.Parameter.VAR_POSITIONAL: + parts.append(f"*{p.name}") + star = True + elif p.kind == inspect.Parameter.VAR_KEYWORD: + parts.append(f"**{p.name}") + else: + if p.kind == inspect.Parameter.KEYWORD_ONLY and not star: + parts.append("*") + star = True + parts.append(f"{p.name}=_MISSING") + is_last_positional_only = p.kind == inspect.Parameter.POSITIONAL_ONLY and ( + i + 1 == len(parameters) + or parameters[i + 1].kind != inspect.Parameter.POSITIONAL_ONLY + ) + if is_last_positional_only: + parts.append("/") + return ", ".join(parts) + + +class _ServerSignature(inspect.Signature): + """Signature of a proxy method. Its parameters match the generated method, + so ``bind()`` behaves like the proxy, but ``str()`` gives the server's + signature text, annotations and defaults included.""" + + __slots__ = ("_server_text",) + + def __init__(self, *args: Any, server_text: str = "", **kwargs: Any) -> None: + super().__init__(*args, **kwargs) + self._server_text = server_text + + def __str__(self) -> str: + return self._server_text + + def replace(self, **kwargs: Any) -> "_ServerSignature": + # inspect calls this to drop ``self`` from a bound method's signature. + new = super().replace(**kwargs) + new._server_text = self._server_text + return new + + __replace__ = replace + + class ProxyMixin: """A simple mixin class for proxy objects.""" @@ -352,37 +429,62 @@ def wrap(*a: Any, **k: Any) -> Any: ) return self.askServer(msg) - sig = bp.call_signature_str - params = bp.signature_parameters - args = [] - # FIXME: a better solution to this would probably be to convet kind into the enum object. But it seems that the - # parameter kind enum is private. - for pn, kind in params.items(): - if kind in [ - str(inspect.Parameter.POSITIONAL_OR_KEYWORD), - str(inspect.Parameter.POSITIONAL_ONLY), - ]: - args.append(f"{pn}") - elif kind == str(inspect.Parameter.VAR_POSITIONAL): - args.append(f"*{pn}") - elif kind == str(inspect.Parameter.KEYWORD_ONLY): - args.append(f"{pn}={pn}") - elif kind == str(inspect.Parameter.VAR_KEYWORD): - args.append(f"**{pn}") + # The server signature can hold annotations and defaults the client + # can't evaluate, so only names and kinds are used here. Every + # parameter defaults to _MISSING, and only what the caller passed is + # sent, so the server applies its own defaults. + parameters = [ + inspect.Parameter( + pn, + _PARAMETER_KINDS[kind], + default=( + inspect.Parameter.empty + if _PARAMETER_KINDS[kind] in _VARIADIC_KINDS + else _MISSING + ), + ) + for pn, kind in bp.signature_parameters.items() + ] + + def forward(values: Dict[str, Any]) -> Any: + args: List[Any] = [] + kwargs: Dict[str, Any] = {} + positional = True + for p in parameters: + value = values[p.name] + if p.kind in _POSITIONAL_KINDS: + # send by position until the first omitted one, then by keyword. + if value is _MISSING: + positional = False + elif positional: + args.append(value) + else: + kwargs[p.name] = value + elif p.kind == inspect.Parameter.VAR_POSITIONAL: + args.extend(value) + elif p.kind == inspect.Parameter.KEYWORD_ONLY: + if value is not _MISSING: + kwargs[p.name] = value + else: + kwargs.update(value) + return wrap(*args, **kwargs) # we need to add a `self` argument because we want this to be a bound # method of the instrument instance. - sig = sig[0] + "self, " + sig[1:] - new_func_str = f"""from typing import *\ndef {bp.name}{sig}: - return wrap({", ".join(args)})""" - - # make sure the method knows the wrap function. - # TODO: this is not complete! - globs = {"wrap": wrap, "qcodes": qc, "collections": collections} + new_func_str = ( + f"def {bp.name}({_defArguments(parameters)}):\n" + f" return {_FORWARD_NAME}(what is ())" + ) + globs = {_FORWARD_NAME: forward, "_MISSING": _MISSING} exec(new_func_str, globs) fun = globs[bp.name] - fun.__doc__ = bp.docstring - return globs[bp.name] # type: ignore[return-value] + fun.__signature__ = _ServerSignature( + [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)] + + parameters, + server_text=bp.call_signature_str, + ) + fun.__doc__ = f"{bp.name}{bp.call_signature_str}\n\n{bp.docstring}" + return fun # type: ignore[no-any-return] def _getProxySubmodules(self) -> None: """Based on the submodule blue print replied from server, add the proxy From e9b965ec82209f07bb897a9d02b9c4bc6845347a Mon Sep 17 00:00:00 2001 From: marcosf2 Date: Wed, 14 Oct 2026 12:43:33 -0500 Subject: [PATCH 3/3] Fix CI: restore locals() in generated proxy method body, type exec globals, apply ruff format Co-Authored-By: Claude Opus 5.5 (1M context) --- src/instrumentserver/client/proxy.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/instrumentserver/client/proxy.py b/src/instrumentserver/client/proxy.py index 3f2e525..1a65a17 100644 --- a/src/instrumentserver/client/proxy.py +++ b/src/instrumentserver/client/proxy.py @@ -473,18 +473,17 @@ def forward(values: Dict[str, Any]) -> Any: # method of the instrument instance. new_func_str = ( f"def {bp.name}({_defArguments(parameters)}):\n" - f" return {_FORWARD_NAME}(what is ())" + f" return {_FORWARD_NAME}(locals())" ) - globs = {_FORWARD_NAME: forward, "_MISSING": _MISSING} + globs: Dict[str, Any] = {_FORWARD_NAME: forward, "_MISSING": _MISSING} exec(new_func_str, globs) fun = globs[bp.name] fun.__signature__ = _ServerSignature( - [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)] - + parameters, + [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)] + parameters, server_text=bp.call_signature_str, ) fun.__doc__ = f"{bp.name}{bp.call_signature_str}\n\n{bp.docstring}" - return fun # type: ignore[no-any-return] + return fun def _getProxySubmodules(self) -> None: """Based on the submodule blue print replied from server, add the proxy