Globus Groups

class globus_sdk.GroupsClient(*, environment: str | None = None, base_url: str | None = None, authorizer: GlobusAuthorizer | None = None, app_name: str | None = None, transport_params: dict[str, Any] | None = None)

Bases: BaseClient

Client for the Globus Groups API.

This provides a relatively low level client to public groups API endpoints. You may also consider looking at the GroupsManager as a simpler interface to more common actions.

Methods

• batch_membership_action()

• create_group()

• delete_group()

• get_group()

• get_group_policies()

• get_identity_preferences()

• get_membership_fields()

• get_my_groups()

• set_group_policies()

• set_identity_preferences()

• set_membership_fields()

• update_group()

scopes: ScopeBuilder | None = <globus_sdk.scopes.builder.ScopeBuilder object>

the scopes for this client may be present as a ScopeBuilder

get_my_groups(*, query_params: dict[str, Any] | None = None) → ArrayResponse

Return a list of groups your identity belongs to.

Parameters:

query_params (dict, optional) – Additional passthrough query parameters

API Info

GET /v2/groups/my_groups

See Retrieve your groups and membership in the API documentation for details.

get_group(group_id: UUID | str, *, include: None | str | Iterable[str] = None, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Get details about a specific group

Parameters:

• group_id (str or UUID) – the ID of the group

• include (str or iterable of str, optional) – list of additional fields to include (allowed fields are memberships, my_memberships, policies, allowed_actions, and child_ids)

• query_params (dict, optional) – additional passthrough query parameters

API Info

GET /v2/groups/<group_id>

See Get Group in the API documentation for details.

delete_group(group_id: UUID | str, *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Delete a group.

Parameters:

• group_id (str or UUID) – the ID of the group

• query_params (dict, optional) – additional passthrough query parameters

API Info

DELETE /v2/groups/<group_id>

See Delete a Group in the API documentation for details.

create_group(data: dict[str, Any], *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Create a group.

Parameters:

• data (dict) – the group document to create

• query_params (dict, optional) – additional passthrough query parameters

API Info

POST /v2/groups

See Create a Group in the API documentation for details.

update_group(group_id: UUID | str, data: dict[str, Any], *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Update a given group.

Parameters:

• group_id (str or UUID) – the ID of the group

• data (dict) – the group document to use for update

• query_params (dict, optional) – additional passthrough query parameters

API Info

PUT /v2/groups/<group_id>

See Update a Group in the API documentation for details.

get_group_policies(group_id: UUID | str, *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Get policies for the given group

Parameters:

• group_id (str or UUID) – the ID of the group

• query_params (dict, optional) – additional passthrough query parameters

API Info

GET /v2/groups/<group_id>/policies

See Get the policies for a group in the API documentation for details.

set_group_policies(group_id: UUID | str, data: dict[str, Any] | GroupPolicies, *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Set policies for the group.

Parameters:

• group_id (str or UUID) – the ID of the group

• data (dict or GroupPolicies) – the group policy document to set

• query_params (dict, optional) – additional passthrough query parameters

API Info

PUT /v2/groups/<group_id>/policies

See Set the policies for a group in the API documentation for details.

get_identity_preferences(*, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Get identity preferences. Currently this only includes whether the user allows themselves to be added to groups.

Parameters:

query_params (dict, optional) – additional passthrough query parameters

API Info

GET /v2/preferences

See Get the preferences for your identity set in the API documentation for details.

set_identity_preferences(data: dict[str, Any], *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Set identity preferences. Currently this only includes whether the user allows themselves to be added to groups.

Parameters:

• data (dict) – the identity set preferences document

• query_params (dict, optional) – additional passthrough query parameters

Example Usage

gc = globus_sdk.GroupsClient(...)
gc.set_identity_preferences({"allow_add": False})

API Info

PUT /v2/preferences

See Set the preferences for your identity set in the API documentation for details.

get_membership_fields(group_id: UUID | str, *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Get membership fields for your identities.

Parameters:

• group_id (str or UUID) – the ID of the group

• query_params (dict, optional) – additional passthrough query parameters

API Info

GET /v2/groups/<group_id>/membership_fields

See Get the membership fields for your identity set in the API documentation for details.

set_membership_fields(group_id: UUID | str, data: dict[Any, str], *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Set membership fields for your identities.

Parameters:

• group_id (str or UUID) – the ID of the group

• data (dict) – the membership fields document

• query_params (dict, optional) – additional passthrough query parameters

API Info

PUT /v2/groups/<group_id>/membership_fields

See Set the membership fields for your identity set in the API documentation for details.

batch_membership_action(group_id: UUID | str, actions: dict[str, Any] | BatchMembershipActions, *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse

Execute a batch of actions against several group memberships.

Parameters:

• group_id (str or UUID) – the ID of the group

• actions (dict or BatchMembershipActions) – the batch of membership actions to perform, modifying, creating, and removing memberships in the group

• query_params (dict, optional) – additional passthrough query parameters

Example Usage

gc = globus_sdk.GroupsClient(...)
group_id = ...
batch = globus_sdk.BatchMembershipActions()
batch.add_members("ae332d86-d274-11e5-b885-b31714a110e9")
batch.invite_members("c699d42e-d274-11e5-bf75-1fc5bf53bb24")
gc.batch_membership_action(group_id, batch)

API Info

PUT /v2/groups/<group_id>/membership_fields

See Perform actions on members of the group in the API documentation for details.

Helper Objects

These helper objects make it easier to create and submit data to a GroupsClient. Additionally, they may be used in concert with the GroupsManager to perform operations.

These enums define values which can be passed to other helpers:

class globus_sdk.GroupMemberVisibility(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

managers = 'managers'

members = 'members'

class globus_sdk.GroupRequiredSignupFields(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

address = 'address'

address1 = 'address1'

address2 = 'address2'

city = 'city'

country = 'country'

current_project_name = 'current_project_name'

department = 'department'

field_of_science = 'field_of_science'

institution = 'institution'

phone = 'phone'

state = 'state'

zip = 'zip'

class globus_sdk.GroupRole(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

admin = 'admin'

manager = 'manager'

member = 'member'

class globus_sdk.GroupVisibility(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

authenticated = 'authenticated'

private = 'private'

Payload Types

A BatchMembershipActions defines how to formulate requests to add, remove, or modify memberships in a group. It can be used to formulate multiple operations to submit in a single request to the service.

class globus_sdk.BatchMembershipActions(dict=None, /, **kwargs)

An object used to represent a batch action on memberships of a group. Perform actions on group members.

accept_invites(identity_ids: Iterable[UUID | str]) → BatchMembershipActions

Accept invites for identities. The identities must belong to the identity set of authenticated user.

Parameters:

identity_ids (iterable of UUIDs or strings) – The identities for whom to accept invites

add_members(identity_ids: Iterable[UUID | str], *, role: GroupRole | Literal['member', 'manager', 'admin'] = 'member') → BatchMembershipActions

Add a list of identities to a group with the given role.

Parameters:

• identity_ids (iterable of UUIDs or strings) – The identities to add to the group

• role (str or GroupRole) – The role for the new group members

approve_pending(identity_ids: Iterable[UUID | str]) → BatchMembershipActions

Approve a list of identities with pending join requests.

Parameters:

identity_ids (iterable of UUIDs or strings) – The identities to approve as members of the group

decline_invites(identity_ids: Iterable[UUID | str]) → BatchMembershipActions

Decline an invitation for a given set of identities.

Parameters:

identity_ids (iterable of UUIDs or strings) – The identities for whom invitations should be declined

invite_members(identity_ids: Iterable[UUID | str], *, role: GroupRole | Literal['member', 'manager', 'admin'] = 'member') → BatchMembershipActions

Invite a list of identities to a group with the given role.

Parameters:

• identity_ids (iterable of UUIDs or strings) – The identities to invite to the group

• role (str or GroupRole) – The role for the invited group members

join(identity_ids: Iterable[UUID | str]) → BatchMembershipActions

Join a group with the given identities. The identities must be in the authenticated users identity set.

Parameters:

identity_ids (iterable of UUIDs or strings) – The identities to use to join the group

leave(identity_ids: Iterable[UUID | str]) → BatchMembershipActions

Leave a group that one of the identities in the authenticated user’s identity set is a member of.

Parameters:

identity_ids (iterable of UUIDs or strings) – The identities to remove from the group

reject_join_requests(identity_ids: Iterable[UUID | str]) → BatchMembershipActions

Reject identities which have requested to join the group.

Parameters:

identity_ids (iterable of UUIDs or strings) – The identities to reject from the group

remove_members(identity_ids: Iterable[UUID | str]) → BatchMembershipActions

Remove members from a group. This must be done as an admin or manager of the group.

Parameters:

identity_ids (iterable of UUIDs or strings) – The identities to remove from the group

request_join(identity_ids: Iterable[UUID | str]) → BatchMembershipActions

Request to join a group.

Parameters:

identity_ids (iterable of UUIDs or strings) – The identities to use to request membership in the group

A GroupPolicies object defines the various policies which can be set on a group. It can be used with the GroupsClient or the GroupsManager.

class globus_sdk.GroupPolicies(*, is_high_assurance: bool, group_visibility: ~globus_sdk.services.groups.data.GroupVisibility | ~typing.Literal['authenticated', 'private'], group_members_visibility: ~globus_sdk.services.groups.data.GroupMemberVisibility | ~typing.Literal['members', 'managers'], join_requests: bool, signup_fields: ~typing.Iterable[~globus_sdk.services.groups.data.GroupRequiredSignupFields | ~typing.Literal['institution', 'current_project_name', 'address', 'city', 'state', 'country', 'address1', 'address2', 'zip', 'phone', 'department', 'field_of_science']], authentication_assurance_timeout: int | None | ~globus_sdk.utils.MissingType = <globus_sdk.MISSING>)

An object used to represent the policy settings of a group. This may be used to set or modify group settings.

See also: API documentation on setting the policies for the group.

High-Level Client Wrappers

The GroupsManager is a high-level helper which wraps a GroupsClient. Many common operations which require assembling a BatchMembershipActions and submitting the result can be achieved with a single method-call on a GroupsManager.

class globus_sdk.GroupsManager(client: GroupsClient | None = None)

A wrapper for the groups client with common membership and group actions wrapped in convenient methods with parameters and type hints.

Methods

• accept_invite()

• add_member()

• approve_pending()

• create_group()

• decline_invite()

• invite_member()

• join()

• leave()

• reject_join_request()

• remove_member()

• request_join()

• set_group_policies()

accept_invite(group_id: UUID | str, identity_id: UUID | str) → GlobusHTTPResponse

Accept invite for an identity. The identity must belong to the identity set of the authenticated user.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity for whom to accept the invite

add_member(group_id: UUID | str, identity_id: UUID | str, *, role: GroupRole | Literal['member', 'manager', 'admin'] = 'member') → GlobusHTTPResponse

Add an identity to a group with the given role.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity to add to the group

• role (str or GroupRole) – The role for the new group member

approve_pending(group_id: UUID | str, identity_id: UUID | str) → GlobusHTTPResponse

Approve an identity with a pending join request.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity to approve as a member of the group

create_group(name: str, description: str, *, parent_id: UUID | str | None = None) → GlobusHTTPResponse

Create a group with the given name. If a parent ID is included, the group will be a subgroup of the given parent group.

Parameters:

• name (str) – The name of the group

• description (str) – A description of the group

• parent_id (str or UUID, optional) – The ID of the parent group, if there is one

decline_invite(group_id: UUID | str, identity_id: UUID | str) → GlobusHTTPResponse

Decline an invitation for a given identity.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity for whom to decline the invitation

invite_member(group_id: UUID | str, identity_id: UUID | str, *, role: GroupRole | Literal['member', 'manager', 'admin'] = 'member') → GlobusHTTPResponse

Invite an identity to a group with the given role.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity to invite as a new group member

• role (str or GroupRole) – The role for the invited group member

join(group_id: UUID | str, identity_id: UUID | str) → GlobusHTTPResponse

Join a group with the given identity. The identity must be in the authenticated users identity set.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity to use to join the group

leave(group_id: UUID | str, identity_id: UUID | str) → GlobusHTTPResponse

Leave a group that one of the identities in the authenticated user’s identity set is a member of.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity to remove from the group

reject_join_request(group_id: UUID | str, identity_id: UUID | str) → GlobusHTTPResponse

Reject a member that has requested to join the group.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity to reject from the group

remove_member(group_id: UUID | str, identity_id: UUID | str) → GlobusHTTPResponse

Remove a member from a group. This must be done as an admin or manager of the group.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity to remove from the group

request_join(group_id: UUID | str, identity_id: UUID | str) → GlobusHTTPResponse

Request to join a group.

Parameters:

• group_id (str or UUID) – The ID of the group

• identity_id (str or UUID) – The identity to use to request membership in the group

set_group_policies(group_id: UUID | str, *, is_high_assurance: bool, group_visibility: GroupVisibility | Literal['authenticated', 'private'], group_members_visibility: GroupMemberVisibility | Literal['members', 'managers'], join_requests: bool, signup_fields: Iterable[GroupRequiredSignupFields | Literal['institution', 'current_project_name', 'address', 'city', 'state', 'country', 'address1', 'address2', 'zip', 'phone', 'department', 'field_of_science']], authentication_assurance_timeout: int | None = None) → GlobusHTTPResponse

Set the group policies for the given group.

Parameters:

• group_id (str or UUID) – The ID of the group on which to set policies

• is_high_assurance (bool) – Whether the group can provide a High Assurance guarantee when used for access controls

• group_visibility (str or GroupVisibility) – The visibility of the group

• group_members_visibility (str or GroupMemberVisibility) – The visibility of memberships within the group

• join_requests (bool) – Whether the group allows users to request to join

• signup_fields (iterable of str or GroupRequiredSignupFields) – The required fields for a user to sign up for the group

• authentication_assurance_timeout (int, optional) – The timeout used when this group is used to apply a High Assurance authentication guarantee

Client Errors

When an error occurs, a GroupsClient will raise this type of error:

class globus_sdk.GroupsAPIError(r: Response, *args: Any, **kwargs: Any)

Bases: GlobusAPIError

Error class for the Globus Groups Service.