diff --git a/src/globus_sdk/services/groups/data.py b/src/globus_sdk/services/groups/data.py index e58788149..8760c58fd 100644 --- a/src/globus_sdk/services/groups/data.py +++ b/src/globus_sdk/services/groups/data.py @@ -87,6 +87,9 @@ def accept_invites( """ Accept invites for identities. The identities must belong to the identity set of authenticated user. + + :param identity_ids: The identities for whom to accept invites + :type identity_ids: iterable of UUIDs or strings """ self.setdefault("accept", []).extend( {"identity_id": identity_id} @@ -102,6 +105,11 @@ def add_members( ) -> BatchMembershipActions: """ Add a list of identities to a group with the given role. + + :param identity_ids: The identities to add to the group + :type identity_ids: iterable of UUIDs or strings + :param role: The role for the new group members + :type role: str or :class:`~.GroupRole` """ self.setdefault("add", []).extend( {"identity_id": identity_id, "role": utils.render_enums_for_api(role)} @@ -114,6 +122,9 @@ def approve_pending( ) -> BatchMembershipActions: """ Approve a list of identities with pending join requests. + + :param identity_ids: The identities to approve as members of the group + :type identity_ids: iterable of UUIDs or strings """ self.setdefault("approve", []).extend( {"identity_id": identity_id} @@ -126,6 +137,9 @@ def decline_invites( ) -> BatchMembershipActions: """ Decline an invitation for a given set of identities. + + :param identity_ids: The identities for whom invitations should be declined + :type identity_ids: iterable of UUIDs or strings """ self.setdefault("decline", []).extend( {"identity_id": identity_id} @@ -141,6 +155,11 @@ def invite_members( ) -> BatchMembershipActions: """ Invite a list of identities to a group with the given role. + + :param identity_ids: The identities to invite to the group + :type identity_ids: iterable of UUIDs or strings + :param role: The role for the invited group members + :type role: str or :class:`~.GroupRole` """ self.setdefault("invite", []).extend( {"identity_id": identity_id, "role": utils.render_enums_for_api(role)} @@ -152,6 +171,9 @@ def join(self, identity_ids: t.Iterable[UUIDLike]) -> BatchMembershipActions: """ Join a group with the given identities. The identities must be in the authenticated users identity set. + + :param identity_ids: The identities to use to join the group + :type identity_ids: iterable of UUIDs or strings """ self.setdefault("join", []).extend( {"identity_id": identity_id} @@ -163,6 +185,9 @@ def leave(self, identity_ids: t.Iterable[UUIDLike]) -> BatchMembershipActions: """ Leave a group that one of the identities in the authenticated user's identity set is a member of. + + :param identity_ids: The identities to remove from the group + :type identity_ids: iterable of UUIDs or strings """ self.setdefault("leave", []).extend( {"identity_id": identity_id} @@ -174,7 +199,10 @@ def reject_join_requests( self, identity_ids: t.Iterable[UUIDLike] ) -> BatchMembershipActions: """ - Reject a members that have requested to join the group. + Reject identities which have requested to join the group. + + :param identity_ids: The identities to reject from the group + :type identity_ids: iterable of UUIDs or strings """ self.setdefault("reject", []).extend( {"identity_id": identity_id} @@ -188,6 +216,9 @@ def remove_members( """ Remove members from a group. This must be done as an admin or manager of the group. + + :param identity_ids: The identities to remove from the group + :type identity_ids: iterable of UUIDs or strings """ self.setdefault("remove", []).extend( {"identity_id": identity_id} @@ -200,6 +231,9 @@ def request_join( ) -> BatchMembershipActions: """ Request to join a group. + + :param identity_ids: The identities to use to request membership in the group + :type identity_ids: iterable of UUIDs or strings """ self.setdefault("request_join", []).extend( {"identity_id": identity_id} diff --git a/src/globus_sdk/services/groups/manager.py b/src/globus_sdk/services/groups/manager.py index 4f4c908cb..3164ed2d4 100644 --- a/src/globus_sdk/services/groups/manager.py +++ b/src/globus_sdk/services/groups/manager.py @@ -35,8 +35,15 @@ def create_group( parent_id: UUIDLike | None = None, ) -> response.GlobusHTTPResponse: """ - Create a group with the given name. If a parent id is included, the + Create a group with the given name. If a parent ID is included, the group will be a subgroup of the given parent group. + + :param name: The name of the group + :type name: str + :param description: A description of the group + :type description: str + :param parent_id: The ID of the parent group, if there is one + :type parent_id: str or UUID, optional """ data = { "name": name, @@ -58,6 +65,23 @@ def set_group_policies( ) -> response.GlobusHTTPResponse: """ Set the group policies for the given group. + + :param group_id: The ID of the group on which to set policies + :type group_id: str or UUID + :param is_high_assurance: Whether the group can provide a High Assurance + guarantee when used for access controls + :type is_high_assurance: bool + :param group_visibility: The visibility of the group + :type group_visibility: str or :class:`~.GroupVisibility` + :param group_members_visibility: The visibility of memberships within the group + :type group_members_visibility: str or :class:`~.GroupMemberVisibility` + :param join_requests: Whether the group allows users to request to join + :type join_requests: bool + :param signup_fields: The required fields for a user to sign up for the group + :type signup_fields: iterable of str or :class:`~.GroupRequiredSignupFields` + :param authentication_assurance_timeout: The timeout used when this group is + used to apply a High Assurance authentication guarantee + :type authentication_assurance_timeout: int, optional """ data = GroupPolicies( is_high_assurance=is_high_assurance, @@ -75,6 +99,11 @@ def accept_invite( """ Accept invite for an identity. The identity must belong to the identity set of the authenticated user. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity for whom to accept the invite + :type identity_id: str or UUID """ actions = BatchMembershipActions().accept_invites([identity_id]) return self.client.batch_membership_action(group_id, actions) @@ -87,7 +116,14 @@ def add_member( role: _GROUP_ROLE_T = "member", ) -> response.GlobusHTTPResponse: """ - Add a list of identities to a group with the given role. + Add an identity to a group with the given role. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity to add to the group + :type identity_id: str or UUID + :param role: The role for the new group member + :type role: str or :class:`~.GroupRole` """ actions = BatchMembershipActions().add_members([identity_id], role=role) return self.client.batch_membership_action(group_id, actions) @@ -96,7 +132,12 @@ def approve_pending( self, group_id: UUIDLike, identity_id: UUIDLike ) -> response.GlobusHTTPResponse: """ - Approve a list of identities with pending join requests. + Approve an identity with a pending join request. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity to approve as a member of the group + :type identity_id: str or UUID """ actions = BatchMembershipActions().approve_pending([identity_id]) return self.client.batch_membership_action(group_id, actions) @@ -106,6 +147,11 @@ def decline_invite( ) -> response.GlobusHTTPResponse: """ Decline an invitation for a given identity. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity for whom to decline the invitation + :type identity_id: str or UUID """ actions = BatchMembershipActions().decline_invites([identity_id]) return self.client.batch_membership_action(group_id, actions) @@ -119,6 +165,13 @@ def invite_member( ) -> response.GlobusHTTPResponse: """ Invite an identity to a group with the given role. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity to invite as a new group member + :type identity_id: str or UUID + :param role: The role for the invited group member + :type role: str or :class:`~.GroupRole` """ actions = BatchMembershipActions().invite_members([identity_id], role=role) return self.client.batch_membership_action(group_id, actions) @@ -129,6 +182,11 @@ def join( """ Join a group with the given identity. The identity must be in the authenticated users identity set. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity to use to join the group + :type identity_id: str or UUID """ actions = BatchMembershipActions().join([identity_id]) return self.client.batch_membership_action(group_id, actions) @@ -139,6 +197,11 @@ def leave( """ Leave a group that one of the identities in the authenticated user's identity set is a member of. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity to remove from the group + :type identity_id: str or UUID """ actions = BatchMembershipActions().leave([identity_id]) return self.client.batch_membership_action(group_id, actions) @@ -148,6 +211,11 @@ def reject_join_request( ) -> response.GlobusHTTPResponse: """ Reject a member that has requested to join the group. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity to reject from the group + :type identity_id: str or UUID """ actions = BatchMembershipActions().reject_join_requests([identity_id]) return self.client.batch_membership_action(group_id, actions) @@ -156,8 +224,13 @@ def remove_member( self, group_id: UUIDLike, identity_id: UUIDLike ) -> response.GlobusHTTPResponse: """ - Remove members from a group. This must be done as an admin or manager + Remove a member from a group. This must be done as an admin or manager of the group. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity to remove from the group + :type identity_id: str or UUID """ actions = BatchMembershipActions().remove_members([identity_id]) return self.client.batch_membership_action(group_id, actions) @@ -167,6 +240,11 @@ def request_join( ) -> response.GlobusHTTPResponse: """ Request to join a group. + + :param group_id: The ID of the group + :type group_id: str or UUID + :param identity_id: The identity to use to request membership in the group + :type identity_id: str or UUID """ actions = BatchMembershipActions().request_join([identity_id]) return self.client.batch_membership_action(group_id, actions)