Merge pull request #7686 from microsoft/jenshnielsen/add_channel_type

Add more explicit channel attributes

Author: jenshnielsen

docs/changes/newsfragments/7686.improved

@@ -0,0 +1,7 @@
+The ``ChannelTuple`` class now has ``multi_parameter`` and ``multi_function`` methods that
+provide type-safe access to parameters and functions on all channels in the tuple. These methods
+allow accessing attributes with proper type information, improving IDE integration and type checking.
+The return type annotation of ``__getattr__`` has been changed to ``Any`` reflecting the fact that
+this is not a type safe interface and it is impossible for a static type checker to infer the type
+of the dynamic attribute. ``multi_parameter``, ``multi_function`` and ``get_channel_by_name`` should
+be used when a more specific type is requested.

docs/changes/newsfragments/7686.improved_driver

@@ -0,0 +1,3 @@
+The ``RohdeSchwarzZNBBase``, ``MiniCircuitsRCSPDT``, and ``TektronixTPS2012`` drivers now have
+explicit type annotations on their ``channels`` submodule, enabling better type checking and
+IDE integration.

src/qcodes/instrument/channel.py

@@ -5,7 +5,7 @@
 import sys
 import warnings
 from collections.abc import Callable, Iterable, Iterator, MutableSequence, Sequence
-from typing import TYPE_CHECKING, Any, Generic, cast, overload
+from typing import TYPE_CHECKING, Any, Generic, Self, cast, overload
 
 from typing_extensions import TypeVar
 
@@ -441,15 +441,92 @@ def snapshot_base(
             }
         return snap
 
-    def __getattr__(
-        self, name: str
-    ) -> MultiChannelInstrumentParameter | Callable[..., None] | InstrumentModuleType:
+    def multi_parameter(
+        self: Self, name: str
+    ) -> MultiChannelInstrumentParameter[InstrumentModuleType]:
+        """
+        Look up a parameter by name. If this is the name of a parameter on the
+        channel type contained in this container return a multi-channel parameter
+        that controls this parameter on all channels in the Sequence.
+
+        Args:
+            name: The name of the parameter that we want to
+                operate on.
+
+        Returns:
+            MultiChannelInstrumentParameter: The multi-channel parameter
+                that can be used to get or set all items in a channel list
+                simultaneously.
+
+        Raises:
+            AttributeError: If no parameter with the given name exists.
+
+        """
+        if len(self) > 0:
+            # Check if this is a valid parameter
+            if name in self._channels[0].parameters:
+                param = self._construct_multiparam(name)
+                return param
+        raise AttributeError(
+            f"'{self.__class__.__name__}' object has no parameter '{name}'"
+        )
+
+    def multi_function(self, name: str) -> Callable[..., None]:
+        """
+        Look up a callable or QCoDeS function by name. If this is the name of a callable or function
+        on the channel type contained in this container return a callable that calls this callable on
+        all channels in the Sequence
+
+        Args:
+            name: The name of the callable/function that we want to
+                operate on.
+
+        Returns:
+            Callable that calls the functions/callables on all channels in the Sequence.
+
+        Raises:
+            AttributeError: If no callable with the given name exists.
+
+        """
+        if len(self) == 0:
+            raise AttributeError(
+                f"'{self.__class__.__name__}' object has no callable or function '{name}'"
+            )
+        # Check if this is a valid function
+        if name in self._channels[0].functions:
+            # We want to return a reference to a function that would call the
+            # function for each of the channels in turn.
+            def multi_func(*args: Any) -> None:
+                for chan in self._channels:
+                    chan.functions[name](*args)
+
+            return multi_func
+
+        # check if this is a method on the channels in the
+        # sequence
+        maybe_callable = getattr(self._channels[0], name, None)
+        if callable(maybe_callable):
+
+            def multi_callable(*args: Any) -> None:
+                for chan in self._channels:
+                    getattr(chan, name)(*args)
+
+            return multi_callable
+        raise AttributeError(
+            f"'{self.__class__.__name__}' object has no callable or function '{name}'"
+        )
+
+    def __getattr__(self, name: str) -> Any:
         """
         Look up an attribute by name. If this is the name of a parameter or
         a function on the channel type contained in this container return a
         multi-channel function or parameter that can be used to get or
         set all items in a channel list simultaneously. If this is the
-        name of a channel, return that channel.
+        name of a channel, return that channel. This interface is not
+        type safe as it will return any matching attribute. To get a channel
+        by name use ``get_channels_by_name`` instead. To get a parameter use
+        ``multi_parameter``. To get a a callable or a qcodes function use
+        ``multi_function``
 
         Args:
             name: The name of the parameter, function or channel that we want to

src/qcodes/instrument_drivers/Minicircuits/_minicircuits_rc_spdt.py

@@ -11,6 +11,7 @@
 if TYPE_CHECKING:
     from typing_extensions import Unpack
 
+    from qcodes.instrument.channel import ChannelTuple
     from qcodes.parameters import Parameter
 
 
@@ -91,7 +92,10 @@ def __init__(
             channel = MiniCircuitsRCSPDTChannel(self, f"channel_{c}", c)
             channels.append(channel)
             self.add_submodule(f"channel_{c}", channel)
-        self.add_submodule("channels", channels.to_channel_tuple())
+        self.channels: ChannelTuple[MiniCircuitsRCSPDTChannel] = self.add_submodule(
+            "channels", channels.to_channel_tuple()
+        )
+        """Tuple of MiniCircuitsRCSPDTChannel"""
 
         self.connect_message()
 

src/qcodes/instrument_drivers/rohde_schwarz/ZNB.py

@@ -1173,14 +1173,17 @@ def __init__(
         channels = ChannelList(
             self, "VNAChannels", self.CHANNEL_CLASS, snapshotable=True
         )
-        self.add_submodule("channels", channels)
+        self.channels: ChannelList[RohdeSchwarzZNBChannel] = self.add_submodule(
+            "channels", channels
+        )
+        """Submodule channels: List of VNA channels."""
         if init_s_params:
             for i in range(1, num_ports + 1):
                 for j in range(1, num_ports + 1):
                     ch_name = "S" + str(i) + str(j)
                     self.add_channel(ch_name)
             self.display_sij_split()
-            self.channels.autoscale()
+            self.channels.multi_function("autoscale")()
 
         self.update_display_on()
         if reset_channels:

src/qcodes/instrument_drivers/tektronix/TPS2012.py

@@ -1,7 +1,7 @@
 import binascii
 import logging
 from functools import partial
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 import numpy.typing as npt
@@ -18,6 +18,9 @@
 )
 from qcodes.parameters import ArrayParameter, Parameter, ParamRawDataType
 
+if TYPE_CHECKING:
+    from qcodes.instrument.channel import ChannelTuple
+
 log = logging.getLogger(__name__)
 
 
@@ -416,7 +419,10 @@ def __init__(
             channel = TektronixTPS2012Channel(self, ch_name, ch_num)
             channels.append(channel)
             self.add_submodule(ch_name, channel)
-        self.add_submodule("channels", channels.to_channel_tuple())
+        self.channels: ChannelTuple[TektronixTPS2012Channel] = self.add_submodule(
+            "channels", channels.to_channel_tuple()
+        )
+        """Tuple of TektronixTPS2012Channel"""
 
         # Necessary settings for parsing the binary curve data
         self.visa_handle.encoding = "latin-1"

tests/test_channels.py

@@ -753,6 +753,98 @@ def test_channel_tuple_names(dci: DummyChannelInstrument) -> None:
     assert dci.channels.full_name == "dci_TempSensors"
 
 
+def test_multi_parameter_returns_multichannel_parameter(
+    dci: DummyChannelInstrument,
+) -> None:
+    """Test that multi_parameter returns a MultiChannelInstrumentParameter for valid parameter name."""
+    temp_multi_param = dci.channels.multi_parameter("temperature")
+    assert isinstance(temp_multi_param, MultiChannelInstrumentParameter)
+
+    temperatures = temp_multi_param.get()
+    assert len(temperatures) == 6
+
+
+def test_multi_parameter_invalid_name_raises(dci: DummyChannelInstrument) -> None:
+    """Test that multi_parameter raises AttributeError for invalid parameter name."""
+    with pytest.raises(
+        AttributeError,
+        match="'ChannelTuple' object has no parameter 'nonexistent_param'",
+    ):
+        dci.channels.multi_parameter("nonexistent_param")
+
+
+def test_multi_parameter_on_empty_channel_tuple_raises(
+    empty_instrument: Instrument,
+) -> None:
+    """Test that multi_parameter raises AttributeError on empty channel tuple."""
+    channels = ChannelTuple(empty_instrument, "channels", chan_type=DummyChannel)
+    empty_instrument.add_submodule("channels", channels)
+
+    with pytest.raises(
+        AttributeError,
+        match="'ChannelTuple' object has no parameter 'temperature'",
+    ):
+        channels.multi_parameter("temperature")
+
+
+def test_multi_function_returns_callable(dci: DummyChannelInstrument) -> None:
+    """Test that multi_function returns a callable for valid function name."""
+    multi_func = dci.channels.multi_function("log_my_name")
+    assert callable(multi_func)
+
+
+def test_multi_function_calls_function_on_all_channels(
+    dci: DummyChannelInstrument, caplog: LogCaptureFixture
+) -> None:
+    """Test that the returned callable calls the function on all channels."""
+    with caplog.at_level(
+        logging.DEBUG, logger="qcodes.instrument_drivers.mock_instruments"
+    ):
+        caplog.clear()
+        multi_func = dci.channels.multi_function("log_my_name")
+        multi_func()
+        mssgs = [rec.message for rec in caplog.records]
+        names = [ch.name.replace("dci_", "") for ch in dci.channels]
+        assert mssgs == names
+
+
+def test_multi_function_with_callable_method(
+    dci: DummyChannelInstrument, mocker: "pytest_mock.MockerFixture"
+) -> None:
+    """Test that multi_function works with callable methods on channels."""
+    for channel in dci.channels:
+        channel.turn_on = mocker.MagicMock(return_value=1)
+
+    multi_func = dci.channels.multi_function("turn_on")
+    result = multi_func("bar")
+    assert result is None
+    for channel in dci.channels:
+        channel.turn_on.assert_called_with("bar")  # type: ignore[union-attr]
+
+
+def test_multi_function_invalid_name_raises(dci: DummyChannelInstrument) -> None:
+    """Test that multi_function raises AttributeError for invalid function/callable name."""
+    with pytest.raises(
+        AttributeError,
+        match="'ChannelTuple' object has no callable or function 'nonexistent_func'",
+    ):
+        dci.channels.multi_function("nonexistent_func")
+
+
+def test_multi_function_on_empty_channel_tuple_raises(
+    empty_instrument: Instrument,
+) -> None:
+    """Test that multi_function raises AttributeError on empty channel tuple."""
+    channels = ChannelTuple(empty_instrument, "channels", chan_type=DummyChannel)
+    empty_instrument.add_submodule("channels", channels)
+
+    with pytest.raises(
+        AttributeError,
+        match="'ChannelTuple' object has no callable or function 'temperature'",
+    ):
+        channels.multi_function("temperature")
+
+
 def _verify_multiparam_data(data) -> None:
     assert "multi_setpoint_param_this_setpoint_set" in data.arrays.keys()
     assert_array_equal(