feat: Add the parent folder uid functionality and adjust the documentation

Author: ZPascal

grafana_api/folder.py

@@ -23,6 +23,10 @@ def __init__(self, grafana_api_model: APIModel):
     def get_folders(self) -> list:
         """The method includes a functionality to extract all folders inside the organization
 
+        Required Permissions:
+            Action: folders:read
+            Scope: folders:*
+
         Raises:
             Exception: Unspecified error by executing the API call
 
@@ -46,6 +50,10 @@ def get_folder_by_uid(self, uid: str) -> dict:
         Args:
             uid (str): Specify the uid of the folder
 
+        Required Permissions:
+            Action: folders:read
+            Scope: folders:*
+
         Raises:
             ValueError: Missed specifying a necessary value
             Exception: Unspecified error by executing the API call
@@ -74,6 +82,10 @@ def get_folder_by_id(self, id: int) -> dict:
         Args:
             id (int): Specify the id of the folder
 
+        Required Permissions:
+            Action: folders:read
+            Scope: folders:*
+
         Raises:
             ValueError: Missed specifying a necessary value
             Exception: Unspecified error by executing the API call
@@ -96,12 +108,17 @@ def get_folder_by_id(self, id: int) -> dict:
             logging.error("There is no folder id defined.")
             raise ValueError
 
-    def create_folder(self, title: str, uid: str = None) -> dict:
+    def create_folder(self, title: str, uid: str = None, parent_uid: str = None) -> dict:
         """The method includes a functionality to create a new folder inside the organization specified by the defined title and the optional uid
 
         Args:
             title (str): Specify the title of the folder
             uid (str): Specify the uid of the folder (default None)
+            parent_uid (str): Specify the parent_uid of the folder (default None)
+
+        Required Permissions:
+            Action: folders:create, folders:write
+            Scope: folders:*
 
         Raises:
             ValueError: Missed specifying a necessary value
@@ -118,6 +135,9 @@ def create_folder(self, title: str, uid: str = None) -> dict:
             if uid is not None and len(uid) != 0:
                 folder_information.update({"uid": uid})
 
+            if parent_uid is not None and len(parent_uid) != 0:
+                folder_information.update({"parentUid": parent_uid})
+
             api_call: dict = Api(self.grafana_api_model).call_the_api(
                 APIEndpoints.FOLDERS.value,
                 RequestsMethods.POST,
@@ -144,6 +164,10 @@ def update_folder(
             version (int): Specify the version of the folder (default 0)
             overwrite (bool): Should the already existing folder information be overwritten (default False)
 
+        Required Permissions:
+            Action: folders:write
+            Scope: folders:*
+
         Raises:
             ValueError: Missed specifying a necessary value
             Exception: Unspecified error by executing the API call
@@ -179,12 +203,57 @@ def update_folder(
             logging.error("There is no folder title, version or uid defined.")
             raise ValueError
 
+    def move_folder(self, uid: str, parent_uid: str = None):
+        """The method includes a functionality to move a folder inside the organization specified by the defined uid. This feature is only relevant if nested folders are enabled
+
+        Args:
+            uid (str): Specify the uid of the folder
+            parent_uid (str): Specify the parent_uid of the folder. If the value is None, then the folder is moved under the root (default None)
+
+        Required Permissions:
+            Action: folders:create, folders:write
+            Scope: folders:*, folders:uid:<destination folder UID>
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            api_call (dict): Returns the moved folder
+        """
+
+        if len(uid) != 0:
+            folder_information: dict = dict()
+
+            if parent_uid is not None and len(parent_uid) != 0:
+                folder_information.update({"parentUid": parent_uid})
+
+            api_call = Api(self.grafana_api_model).call_the_api(
+                f"{APIEndpoints.FOLDERS.value}/{uid}/move",
+                RequestsMethods.POST,
+                json.dumps(folder_information),
+            )
+
+            if api_call == dict() or api_call.get("id") is None:
+                logging.error(f"Please, check the error: {api_call}.")
+                raise Exception
+            else:
+                return api_call
+        else:
+            logging.error("There is no folder uid defined.")
+            raise ValueError
+
+
     def delete_folder(self, uid: str):
         """The method includes a functionality to delete a folder inside the organization specified by the defined uid
 
         Args:
             uid (str): Specify the uid of the folder
 
+        Required Permissions:
+            Action: folders:delete
+            Scope: folders:*
+
         Raises:
             ValueError: Missed specifying a necessary value
             Exception: Unspecified error by executing the API call
@@ -220,6 +289,10 @@ def get_folder_permissions(self, uid: str) -> list:
         Args:
             uid (str): Specify the uid of the folder
 
+        Required Permissions:
+            Action: folders.permissions:read
+            Scope: folders:*
+
         Raises:
             ValueError: Missed specifying a necessary value
             Exception: Unspecified error by executing the API call
@@ -250,6 +323,10 @@ def update_folder_permissions(self, uid: str, permission_json: dict):
             uid (str): Specify the uid of the folder
             permission_json (dict): Specify the inserted permissions as dict
 
+        Required Permissions:
+            Action: folders.permissions:write
+            Scope: folders:*
+
         Raises:
             ValueError: Missed specifying a necessary value
             Exception: Unspecified error by executing the API call

tests/integrationtest/test_folder.py

@@ -69,14 +69,35 @@ def test_a_create_folder(self):
 
         self.assertEqual("test1", self.folder.get_folders()[1].get("title"))
 
-    def test_b_update_folder(self):
+    def test_b_subfolder(self):
+        parent_uid = self.folder.get_folders()[1].get("uid")
+
+        subfolder: dict = self.folder.create_folder("test2", parent_uid=parent_uid)
+
+        self.assertEqual("test2", self.folder.get_folder_by_uid(subfolder["uid"]).get("title"))
+
+    def test_c_update_folder(self):
         self.folder.update_folder(
             "test2", self.folder.get_folders()[1].get("uid"), version=1
         )
 
         self.assertEqual("test2", self.folder.get_folders()[1].get("title"))
 
-    def test_c_delete_folder(self):
+    def test_d_move_folder(self):
+        parent_uid = self.folder.get_folders()[1].get("uid")
+
+        folder_uid_a = self.folder.create_folder("test11", parent_uid=parent_uid)["uid"]
+        folder_uid_b = self.folder.create_folder("test12")["uid"]
+
+        self.assertEqual("test12", self.folder.get_folder_by_uid(folder_uid_b)["title"])
+
+        moved_folder: dict = self.folder.move_folder(folder_uid_a, parent_uid=folder_uid_b)
+
+        self.assertEqual("test12", moved_folder["parents"][0]["title"])
+        self.folder.delete_folder(moved_folder["parents"][0]["uid"])
+
+
+    def test_e_delete_folder(self):
         self.folder.delete_folder(self.folder.get_folders()[1].get("uid"))
 
         self.assertEqual(1, len(self.folder.get_folders()))
@@ -110,7 +131,7 @@ def test_get_folder_permissions(self):
             self.folder.get_folder_permissions("6U_QdWJnz"),
         )
 
-    def test_d_update_folder_permissions(self):
+    def test_f_update_folder_permissions(self):
         permission_dict: dict = dict({"items": [{"role": "Viewer", "permission": 2}]})
 
         self.folder.update_folder_permissions("6U_QdWJnz", permission_dict)

tests/unittests/test_alerting.py

@@ -738,7 +738,7 @@ def test_test_backtest_rule(self, call_the_api_mock):
         model: APIModel = APIModel(host=MagicMock(), token=MagicMock())
         alerting: Alerting = Alerting(grafana_api_model=model)
         datasource_rule_query: DatasourceRuleQuery = DatasourceRuleQuery(
-            "test", {"test": "test"}, "test", "test", {"test": "test"}
+            "test", {"test": "test"}, "datasourceUid", "test", {"test": "test"}
         )
 
         call_the_api_mock.return_value = dict({"test": "test"})
@@ -756,17 +756,30 @@ def test_test_backtest_rule_no_condition(self):
             alerting.test_backtest_rule("", list())
 
     @patch("grafana_api.api.Api.call_the_api")
-    def test_test_recipient_rule_test_not_possible(self, call_the_api_mock):
+    def test_test_backtest_rule_no_fields(self, call_the_api_mock):
         model: APIModel = APIModel(host=MagicMock(), token=MagicMock())
         alerting: Alerting = Alerting(grafana_api_model=model)
         datasource_rule_query: DatasourceRuleQuery = DatasourceRuleQuery(
-            "test", {"test": "test"}, "test", "test", {"test": "test"}
+            "test", {"test": "test"}, "datasourceUid", "test", {"test": "test"}
+        )
+
+        call_the_api_mock.return_value = dict()
+
+        with self.assertRaises(Exception):
+            alerting.test_backtest_rule("test", [datasource_rule_query])
+
+    @patch("grafana_api.api.Api.call_the_api")
+    def test_test_datasource_uid_rule_test_not_possible(self, call_the_api_mock):
+        model: APIModel = APIModel(host=MagicMock(), token=MagicMock())
+        alerting: Alerting = Alerting(grafana_api_model=model)
+        datasource_rule_query: DatasourceRuleQuery = DatasourceRuleQuery(
+            "test", {"test": "test"}, "datasourceUid", "test", {"test": "test"}
         )
 
         call_the_api_mock.return_value = dict()
 
         with self.assertRaises(Exception):
-            alerting.test_recipient_rule("test", "test", [datasource_rule_query])
+            alerting.test_datasource_uid_rule("test", "test", [datasource_rule_query])
 
     @patch("grafana_api.api.Api.call_the_api")
     def test_delete_ngalert_organization_configuration(self, call_the_api_mock):

tests/unittests/test_folder.py

@@ -108,6 +108,18 @@ def test_create_folder_specified_uid(self, call_the_api_mock):
             folder.create_folder("test", "test"),
         )
 
+    @patch("grafana_api.api.Api.call_the_api")
+    def test_create_folder_parent_uid(self, call_the_api_mock):
+        model: APIModel = APIModel(host=MagicMock(), token=MagicMock())
+        folder: Folder = Folder(grafana_api_model=model)
+
+        call_the_api_mock.return_value = dict({"title": None, "id": 12, "parent_uid": "test"})
+
+        self.assertEqual(
+            dict({"title": None, "id": 12, "parent_uid": "test"}),
+            folder.create_folder("test", parent_uid="test"),
+        )
+
     @patch("grafana_api.api.Api.call_the_api")
     def test_create_folder_no_title(self, call_the_api_mock):
         model: APIModel = APIModel(host=MagicMock(), token=MagicMock())
@@ -184,6 +196,49 @@ def test_update_folder_error_response(self, call_the_api_mock):
         with self.assertRaises(Exception):
             folder.update_folder("test", "test", 10)
 
+    @patch("grafana_api.api.Api.call_the_api")
+    def test_move_folder(self, call_the_api_mock):
+        model: APIModel = APIModel(host=MagicMock(), token=MagicMock())
+        folder: Folder = Folder(grafana_api_model=model)
+
+        call_the_api_mock.return_value = dict({"title": "test1", "id": 12})
+
+        self.assertEqual(
+            dict({"title": "test1", "id": 12}),
+            folder.move_folder("test"),
+        )
+
+    def test_move_folder_no_uid(self):
+        model: APIModel = APIModel(host=MagicMock(), token=MagicMock())
+        folder: Folder = Folder(grafana_api_model=model)
+
+        with self.assertRaises(ValueError):
+            folder.move_folder("")
+
+
+    @patch("grafana_api.api.Api.call_the_api")
+    def test_move_folder_parent_uid(self, call_the_api_mock):
+        model: APIModel = APIModel(host=MagicMock(), token=MagicMock())
+        folder: Folder = Folder(grafana_api_model=model)
+
+        call_the_api_mock.return_value = dict({"title": "test", "id": 12})
+
+        self.assertEqual(
+            dict({"title": "test", "id": 12}),
+            folder.move_folder("test", "test"),
+        )
+
+    @patch("grafana_api.api.Api.call_the_api")
+    def test_move_folder_no_id(self, call_the_api_mock):
+        model: APIModel = APIModel(host=MagicMock(), token=MagicMock())
+        folder: Folder = Folder(grafana_api_model=model)
+
+        call_the_api_mock.return_value = dict({})
+
+        with self.assertRaises(Exception):
+            folder.move_folder("test")
+
+
     @patch("grafana_api.api.Api.call_the_api")
     def test_delete_folder(self, call_the_api_mock):
         model: APIModel = APIModel(host=MagicMock(), token=MagicMock())