Merge pull request #7880 from jenshnielsen/parameter_deprecate_args

Deprecate positional args to parameter classes

Author: jenshnielsen

docs/changes/newsfragments/7880.breaking

@@ -0,0 +1,4 @@
+Passing arguments as positional arguments is deprecated for ``ParameterBase``, ``Parameter``,
+``ArrayParameter``, ``DelegateParameter``, ``GroupParameter``, ``GroupedParameter``,
+``MultiParameter``, ``MultiChannelInstrumentParameter``, ``ElapsedTimeParameter``,
+and ``InstrumentRefParameter``. Please pass all arguments except ``name`` as keyword arguments.

src/qcodes/instrument/channel.py

@@ -608,7 +608,7 @@ def _construct_multiparam(self, name: str) -> MultiChannelInstrumentParameter:
         else:
             shapes = tuple(() for _ in self._channels)
         param = self._paramclass(
-            self._channels,
+            channels=self._channels,
             param_name=name,
             name=f"Multi_{name}",
             names=names,

src/qcodes/instrument_drivers/QDev/QDac_channels.py

@@ -182,10 +182,9 @@ def __init__(
         self,
         channels: "Sequence[InstrumentChannel]",
         param_name: str,
-        *args: Any,
         **kwargs: Any,
     ):
-        super().__init__(channels, param_name, *args, **kwargs)
+        super().__init__(channels=channels, param_name=param_name, **kwargs)
 
     def get_raw(self) -> tuple[ParamRawDataType, ...]:
         """

src/qcodes/instrument_drivers/mock_instruments/__init__.py

@@ -675,8 +675,8 @@ def __init__(
         setpoint_units = (("this setpointunit",), ("this setpointunit",))
         super().__init__(
             name,
-            names,
-            shapes,
+            names=names,
+            shapes=shapes,
             instrument=instrument,
             labels=labels,
             units=units,
@@ -732,8 +732,8 @@ def __init__(
         )
         super().__init__(
             name,
-            names,
-            shapes,
+            names=names,
+            shapes=shapes,
             instrument=instrument,
             labels=labels,
             units=units,
@@ -792,8 +792,8 @@ def __init__(
         )
         super().__init__(
             name,
-            names,
-            shapes,
+            names=names,
+            shapes=shapes,
             instrument=instrument,
             labels=labels,
             units=units,
@@ -828,8 +828,8 @@ def __init__(
         setpoints = ((), ())
         super().__init__(
             name,
-            names,
-            shapes,
+            names=names,
+            shapes=shapes,
             instrument=instrument,
             labels=labels,
             units=units,
@@ -864,8 +864,8 @@ def __init__(
         setpoint_units = ("this setpointunit",)
         super().__init__(
             name,
-            shape,
-            instrument,
+            shape=shape,
+            instrument=instrument,
             label=label,
             unit=unit,
             setpoints=setpoints,
@@ -901,8 +901,8 @@ def __init__(
         setpoint_units = ("this setpointunit",)
         super().__init__(
             name,
-            shape,
-            instrument,
+            shape=shape,
+            instrument=instrument,
             label=label,
             unit=unit,
             setpoints=setpoints,

src/qcodes/parameters/array_parameter.py

@@ -2,7 +2,8 @@
 
 import collections.abc
 import os
-from typing import TYPE_CHECKING, Any
+import warnings
+from typing import TYPE_CHECKING, Any, ClassVar
 
 import numpy as np
 
@@ -14,6 +15,8 @@
     has_loop = False
 from typing import Generic
 
+from qcodes.utils import QCoDeSDeprecationWarning
+
 from .parameter_base import InstrumentTypeVar_co, ParameterBase, ParameterDataTypeVar
 from .sequence_helpers import is_sequence_of
 
@@ -40,6 +43,9 @@
     )
 
 
+_SHAPE_UNSET: Any = object()
+
+
 class ArrayParameter(
     ParameterBase[ParameterDataTypeVar, InstrumentTypeVar_co],
     Generic[ParameterDataTypeVar, InstrumentTypeVar_co],
@@ -129,10 +135,27 @@ class ArrayParameter(
 
     """
 
+    _DEPRECATED_POSITIONAL_ARGS: ClassVar[tuple[str, ...]] = (
+        "shape",
+        "instrument",
+        "label",
+        "unit",
+        "setpoints",
+        "setpoint_names",
+        "setpoint_labels",
+        "setpoint_units",
+        "docstring",
+        "snapshot_get",
+        "snapshot_value",
+        "snapshot_exclude",
+        "metadata",
+    )
+
     def __init__(
         self,
         name: str,
-        shape: Sequence[int],
+        *args: Any,
+        shape: Sequence[int] = _SHAPE_UNSET,
         # mypy seems to be confused here. The bound and default for InstrumentTypeVar_co
         # contains None but mypy will not allow it as a default as of v 1.19.0
         instrument: InstrumentTypeVar_co = None,  # type: ignore[assignment]
@@ -149,6 +172,90 @@ def __init__(
         metadata: Mapping[Any, Any] | None = None,
         **kwargs: Any,
     ) -> None:
+        if args:
+            # TODO: After QCoDeS 0.57 remove the args argument and delete this code block.
+            # we hardcode the class since mypy does not support __class__ and
+            # self / self.__class__ / type(self) in class bodies does not give
+            # exactly this class but the type of a subclass
+            positional_names = ArrayParameter._DEPRECATED_POSITIONAL_ARGS
+            if len(args) > len(positional_names):
+                raise TypeError(
+                    f"{type(self).__name__}.__init__() takes at most "
+                    f"{len(positional_names) + 2} positional arguments "
+                    f"({len(args) + 2} given)"
+                )
+
+            _defaults: dict[str, Any] = {
+                "shape": _SHAPE_UNSET,
+                "instrument": None,
+                "label": None,
+                "unit": None,
+                "setpoints": None,
+                "setpoint_names": None,
+                "setpoint_labels": None,
+                "setpoint_units": None,
+                "docstring": None,
+                "snapshot_get": True,
+                "snapshot_value": False,
+                "snapshot_exclude": False,
+                "metadata": None,
+            }
+
+            _kwarg_vals: dict[str, Any] = {
+                "shape": shape,
+                "instrument": instrument,
+                "label": label,
+                "unit": unit,
+                "setpoints": setpoints,
+                "setpoint_names": setpoint_names,
+                "setpoint_labels": setpoint_labels,
+                "setpoint_units": setpoint_units,
+                "docstring": docstring,
+                "snapshot_get": snapshot_get,
+                "snapshot_value": snapshot_value,
+                "snapshot_exclude": snapshot_exclude,
+                "metadata": metadata,
+            }
+
+            for i in range(len(args)):
+                arg_name = positional_names[i]
+                if _kwarg_vals[arg_name] is not _defaults[arg_name]:
+                    raise TypeError(
+                        f"{type(self).__name__}.__init__() got multiple "
+                        f"values for argument '{arg_name}'"
+                    )
+
+            positional_arg_names = positional_names[: len(args)]
+            names_str = ", ".join(f"'{n}'" for n in positional_arg_names)
+            warnings.warn(
+                f"Passing {names_str} as positional argument(s) to "
+                f"{type(self).__name__} is deprecated. "
+                f"Please pass them as keyword arguments.",
+                QCoDeSDeprecationWarning,
+                stacklevel=2,
+            )
+
+            _pos = dict(zip(positional_names, args))
+            shape = _pos.get("shape", shape)
+            instrument = _pos.get("instrument", instrument)
+            label = _pos.get("label", label)
+            unit = _pos.get("unit", unit)
+            setpoints = _pos.get("setpoints", setpoints)
+            setpoint_names = _pos.get("setpoint_names", setpoint_names)
+            setpoint_labels = _pos.get("setpoint_labels", setpoint_labels)
+            setpoint_units = _pos.get("setpoint_units", setpoint_units)
+            docstring = _pos.get("docstring", docstring)
+            snapshot_get = _pos.get("snapshot_get", snapshot_get)
+            snapshot_value = _pos.get("snapshot_value", snapshot_value)
+            snapshot_exclude = _pos.get("snapshot_exclude", snapshot_exclude)
+            metadata = _pos.get("metadata", metadata)
+
+        if shape is _SHAPE_UNSET:
+            raise TypeError(
+                f"{type(self).__name__}.__init__() missing required "
+                f"keyword argument: 'shape'"
+            )
+
         super().__init__(
             name,
             instrument=instrument,

src/qcodes/parameters/delegate_parameter.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Generic
+import warnings
+from typing import TYPE_CHECKING, Any, ClassVar, Generic
 
 from typing_extensions import TypeVar
 
+from qcodes.utils import QCoDeSDeprecationWarning
+
 from .parameter import Parameter
 from .parameter_base import InstrumentTypeVar_co, ParameterDataTypeVar
 
@@ -28,6 +31,7 @@
     default="InstrumentBase | None",
     covariant=True,
 )
+_SOURCE_UNSET: Any = object()
 
 
 class DelegateParameter(
@@ -71,6 +75,11 @@ class DelegateParameter(
 
     """
 
+    _DEPRECATED_POSITIONAL_ARGS: ClassVar[tuple[str, ...]] = (
+        "source",
+        *Parameter._DEPRECATED_POSITIONAL_ARGS,
+    )
+
     class _DelegateCache(
         Generic[_local_ParameterDataTypeVar, _local_InstrumentTypeVar_co]
     ):
@@ -175,10 +184,58 @@ def __call__(self) -> _local_ParameterDataTypeVar:
     def __init__(
         self,
         name: str,
-        source: Parameter | None,
         *args: Any,
+        source: Parameter | None = _SOURCE_UNSET,
         **kwargs: Any,
     ):
+        if args:
+            # TODO: After QCoDeS 0.57 remove the args argument and delete this code block.
+            positional_names = DelegateParameter._DEPRECATED_POSITIONAL_ARGS
+            if len(args) > len(positional_names):
+                raise TypeError(
+                    f"{type(self).__name__}.__init__() takes at most "
+                    f"{len(positional_names) + 2} positional arguments "
+                    f"({len(args) + 2} given)"
+                )
+
+            for i in range(len(args)):
+                arg_name = positional_names[i]
+                if arg_name == "source":
+                    if source is not _SOURCE_UNSET:
+                        raise TypeError(
+                            f"{type(self).__name__}.__init__() got multiple "
+                            f"values for argument '{arg_name}'"
+                        )
+                elif arg_name in kwargs:
+                    raise TypeError(
+                        f"{type(self).__name__}.__init__() got multiple "
+                        f"values for argument '{arg_name}'"
+                    )
+
+            positional_arg_names = positional_names[: len(args)]
+            names_str = ", ".join(f"'{n}'" for n in positional_arg_names)
+            warnings.warn(
+                f"Passing {names_str} as positional argument(s) to "
+                f"{type(self).__name__} is deprecated. "
+                "Please pass them as keyword arguments.",
+                QCoDeSDeprecationWarning,
+                stacklevel=2,
+            )
+
+            positional_values = dict(zip(positional_names, args))
+            if "source" in positional_values:
+                source = positional_values["source"]
+
+            for arg_name in positional_names[1:]:
+                if arg_name in positional_values:
+                    kwargs[arg_name] = positional_values[arg_name]
+
+        if source is _SOURCE_UNSET:
+            raise TypeError(
+                f"{type(self).__name__}.__init__() missing required keyword "
+                "argument: 'source'"
+            )
+
         if "bind_to_instrument" not in kwargs.keys():
             kwargs["bind_to_instrument"] = False
 
@@ -200,7 +257,7 @@ def __init__(
 
         initial_cache_value = kwargs.pop("initial_cache_value", None)
         self.source = source
-        super().__init__(name, *args, **kwargs)
+        super().__init__(name, **kwargs)
         self.label = kwargs.get("label", None)
         self.unit = kwargs.get("unit", None)