feat: Add Permission.create(principal:User | Group) support

src/posit/connect/permissions.py

@@ -67,36 +67,105 @@ 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]:
         """Create a permission.
 
         Parameters
         ----------
+        *args : User | Group
+            The principal users or groups to add.
+        role : str
+            The principal role. Currently only `"viewer"` and `"owner"` are supported.
         principal_guid : str
+            User guid or Group guid.
         principal_type : str
+            The principal type. Either `"user"` or `"group"`.
         role : str
+            The principal role. Currently only `"viewer"` and `"owner"` are supported
 
         Returns
         -------
-        Permission
-        """
-
-    @overload
-    def create(self, **kwargs) -> Permission:
-        """Create a permission.
+        Permission | List[Permission]
+            Returns a `Permission` when the kwargs: `principal_guid` and `principal_type` are used.
+            Returns a `list[Permission]` when `*args` are used.
 
-        Returns
-        -------
-        Permission
-        """
+        Examples
+        --------
+        ```python
+        from posit import connect
 
-    def create(self, **kwargs) -> Permission:
-        """Create a permission.
+        client = connect.Client()
+        content_item = client.content.get(content_guid)
+
+        # New permission role
+        role = "viewer"  # Or "owner"
+
+        # Example groups and users
+        groups = client.groups.find(prefix="GROUP_NAME_PREFIX_HERE")
+        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)
+
+        # 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 a group permission manually
+        content_item.permissions.create(
+            principal_guid=group["guid"],
+            principal_type="group",
+            role=role,
+        )
+        # Add a user permission manually
+        content_item.permissions.create(
+            principal_guid=user["guid"],
+            principal_type="user",
+            role=role,
+        )
 
-        Returns
-        -------
-        Permission
+        # Confirm new permissions
+        content_item.permissions.find()
+        ```
         """
+        if len(args) > 0:
+            # 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 "principal_guid" in kwargs:
+                raise ValueError("'principal_guid' can not be defined with `*args` 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
+
         path = f"v1/content/{self.content_guid}/permissions"
         url = self.params.url + path
         response = self.params.session.post(url, json=kwargs)
@@ -158,7 +227,7 @@ def destroy(self, *permissions: str | Group | User | Permission) -> list[Permiss
         Returns
         -------
         list[Permission]
-            The removed permissions. If a permission is not found, there is nothing to remove and 
+            The removed permissions. If a permission is not found, there is nothing to remove and
             it is not included in the returned list.
 
         Examples

tests/posit/connect/test_permissions.py

@@ -193,6 +193,83 @@ def test(self):
         # assert
         assert permission == fake_permission
 
+    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)
+
+        # behavior
+        with pytest.raises(TypeError, match="str"):
+            permissions.create(  # pyright: ignore[reportCallIssue]
+                user,
+                group,
+                "not a user or group",
+            )
+        with pytest.raises(ValueError):
+            permissions.create(  # pyright: ignore[reportCallIssue]
+                user,
+                principal_guid=principal_guid,
+            )
+        with pytest.raises(ValueError):
+            permissions.create(  # pyright: ignore[reportCallIssue]
+                user,
+                principal_type="viewer",
+            )
+
+    @responses.activate
+    def test_multiple(self):
+        # data
+        content_guid = "CONTENT_GUID"
+        user_guid = "USER_GUID"
+        group_guid = "GROUP_GUID"
+
+        fake_user = {
+            "principal_guid": user_guid,
+            "principal_type": "user",
+            "role": "viewer",
+        }
+        fake_group = {
+            "principal_guid": group_guid,
+            "principal_type": "group",
+            "role": "viewer",
+        }
+        res_user = responses.post(
+            f"https://connect.example/__api__/v1/content/{content_guid}/permissions",
+            json=fake_user,
+            match=[matchers.json_params_matcher(fake_user)],
+        )
+        res_group = responses.post(
+            f"https://connect.example/__api__/v1/content/{content_guid}/permissions",
+            json=fake_group,
+            match=[matchers.json_params_matcher(fake_group)],
+        )
+
+        # 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)
+
+        # invoke
+        permissions = permissions.create(user, group, role="viewer")
+
+        # assert
+        assert res_user.call_count == 1
+        assert res_group.call_count == 1
+
+        assert isinstance(permissions, list)
+        for permission in 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"),
+        ]
+
 
 class TestPermissionsFind:
     @responses.activate