ENH: implementation for 'restore_node' and 'restore_items' API

Author: dmgav

src/save_and_restore_api/_api_async.py

@@ -40,6 +40,10 @@ async def send_request(
 
         return response
 
+    # =============================================================================================
+    #                         AUTHENTICATION-CONTROLLER API METHODS
+    # =============================================================================================
+
     async def login(self, *, username=None, password=None):
         method, url, params = self._prepare_login(username=username, password=password)
         return await self.send_request(method, url, params=params)
@@ -153,36 +157,36 @@ async def snapshot_get(self, uniqueId):
         return await self.send_request(method, url)
 
     async def snapshot_add(self, parentNodeId, *, snapshotNode, snapshotData, auth=None):
-        """
-        Upload data for the new snapshot and save it to the database. The new node is created
-        under the existing configuration node specified by ``parentNodeId``.
-
-        API: PUT /snapshot?parentNodeId={parentNodeId}
-        """
+        # Reusing docstrings from the threaded version
         method, url, params = self._prepare_snapshot_add(
             parentNodeId=parentNodeId, snapshotNode=snapshotNode, snapshotData=snapshotData
         )
         return await self.send_request(method, url, params=params, auth=auth)
 
     async def snapshot_update(self, *, snapshotNode, snapshotData, auth=None):
-        """
-        Upload and update data for an existing snapshot. Both ``snapshotNode`` and ``snapshotData``
-        must have valid ``uniqueId`` fields pointing to an existing node.
-
-        API: POST /snapshot
-        """
+        # Reusing docstrings from the threaded version
         method, url, params = self._prepare_snapshot_update(snapshotNode=snapshotNode, snapshotData=snapshotData)
         return await self.send_request(method, url, params=params, auth=auth)
 
     async def snapshots_get(self):
-        """
-        Returns a list of all existing snapshots (list of ``snapshotNode`` objects).
-
-        API: GET /snapshots
-        """
+        # Reusing docstrings from the threaded version
         method, url = self._prepare_snapshots_get()
         return await self.send_request(method, url)
 
+    # =============================================================================================
+    #                     SNAPSHOT-RESTORE-CONTROLLER API METHODS
+    # =============================================================================================
+
+    async def restore_node(self, nodeId, *, auth=None):
+        # Reusing docstrings from the threaded version
+        method, url, url_params = self._prepare_restore_node(nodeId=nodeId)
+        return await self.send_request(method, url, url_params=url_params, auth=auth)
+
+    async def restore_items(self, *, snapshotItems, auth=None):
+        # Reusing docstrings from the threaded version
+        method, url, params = self._prepare_restore_items(snapshotItems=snapshotItems)
+        return await self.send_request(method, url, params=params, auth=auth)
+
 
 SaveRestoreAPI.node_get.__doc__ = _SaveRestoreAPI_Threads.node_get.__doc__
 SaveRestoreAPI.nodes_get.__doc__ = _SaveRestoreAPI_Threads.nodes_get.__doc__
@@ -203,3 +207,5 @@ async def snapshots_get(self):
 SaveRestoreAPI.snapshot_add.__doc__ = _SaveRestoreAPI_Threads.snapshot_add.__doc__
 SaveRestoreAPI.snapshot_update.__doc__ = _SaveRestoreAPI_Threads.snapshot_update.__doc__
 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__

src/save_and_restore_api/_api_base.py

@@ -275,6 +275,20 @@ def _prepare_snapshots_get(self):
         method, url = "GET", "/snapshots"
         return method, url
 
+    # =============================================================================================
+    #                     SNAPSHOT-RESTORE-CONTROLLER API METHODS
+    # =============================================================================================
+
+    def _prepare_restore_node(self, *, nodeId):
+        method, url = "POST", "/restore/node"
+        url_params = {"nodeId": nodeId}
+        return method, url, url_params
+
+    def _prepare_restore_items(self, *, snapshotItems):
+        method, url = "POST", "/restore/items"
+        params = snapshotItems
+        return method, url, params
+
     # =============================================================================================
 
     # def create_config(self, parent_node_uid, name, pv_list):

src/save_and_restore_api/_api_threads.py

@@ -39,6 +39,10 @@ def send_request(
 
         return response
 
+    # =============================================================================================
+    #                         AUTHENTICATION-CONTROLLER API METHODS
+    # =============================================================================================
+
     def login(self, *, username=None, password=None):
         method, url, params = self._prepare_login(username=username, password=password)
         return self.send_request(method, url, params=params)
@@ -269,3 +273,26 @@ def snapshots_get(self):
         """
         method, url = self._prepare_snapshots_get()
         return self.send_request(method, url)
+
+    # =============================================================================================
+    #                     SNAPSHOT-RESTORE-CONTROLLER API METHODS
+    # =============================================================================================
+
+    def restore_node(self, nodeId, *, auth=None):
+        """
+        Restore PVs based on the data from an existing snapshot node specified by nodeId.
+
+        API: POST /restore/node
+        """
+        method, url, url_params = self._prepare_restore_node(nodeId=nodeId)
+        return self.send_request(method, url, url_params=url_params, auth=auth)
+
+    def restore_items(self, *, snapshotItems, auth=None):
+        """
+        Restore PVs based on the list of snapshot items passed with the request. The list
+        format matches the format of ``snapshotData["snapshotItems"]``
+
+        API: POST /restore/items
+        """
+        method, url, params = self._prepare_restore_items(snapshotItems=snapshotItems)
+        return self.send_request(method, url, params=params, auth=auth)

tests/test_misc.py

@@ -65,6 +65,11 @@ def test_version_01():
 #         asyncio.run(testing())
 
 
+# =============================================================================================
+#                         TESTS FOR AUTHENTICATION-CONTROLLER API METHODS
+# =============================================================================================
+
+
 # fmt: off
 @pytest.mark.parametrize("library", ["THREADS", "ASYNC"])
 @pytest.mark.parametrize("username, password, roles, code", [