ENH: implementation for 'structure_path_get' and 'structure_path_nodes' API

Author: dmgav

src/save_and_restore_api/_api_async.py

@@ -249,6 +249,16 @@ async def structure_copy(self, nodeIds, newParentNodeId, *, auth=None):
         )
         return await self.send_request(method, url, params=params, url_params=url_params, auth=auth)
 
+    async def structure_path_get(self, uniqueNodeId):
+        # Reusing docstrings from the threaded version
+        method, url = self._prepare_structure_path_get(uniqueNodeId=uniqueNodeId)
+        return await self.send_request(method, url)
+
+    async def structure_path_nodes(self, path):
+        # Reusing docstrings from the threaded version
+        method, url, url_params = self._prepare_structure_path_nodes(path=path)
+        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__
@@ -278,3 +288,5 @@ async def structure_copy(self, nodeIds, newParentNodeId, *, auth=None):
 SaveRestoreAPI.compare.__doc__ = _SaveRestoreAPI_Threads.compare.__doc__
 SaveRestoreAPI.structure_move.__doc__ = _SaveRestoreAPI_Threads.structure_move.__doc__
 SaveRestoreAPI.structure_copy.__doc__ = _SaveRestoreAPI_Threads.structure_copy.__doc__
+SaveRestoreAPI.structure_path_get.__doc__ = _SaveRestoreAPI_Threads.structure_path_get.__doc__
+SaveRestoreAPI.structure_path_nodes.__doc__ = _SaveRestoreAPI_Threads.structure_path_nodes.__doc__

src/save_and_restore_api/_api_base.py

@@ -361,6 +361,15 @@ def _prepare_structure_copy(self, *, nodeIds, newParentNodeId):
         params = nodeIds
         return method, url, params, url_params
 
+    def _prepare_structure_path_get(self, *, uniqueNodeId):
+        method, url = "GET", f"/path/{uniqueNodeId}"
+        return method, url
+
+    def _prepare_structure_path_nodes(self, *, path):
+        method, url = "GET", "/path"
+        url_params = {"path": path}
+        return method, url, url_params
+
     # =============================================================================================
 
     # def create_config(self, parent_node_uid, name, pv_list):

src/save_and_restore_api/_api_threads.py

@@ -385,7 +385,7 @@ def structure_move(self, nodeIds, *, newParentNodeId, auth=None):
         Move nodes specified by a list of UIDs ``nodeIds`` to a new parent node specified
         by ``newParentNodeId``. The API requires 'admin' priviledges.
 
-        API: POST /structure/move
+        API: POST /move
         """
         method, url, params, url_params = self._prepare_structure_move(
             nodeIds=nodeIds, newParentNodeId=newParentNodeId
@@ -397,9 +397,29 @@ def structure_copy(self, nodeIds, *, newParentNodeId, auth=None):
         Copy nodes specified by a list of UIDs ``nodeIds`` to a new parent node specified
         by ``newParentNodeId``. The API requires 'admin' priviledges.
 
-        API: POST /structure/copy
+        API: POST /copy
         """
         method, url, params, url_params = self._prepare_structure_copy(
             nodeIds=nodeIds, newParentNodeId=newParentNodeId
         )
         return self.send_request(method, url, params=params, url_params=url_params, auth=auth)
+
+    def structure_path_get(self, uniqueNodeId):
+        """
+        Get path for the node with specified uniqueNodeId.
+
+        API: GET /path/{uniqueNodeId}
+        """
+        method, url = self._prepare_structure_path_get(uniqueNodeId=uniqueNodeId)
+        return self.send_request(method, url)
+
+    def structure_path_nodes(self, path):
+        """
+        Get a list of nodes that match the specified path. The path can point to multiple
+        nodes as long as node type is different (e.g. a folder and a configuration may have
+        the same name).
+
+        API: GET /path
+        """
+        method, url, url_params = self._prepare_structure_path_nodes(path=path)
+        return self.send_request(method, url, url_params=url_params)

tests/test_structure_control.py

@@ -13,6 +13,7 @@
     base_url,
     clear_sar,  # noqa: F401
     create_root_folder,
+    root_folder_node_name,
 )
 
 # =============================================================================================
@@ -129,3 +130,72 @@ async def testing():
                 assert len(response) == n_folder2
 
         asyncio.run(testing())
+
+
+
+# fmt: off
+@pytest.mark.parametrize("usesetauth", [True, False])
+@pytest.mark.parametrize("library", ["THREADS", "ASYNC"])
+# fmt: on
+def test_structure_path_01(clear_sar, library, usesetauth):  # noqa: F811
+    """
+    Basic tests for the 'path_get' and 'path_nodes' 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)
+
+            # Create two folders
+            folder1_name = "Folder1"
+            response = SR.node_add(root_folder_uid, name=folder1_name, nodeType="FOLDER", **auth)
+            folder1_uid = response["uniqueId"]
+
+            node_name = "Node Name"
+            response = SR.node_add(folder1_uid, name=node_name, nodeType="FOLDER", **auth)
+            folder2_uid = response["uniqueId"]
+
+            # Create two configurations in folder1
+            response = SR.config_create(
+                folder1_uid,
+                configurationNode={"name": node_name},
+                configurationData={"pvList": []},
+                **auth
+            )
+
+            folder1_path = SR.structure_path_get(folder2_uid)
+            assert folder1_path == "/" + root_folder_node_name + "/" + folder1_name + "/" + node_name
+
+            response = SR.structure_path_nodes(folder1_path)
+            assert len(response) == 2
+
+    else:
+        async def testing():
+            async with SaveRestoreAPI_Async(base_url=base_url, timeout=2) as SR:
+                auth = _select_auth(SR=SR, usesetauth=usesetauth)
+
+                # Create two folders
+                folder1_name = "Folder1"
+                response = await SR.node_add(root_folder_uid, name=folder1_name, nodeType="FOLDER", **auth)
+                folder1_uid = response["uniqueId"]
+
+                node_name = "Node Name"
+                response = await SR.node_add(folder1_uid, name=node_name, nodeType="FOLDER", **auth)
+                folder2_uid = response["uniqueId"]
+
+                # Create two configurations in folder1
+                response = await SR.config_create(
+                    folder1_uid,
+                    configurationNode={"name": node_name},
+                    configurationData={"pvList": []},
+                    **auth
+                )
+
+                folder1_path = await SR.structure_path_get(folder2_uid)
+                assert folder1_path == "/" + root_folder_node_name + "/" + folder1_name + "/" + node_name
+
+                response = await SR.structure_path_nodes(folder1_path)
+                assert len(response) == 2
+
+        asyncio.run(testing())