feat: Add the parent folder uid functionality and adjust the docs (#105)

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

Author: ZPascal

Diff for: 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**:
 

Diff for: docs/coverage.svg

@@ -151,11 +151,7 @@ def delete_alertmanager_silence_by_id(
                 RequestsMethods.DELETE,
             )
 
-            if (
-                    api_call == dict()
-                    or api_call.get("message")
-                    != "silence deleted"
-            ):
+            if api_call == dict() or api_call.get("message") != "silence deleted":
                 logging.error(f"Please, check the error: {api_call}.")
                 raise Exception
             else:
@@ -258,7 +254,9 @@ def create_or_update_alertmanager_silence(
                 json.dumps(silence_json_dict),
             )
 
-            if api_call == dict() or (api_call.get("id") is None and api_call.get("silenceID") is None):
+            if api_call == dict() or (
+                api_call.get("id") is None and api_call.get("silenceID") is None
+            ):
                 logging.error(f"Check the error: {api_call}.")
                 raise Exception
             else:
@@ -661,7 +659,12 @@ def create_or_update_ruler_group_by_namespace(
             None
         """
 
-        if len(datasource_uid) != 0 and len(namespace) != 0 and len(group_name) != 0 and rules != list():
+        if (
+            len(datasource_uid) != 0
+            and len(namespace) != 0
+            and len(group_name) != 0
+            and rules != list()
+        ):
             rules_json_list: list = list()
 
             for rule in rules:
@@ -696,7 +699,9 @@ def create_or_update_ruler_group_by_namespace(
             else:
                 logging.info("You successfully created an ruler group.")
         else:
-            logging.error("There is no datasource_uid, namespace, name or rules defined.")
+            logging.error(
+                "There is no datasource_uid, namespace, name or rules defined."
+            )
             raise ValueError
 
     def delete_ruler_group(
@@ -729,7 +734,9 @@ def delete_ruler_group(
             else:
                 logging.info("You successfully deleted a ruler group.")
         else:
-            logging.error("There is no datasource_uid, namespace or group_name defined.")
+            logging.error(
+                "There is no datasource_uid, namespace or group_name defined."
+            )
             raise ValueError
 
     def get_ruler_group(
@@ -761,7 +768,9 @@ def get_ruler_group(
             else:
                 return api_call
         else:
-            logging.error("There is no datasource_uid, namespace or group_name defined.")
+            logging.error(
+                "There is no datasource_uid, namespace or group_name defined."
+            )
             raise ValueError
 
     def test_rule(self, data_query: list) -> dict:
@@ -823,7 +832,11 @@ def test_rule(self, data_query: list) -> dict:
             raise ValueError
 
     def test_datasource_uid_rule(
-        self, expr: str, condition: str, data_query: list, datasource_uid: str = "grafana"
+        self,
+        expr: str,
+        condition: str,
+        data_query: list,
+        datasource_uid: str = "grafana",
     ) -> dict:
         """The method includes a functionality to test a datasource uid rule specified by the expr, the condition, a list of data queries and the datasource_uid
 
@@ -841,7 +854,12 @@ def test_datasource_uid_rule(
             api_call (dict): Returns the result of the specified datasource_uid rule
         """
 
-        if len(datasource_uid) != 0 and len(expr) != 0 and len(condition) != 0 and data_query != list():
+        if (
+            len(datasource_uid) != 0
+            and len(expr) != 0
+            and len(condition) != 0
+            and data_query != list()
+        ):
             datasource_rule_query_objects_json: list = list()
             datasource_rule_query_object_json: dict = dict()
 
@@ -1045,9 +1063,7 @@ def create_or_update_ngalert_organization_configuration(
                     "You successfully created an NGAlert organization configuration."
                 )
         else:
-            logging.error(
-                "There is no alert_managers or alertmanagers_choice defined."
-            )
+            logging.error("There is no alert_managers or alertmanagers_choice defined.")
             raise ValueError
 
     def get_ngalert_alertmanagers_by_organization(self) -> dict: