Support type checking with TY

.github/workflows/pytest.yaml

@@ -116,6 +116,10 @@ jobs:
       run: mypy -p qcodes
       if: ${{ !matrix.min-version && always() }}
       id: mypy
+    - name: Run ty
+      run: ty check --output-format github
+      if: ${{ !matrix.min-version && always() }}
+      id: ty
     - name: Set pytest basetemp
       if: ${{ runner.os == 'Windows' }}
       run: echo "PYTEST_BASETEMP=--basetemp=D:\\tmp" >> $GITHUB_ENV

docs/changes/newsfragments/8441.improved.1

@@ -0,0 +1,6 @@
+The ``callback`` argument of :meth:`.DataSet.subscribe` is now typed as
+``Callable[..., None]``. The previous annotation described a callback taking
+exactly three arguments, which contradicted ``callback_kwargs``: those are bound
+onto the callback with ``functools.partial``, so a callback using them takes
+further arguments. ``_Subscriber``, which ``subscribe`` forwards to, already
+typed it this way.

docs/changes/newsfragments/8441.improved.10

@@ -0,0 +1,3 @@
+The offline plotting tutorial now checks the optional values it gets back from
+:func:`.plot_dataset` before using them, and asks for the root figure when
+saving. ``Axes.figure`` may be a ``SubFigure``, which has no ``savefig``.

docs/changes/newsfragments/8441.improved.11

@@ -0,0 +1,5 @@
+``snapshot_raw`` is now part of :class:`.DataSetProtocol` and is available on
+:class:`.DataSetInMem` as well as on :class:`.DataSet`. It is documented as the
+way to get the snapshot of a run as a JSON string, and is used as such in the
+example notebooks, but it was only declared on one of the two dataset classes,
+so reading it from a dataset returned by a measurement did not type check.

docs/changes/newsfragments/8441.improved.12

@@ -0,0 +1,3 @@
+The snapshot example notebook now checks that the snapshots it reads back from
+the datasets are present before using them. A run only has a snapshot if one was
+recorded, so both ``snapshot`` and ``snapshot_raw`` are optional.

docs/changes/newsfragments/8441.improved.13

@@ -0,0 +1,5 @@
+The type alias ``ValuesType``, used by ``DataSaver.add_result`` and related
+methods, now also accepts a sequence of numpy arrays. This is what a
+``MultiParameter`` measuring more than one array returns, so passing such a
+result to ``DataSaver.add_result`` no longer produces a type checking error.
+The behavior at runtime is unchanged since this was already supported.

docs/changes/newsfragments/8441.improved.14

@@ -0,0 +1,5 @@
+The annotation of ``qcodes.utils.types.numpy_complex`` now correctly
+describes its content as a tuple of numpy complex types. It was previously
+annotated as also containing the builtin ``complex``, which via the implicit
+numeric tower made type checkers treat it as possibly containing ``int`` or
+``float`` as well.

docs/changes/newsfragments/8441.improved.15

@@ -0,0 +1,3 @@
+The module level ports used by ``qcodes.monitor`` are now annotated as
+``int``. They are intended to be reassigned to select another port, which
+type checkers rejected since the type was inferred from the default value.

docs/changes/newsfragments/8441.improved.16

@@ -0,0 +1,7 @@
+The type alias ``VALUE`` in ``qcodes.dataset.sqlite.query_helpers`` now includes
+the numpy integer, floating point and complex scalar types. These are already
+supported at runtime by ``DataSet.add_results`` and the other functions that
+store data in the database, so passing numpy scalars to them no longer produces a
+type checking error. Since ``VALUE`` is also used as the return type of methods
+such as ``DataSet.get_metadata``, code that annotates the returned values may
+need to handle numpy scalar types too.

docs/changes/newsfragments/8441.improved.2

@@ -0,0 +1,7 @@
+``Keysight34980A.module`` is now a ``dict`` of
+``Keysight34980ASwitchMatrixSubModule`` rather than one built with
+``dict.fromkeys``, whose values were typed as possibly ``None``. ``scan_slots``
+puts an entry in for every slot, either the driver for the installed module or a
+generic submodule, so the values were never ``None`` once the instrument was
+constructed. Code using ``instrument.module[slot]`` no longer has to account for
+a ``None`` that cannot occur.

docs/changes/newsfragments/8441.improved.3

@@ -0,0 +1,6 @@
+The return type of :func:`.parse_awg_file` has been corrected. The waveform and
+marker entries were declared as lists of dicts, but the parser returns the arrays
+from inside those dicts, and the loop counts and sequencing values were declared
+as possibly ``str`` when they are always ``int``. The type now matches the call
+signature of :meth:`.TektronixAWG5014.make_send_and_load_awg_file`, which the
+docstring already promised and which is how the function is meant to be used.

docs/changes/newsfragments/8441.improved.4

@@ -0,0 +1,6 @@
+The Keysight B1500 example notebook called
+``b1500.run_iv_staircase_sweep.measurement_status()`` in the phase compensation
+section. ``IVSweepMeasurement`` has no such method, so the cell raised
+``AttributeError``. The surrounding text asks for all channel outputs to be
+enabled before performing phase compensation, so the cell now calls
+``b1500.enable_channels()``.

docs/changes/newsfragments/8441.improved.5

@@ -0,0 +1,7 @@
+``KeysightE4980AMeasurementPair`` now declares a ``__getattr__`` for type
+checkers. The two measured values are exposed as attributes named after the
+``names`` of the measurement function, for example ``capacitance`` for ``CPD``
+and ``inductance`` for ``LPD``, so which attributes exist is only known at
+runtime. The declaration lets this documented usage be written in typed code. It
+is not defined at runtime, so accessing an attribute that the current
+measurement function does not provide still raises the usual ``AttributeError``.

docs/changes/newsfragments/8441.improved.6

@@ -0,0 +1,4 @@
+The Stanford SR86x buffered readout example notebook now packs the waveforms for
+:meth:`.TektronixAWG70000Base.makeSEQXFile` in lists rather than wrapping them in
+further numpy arrays, which is the shape the method documents. The two forms
+behave the same at runtime.

docs/changes/newsfragments/8441.improved.7

@@ -0,0 +1,6 @@
+``connect_paths``, ``disconnect_paths`` and ``to_channel_list`` on the Keysight
+B220X switch matrix drivers now accept any iterable of paths rather than only a
+``Sequence``. They iterate the paths once and do not index them, so passing a
+set, as the example notebook does, is fine. Note that the order in which the
+paths appear in the channel list then follows the iteration order of the
+argument.

docs/changes/newsfragments/8441.improved.8

@@ -0,0 +1,6 @@
+The path arguments of ``connect_paths``, ``disconnect_paths``, ``are_closed``,
+``are_open`` and ``to_channel_list`` on the Keysight 34980A switch matrix
+submodules are now typed as a ``Collection`` rather than a ``list``, so a set or
+a tuple of paths is accepted as well. A ``Collection`` rather than an
+``Iterable`` because these methods walk the paths twice, once to validate them
+and once to build the channel list, which a one shot iterator would not survive.

docs/changes/newsfragments/8441.improved.9

@@ -0,0 +1,5 @@
+The live temperature plot helper in the two Lakeshore example notebooks keeps
+the appended y data in a local variable instead of reading it back with
+``Line2D.get_ydata``. The return of ``get_ydata`` is typed as ``ArrayLike``,
+which is not necessarily sized, so taking its length was a type error. This also
+avoids reading the data back from the line on every iteration.

docs/changes/newsfragments/8441.underthehood.1

@@ -0,0 +1,9 @@
+:class:`.Parameter` no longer replaces its own ``get_raw``/``set_raw`` methods
+with the implementation generated from ``get_cmd``/``set_cmd``. The generated
+implementation is stored on the parameter instead, and ``get_raw``/``set_raw``
+are now regular methods that dispatch to it. Assigning over the methods made
+static type checkers infer ``get_raw``/``set_raw`` to be instance attributes of
+:class:`.Parameter`, which in turn made every subclass implementing them as
+regular methods an invalid override. There is no change in behaviour; note only
+that ``parameter.get_raw`` is now always a bound method rather than, depending
+on the arguments, a ``Command`` instance.

docs/changes/newsfragments/8441.underthehood.2

@@ -0,0 +1,9 @@
+The ``TParameter`` type variable used by :meth:`.InstrumentBase.add_parameter`
+now defaults to ``Parameter[Any, Any]`` rather than to a bare ``Parameter``.
+When ``add_parameter`` is called without an explicit ``parameter_class`` the
+returned parameter is bound to the instrument it is added to, so the previous
+default (which expands to ``Parameter[Any, InstrumentBase | None]``) wrongly
+claimed that the instrument was ``InstrumentBase | None``. This made the result
+unassignable to the ``Parameter[SomeType, Self]`` annotations that drivers use.
+Code that relies on the inferred type of an unannotated
+``instrument.add_parameter("name")`` will now see ``Parameter[Any, Any]``.

docs/changes/newsfragments/8441.underthehood.3

@@ -0,0 +1,5 @@
+``DataSet._finalize_res_dict_standalones`` now appends to its result list
+directly instead of building intermediate lists. The intermediate lists took
+their element type from the branch that built them rather than from the
+declaration, and ``dict`` is invariant in its value type, so the result was not
+assignable back. There is no change in behaviour.

docs/changes/newsfragments/8441.underthehood.4

@@ -0,0 +1,4 @@
+The Alazar DLL wrapper no longer assumes that the callable handed to a ctypes
+``errcheck`` has a ``__name__``, which a plain ``Callable`` does not guarantee.
+The error message falls back to the repr of the callable instead. This only
+affects the text of an error that should not occur in practice.

docs/changes/newsfragments/8441.underthehood.5

@@ -0,0 +1,5 @@
+``numpy_ints`` and ``numpy_floats`` in ``qcodes.utils.types`` are now annotated
+as tuples of ``type[np.integer]`` and ``type[np.floating]`` rather than of bare
+``type``. As a consequence ``_adapt_float``, which is registered as a sqlite
+adapter for the numpy float types as well as for ``float``, now declares that it
+accepts ``np.floating`` too. Its behaviour is unchanged.

docs/changes/newsfragments/8441.underthehood.6

@@ -0,0 +1,5 @@
+The ``__getattr__`` that provides backwards-compatible access to the old flat
+parameter names on the Tektronix AWG5014 now names its parameter ``key``,
+matching ``DelegateAttributes.__getattr__`` which it overrides and delegates to.
+Python only ever calls ``__getattr__`` positionally, so this has no effect at
+runtime.

docs/changes/newsfragments/8441.underthehood.7

@@ -0,0 +1,5 @@
+``json_template_linear`` and ``json_template_heatmap`` in
+``qcodes.dataset.json_exporter`` are now annotated as ``dict[str, Any]``. They
+are templates for a JSON document, so their values are deliberately
+heterogeneous, and without the annotation the inferred value type made indexing
+into them an error for callers filling the template in.

docs/changes/newsfragments/8441.underthehood.8

@@ -0,0 +1,5 @@
+The type checker ``ty`` is now a test dependency and is run as part of the
+CI job that also runs ``mypy`` and ``pyright``. Unlike the other type
+checkers ``ty`` understands Jupyter notebooks, so this type checks the
+example notebooks in ``docs`` in addition to the source code in ``src``
+and the test suite. ``ty`` 0.0.87 or newer is required.

docs/conf.py

@@ -33,7 +33,7 @@
 # this should happen as early as possible
 import qcodes.instrument.instrument_meta
 
-qcodes.instrument.instrument_meta.InstrumentMeta = ABCMeta
+qcodes.instrument.instrument_meta.InstrumentMeta = ABCMeta  # ty: ignore[invalid-assignment]
 # we need to reload any module that has been imported and
 # makes use of this metaclass. The modules below are all imported
 # by importing qcodes.instrument so we need to reload them

docs/examples/DataSet/Accessing-data-in-DataSet.ipynb

@@ -710,26 +710,6 @@
     "dataset.get_parameters()"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": 24,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "'x,t,y,y2,q'"
-      ]
-     },
-     "execution_count": 24,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "dataset.parameters"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -1047,7 +1027,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "qcodes",
    "language": "python",
    "name": "python3"
   },
@@ -1061,7 +1041,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.12"
+   "version": "3.14.7"
   },
   "toc": {
    "base_numbering": 1,

docs/examples/DataSet/Exporting-data-to-other-file-formats.ipynb

@@ -1116,7 +1116,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 25,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
@@ -1131,6 +1131,12 @@
     }
    ],
    "source": [
+    "from qcodes.dataset.data_set_in_memory import DataSetInMem\n",
+    "\n",
+    "# the set_netcdf_location only exists for DataSetInMem so we validate that we are indeed using that.\n",
+    "if not isinstance(reloaded_ds, DataSetInMem):\n",
+    "    raise TypeError(\"reloaded_ds must be an instance of DataSetInMem\")\n",
+    "\n",
     "reloaded_ds.set_netcdf_location(new_file_path)\n",
     "reloaded_ds.export_info"
    ]

docs/examples/DataSet/Offline Plotting Tutorial.ipynb

@@ -477,6 +477,8 @@
    "outputs": [],
    "source": [
     "colorbar = colorbars[0]\n",
+    "# 2D plots have a colorbar, 1D plots do not, so the entries are optional\n",
+    "assert colorbar is not None\n",
     "colorbar.set_label(\"Correct science label\")"
    ]
   },
@@ -939,9 +941,11 @@
    "source": [
     "%%time\n",
     "axeslist, _ = plot_dataset(dataset)\n",
-    "axeslist[0].figure.savefig(\n",
-    "    Path.cwd().parent / \"example_output\" / f\"test_plot_dataset_{dataid}.pdf\"\n",
-    ")"
+    "# Axes.figure may be a SubFigure, which cannot be saved, so ask for the\n",
+    "# root figure\n",
+    "figure = axeslist[0].get_figure(root=True)\n",
+    "assert figure is not None\n",
+    "figure.savefig(Path.cwd().parent / \"example_output\" / f\"test_plot_dataset_{dataid}.pdf\")"
    ]
   },
   {
@@ -971,9 +975,11 @@
    "source": [
     "%%time\n",
     "axeslist, _ = plot_dataset(dataset, rasterized=False)\n",
-    "axeslist[0].figure.savefig(\n",
-    "    Path.cwd().parent / \"example_output\" / f\"test_plot_dataset_{dataid}.pdf\"\n",
-    ")"
+    "# Axes.figure may be a SubFigure, which cannot be saved, so ask for the\n",
+    "# root figure\n",
+    "figure = axeslist[0].get_figure(root=True)\n",
+    "assert figure is not None\n",
+    "figure.savefig(Path.cwd().parent / \"example_output\" / f\"test_plot_dataset_{dataid}.pdf\")"
    ]
   }
  ],

docs/examples/DataSet/Threaded data acquisition.ipynb

@@ -92,7 +92,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "id": "2add302b",
    "metadata": {
     "ExecuteTime": {
@@ -115,6 +115,17 @@
     "        time.sleep(0.1)\n",
     "        return val\n",
     "\n",
+    "    @property\n",
+    "    def root_instrument(self) -> \"DummyInstrumentWithMeasurement\":\n",
+    "        if self.instrument is None or not isinstance(\n",
+    "            self.instrument.root_instrument, DummyInstrumentWithMeasurement\n",
+    "        ):\n",
+    "            raise ValueError(\n",
+    "                \"SleepyDmmExponentialParameter must be bound to a DummyInstrumentWithMeasurement\"\n",
+    "            )\n",
+    "        instr = self.instrument.root_instrument\n",
+    "        return instr\n",
+    "\n",
     "    @staticmethod\n",
     "    def _exponential_decay(a: float, b: float):\n",
     "        x = 0\n",

docs/examples/DataSet/Using_doNd_functions_in_comparison_to_Measurement_context_manager_for_performing_measurements.ipynb

@@ -1404,7 +1404,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 24,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
@@ -1451,7 +1451,15 @@
     }
    ],
    "source": [
-    "result = dond(sweep_1, sweep_2, [dmm.v1], [dmm.v2], do_plot=True, show_progress=True)"
+    "result = dond(\n",
+    "    sweep_1,\n",
+    "    sweep_2,\n",
+    "    [dmm.v1],\n",
+    "    [dmm.v2],\n",
+    "    do_plot=True,\n",
+    "    show_progress=True,\n",
+    "    squeeze=False,\n",
+    ")"
    ]
   },
   {
@@ -1979,7 +1987,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "qcodes",
    "language": "python",
    "name": "python3"
   },
@@ -1993,7 +2001,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.7"
+   "version": "3.14.7"
   },
   "toc": {
    "base_numbering": 1,

docs/examples/DataSet/Working with snapshots.ipynb

@@ -593,7 +593,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "snapshot_of_run = dataset.snapshot"
+    "snapshot_of_run = dataset.snapshot\n",
+    "# a run only has a snapshot if one was recorded, this one has\n",
+    "assert snapshot_of_run is not None"
    ]
   },
   {
@@ -602,7 +604,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "snapshot_of_run_in_json_format = dataset.snapshot_raw"
+    "snapshot_of_run_in_json_format = dataset.snapshot_raw\n",
+    "assert snapshot_of_run_in_json_format is not None"
    ]
   },
   {
@@ -881,7 +884,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "diff_param_values(dataset.snapshot, bad_dataset.snapshot).changed"
+    "snapshot_of_bad_run = bad_dataset.snapshot\n",
+    "assert snapshot_of_bad_run is not None\n",
+    "\n",
+    "diff_param_values(snapshot_of_run, snapshot_of_bad_run).changed"
    ]
   },
   {