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

Author: ZPascal

docs/content/grafana_api/folder.md

@@ -7,6 +7,7 @@
     * [get\_folder\_by\_id](#folder.Folder.get_folder_by_id)
     * [create\_folder](#folder.Folder.create_folder)
     * [update\_folder](#folder.Folder.update_folder)
+    * [move\_folder](#folder.Folder.move_folder)
     * [delete\_folder](#folder.Folder.delete_folder)
     * [get\_folder\_permissions](#folder.Folder.get_folder_permissions)
     * [update\_folder\_permissions](#folder.Folder.update_folder_permissions)
@@ -46,6 +47,10 @@ def get_folders() -> 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
@@ -69,6 +74,10 @@ The method includes a functionality to extract all folder information specified
 
 - `uid` _str_ - Specify the uid of the folder
 
+  Required Permissions:
+- `Action` - folders:read
+- `Scope` - folders:*
+  
 
 **Raises**:
 
@@ -94,6 +103,10 @@ The method includes a functionality to extract all folder information specified
 
 - `id` _int_ - Specify the id of the folder
 
+  Required Permissions:
+- `Action` - folders:read
+- `Scope` - folders:*
+  
 
 **Raises**:
 
@@ -110,7 +123,7 @@ The method includes a functionality to extract all folder information specified
 #### create\_folder
 
 ```python
-def create_folder(title: str, uid: str = None) -> dict
+def create_folder(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
@@ -119,6 +132,11 @@ The method includes a functionality to create a new folder inside the organizati
 
 - `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**:
@@ -151,6 +169,10 @@ The method includes a functionality to update a folder information inside the or
 - `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**:
 
@@ -162,6 +184,36 @@ The method includes a functionality to update a folder information inside the or
 
 - `api_call` _dict_ - Returns an updated folder
 
+<a id="folder.Folder.move_folder"></a>
+
+#### move\_folder
+
+```python
+def move_folder(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
+
+**Arguments**:
+
+- `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
+
 <a id="folder.Folder.delete_folder"></a>
 
 #### delete\_folder
@@ -176,6 +228,10 @@ The method includes a functionality to delete a folder inside the organization s
 
 - `uid` _str_ - Specify the uid of the folder
 
+  Required Permissions:
+- `Action` - folders:delete
+- `Scope` - folders:*
+  
 
 **Raises**:
 
@@ -201,6 +257,10 @@ The method includes a functionality to extract the folder permissions inside the
 
 - `uid` _str_ - Specify the uid of the folder
 
+  Required Permissions:
+- `Action` - folders.permissions:read
+- `Scope` - folders:*
+  
 
 **Raises**:
 
@@ -227,6 +287,10 @@ The method includes a functionality to update the folder permissions based on th
 - `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**:
 

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):