Merge pull request #8024 from jenshnielsen/parameter_kwargs_dict

Parameter kwargs dict

Author: jenshnielsen

docs/changes/newsfragments/8024.improved

@@ -0,0 +1,3 @@
+Add ``ParameterBaseKWArgs`` and ``ParameterKWArgs`` TypedDicts for typing ``**kwargs``
+forwarded through the ``Parameter`` class hierarchy. Subclasses of ``Parameter`` can now
+use ``**kwargs: Unpack[ParameterKWArgs]`` for statically checked kwargs forwarding.

src/qcodes/instrument_drivers/Keysight/N52xx.py

@@ -79,7 +79,7 @@ class FormattedSweep(ParameterWithSetpoints[npt.NDArray, "KeysightPNATrace"]):
     def __init__(
         self,
         name: str,
-        instrument: "KeysightPNABase",
+        instrument: "KeysightPNATrace",
         sweep_format: str,
         label: str,
         unit: str,

src/qcodes/parameters/__init__.py

@@ -77,10 +77,11 @@
 from .grouped_parameter import DelegateGroup, DelegateGroupParameter, GroupedParameter
 from .multi_channel_instrument_parameter import MultiChannelInstrumentParameter
 from .multi_parameter import MultiParameter
-from .parameter import ManualParameter, Parameter
+from .parameter import ManualParameter, Parameter, ParameterKWArgs
 from .parameter_base import (
     ParamDataType,
     ParameterBase,
+    ParameterBaseKWArgs,
     ParameterSet,
     ParamRawDataType,
     invert_val_mapping,
@@ -112,6 +113,8 @@
     "ParamSpecBaseDict",
     "Parameter",
     "ParameterBase",
+    "ParameterBaseKWArgs",
+    "ParameterKWArgs",
     "ParameterSet",
     "ParameterWithSetpoints",
     "ScaledParameter",

src/qcodes/parameters/array_parameter.py

@@ -14,11 +14,18 @@
     has_loop = False
 from typing import Generic
 
-from .parameter_base import InstrumentTypeVar_co, ParameterBase, ParameterDataTypeVar
+from .parameter_base import (
+    InstrumentTypeVar_co,
+    ParameterBase,
+    ParameterBaseKWArgs,
+    ParameterDataTypeVar,
+)
 from .sequence_helpers import is_sequence_of
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping, Sequence
+    from collections.abc import Sequence
+
+    from typing_extensions import Unpack
 
 
 try:
@@ -80,9 +87,6 @@ class ArrayParameter(
             to expect. Scalars should be denoted by (), 1D arrays as (n,),
             2D arrays as (n, m), etc.
 
-        instrument: The instrument this parameter
-            belongs to, if any.
-
         label: Normally used as the axis label when this
             parameter is graphed, along with ``unit``.
 
@@ -111,21 +115,10 @@ class ArrayParameter(
             field of the object. The ``__doc__`` field of the instance
             is used by some help systems, but not all.
 
-        snapshot_get: Prevent any update to the parameter, for example
-            if it takes too long to update. Default ``True``.
-
-        snapshot_value: Should the value of the parameter be stored in the
-            snapshot. Unlike Parameter this defaults to False as
-            ArrayParameters are potentially huge.
-
-        snapshot_exclude: ``True`` prevents parameter to be
-            included in the snapshot. Useful if there are many of the same
-            parameter which are clogging up the snapshot.
-
-            Default ``False``.
-
-        metadata: Extra information to include with the
-            JSON snapshot of the parameter.
+        **kwargs: Forwarded to the ``ParameterBase`` base class.
+            Note that ``snapshot_value`` defaults to ``False`` for
+            ``ArrayParameter``. See :class:`ParameterBaseKWArgs` for
+            details.
 
     """
 
@@ -134,29 +127,20 @@ def __init__(
         name: str,
         *,
         shape: Sequence[int],
-        # 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]
         label: str | None = None,
         unit: str | None = None,
         setpoints: Sequence[Any] | None = None,
         setpoint_names: Sequence[str] | None = None,
         setpoint_labels: Sequence[str] | None = None,
         setpoint_units: Sequence[str] | None = None,
         docstring: str | None = None,
-        snapshot_get: bool = True,
-        snapshot_value: bool = False,
-        snapshot_exclude: bool = False,
-        metadata: Mapping[Any, Any] | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[
+            ParameterBaseKWArgs[ParameterDataTypeVar, InstrumentTypeVar_co]
+        ],
     ) -> None:
+        kwargs.setdefault("snapshot_value", False)
         super().__init__(
             name,
-            instrument=instrument,
-            snapshot_get=snapshot_get,
-            metadata=metadata,
-            snapshot_value=snapshot_value,
-            snapshot_exclude=snapshot_exclude,
             **kwargs,
         )
 

src/qcodes/parameters/delegate_parameter.py

@@ -4,13 +4,15 @@
 
 from typing_extensions import TypeVar
 
-from .parameter import Parameter
+from .parameter import Parameter, ParameterKWArgs
 from .parameter_base import InstrumentTypeVar_co, ParameterDataTypeVar
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
     from datetime import datetime
 
+    from typing_extensions import Unpack
+
     from qcodes.instrument import InstrumentBase
     from qcodes.validators.validators import Validator
 
@@ -70,6 +72,10 @@ class DelegateParameter(
         You should pass ``bind_to_instrument=True`` if you want this to
         be the case.
 
+        ``set_cmd`` and ``get_cmd`` are not allowed since the source
+        parameter's commands are used. Providing ``initial_value`` or
+        ``initial_cache_value`` without a source is also an error.
+
     """
 
     class _DelegateCache(
@@ -178,10 +184,9 @@ def __init__(
         name: str,
         *,
         source: Parameter | None,
-        **kwargs: Any,
+        **kwargs: Unpack[ParameterKWArgs[ParameterDataTypeVar, InstrumentTypeVar_co]],
     ):
-        if "bind_to_instrument" not in kwargs.keys():
-            kwargs["bind_to_instrument"] = False
+        kwargs.setdefault("bind_to_instrument", False)
 
         for cmd in ("set_cmd", "get_cmd"):
             if cmd in kwargs:

src/qcodes/parameters/group_parameter.py

@@ -9,11 +9,13 @@
 from collections import OrderedDict
 from typing import TYPE_CHECKING, Any
 
-from .parameter import Parameter
+from .parameter import Parameter, ParameterKWArgs
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
 
+    from typing_extensions import Unpack
+
     from qcodes.instrument import InstrumentBase
 
     from .parameter_base import ParamDataType, ParamRawDataType
@@ -37,33 +39,28 @@ class GroupParameter(Parameter):
 
     Args:
         name: Name of the parameter.
-        instrument: Instrument that this parameter belongs to; this instrument
-            is used by the group to call its get and set commands.
-        initial_value: Initial value of the parameter. Note that either none or
-            all of the parameters in a :class:`.Group` should have an initial
-            value.
-
-        **kwargs: All kwargs used by the :class:`.Parameter` class, except
-             ``set_cmd`` and ``get_cmd``.
+        **kwargs: Forwarded to the ``Parameter`` base class.
+            See :class:`ParameterKWArgs` for details.
+            Note that ``set_cmd`` and ``get_cmd`` are not allowed.
+            ``initial_value``, if provided, is deferred until the
+            parameter is added to a :class:`.Group`.
 
     """
 
     def __init__(
         self,
         name: str,
-        *,
-        instrument: InstrumentBase | None = None,
-        initial_value: float | str | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[ParameterKWArgs],
     ) -> None:
         if "set_cmd" in kwargs or "get_cmd" in kwargs:
             raise ValueError(
                 "A GroupParameter does not use 'set_cmd' or 'get_cmd' kwarg"
             )
 
         self._group: Group | None = None
-        self._initial_value = initial_value
-        super().__init__(name, instrument=instrument, **kwargs)
+        self._initial_value = kwargs.get("initial_value")
+        kwargs["initial_value"] = None
+        super().__init__(name, **kwargs)
 
     @property
     def group(self) -> Group | None:

src/qcodes/parameters/grouped_parameter.py

@@ -6,14 +6,19 @@
 
 from .delegate_parameter import DelegateParameter
 from .group_parameter import Group, GroupParameter
-from .parameter_base import ParamDataType, ParameterBase, ParamRawDataType
+from .parameter_base import (
+    ParamDataType,
+    ParameterBase,
+    ParameterBaseKWArgs,
+    ParamRawDataType,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Mapping, Sequence
 
-    from qcodes.instrument import InstrumentBase
+    from typing_extensions import Unpack
 
-    from .parameter import Parameter
+    from .parameter import Parameter, ParameterKWArgs
 
 
 _log = logging.getLogger(__name__)
@@ -24,15 +29,11 @@ def __init__(
         self,
         name: str,
         source: Parameter | None,
-        instrument: InstrumentBase | None = None,
-        initial_value: float | str | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[ParameterKWArgs],
     ) -> None:
         super().__init__(
             name=name,
             source=source,
-            instrument=instrument,
-            initial_value=initial_value,
             **kwargs,
         )
 
@@ -161,7 +162,8 @@ class GroupedParameter(ParameterBase):
         group: Group that contains the target parameter(s).
         unit: The unit of measure. Use ``''`` for unitless.
         label: Optional label, defaults to parameter name.
-        default set method(s).
+        **kwargs: Forwarded to the ``ParameterBase`` base class.
+            See :class:`ParameterBaseKWArgs` for details.
 
     """
 
@@ -172,7 +174,7 @@ def __init__(
         group: DelegateGroup,
         unit: str | None = None,
         label: str | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[ParameterBaseKWArgs],
     ):
         super().__init__(name, **kwargs)
         self.label = name if label is None else label

src/qcodes/parameters/multi_parameter.py

@@ -1,14 +1,22 @@
 from __future__ import annotations
 
 import os
-from collections.abc import Iterator, Mapping, Sequence
-from typing import Any, Generic
+from collections.abc import Iterator, Sequence
+from typing import TYPE_CHECKING, Any, Generic
 
 import numpy as np
 
-from .parameter_base import InstrumentTypeVar_co, ParameterBase, ParameterDataTypeVar
+from .parameter_base import (
+    InstrumentTypeVar_co,
+    ParameterBase,
+    ParameterBaseKWArgs,
+    ParameterDataTypeVar,
+)
 from .sequence_helpers import is_sequence_of
 
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
 try:
     from qcodes_loop.data.data_array import DataArray
 
@@ -84,9 +92,6 @@ class MultiParameter(
             each item. Scalars should be denoted by (), 1D arrays as (n,),
             2D arrays as (n, m), etc.
 
-        instrument: The instrument this parameter
-            belongs to, if any.
-
         labels: A label for each item. Normally used
             as the axis label when a component is graphed, along with the
             matching entry from ``units``.
@@ -119,20 +124,10 @@ class MultiParameter(
             field of the object. The ``__doc__`` field of the  instance is
             used by some help systems, but not all
 
-        snapshot_get: Prevent any update to the parameter, for example
-            if it takes too long to update. Default ``True``.
-
-        snapshot_value: Should the value of the parameter be stored in the
-            snapshot. Unlike Parameter this defaults to False as
-            MultiParameters are potentially huge.
-
-        snapshot_exclude: True prevents parameter to be
-            included in the snapshot. Useful if there are many of the same
-            parameter which are clogging up the snapshot.
-            Default ``False``.
-
-        metadata: Extra information to include with the
-            JSON snapshot of the parameter.
+        **kwargs: Forwarded to the ``ParameterBase`` base class.
+            Note that ``snapshot_value`` defaults to ``False`` for
+            ``MultiParameter``. See :class:`ParameterBaseKWArgs` for
+            details.
 
     """
 
@@ -142,29 +137,20 @@ def __init__(
         *,
         names: Sequence[str],
         shapes: Sequence[Sequence[int]],
-        # 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]
         labels: Sequence[str] | None = None,
         units: Sequence[str] | None = None,
         setpoints: Sequence[Sequence[Any]] | None = None,
         setpoint_names: Sequence[Sequence[str]] | None = None,
         setpoint_labels: Sequence[Sequence[str]] | None = None,
         setpoint_units: Sequence[Sequence[str]] | None = None,
         docstring: str | None = None,
-        snapshot_get: bool = True,
-        snapshot_value: bool = False,
-        snapshot_exclude: bool = False,
-        metadata: Mapping[Any, Any] | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[
+            ParameterBaseKWArgs[ParameterDataTypeVar, InstrumentTypeVar_co]
+        ],
     ) -> None:
+        kwargs.setdefault("snapshot_value", False)
         super().__init__(
             name,
-            instrument=instrument,
-            snapshot_get=snapshot_get,
-            metadata=metadata,
-            snapshot_value=snapshot_value,
-            snapshot_exclude=snapshot_exclude,
             **kwargs,
         )