Simplify add and delete methods to only accept a single user/group for consistency.

Author: schloerke

src/posit/connect/groups.py

@@ -74,17 +74,17 @@ def __init__(self, ctx: Context, group_guid: str) -> None:
         self._ctx: Context = ctx
 
     @overload
-    def add(self, *args: User) -> None: ...
+    def add(self, user: User, /) -> None: ...
     @overload
-    def add(self, *, user_guid: str) -> None: ...
+    def add(self, /, *, user_guid: str) -> None: ...
 
-    def add(self, *args: User, user_guid: Optional[str] = None) -> None:
+    def add(self, user: Optional[User] = None, /, *, user_guid: Optional[str] = None) -> None:
         """Add a user to the group.
 
         Parameters
         ----------
-        *args : User
-            User objects to add to the group.
+        user : User
+            User object to add to the group. Only one of `user=` or `user_guid=` can be provided.
         user_guid : str
             The user GUID.
 
@@ -103,7 +103,8 @@ def add(self, *args: User, user_guid: Optional[str] = None) -> None:
 
         # Add multiple users to the group
         users = client.users.find()
-        group.members.add(*users)
+        for user in users:
+            group.members.add(user)
 
         # Add a user to the group by GUID
         group.members.add(user_guid="USER_GUID_HERE")
@@ -113,19 +114,15 @@ def add(self, *args: User, user_guid: Optional[str] = None) -> None:
         --------
         * https://docs.posit.co/connect/api/#post-/v1/groups/-group_guid-/members
         """
-        if len(args) > 0:
+        if user is not None:
             from .users import User
 
             if user_guid:
-                raise ValueError("Only one of `*args` or `user_guid=` should be provided.")
-            for i, user in enumerate(args):
-                if not isinstance(user, User):
-                    raise TypeError(f"args[{i}] is not a `User` object. Received {user}")
+                raise ValueError("Only one of `user=` or `user_guid=` should be provided.")
+            if not isinstance(user, User):
+                raise TypeError(f"`user=` is not a `User` object. Received {user}")
 
-            for user in args:
-                self.add(user_guid=user["guid"])
-
-            return
+            user_guid = user["guid"]
 
         if not isinstance(user_guid, str):
             raise TypeError(f"`user_guid=` should be a string. Received {user_guid}")
@@ -137,17 +134,17 @@ def add(self, *args: User, user_guid: Optional[str] = None) -> None:
         self._ctx.session.post(url, json={"user_guid": user_guid})
 
     @overload
-    def delete(self, *args: User) -> None: ...
+    def delete(self, user: User, /) -> None: ...
     @overload
-    def delete(self, *, user_guid: str) -> None: ...
+    def delete(self, /, *, user_guid: str) -> None: ...
 
-    def delete(self, *args: User, user_guid: Optional[str] = None) -> None:
+    def delete(self, user: Optional[User] = None, /, *, user_guid: Optional[str] = None) -> None:
         """Remove a user from the group.
 
         Parameters
         ----------
-        *args : User
-            User objects to remove from the group.
+        user : User
+            User object to add to the group. Only one of `user=` or `user_guid=` can be provided.
         user_guid : str
             The user GUID.
 
@@ -166,7 +163,8 @@ def delete(self, *args: User, user_guid: Optional[str] = None) -> None:
 
         # Remove multiple users from the group
         group_users = group.members.find()[:2]
-        group.members.delete(*group_users)
+        for group_user in group_users:
+            group.members.delete(group_user)
 
         # Remove a user from the group by GUID
         group.members.delete(user_guid="USER_GUID_HERE")
@@ -176,19 +174,15 @@ def delete(self, *args: User, user_guid: Optional[str] = None) -> None:
         --------
         * https://docs.posit.co/connect/api/#delete-/v1/groups/-group_guid-/members/-user_guid-
         """
-        if len(args) > 0:
+        if user is not None:
             from .users import User
 
             if user_guid:
-                raise ValueError("Only one of `*args` or `user_guid=` should be provided.")
-            for i, user in enumerate(args):
-                if not isinstance(user, User):
-                    raise TypeError(f"`args[{i}]` is not a `User` object. Received {user}")
-
-            for user in args:
-                self.delete(user_guid=user["guid"])
+                raise ValueError("Only one of `user=` or `user_guid=` should be provided.")
+            if not isinstance(user, User):
+                raise TypeError(f"`user=` is not a `User` object. Received {user}")
 
-            return
+            user_guid = user["guid"]
 
         if not isinstance(user_guid, str):
             raise TypeError(f"`user_guid=` should be a string. Received {user_guid}")

src/posit/connect/users.py

@@ -170,22 +170,19 @@ def __init__(self, ctx: Context, user_guid: str) -> None:
         self._user_guid: str = user_guid
 
     @overload
-    def add(self, *args: Group) -> None: ...
+    def add(self, group: Group, /) -> None: ...
     @overload
-    def add(self, *, group_guid: str) -> None: ...
+    def add(self, /, *, group_guid: str) -> None: ...
 
-    def add(
-        self,
-        *args: Group,
-        group_guid: Optional[str] = None,
-    ) -> None:
+    def add(self, group: Optional[Group] = None, /, *, group_guid: Optional[str] = None) -> None:
         """
-        Add the user to the specified groups.
+        Add the user to the specified group.
 
         Parameters
         ----------
-        *args : Group
-            The groups to which the user will be added.
+        group : Group
+            The groups to which the user will be added. Only one of `group=` or `group_guid=` can
+            be provided.
         group_guid : str
             The unique identifier (guid) of the group to which the user will be added.
 
@@ -211,7 +208,8 @@ def add(
             client.groups.get("GROUP_GUID_1"),
             client.groups.get("GROUP_GUID_2"),
         ]
-        user.groups.add(*groups)
+        for group in groups:
+            user.groups.add(group)
 
         # Add the user to a group by GUID
         user.groups.add(group_guid="GROUP_GUID_HERE")
@@ -221,43 +219,44 @@ def add(
         --------
         * https://docs.posit.co/connect/api/#post-/v1/groups/-group_guid-/members
         """
-        if len(args) > 0:
+        if group is not None:
             from .groups import Group
 
             if group_guid:
-                raise ValueError("Only one of `*args` or `group_guid` may be be provided.")
-
-            for i, group in enumerate(args):
-                if not isinstance(group, Group):
-                    raise TypeError(
-                        f"`args[{i}]` is not an instance of Group. Received {group}",
-                    )
-            for group in args:
-                group.members.add(user_guid=self._user_guid)
+                raise ValueError("Only one of `group=` or `group_guid` may be be provided.")
+
+            if not isinstance(group, Group):
+                raise TypeError(
+                    f"`group=` is not an instance of Group. Received {group}",
+                )
+            group.members.add(user_guid=self._user_guid)
             return
 
         if not group_guid:
-            raise ValueError("Only one of `*args` or `group_guid` may be be provided.")
+            raise ValueError("Only one of `group=` or `group_guid` may be be provided.")
         group = self._ctx.client.groups.get(group_guid)
         group.members.add(user_guid=self._user_guid)
 
     @overload
-    def delete(self, *args: Group) -> None: ...
+    def delete(self, group: Group, /) -> None: ...
     @overload
-    def delete(self, *, group_guid: str) -> None: ...
+    def delete(self, /, *, group_guid: str) -> None: ...
 
     def delete(
         self,
-        *args: Group,
+        group: Optional[Group] = None,
+        /,
+        *,
         group_guid: Optional[str] = None,
     ) -> None:
         """
-        Remove the user from the specified groups.
+        Remove the user from the specified group.
 
         Parameters
         ----------
-        *args : Group
-            The groups from which the user will be removed.
+        group : Group
+            The groups to which the user will be added. Only one of `group=` or `group_guid=` can
+            be provided.
         group_guid : str
             The unique identifier (guid) of the group from which the user will be removed.
 
@@ -283,7 +282,8 @@ def delete(
             client.groups.get("GROUP_GUID_1"),
             client.groups.get("GROUP_GUID_2"),
         ]
-        user.groups.delete(*groups)
+        for group in groups:
+            user.groups.delete(group)
 
         # Remove the user from a group by GUID
         user.groups.delete(group_guid="GROUP_GUID_HERE")
@@ -293,19 +293,17 @@ def delete(
         --------
         * https://docs.posit.co/connect/api/#delete-/v1/groups/-group_guid-/members/-user_guid-
         """
-        if len(args) > 0:
+        if group is not None:
             from .groups import Group
 
             if group_guid:
-                raise ValueError("Only one of `*args` or `group_guid=` may be be provided.")
-
-            for i, group in enumerate(args):
-                if not isinstance(group, Group):
-                    raise TypeError(
-                        f"`args[{i}]` is not an instance of Group. Received {group}",
-                    )
-            for group in args:
-                group.members.delete(user_guid=self._user_guid)
+                raise ValueError("Only one of `group=` or `group_guid=` may be be provided.")
+
+            if not isinstance(group, Group):
+                raise TypeError(
+                    f"`group=` is not an instance of Group. Received {group}",
+                )
+            group.members.delete(user_guid=self._user_guid)
             return
 
         if not isinstance(group_guid, str):

tests/posit/connect/test_groups.py

@@ -73,7 +73,6 @@ def test_members_add(self):
 
         user = User(self.client._ctx, guid=user_guid)
         self.group.members.add(user)
-        self.group.members.add(user, user)
         self.group.members.add(user_guid=user["guid"])
 
         with pytest.raises(TypeError):
@@ -102,7 +101,6 @@ def test_members_delete(self):
         user = User(self.client._ctx, guid=user_guid)
 
         self.group.members.delete(user)
-        self.group.members.delete(user, user)
         self.group.members.delete(user_guid=user["guid"])
 
         with pytest.raises(TypeError):