Simplify creating of Permissions to only create a single permission

Author: schloerke

src/posit/connect/permissions.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, List, overload
+from typing import TYPE_CHECKING, List, Optional, overload
 
 from requests.sessions import Session as Session
 
@@ -67,18 +67,23 @@ def count(self) -> int:
         return len(self.find())
 
     @overload
-    def create(self, *, principal_guid: str, principal_type: str, role: str) -> Permission: ...
+    def create(self, /, *, principal_guid: str, principal_type: str, role: str) -> Permission: ...
 
     @overload
-    def create(self, *args: User | Group, role: str) -> list[Permission]: ...
-
-    def create(self, *args: User | Group, **kwargs) -> Permission | list[Permission]:
+    def create(self, principal: User | Group, /, *, role: str) -> Permission: ...
+
+    def create(
+        self,
+        principal: Optional[User | Group] = None,
+        /,
+        **kwargs,
+    ) -> Permission:
         """Create a permission.
 
         Parameters
         ----------
-        *args : User | Group
-            The principal users or groups to add.
+        principal : User | Group
+            The principal user or group to add.
         role : str
             The principal role. Currently only `"viewer"` and `"owner"` are supported.
         principal_guid : str
@@ -90,9 +95,8 @@ def create(self, *args: User | Group, **kwargs) -> Permission | list[Permission]
 
         Returns
         -------
-        Permission | List[Permission]
-            Returns a `Permission` when the kwargs: `principal_guid` and `principal_type` are used.
-            Returns a `list[Permission]` when `*args` are used.
+        Permission
+            The created permission.
 
         Examples
         --------
@@ -107,18 +111,19 @@ def create(self, *args: User | Group, **kwargs) -> Permission | list[Permission]
 
         # Example groups and users
         groups = client.groups.find(prefix="GROUP_NAME_PREFIX_HERE")
+        group = groups[0]
         user = client.users.get("USER_GUID_HERE")
-        users = [user]
-
-        # Add many group and user permissions with the same role
-        content_item.permissions.create(*groups, *users, role=role)
+        users_and_groups = [user, *groups]
 
         # Add a group permission
-        group = groups[0]
         content_item.permissions.create(group, role=role)
         # Add a user permission
         content_item.permissions.create(user, role=role)
 
+        # Add many group and user permissions with the same role
+        for principal in users_and_groups:
+            content_item.permissions.create(principal, role=role)
+
         # Add a group permission manually
         content_item.permissions.create(
             principal_guid=group["guid"],
@@ -136,35 +141,26 @@ def create(self, *args: User | Group, **kwargs) -> Permission | list[Permission]
         content_item.permissions.find()
         ```
         """
-        if len(args) > 0:
+        if principal is not None:
             # Avoid circular imports
             from .groups import Group
             from .users import User
 
-            for arg in args:
-                if not isinstance(arg, (User, Group)):
-                    raise TypeError(f"Invalid argument type: {type(arg)}")
+            if isinstance(principal, User):
+                principal_type = "user"
+            elif isinstance(principal, Group):
+                principal_type = "group"
+            else:
+                raise TypeError(f"Invalid argument type: {type(principal).__name__}")
+
             if "principal_guid" in kwargs:
-                raise ValueError("'principal_guid' can not be defined with `*args` present.")
+                raise ValueError("'principal_guid' can not be defined with `principal` present.")
             if "principal_type" in kwargs:
-                raise ValueError("'principal_guid' can not be defined with `*args` present.")
-
-            perms: list[Permission] = []
-            for arg in args:
-                if isinstance(arg, User):
-                    principal_type = "user"
-                elif isinstance(arg, Group):
-                    principal_type = "group"
-                else:
-                    raise TypeError(f"Invalid argument type: {type(arg)}")
-
-                perm = self.create(
-                    principal_guid=arg["guid"],
-                    principal_type=principal_type,
-                    role=kwargs["role"],
-                )
-                perms.append(perm)
-            return perms
+                raise ValueError("'principal_guid' can not be defined with `principal` present.")
+
+            # Set the corresponding kwargs
+            kwargs["principal_guid"] = principal["guid"]
+            kwargs["principal_type"] = principal_type
 
         path = f"v1/content/{self.content_guid}/permissions"
         url = self.params.url + path

tests/posit/connect/test_permissions.py

@@ -199,16 +199,14 @@ def test_assertions(self):
         # setup
         principal_guid = "principal_guid"
         content_guid = "content_guid"
-        params = ResourceParameters(requests.Session(), Url("https://connect.example/__api__"))
-        permissions = Permissions(params, content_guid=content_guid)
-        user = User(params, guid=principal_guid)
-        group = User(params, guid=principal_guid)
+        client = Client("https://connect.example/__api__", "12345")
+        permissions = Permissions(client.resource_params, content_guid=content_guid)
+        user = User(client._ctx, guid=principal_guid)
+        group = User(client._ctx, guid=principal_guid)
 
         # behavior
         with pytest.raises(TypeError, match="str"):
             permissions.create(  # pyright: ignore[reportCallIssue]
-                user,
-                group,
                 "not a user or group",
             )
         with pytest.raises(ValueError):
@@ -223,7 +221,7 @@ def test_assertions(self):
             )
 
     @responses.activate
-    def test_multiple(self):
+    def test_user_group(self):
         # data
         content_guid = "CONTENT_GUID"
         user_guid = "USER_GUID"
@@ -251,25 +249,37 @@ def test_multiple(self):
         )
 
         # setup
-        params = ResourceParameters(requests.Session(), Url("https://connect.example/__api__"))
-        permissions = Permissions(params, content_guid=content_guid)
-        user = User(params, guid=user_guid)
-        group = Group(params, guid=group_guid)
+        client = Client("https://connect.example/__api__", "12345")
+        permissions = Permissions(client.resource_params, content_guid=content_guid)
+        user = User(client._ctx, guid=user_guid)
+        group = Group(client._ctx, guid=group_guid)
 
         # invoke
-        permissions = permissions.create(user, group, role="viewer")
+        user_perm = permissions.create(user, role="viewer")
+        group_perm = permissions.create(group, role="viewer")
+
+        created_permissions = [user_perm, group_perm]
 
         # assert
         assert res_user.call_count == 1
         assert res_group.call_count == 1
 
-        assert isinstance(permissions, list)
-        for permission in permissions:
+        for permission in created_permissions:
             assert isinstance(permission, Permission)
 
-        assert permissions == [
-            Permission(params, principal_guid=user_guid, principal_type="user", role="viewer"),
-            Permission(params, principal_guid=group_guid, principal_type="group", role="viewer"),
+        assert created_permissions == [
+            Permission(
+                client.resource_params,
+                principal_guid=user_guid,
+                principal_type="user",
+                role="viewer",
+            ),
+            Permission(
+                client.resource_params,
+                principal_guid=group_guid,
+                principal_type="group",
+                role="viewer",
+            ),
         ]