ENH: refactoring of 'node_add' API

Author: dmgav

src/save_and_restore_api/_api_async.py

@@ -102,11 +102,9 @@ async def nodes_get(self, uniqueIds):
         method, url, body_json = self._prepare_nodes_get(uniqueIds=uniqueIds)
         return await self.send_request(method, url, body_json=body_json)
 
-    async def node_add(self, parentNodeId, *, name, nodeType, auth=None, **kwargs):
+    async def node_add(self, parentNodeId, *, node, auth=None, **kwargs):
         # Reusing docstrings from the threaded version
-        method, url, params, body_json = self._prepare_node_add(
-            parentNodeId=parentNodeId, name=name, nodeType=nodeType, **kwargs
-        )
+        method, url, params, body_json = self._prepare_node_add(parentNodeId=parentNodeId, node=node)
         return await self.send_request(method, url, params=params, body_json=body_json, auth=auth)
 
     async def node_delete(self, nodeId, *, auth=None):

src/save_and_restore_api/_api_base.py

@@ -231,13 +231,14 @@ def _prepare_nodes_get(self, *, uniqueIds):
         body_json = uniqueIds
         return method, url, body_json
 
-    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}.")
+    def _prepare_node_add(self, *, parentNodeId, node):
+        if "name" not in node or "nodeType" not in node:
+            raise self.RequestParameterError(f"Parameters 'name' and 'nodeType' are required in 'node': {node!r}.")
+        node_type, node_types = node["nodeType"], ("FOLDER", "CONFIGURATION")
+        if node_type not in node_types:
+            raise self.RequestParameterError(f"Invalid 'nodeType': {node_type!r}. Supported types: {node_types}.")
         method, url, params = "PUT", "/node", {"parentNodeId": parentNodeId}
-        body_json = kwargs
-        body_json.update({"name": name, "nodeType": nodeType})
+        body_json = node
         return method, url, params, body_json
 
     def _prepare_node_delete(self, *, nodeId):

src/save_and_restore_api/_api_threads.py

@@ -230,16 +230,54 @@ def nodes_get(self, uniqueIds):
         method, url, body_json = self._prepare_nodes_get(uniqueIds=uniqueIds)
         return self.send_request(method, url, body_json=body_json)
 
-    def node_add(self, parentNodeId, *, name, nodeType, auth=None, **kwargs):
+    def node_add(self, parentNodeId, *, node, auth=None, **kwargs):
         """
-        Creates a new node under the specified parent node. Required parameters:
-        ``name`` and ``nodeType``. Supported types: ``"FOLDER"``, ``"CONFIGURATION"``.
+        Creates a new node under the specified parent node.
 
         API: PUT /node?parentNodeId={parentNodeId}
+
+        Parameters
+        ----------
+        parentNodeId : str
+            Unique ID of the parent node.
+        node : dict
+            Node metadata. The required fields are ``name`` and ``nodeType``.
+            Supported node types: ``"FOLDER"``, ``"CONFIGURATION"``.
+        auth : httpx.BasicAuth
+            Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
+            then the authentication set using ``auth_set`` method is used.
+
+        Returns
+        -------
+        dict
+            Created node metadata as returned by the server.
+
+        Examples
+        --------
+
+        .. code-block:: python
+
+            from save_and_restore_api import SaveRestoreAPI
+
+            with SaveRestoreAPI(base_url="http://localhost:8080/save-restore") as SR:
+                SR.auth_set(username="user", password="user_password")
+                root_folder_uid = SR.ROOT_NODE_UID
+                folder = SR.node_add(root_folder_uid, node={"name": "My Folder", "nodeType": "FOLDER"})
+                print(f"Created folder metadata: {folder}")
+
+        Async version:
+
+        .. code-block:: python
+
+            from save_and_restore_api.aio import SaveRestoreAPI
+
+            async with SaveRestoreAPI(base_url="http://localhost:8080/save-restore") as SR:
+                await SR.auth_set(username="user", password="user_password")
+                root_folder_uid = SR.ROOT_NODE_UID
+                folder = await SR.node_add(root_folder_uid, node={"name": "My Folder", "nodeType": "FOLDER"})
+                print(f"Created folder metadata: {folder}")
         """
-        method, url, params, body_json = self._prepare_node_add(
-            parentNodeId=parentNodeId, name=name, nodeType=nodeType, **kwargs
-        )
+        method, url, params, body_json = self._prepare_node_add(parentNodeId=parentNodeId, node=node)
         return self.send_request(method, url, params=params, body_json=body_json, auth=auth)
 
     def node_delete(self, nodeId, *, auth=None):

src/save_and_restore_api/tools/cli.py

@@ -559,7 +559,7 @@ def create_missing_folders(SR, folder_name, *, create_folders=False):
             path += f"/{f}"
             node_uid = check_node_exists(SR, path, node_type="FOLDER")
             if not node_uid:
-                response = SR.node_add(parent_uid, name=f, nodeType="FOLDER")
+                response = SR.node_add(parent_uid, node={"name": f, "nodeType": "FOLDER"})
                 node_uid = response["uniqueId"]
             parent_uid = node_uid
 

tests/common.py

@@ -64,7 +64,7 @@ def create_root_folder():
     """
     with SaveRestoreAPI(base_url=base_url, timeout=2) as SR:
         SR.auth_set(username=admin_username, password=admin_password)
-        res = SR.node_add(SR.ROOT_NODE_UID, name=root_folder_node_name, nodeType="FOLDER")
+        res = SR.node_add(SR.ROOT_NODE_UID, node={"name": root_folder_node_name, "nodeType": "FOLDER"})
         return res["uniqueId"]
 
 

tests/test_config_control.py

@@ -67,7 +67,7 @@ def test_config_add_01(clear_sar, library, usesetauth):  # noqa: F811
         with SaveRestoreAPI_Threads(base_url=base_url, timeout=2) as SR:
             auth = _select_auth(SR=SR, usesetauth=usesetauth)
 
-            response = SR.node_add(root_folder_uid, name="Child Folder", nodeType="FOLDER", **auth)
+            response = SR.node_add(root_folder_uid, node={"name": "Child Folder", "nodeType": "FOLDER"}, **auth)
             folder_uid = response["uniqueId"]
 
 
@@ -96,7 +96,8 @@ async def testing():
             async with SaveRestoreAPI_Async(base_url=base_url, timeout=2) as SR:
                 auth = _select_auth(SR=SR, usesetauth=usesetauth)
 
-                response = await SR.node_add(root_folder_uid, name="Child Folder", nodeType="FOLDER", **auth)
+                node = {"name": "Child Folder", "nodeType": "FOLDER"}
+                response = await SR.node_add(root_folder_uid, node=node, **auth)
                 folder_uid = response["uniqueId"]
 
                 response = await SR.config_add(
@@ -140,7 +141,7 @@ def test_config_update_01(clear_sar, library, usesetauth):  # noqa: F811
         with SaveRestoreAPI_Threads(base_url=base_url, timeout=2) as SR:
             auth = _select_auth(SR=SR, usesetauth=usesetauth)
 
-            response = SR.node_add(root_folder_uid, name="Child Folder", nodeType="FOLDER", **auth)
+            response = SR.node_add(root_folder_uid, node={"name": "Child Folder", "nodeType": "FOLDER"}, **auth)
             folder_uid = response["uniqueId"]
 
             response = SR.config_add(
@@ -186,7 +187,8 @@ async def testing():
             async with SaveRestoreAPI_Async(base_url=base_url, timeout=2) as SR:
                 auth = _select_auth(SR=SR, usesetauth=usesetauth)
 
-                response = await SR.node_add(root_folder_uid, name="Child Folder", nodeType="FOLDER", **auth)
+                node = {"name": "Child Folder", "nodeType": "FOLDER"}
+                response = await SR.node_add(root_folder_uid, node=node, **auth)
                 folder_uid = response["uniqueId"]
 
                 response = await SR.config_add(