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`, `principal_type`, and `role`
+            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

@@ -190,6 +190,21 @@ def test(self):
             role=role,
         )
 
+        with pytest.raises(TypeError):
+            permissions.create(  # pyright: ignore[reportCallIssue]
+                "not a user or group",
+            )
+        with pytest.raises(ValueError):
+            permissions.create(  # pyright: ignore[reportCallIssue]
+                User(params, guid=principal_guid),
+                principal_guid=principal_guid,
+            )
+        with pytest.raises(ValueError):
+            permissions.create(  # pyright: ignore[reportCallIssue]
+                User(params, guid=principal_guid),
+                principal_type=principal_type,
+            )
+
         # assert
         assert permission == fake_permission