ENH: implementation of 'compare' API

Author: dmgav

src/save_and_restore_api/_api_async.py

@@ -220,6 +220,17 @@ async def restore_items(self, *, snapshotItems, auth=None):
         method, url, params = self._prepare_restore_items(snapshotItems=snapshotItems)
         return await self.send_request(method, url, params=params, auth=auth)
 
+    # =============================================================================================
+    #                     COMPARISON-CONTROLLER API METHODS
+    # =============================================================================================
+
+    async def compare(self, nodeId, *, tolerance=None, compareMode=None, skipReadback=None):
+        # Reusing docstrings from the threaded version
+        method, url, url_params = self._prepare_compare(
+            nodeId=nodeId, tolerance=tolerance, compareMode=compareMode, skipReadback=skipReadback
+        )
+        return await self.send_request(method, url, url_params=url_params)
+
 
 SaveRestoreAPI.info_get.__doc__ = _SaveRestoreAPI_Threads.info_get.__doc__
 SaveRestoreAPI.version_get.__doc__ = _SaveRestoreAPI_Threads.version_get.__doc__
@@ -246,3 +257,4 @@ async def restore_items(self, *, snapshotItems, auth=None):
 SaveRestoreAPI.snapshots_get.__doc__ = _SaveRestoreAPI_Threads.snapshots_get.__doc__
 SaveRestoreAPI.restore_node.__doc__ = _SaveRestoreAPI_Threads.restore_node.__doc__
 SaveRestoreAPI.restore_items.__doc__ = _SaveRestoreAPI_Threads.restore_items.__doc__
+SaveRestoreAPI.compare.__doc__ = _SaveRestoreAPI_Threads.compare.__doc__

src/save_and_restore_api/_api_base.py

@@ -328,6 +328,23 @@ def _prepare_restore_items(self, *, snapshotItems):
         params = snapshotItems
         return method, url, params
 
+    # =============================================================================================
+    #                     COMPARISON-CONTROLLER API METHODS
+    # =============================================================================================
+
+    def _prepare_compare(self, *, nodeId, tolerance, compareMode, skipReadback):
+        method, url = "GET", f"/compare/{nodeId}"
+        url_params = {}
+        if tolerance:
+            url_params["tolerance"] = tolerance
+        if compareMode:
+            url_params["compareMode"] = compareMode
+        if skipReadback is not None:
+            url_params["skipReadback"] = str(skipReadback).lower()
+        if not url_params:
+            url_params = None
+        return method, url, url_params
+
     # =============================================================================================
 
     # def create_config(self, parent_node_uid, name, pv_list):

src/save_and_restore_api/_api_threads.py

@@ -358,3 +358,20 @@ def restore_items(self, *, snapshotItems, auth=None):
         """
         method, url, params = self._prepare_restore_items(snapshotItems=snapshotItems)
         return self.send_request(method, url, params=params, auth=auth)
+
+    # =============================================================================================
+    #                     COMPARISON-CONTROLLER API METHODS
+    # =============================================================================================
+
+    def compare(self, nodeId, *, tolerance=None, compareMode=None, skipReadback=None):
+        """
+        Compare stored PV values with live values for the selected snapshot or composite snapshot.
+        The snapshot is selected by ``nodeId``. The API returns a list of results for each PV in
+        the snapshot.
+
+        API: GET /compare/{nodeId}
+        """
+        method, url, url_params = self._prepare_compare(
+            nodeId=nodeId, tolerance=tolerance, compareMode=compareMode, skipReadback=skipReadback
+        )
+        return self.send_request(method, url, url_params=url_params)

tests/test_compare_control.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from epics import caput
+
+from save_and_restore_api import SaveRestoreAPI as SaveRestoreAPI_Threads
+from save_and_restore_api.aio import SaveRestoreAPI as SaveRestoreAPI_Async
+
+from .common import (
+    _is_async,
+    _select_auth,
+    base_url,
+    clear_sar,  # noqa: F401
+    create_root_folder,
+    ioc,  # noqa: F401
+    ioc_pvs,
+)
+
+# =============================================================================================
+#                         TESTS FOR COMPARISON-CONTROLLER API METHODS
+# =============================================================================================
+
+
+# fmt: off
+@pytest.mark.parametrize("usesetauth", [True, False])
+@pytest.mark.parametrize("library", ["THREADS", "ASYNC"])
+# fmt: on
+def test_compare_01(clear_sar, ioc, library, usesetauth):  # noqa: F811
+    """
+    Basic tests for the 'compare' API.
+    """
+    root_folder_uid = create_root_folder()
+
+    if not _is_async(library):
+        with SaveRestoreAPI_Threads(base_url=base_url, timeout=10) as SR:
+            auth = _select_auth(SR=SR, usesetauth=usesetauth)
+
+            configurationNode = {"name": "Test Config"}
+            configurationData = {"pvList": [{"pvName": _} for _ in ioc_pvs.keys()]}
+
+            response = SR.config_create(
+                root_folder_uid,
+                configurationNode=configurationNode,
+                configurationData=configurationData,
+                **auth
+            )
+            config_uid = response["configurationNode"]["uniqueId"]
+
+            response = SR.take_snapshot_save(config_uid)
+            shot_uid = response["snapshotData"]["uniqueId"]
+
+            caput("simulated:C", 100)
+            caput("simulated:D", 200)
+
+            response = SR.compare(shot_uid)
+            pv_sim_C, pv_sim_D = None, None
+            for v in response:
+                if v["pvName"] == "simulated:C":
+                    pv_sim_C = v
+                if v["pvName"] == "simulated:D":
+                    pv_sim_D = v
+
+            assert pv_sim_C["equal"] is False
+            assert pv_sim_C["storedValue"]["value"] == 3
+            assert pv_sim_C["liveValue"]["value"] == 100
+            assert pv_sim_D["equal"] is False
+            assert pv_sim_D["storedValue"]["value"] == 4
+            assert pv_sim_D["liveValue"]["value"] == 200
+
+    else:
+        async def testing():
+            async with SaveRestoreAPI_Async(base_url=base_url, timeout=2) as SR:
+                auth = _select_auth(SR=SR, usesetauth=usesetauth)
+
+                configurationNode = {"name": "Test Config"}
+                configurationData = {"pvList": [{"pvName": _} for _ in ioc_pvs.keys()]}
+
+                response = await SR.config_create(
+                    root_folder_uid,
+                    configurationNode=configurationNode,
+                    configurationData=configurationData,
+                    **auth
+                )
+                config_uid = response["configurationNode"]["uniqueId"]
+
+                response = await SR.take_snapshot_save(config_uid)
+                shot_uid = response["snapshotData"]["uniqueId"]
+
+                caput("simulated:C", 100)
+                caput("simulated:D", 200)
+
+                response = await SR.compare(shot_uid)
+                pv_sim_C, pv_sim_D = None, None
+                for v in response:
+                    if v["pvName"] == "simulated:C":
+                        pv_sim_C = v
+                    if v["pvName"] == "simulated:D":
+                        pv_sim_D = v
+
+                assert pv_sim_C["equal"] is False
+                assert pv_sim_C["storedValue"]["value"] == 3
+                assert pv_sim_C["liveValue"]["value"] == 100
+                assert pv_sim_D["equal"] is False
+                assert pv_sim_D["storedValue"]["value"] == 4
+                assert pv_sim_D["liveValue"]["value"] == 200
+
+        asyncio.run(testing())