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

src/posit/connect/permissions.py

@@ -73,30 +73,104 @@ def create(self, *, principal_guid: str, principal_type: str, role: str) -> Perm
         Parameters
         ----------
         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:
+    def create(self, *args: User | Group, role: str) -> 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.
+
         Returns
         -------
         Permission
-        """
 
-    def create(self, **kwargs) -> Permission:
-        """Create a permission.
+        Examples
+        --------
+        ```python
+        from posit import connect
 
-        Returns
-        -------
-        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,
+        )
+
+        # Confirm new permissions
+        content_item.permissions.find()
+        ```
         """
+
+    def create(self, *args: User | Group, **kwargs) -> Permission | list[Permission]:
+        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.")
+
+            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)