[DOC] Add flake8-docstrings and adapt the docstring and typing to it

docs/source/spelling_wordlist.txt

@@ -107,3 +107,5 @@ Waveforms
 superheterodyne
 customizations
 submodule
+Enum
+boolean

scripts/__init__.py

@@ -0,0 +1 @@
+"""Package containing a set of scripts to ease the use of this project."""

scripts/generate_notebooks.py

@@ -17,8 +17,9 @@
 def download_example_file(filename: str) -> bytes:
     """Download example file.
 
-    Arguments:
+    Args:
         filename: notebook filename.
+
     Returns:
         Notebook contents
     """
@@ -43,7 +44,7 @@ def get_notebook_examples() -> None:
 def generate_and_sync_example_notebooks(src: t.List[Path]) -> None:
     """Generate and sync given source files to notebooks.
 
-    Arguments:
+    Args:
         src: Source files
     """
     str_path = [str(path) for path in src]
@@ -53,7 +54,7 @@ def generate_and_sync_example_notebooks(src: t.List[Path]) -> None:
 def generate_notebooks(args: argparse.Namespace) -> None:
     """Generate notebooks either from local or remote.
 
-    Arguments:
+    Args:
         args: Namespace arguments
     """
     if args.src == "local":

scripts/zhinst_toolkit_symlink.py

@@ -1,4 +1,6 @@
-"""A helper script for developers to create symbolic link between existing toolkit and
+"""Helper script for developers.
+
+The script creates a symbolic link between existing toolkit and
 Python environment directories.
 
 By running the script, zhinst-toolkit is added to the ``zhinst`` package namespace
@@ -10,7 +12,7 @@
 
 Running the script:
 
-    >>> python scripts\\zhinst_toolkit_symlink.py
+    >>> python scripts/zhinst_toolkit_symlink.py
 """
 import os
 import sysconfig
@@ -22,8 +24,14 @@
 
 
 def create_symlink(src: Path, dest: Path) -> None:
-    """Create symbolic link between existing toolkit and
+    """Create symbolic link between working dir and python environment.
+
+    Create symbolic link between existing toolkit and
     Python environment directories.
+
+    Args:
+        src: Toolkit directory (e.g. a/b/src/zhinst/toolkit).
+        dest: Python environment directory
     """
     try:
         # Windows: Requires administrator when running tests without symlink

setup.cfg

@@ -66,25 +66,15 @@ exclude =
 per-file-ignores =
     # disable unused-imports errors on __init__.py
     __init__.py: F401
+docstring-convention=google
 
 [mypy]
 ignore_missing_imports = True
 exclude = (?x)(
-    src/zhinst/toolkit/nodetree/helper\.py$
-    | src/zhinst/toolkit/command_table\.py$
+    src/zhinst/toolkit/command_table\.py$
     | src/zhinst/toolkit/nodetree/nodetree\.py$
     | src/zhinst/toolkit/nodetree/node\.py$
-    | src/zhinst/toolkit/nodetree/connection_dict\.py$
-    | src/zhinst/toolkit/driver/modules/base_module\.py$
-    | src/zhinst/toolkit/driver/modules/shfqa_sweeper\.py$
-    | src/zhinst/toolkit/driver/modules/daq_module\.py$
-    | src/zhinst/toolkit/driver/modules/sweeper_module\.py$
-    | src/zhinst/toolkit/driver/devices/uhfqa\.py$
-    | src/zhinst/toolkit/driver/devices/hdawg\.py$
-    | src/zhinst/toolkit/driver/devices/base\.py$
-    | src/zhinst/toolkit/driver/nodes/readout\.py$
-    | src/zhinst/toolkit/driver/nodes/spectroscopy\.py$
-    | src/zhinst/toolkit/driver/nodes/command_table_node\.py$
-    | src/zhinst/toolkit/driver/nodes/generator\.py$
-    | src/zhinst/toolkit/driver/nodes/awg\.py$
+    | src/zhinst/toolkit/nodetree/connection_dict\.py$ # Weird dict problem
+    | src/zhinst/toolkit/driver/modules/shfqa_sweeper\.py$ # Weird dict problem
+    | src/zhinst/toolkit/driver/devices/uhfqa\.py$ # Numpy array
   )

src/zhinst/toolkit/__init__.py

@@ -2,7 +2,7 @@
 #
 # This software may be modified and distributed under the terms
 # of the MIT license. See the LICENSE file for details.
-"""The Zurich Instruments Toolkit (zhinst-toolkit)
+"""The Zurich Instruments Toolkit (zhinst-toolkit).
 
 This package is a collection of Python tools for high level device
 control. Based on the native interface to Zurich Instruments LabOne,

src/zhinst/toolkit/command_table.py

@@ -143,6 +143,7 @@ def info(self, value: t.Optional[str] = None) -> dict:
         Args:
             value: Info about to specific property. Otherwise
                 return info about the whole property.
+
         Returns:
             Info about the property.
         """
@@ -236,8 +237,10 @@ def _derefence_json(schema: t.Union[str, dict]) -> t.Any:
 
     Args:
         schema: JSON schema as a string or dictionary.
+
     Returns:
         Dereferenced schema.
+
     Raises:
         ValueError: Wrong `schema` type.
     """
@@ -260,7 +263,6 @@ class CommandTable:
         json_schema: JSON Schema of the command table.
 
     Example:
-
     .. code-block:: python
 
         from zhinst.toolkit import CommandTable

src/zhinst/toolkit/driver/devices/base.py

@@ -1,4 +1,4 @@
-"""Base Instrument Driver
+"""Base Instrument Driver.
 
 Natively works with all device types and provides the basic functionality like
 the device specific nodetree.
@@ -111,14 +111,14 @@ def _version_string_to_tuple(version: str) -> t.Tuple[int, int, int]:
             except ValueError:
                 if i < 3:  # ignore dev verisons
                     result[i] = 0
-        return tuple(result)
+        return result[0], result[1], result[2]
 
     @staticmethod
     def _check_python_versions(
         zi_python_version: t.Tuple[int, int, int],
         zi_utils_version: t.Tuple[int, int, int],
     ) -> None:
-        """Check if the minimum required zhinst packages are installed
+        """Check if the minimum required zhinst packages are installed.
 
         Checks if all zhinst packages that toolkit require have the minimum
         required version installed.
@@ -322,5 +322,5 @@ def serial(self) -> str:
 
     @property
     def device_type(self) -> str:
-        """Type of the instrument (e.g. MFLI)"""
+        """Type of the instrument (e.g. MFLI)."""
         return self._device_type

src/zhinst/toolkit/driver/devices/hdawg.py

@@ -14,7 +14,7 @@ class HDAWG(BaseInstrument):
     """High-level driver for the Zurich Instruments HDAWG."""
 
     def enable_qccs_mode(self) -> None:
-        """Configure the instrument to work with PQSC
+        """Configure the instrument to work with PQSC.
 
         This method sets the reference clock source to
         connect the instrument to the PQSC.
@@ -41,7 +41,7 @@ def enable_qccs_mode(self) -> None:
 
     @lazy_property
     def awgs(self) -> t.Sequence[AWG]:
-        """A Sequence of AWG Cores"""
+        """A Sequence of AWG Cores."""
         return NodeList(
             [
                 AWG(

src/zhinst/toolkit/driver/devices/shfqa.py

@@ -76,7 +76,7 @@ def configure_channel(
 
     @lazy_property
     def generator(self) -> Generator:
-        """Generator"""
+        """Generator."""
         return Generator(
             self._root,
             self._tree + ("generator",),
@@ -88,7 +88,7 @@ def generator(self) -> Generator:
 
     @lazy_property
     def readout(self) -> Readout:
-        """Readout"""
+        """Readout."""
         return Readout(
             self._root,
             self._tree + ("readout",),
@@ -100,7 +100,7 @@ def readout(self) -> Readout:
 
     @lazy_property
     def spectroscopy(self) -> Spectroscopy:
-        """Spectroscopy"""
+        """Spectroscopy."""
         return Spectroscopy(
             self._root,
             self._tree + ("spectroscopy",),
@@ -139,7 +139,6 @@ def start_continuous_sw_trigger(
             num_triggers: Number of triggers to be issued
             wait_time: Time between triggers in seconds
         """
-
         deviceutils.start_continuous_sw_trigger(
             self._session.daq_server,
             self.serial,
@@ -154,7 +153,7 @@ def max_qubits_per_channel(self) -> int:
 
     @lazy_property
     def qachannels(self) -> t.Sequence[QAChannel]:
-        """A Sequence of QAChannels"""
+        """A Sequence of QAChannels."""
         return NodeList(
             [
                 QAChannel(self, self._session, self._tree + ("qachannels", str(i)))
@@ -166,7 +165,7 @@ def qachannels(self) -> t.Sequence[QAChannel]:
 
     @lazy_property
     def scopes(self) -> t.Sequence[SHFScope]:
-        """A Sequence of SHFScopes"""
+        """A Sequence of SHFScopes."""
         return NodeList(
             [
                 SHFScope(

src/zhinst/toolkit/driver/devices/shfsg.py

@@ -19,7 +19,7 @@
 
 
 class AWGCore(AWG):
-    """AWG Core Node"""
+    """AWG Core Node."""
 
     def configure_marker_and_trigger(
         self,
@@ -222,7 +222,7 @@ def awg_modulation_freq(self) -> float:
 
     @lazy_property
     def awg(self) -> AWGCore:
-        """AWG"""
+        """AWG."""
         return AWGCore(
             self._root,
             self._tree + ("awg",),
@@ -249,7 +249,7 @@ def factory_reset(self, *, deep: bool = True) -> None:
 
     @lazy_property
     def sgchannels(self) -> t.Sequence[SGChannel]:
-        """A Sequence of SG Channels"""
+        """A Sequence of SG Channels."""
         return NodeList(
             [
                 SGChannel(self, self._session, self._tree + ("sgchannels", str(i)))

src/zhinst/toolkit/driver/devices/uhfqa.py

@@ -45,14 +45,12 @@ def write_integration_weights(self, weights: t.Union[Waveforms, dict]) -> None:
                 keys correspond to the indices of the integration weights to be
                 configured.
 
-        note:
-
+        Note:
             Does not raise an error when sample limit is exceeded, but applies only
             the maximum number of samples. Please refer to LabOne node documentation
             for the number of maximum integration weight samples.
 
-        note:
-
+        Note:
             This function calls both `/qas/n/integration/weights/n/real` and
             `/qas/n/integration/weights/n/imag` nodes.
 
@@ -121,6 +119,7 @@ def crosstalk_matrix(self, matrix: Numpy2DArray = None) -> t.Optional[Numpy2DArr
             for r in range(rows):
                 for c in range(cols):
                     self.crosstalk.rows[r].cols[c](matrix[r, c])
+        return None
 
     def adjusted_delay(self, value: int = None) -> int:
         """Set or get the adjustment in the quantum analyzer delay.
@@ -166,7 +165,7 @@ def adjusted_delay(self, value: int = None) -> int:
 
     @lazy_property
     def integration(self) -> Integration:
-        """Integration
+        """Integration.
 
         .. versionadded:: 0.3.2
         """
@@ -202,7 +201,7 @@ def enable_qccs_mode(self) -> None:
 
     @lazy_property
     def qas(self) -> t.Sequence[QAS]:
-        """A Sequence of QAS"""
+        """A Sequence of QAS."""
         return NodeList(
             [
                 QAS(self.root, self._tree + ("qas", str(i)))

src/zhinst/toolkit/driver/modules/__init__.py

@@ -1,3 +1,4 @@
+"""Module for toolkit representations of native LabOne modules."""
 import typing as t
 
 from zhinst.toolkit.driver.modules.base_module import BaseModule

src/zhinst/toolkit/driver/modules/base_module.py

@@ -1,4 +1,4 @@
-"""Base Module Driver
+"""Base Module Driver.
 
 Natively works with all module types and provides the basic functionality like
 the module specific nodetree.
@@ -7,6 +7,7 @@
 import time
 import typing as t
 
+from zhinst.ziPython import ModuleBase
 from zhinst.toolkit.nodetree import Node, NodeTree
 
 logger = logging.getLogger(__name__)
@@ -15,7 +16,7 @@
     from zhinst.toolkit.driver.devices import DeviceType
     from zhinst.toolkit.session import Session
 
-ZIModule = t.TypeVar("ZIModule")
+ZIModule = t.TypeVar("ZIModule", bound=ModuleBase)
 
 
 class BaseModule(Node):
@@ -77,7 +78,7 @@ def _set_device(value: t.Union["DeviceType", str]) -> str:
             str: device serial
         """
         try:
-            return value.serial
+            return value.serial  # type: ignore
         except AttributeError:
             return value
 
@@ -111,7 +112,7 @@ def _set_node(signal: t.Union[Node, str]) -> str:
             str: raw string node
         """
         try:
-            node = signal.node_info.path
+            node = signal.node_info.path  # type: ignore
         except AttributeError:
             node = signal
         return node
@@ -126,6 +127,7 @@ def wait_done(self, *, timeout: float = 20.0, sleep_time: float = 0.5) -> None:
                 measurement (default: 20).
             sleep_time (int): Time in seconds to wait between
                 requesting sweeper state. (default: 0.5)
+
         Raises:
             TimeoutError: The measurement is not completed before
                 timeout.

src/zhinst/toolkit/driver/modules/daq_module.py

@@ -82,7 +82,7 @@ def _set_node(signal: t.Union[Node, str]) -> str:
             str: A raw string representation of Node
         """
         try:
-            node = signal.node_info.path
+            node = signal.node_info.path  # type: ignore
         except AttributeError:
             node = signal
         sample_pos = node.find("sample")