ENH: implementation and tests for take_snapshot_get API

Author: dmgav

container/create_env_file.py

@@ -1,10 +1,12 @@
-import socket
+# import socket
 
 if __name__ == "__main__":
     # Get the local IP address
-    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
-    s.connect(("8.8.8.8", 80))
-    ip = s.getsockname()[0]
+    # s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    # s.connect(("8.8.8.8", 80))
+    # ip = s.getsockname()[0]
+
+    ip = "127.0.0.1"
 
     with open(".env", "w") as f:
         f.write(f"HOST_EXTERNAL_IP_ADDRESS={ip}")

container/save-and-restore.yml

@@ -1,13 +1,15 @@
 services:
   saveandrestore:
-    image: ghcr.io/controlsystemstudio/phoebus/service-save-and-restore:master
-    ports:
-      - "8080:8080"
+    image: ghcr.io/controlsystemstudio/phoebus/service-save-and-restore:v5.0.2
+    network_mode: "host"
+    # ports:
+    #   - "8080:8080"
     depends_on:
       - elasticsearch
     environment:
       ELASTICSEARCH_NETWORK_HOST: ${HOST_EXTERNAL_IP_ADDRESS}
       EPICS_PVA_ADDR_LIST: ${HOST_EXTERNAL_IP_ADDRESS}
+      EPICS_PVAS_INTF_ADDR_LIST: ${HOST_EXTERNAL_IP_ADDRESS}
       EPICS_PVA_AUTO_ADDR_LIST: "NO"
       EPICS_PVA_ENABLE_IPV6: "false"
     command: >
@@ -22,8 +24,9 @@ services:
 
   elasticsearch:
     image: docker.elastic.co/elasticsearch/elasticsearch:8.11.2
-    ports:
-      - "9200:9200"
+    network_mode: "host"
+    # ports:
+    #   - "9200:9200"
     environment:
       discovery.type: single-node
       bootstrap.memory_lock: "true"

ioc/sim_ioc.py

@@ -9,15 +9,16 @@
 
 # Create records
 AA = builder.aOut("A", initial_value=1.0)
-BB = builder.aOut("B", initial_value=1.0)
-CC = builder.aOut("C", initial_value=1.0)
-DD = builder.aOut("D", initial_value=1.0)
-EE = builder.aOut("E", initial_value=1.0)
-FF = builder.aOut("F", initial_value=1.0)
-GG = builder.aOut("G", initial_value=1.0)
-HH = builder.aOut("H", initial_value=1.0)
-II = builder.aOut("I", initial_value=1.0)
-JJ = builder.aOut("J", initial_value=1.0)
+BB = builder.aOut("B", initial_value=2.0)
+CC = builder.aOut("C", initial_value=3.0)
+DD = builder.aOut("D", initial_value=4.0)
+EE = builder.aOut("E", initial_value=5.0)
+FF = builder.aOut("F", initial_value=6.0)
+GG = builder.aOut("G", initial_value=7.0)
+HH = builder.aOut("H", initial_value=8.0)
+II = builder.aOut("I", initial_value=9.0)
+JJ = builder.aOut("J", initial_value=10.0)
+
 
 # Get the IOC started
 builder.LoadDatabase()

ioc/sim_ioc_caproto.py ioc/sim_ioc2.pyioc/sim_ioc_caproto.py renamed to ioc/sim_ioc2.py

@@ -41,7 +41,6 @@ dev = [
   "pytest-asyncio",
   "pre-commit",
   "ruff",
-  # "caproto !=1.2.0",
   "softioc",
   "pyepics",
 ]

pyproject.toml

@@ -60,10 +60,10 @@ async def nodes_get(self, uniqueIds):
 
     async def node_add(self, parentNodeId, *, name, nodeType, auth=None, **kwargs):
         # Reusing docstrings from the threaded version
-        method, url, params = self._prepare_node_add(
+        method, url, url_params, params = self._prepare_node_add(
             parentNodeId=parentNodeId, name=name, nodeType=nodeType, **kwargs
         )
-        return await self.send_request(method, url, params=params, auth=auth)
+        return await self.send_request(method, url, url_params=url_params, params=params, auth=auth)
 
     async def node_delete(self, nodeId, *, auth=None):
         # Reusing docstrings from the threaded version
@@ -113,34 +113,36 @@ async def config_update(self, *, configurationNode, configurationData=None, auth
     # =============================================================================================
 
     async def tags_get(self):
-        """
-        Returns all existing tags.
-
-        API: GET /tags
-        """
+        # Reusing docstrings from the threaded version
         method, url = self._prepare_tags_get()
         return await self.send_request(method, url)
 
     async def tags_add(self, *, uniqueNodeIds, tag, auth=None):
-        """
-        Adds ``tag`` to nodes specified by a list of UIDs ``uniqueNodeIds``. The ``tag``
-        dictionary must contain the ``name`` key and optionally ``comment`` key.
-
-        API: POST /tags
-        """
+        # Reusing docstrings from the threaded version
         method, url, params = self._prepare_tags_add(uniqueNodeIds=uniqueNodeIds, tag=tag)
         return await self.send_request(method, url, params=params, auth=auth)
 
     async def tags_delete(self, *, uniqueNodeIds, tag, auth=None):
-        """
-        Deletes ``tag`` to nodes specified by a list of UIDs ``uniqueNodeIds``. The ``tag``
-        dictionary must contain the ``name`` key and optionally ``comment`` key.
-
-        API: DELETE /tags
-        """
+        # Reusing docstrings from the threaded version
         method, url, params = self._prepare_tags_delete(uniqueNodeIds=uniqueNodeIds, tag=tag)
         return await self.send_request(method, url, params=params, auth=auth)
 
+    # =============================================================================================
+    #                         TAKE-SNAPSHOT-CONTROLLER API METHODS
+    # =============================================================================================
+
+    def take_snapshot_get(self, uniqueNodeId):
+        # Reusing docstrings from the threaded version
+        method, url = self._prepare_take_snapshot_get(uniqueNodeId=uniqueNodeId)
+        return self.send_request(method, url)
+
+    def take_snapshot_save(self, uniqueNodeId, *, name=None, comment=None, auth=None):
+        # Reusing docstrings from the threaded version
+        method, url, url_params = self._prepare_take_snapshot_save(
+            uniqueNodeId=uniqueNodeId, name=name, comment=comment
+        )
+        return self.send_request(method, url, url_params=url_params, auth=auth)
+
 
 SaveRestoreAPI.node_get.__doc__ = _SaveRestoreAPI_Threads.node_get.__doc__
 SaveRestoreAPI.nodes_get.__doc__ = _SaveRestoreAPI_Threads.nodes_get.__doc__
@@ -155,3 +157,5 @@ async def tags_delete(self, *, uniqueNodeIds, tag, auth=None):
 SaveRestoreAPI.tags_get.__doc__ = _SaveRestoreAPI_Threads.tags_get.__doc__
 SaveRestoreAPI.tags_add.__doc__ = _SaveRestoreAPI_Threads.tags_add.__doc__
 SaveRestoreAPI.tags_delete.__doc__ = _SaveRestoreAPI_Threads.tags_delete.__doc__
+SaveRestoreAPI.take_snapshot_get.__doc__ = _SaveRestoreAPI_Threads.take_snapshot_get.__doc__
+SaveRestoreAPI.take_snapshot_save.__doc__ = _SaveRestoreAPI_Threads.take_snapshot_save.__doc__

src/save_and_restore_api/_api_async.py

@@ -181,10 +181,10 @@ def _prepare_node_add(self, *, parentNodeId, name, nodeType, **kwargs):
         node_types = ("FOLDER", "CONFIGURATION")
         if nodeType not in node_types:
             raise self.RequestParameterError(f"Invalid nodeType: {nodeType!r}. Supported types: {node_types}.")
-        method, url = "PUT", f"/node?parentNodeId={parentNodeId}"
+        method, url, url_params = "PUT", "/node", {"parentNodeId": parentNodeId}
         params = kwargs
         params.update({"name": name, "nodeType": nodeType})
-        return method, url, params
+        return method, url, url_params, params
 
     def _prepare_node_delete(self, *, nodeId):
         method, url = "DELETE", f"/node/{nodeId}"
@@ -241,6 +241,19 @@ def _prepare_tags_delete(self, *, uniqueNodeIds, tag):
         params = {"uniqueNodeIds": uniqueNodeIds, "tag": tag}
         return method, url, params
 
+    # =============================================================================================
+    #                         TAKE-SNAPSHOT-CONTROLLER API METHODS
+    # =============================================================================================
+
+    def _prepare_take_snapshot_get(self, *, uniqueNodeId):
+        method, url = "GET", f"/take-snapshot/{uniqueNodeId}"
+        return method, url
+
+    def _prepare_take_snapshot_save(self, *, uniqueNodeId, name, comment):
+        method, url = "PUT", "/take-snapshot"
+        url_params = {"name": name, "comment": comment}
+        return method, url, url_params
+
     # =============================================================================================
 
     # def create_config(self, parent_node_uid, name, pv_list):

src/save_and_restore_api/_api_base.py

@@ -72,10 +72,10 @@ def node_add(self, parentNodeId, *, name, nodeType, auth=None, **kwargs):
 
         API: PUT /node?parentNodeId={parentNodeId}
         """
-        method, url, params = self._prepare_node_add(
+        method, url, url_params, params = self._prepare_node_add(
             parentNodeId=parentNodeId, name=name, nodeType=nodeType, **kwargs
         )
-        return self.send_request(method, url, params=params, auth=auth)
+        return self.send_request(method, url, url_params=url_params, params=params, auth=auth)
 
     def node_delete(self, nodeId, *, auth=None):
         """
@@ -137,7 +137,7 @@ def config_create(self, parentNodeId, *, configurationNode, configurationData, a
         Minimum required fields:
 
         configurationNode = {"name": "test_config"}
-        configurationData = {"pvList": [{"name": "PV1"}, {"name": "PV2"}]}
+        configurationData = {"pvList": [{"pvName": "PV1"}, {"pvName": "PV2"}]}
 
         The fields ``uniqueId``, ``nodeType``, ``userName`` in ``configurationNode`` are ignored
         and overwritten by the server.
@@ -197,3 +197,30 @@ def tags_delete(self, *, uniqueNodeIds, tag, auth=None):
         """
         method, url, params = self._prepare_tags_delete(uniqueNodeIds=uniqueNodeIds, tag=tag)
         return self.send_request(method, url, params=params, auth=auth)
+
+    # =============================================================================================
+    #                         TAKE-SNAPSHOT-CONTROLLER API METHODS
+    # =============================================================================================
+
+    def take_snapshot_get(self, uniqueNodeId):
+        """
+        Reads and returns PV values based on configuration specified by ``uniqueNodeId``.
+        The API does not create any nodes in the database.
+
+        API: GET /take-snapshot/{uniqueNodeId}
+        """
+        method, url = self._prepare_take_snapshot_get(uniqueNodeId=uniqueNodeId)
+        return self.send_request(method, url)
+
+    def take_snapshot_save(self, uniqueNodeId, *, name=None, comment=None, auth=None):
+        """
+        Reads PV values based on configuration specified by ``uniqueNodeId`` and
+        saves the values in a new snapshot node. The parameter ``name`` specifies
+        the name of the snapshot node and ``comment`` specifies the node description.
+
+        API: PUT /take-snapshot/{uniqueNodeId}
+        """
+        method, url, url_params = self._prepare_take_snapshot_save(
+            uniqueNodeId=uniqueNodeId, name=name, comment=comment
+        )
+        return self.send_request(method, url, url_params=url_params, auth=auth)

src/save_and_restore_api/_api_threads.py

@@ -1,17 +1,19 @@
 from __future__ import annotations
 
-# import asyncio
-# import pytest
+import asyncio
+
+import pytest
 from epics import caget
 
-# from save_and_restore_api import SaveRestoreAPI as SaveRestoreAPI_Threads
-# from save_and_restore_api.aio import SaveRestoreAPI as SaveRestoreAPI_Async
+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,
+    _is_async,
+    _select_auth,
+    base_url,
     clear_sar,  # noqa: F401
-    # create_root_folder,
+    create_root_folder,
     ioc,  # noqa: F401
     ioc_pvs,
 )
@@ -24,3 +26,69 @@
 def test_epics(ioc):  # noqa: F811
     for pv, value in ioc_pvs.items():
         assert caget(pv) == value, f"PV {pv} has value {caget(pv)}, expected {value}"
+
+
+# fmt: off
+@pytest.mark.parametrize("usesetauth", [True, False])
+@pytest.mark.parametrize("library", ["THREADS", "ASYNC"])
+# fmt: on
+def test_take_snapshot_get_01(clear_sar, library, usesetauth):  # noqa: F811
+    """
+    Basic tests for the 'take_snapshot_get' 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_get(config_uid)
+
+            snapshot_pv_values = {}
+            for data in response:
+                pv_name, val = data["configPv"]["pvName"], data["value"]["value"]
+                snapshot_pv_values[pv_name] = val
+
+            for pv, value in ioc_pvs.items():
+                assert snapshot_pv_values[pv] == value, \
+                    print(f"pv: {pv}, expected: {value}, got: {snapshot_pv_values[pv]}")
+
+    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_get(config_uid)
+
+                snapshot_pv_values = {}
+                for data in response:
+                    pv_name, val = data["configPv"]["pvName"], data["value"]["value"]
+                    snapshot_pv_values[pv_name] = val
+
+                for pv, value in ioc_pvs.items():
+                    assert snapshot_pv_values[pv] == value, \
+                        print(f"pv: {pv}, expected: {value}, got: {snapshot_pv_values[pv]}")
+
+        asyncio.run(testing())