SIMPLE-7569 API changes for RBAC (#141)

Author: tmikuska

virl2_client/models/group.py

@@ -20,9 +20,10 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
+import warnings
 
-from ..utils import get_url_from_template
+from ..utils import _deprecated_argument, get_url_from_template
 
 if TYPE_CHECKING:
     import httpx
@@ -34,8 +35,6 @@ class GroupManagement:
     _URL_TEMPLATES = {
         "groups": "groups",
         "group": "groups/{group_id}",
-        "members": "groups/{group_id}/members",
-        "labs": "groups/{group_id}/labs",
         "id": "groups/{group_name}/id",
     }
 
@@ -80,83 +79,120 @@ def delete_group(self, group_id: str) -> None:
         url = self._url_for("group", group_id=group_id)
         self._session.delete(url)
 
-    def create_group(
-        self,
-        name: str,
-        description: str = "",
-        members: list[str] | None = None,
-        labs: list[dict[str, str]] | None = None,
-    ) -> dict:
+    def create_group(self, name: str, **kwargs: Any) -> dict:
         """
         Create a group.
 
         :param name: The name of the group.
-        :param description: The description of the group.
-        :param members: The members of the group.
-        :param labs: The labs associated with the group.
+        :param kwargs: Optional parameters. See below.
+
+        :Keyword Arguments:
+            - description: The description of the group.
+            - members: The members of the group.
+            - associations: The lab associations for the group.
+            - labs: DEPRECATED: replaced by 'associations'.
+                The labs associated with the group.
+
         :returns: The created group object.
         """
-        data = {"name": name}
-        optional_data = {
-            "description": description,
-            "members": members,
-            "labs": labs,
-        }
-        for key, value in optional_data.items():
-            if value:
-                data[key] = value
+        data: dict[str, str | list] = {"name": name}
+        self._prepare_body(data, **kwargs)
         url = self._url_for("groups")
         return self._session.post(url, json=data).json()
 
-    def update_group(
-        self,
-        group_id: str,
-        name: str | None = None,
-        description: str | None = None,
-        members: list[str] | None = None,
-        labs: list[dict[str, str]] | None = None,
-    ) -> dict:
+    def update_group(self, group_id: str, **kwargs: Any) -> dict:
         """
         Update a group.
 
         :param group_id: The UUID4 of the group.
-        :param name: The new name of the group.
-        :param description: The description of the group.
-        :param members: The members of the group.
-        :param labs: The labs associated with the group.
+        :param kwargs: Optional parameters. See below.
+
+        :Keyword Arguments:
+            - name: The name of the group.
+            - description: The description of the group.
+            - members: The members of the group.
+            - associations: The lab associations for the group.
+            - labs: DEPRECATED: replaced by 'associations'.
+                The labs associated with the group.
+
         :returns: The updated group object.
         """
         data: dict[str, str | list] = {}
-        if name is not None:
-            data["name"] = name
-        if description is not None:
-            data["description"] = description
-        if members is not None:
-            data["members"] = members
-        if labs is not None:
-            data["labs"] = labs
+        self._prepare_body(data, **kwargs)
         url = self._url_for("group", group_id=group_id)
         return self._session.patch(url, json=data).json()
 
+    def _prepare_body(
+        self,
+        data: dict[str, str | list],
+        name: str | None = None,
+        description: str | None = None,
+        members: list[str] | None = None,
+        labs: list[dict[str, str]] | None = None,
+        associations: list[dict[str, list[str]]] | None = None,
+    ):
+        optional_data = {
+            "name": name,
+            "description": description,
+            "members": members,
+            "labs": labs,
+            "associations": associations,
+        }
+        if labs is not None:
+            func = self.create_group if data else self.update_group
+            _deprecated_argument(func, labs, "labs")
+        for key, value in optional_data.items():
+            if value is not None:
+                data[key] = value
+
     def group_members(self, group_id: str) -> list[str]:
         """
         Get the members of a group.
 
         :param group_id: The UUID4 of the group.
         :returns: A list of users associated with this group.
         """
-        url = self._url_for("members", group_id=group_id)
-        return self._session.get(url).json()
+        return self.get_group(group_id)["members"]
 
     def group_labs(self, group_id: str) -> list[str]:
         """
+        DEPRECATED: Use `.associations()` instead.
+        (Reason: adapted to the new format of lab associations)
+
         Get a list of labs associated with a group.
 
         :param group_id: The UUID4 of the group.
         :returns: A list of labs associated with this group.
         """
-        url = self._url_for("labs", group_id=group_id)
-        return self._session.get(url).json()
+        warnings.warn(
+            "'GroupManagement.group_labs()' is deprecated."
+            "Use '.associations' instead.",
+            DeprecationWarning,
+        )
+        return [lab["id"] for lab in self.get_group(group_id)["labs"]]
+
+    def associations(self, group_id: str) -> list[dict[str, list[str]]]:
+        """
+        Get a list of lab associations for a group.
+
+        :param group_id: The UUID4 of the group.
+        :returns: A list of lab associations for this group.
+        """
+        return self.get_group(group_id)["associations"]
+
+    def update_associations(
+        self, group_id: str, associations: list[dict[str, list[str]]]
+    ) -> dict:
+        """
+        Update the lab associations for a group.
+
+        :param group_id: The UUID4 of the group.
+        :param associations: The new list of lab associations.
+        :returns: The updated group object.
+        """
+        data = {"associations": associations}
+        url = self._url_for("group", group_id=group_id)
+        return self._session.patch(url, json=data).json()
 
     def group_id(self, group_name: str) -> str:
         """

virl2_client/models/lab.py

@@ -86,7 +86,7 @@ class Lab:
         "pyats_testbed": "labs/{lab_id}/pyats_testbed",
         "layer3_addresses": "labs/{lab_id}/layer3_addresses",
         "download": "labs/{lab_id}/download",
-        "groups": "labs/{lab_id}/groups",
+        "associations": "labs/{lab_id}/associations",
         "connector_mappings": "labs/{lab_id}/connector_mappings",
         "resource_pools": "labs/{lab_id}/resource_pools",
         "annotations": "labs/{lab_id}/annotations",
@@ -2107,25 +2107,66 @@ def download(self) -> str:
     @property
     def groups(self) -> list[dict[str, str]]:
         """
+        DEPRECATED: Use `.associations` instead.
+        (Reason: adapted to new format of lab associations)
+
         Return the groups this lab is associated with.
 
         :returns: List of objects consisting of group ID and permissions.
         """
-        url = self._url_for("groups")
-        return self._session.get(url).json()
+        warnings.warn(
+            "'Lab.groups' is deprecated. Use '.associations' instead.",
+            DeprecationWarning,
+        )
+        url = self._url_for("lab")
+        return self._session.get(url).json()["groups"]
 
     @check_stale
     def update_lab_groups(
         self, group_list: list[dict[str, str]]
     ) -> list[dict[str, str]]:
         """
+        DEPRECATED: Use `.update_associations()` instead.
+        (Reason: adapted to new format of lab associations)
+
         Modify lab/group association.
 
         :param group_list: List of objects consisting of group ID and permissions.
         :returns: Updated objects consisting of group ID and permissions.
         """
-        url = self._url_for("groups")
-        return self._session.put(url, json=group_list).json()
+        warnings.warn(
+            "'Lab.update_lab_groups()' is deprecated. Use '.update_associations()' instead.",
+            DeprecationWarning,
+        )
+        url = self._url_for("lab")
+        data = {"groups": group_list}
+        return self._session.patch(url, json=data).json()
+
+    @property
+    def associations(self) -> dict[list[dict[str, str]]]:
+        """
+        Return the group and user associations for this lab.
+
+        :returns: An object containing group and user list of objects consisting of ID
+            and permissions.
+        """
+        url = self._url_for("associations")
+        return self._session.get(url).json()
+
+    @check_stale
+    def update_associations(
+        self, associations: dict[list[dict[str, str]]]
+    ) -> dict[list[dict[str, str]]]:
+        """
+        Modify lab/group/user associations.
+
+        :param associations: An object containing group and user list of objects
+            consisting of ID and permissions.
+        :returns: Updated object containing group and user list of objects consisting
+            of ID and permissions.
+        """
+        url = self._url_for("associations")
+        return self._session.patch(url, json=associations).json()
 
     @property
     def connector_mappings(self) -> list[dict[str, Any]]: