Merge #4355 #4358

4355: API: Split metadata module and make public r=jenshnielsen a=jenshnielsen

Move functions that need to know about dataset to that module
and extend with a function that takes dataset rather than runid

Split Metadatable class and shapshot diff functions into different
submodules and make all public


4358: Remove deprecated units from data array r=jenshnielsen a=jenshnielsen

This was missed as part of #4330 

Co-authored-by: Jens H. Nielsen <[email protected]>
Co-authored-by: Jens Hedegaard Nielsen <[email protected]>

docs/api/index.rst

@@ -24,6 +24,7 @@ QCoDeS API
    interactive_widget
    logger/index
    math_utils/index
+   metadatable/index
    monitor/index
    parameters/index
    plotting/index

docs/api/metadatable/index.rst

@@ -0,0 +1,7 @@
+.. _metadatable_api :
+
+qcodes.metadatable
+==================
+
+.. automodule:: qcodes.metadatable
+    :autosummary:

docs/api/utils/index.rst

@@ -3,18 +3,6 @@
 qcodes.utils
 ============
 
-
-.. autosummary::
-
-    qcodes.utils
-    qcodes.utils.metadata
-
 .. automodule:: qcodes.utils
     :no-inherited-members:
     :autosummary:
-
-.. toctree::
-   :maxdepth: 4
-   :hidden:
-
-   metadata

qcodes/data/data_array.py

@@ -536,11 +536,6 @@ def fraction_complete(self):
 
         return (last_index + 1) / self.ndarray.size
 
-    @property
-    def units(self):
-        warn_units('DataArray', self)
-        return self.unit
-
     def to_xarray(self) -> "xr.DataArray":
         """ Return this DataArray as an xarray dataarray
 

qcodes/dataset/snapshot_utils.py

@@ -0,0 +1,36 @@
+from qcodes.utils import ParameterDiff, diff_param_values
+
+from .data_set import load_by_id
+from .data_set_protocol import DataSetProtocol
+
+
+def diff_param_snapshots(
+    left: DataSetProtocol, right: DataSetProtocol
+) -> ParameterDiff:
+    """
+    Given two datasets, returns the differences between
+    parameter values in each of their snapshots.
+    """
+    left_snapshot = left.snapshot
+    right_snapshot = right.snapshot
+
+    if left_snapshot is None or right_snapshot is None:
+        if left_snapshot is None:
+            empty = left
+        else:
+            empty = right
+        raise RuntimeError(
+            f"Tried to compare two snapshots"
+            f"but the snapshot of {empty.run_id} "
+            f"is empty."
+        )
+
+    return diff_param_values(left_snapshot, right_snapshot)
+
+
+def diff_param_values_by_id(left_id: int, right_id: int) -> ParameterDiff:
+    """
+    Given the IDs of two datasets, returns the differences between
+    parameter values in each of their snapshots.
+    """
+    return diff_param_snapshots(load_by_id(left_id), load_by_id(right_id))

qcodes/instrument/channel.py

@@ -18,6 +18,7 @@
     overload,
 )
 
+from qcodes.metadatable import Metadatable
 from qcodes.parameters import (
     ArrayParameter,
     MultiChannelInstrumentParameter,
@@ -28,7 +29,6 @@
 from qcodes.utils import full_class
 from qcodes.validators import Validator
 
-from ..utils.metadata import Metadatable
 from .instrument import Instrument
 from .instrument_base import InstrumentBase
 

qcodes/instrument/instrument_base.py

@@ -18,9 +18,9 @@
 import numpy as np
 
 from qcodes.logger import get_instrument_logger
+from qcodes.metadatable import Metadatable
 from qcodes.parameters import Function, Parameter, ParameterBase
 from qcodes.utils import DelegateAttributes, full_class
-from qcodes.utils.metadata import Metadatable
 
 if TYPE_CHECKING:
     from qcodes.instrument.channel import ChannelTuple, InstrumentModule

qcodes/loops.py

@@ -48,9 +48,9 @@
 
 from qcodes.data.data_array import DataArray
 from qcodes.data.data_set import new_data
+from qcodes.metadatable import Metadatable
 from qcodes.station import Station
 from qcodes.utils import full_class
-from qcodes.utils.metadata import Metadatable
 
 from .actions import (
     BreakIf,

qcodes/measure.py

@@ -3,9 +3,9 @@
 
 from qcodes.actions import _actions_snapshot
 from qcodes.loops import Loop
+from qcodes.metadatable import Metadatable
 from qcodes.parameters import Parameter
 from qcodes.utils import full_class
-from qcodes.utils.metadata import Metadatable
 
 
 class Measure(Metadatable):

qcodes/metadatable/__init__.py

@@ -0,0 +1,3 @@
+from .metadatable_base import Metadatable
+
+__all__ = ["Metadatable"]

qcodes/metadatable/metadatable_base.py

@@ -0,0 +1,59 @@
+from typing import Any, Dict, Mapping, Optional, Sequence
+
+from qcodes.utils import deep_update
+
+# NB: At the moment, the Snapshot type is a bit weak, as the Any
+#     for the value type doesn't tell us anything about the schema
+#     followed by snapshots.
+#     This is needed, however, since snapshots are Dict instances with
+#     homogeneous keys and heterogeneous values, something that
+#     recent Python versions largely replace with features like
+#     typing.NamedTuple and @dataclass.
+#     As those become more widely available, the weakness of this
+#     type constraint will become less of an issue.
+Snapshot = Dict[str, Any]
+
+
+class Metadatable:
+    def __init__(self, metadata: Optional[Mapping[str, Any]] = None):
+        self.metadata: Dict[str, Any] = {}
+        self.load_metadata(metadata or {})
+
+    def load_metadata(self, metadata: Mapping[str, Any]) -> None:
+        """
+        Load metadata into this classes metadata dictionary.
+
+        Args:
+            metadata: Metadata to load.
+        """
+        deep_update(self.metadata, metadata)
+
+    def snapshot(self, update: Optional[bool] = False) -> Snapshot:
+        """
+        Decorate a snapshot dictionary with metadata.
+        DO NOT override this method if you want metadata in the snapshot
+        instead, override :meth:`snapshot_base`.
+
+        Args:
+            update: Passed to snapshot_base.
+
+        Returns:
+            Base snapshot.
+        """
+
+        snap = self.snapshot_base(update=update)
+
+        if len(self.metadata):
+            snap["metadata"] = self.metadata
+
+        return snap
+
+    def snapshot_base(
+        self,
+        update: Optional[bool] = False,
+        params_to_skip_update: Optional[Sequence[str]] = None,
+    ) -> Snapshot:
+        """
+        Override this with the primary information for a subclass.
+        """
+        return {}

qcodes/parameters/combined_parameter.py

@@ -6,8 +6,8 @@
 
 import numpy as np
 
+from qcodes.metadatable import Metadatable
 from qcodes.utils import full_class
-from qcodes.utils.metadata import Metadatable
 
 from .parameter import Parameter
 

qcodes/parameters/function.py

@@ -1,6 +1,6 @@
 from typing import TYPE_CHECKING, Any, Callable, List, Optional, Sequence, Union
 
-from qcodes.utils.metadata import Metadatable
+from qcodes.metadatable import Metadatable
 from qcodes.validators import Validator, validate_all
 
 from .command import Command

qcodes/parameters/parameter_base.py

@@ -21,8 +21,8 @@
     overload,
 )
 
+from qcodes.metadatable import Metadatable
 from qcodes.utils import DelegateAttributes, full_class, qcodes_abstractmethod
-from qcodes.utils.metadata import Metadatable
 from qcodes.validators import Enum, Ints, Validator
 
 from .cache import _Cache, _CacheProtocol

qcodes/parameters/sweep_values.py

@@ -13,7 +13,7 @@
 
 import numpy as np
 
-from qcodes.utils.metadata import Metadatable
+from qcodes.metadatable import Metadatable
 
 from .named_repr import named_repr
 from .permissive_range import permissive_range

qcodes/station.py

@@ -40,6 +40,7 @@
 from qcodes import validators
 from qcodes.instrument.base import Instrument, InstrumentBase
 from qcodes.instrument.channel import ChannelTuple
+from qcodes.metadatable import Metadatable
 from qcodes.monitor.monitor import Monitor
 from qcodes.parameters import (
     DelegateParameter,
@@ -54,7 +55,6 @@
     get_qcodes_user_path,
     issue_deprecation_warning,
 )
-from qcodes.utils.metadata import Metadatable
 
 log = logging.getLogger(__name__)
 

qcodes/tests/common.py

@@ -9,7 +9,7 @@
 
 import qcodes
 from qcodes.configuration import Config, DotDict
-from qcodes.utils.metadata import Metadatable
+from qcodes.metadatable import Metadatable
 
 if TYPE_CHECKING:
     from pytest import ExceptionInfo

qcodes/tests/test_metadata.py

@@ -1,6 +1,7 @@
 import pytest
 
-from qcodes.utils.metadata import Metadatable, diff_param_values
+from qcodes.metadatable import Metadatable
+from qcodes.utils import diff_param_values
 
 
 class HasSnapshotBase(Metadatable):

qcodes/utils/__init__.py

@@ -20,20 +20,24 @@
 from .numpy_utils import list_of_data_to_maybe_ragged_nd_array
 from .partial_utils import partial_with_docstring
 from .path_helpers import get_qcodes_path, get_qcodes_user_path
+from .snapshot_helpers import ParameterDiff, diff_param_values, extract_param_values
 from .spyder_utils import add_to_spyder_UMR_excludelist
 from .threading_utils import RespondingThread, thread_map
 
 __all__ = [
     "DelayedKeyboardInterrupt",
     "DelegateAttributes",
     "NumpyJSONEncoder",
+    "ParameterDiff",
     "QCoDeSDeprecationWarning",
     "RespondingThread",
     "attribute_set_to",
     "checked_getattr",
     "convert_legacy_version_to_supported_version",
     "deep_update",
     "deprecate",
+    "diff_param_values",
+    "extract_param_values",
     "full_class",
     "get_all_installed_package_versions",
     "get_qcodes_path",