Globus Groups#

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

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: Optional[dict[str, Any]] = None) → ArrayResponse[source]#

Return a list of groups your identity belongs to.

Parameters:: query_params (dict, optional) – Additional passthrough query parameters

External Documentation

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

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

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

External Documentation

See Get Group in the API documentation for details.

delete_group(group_id: Union[UUID, str], *, query_params: Optional[dict[str, Any]] = None) → GlobusHTTPResponse[source]#

Delete a group.

Parameters:

group_id (str or UUID) – the ID of the group
query_params (dict, optional) – additional passthrough query parameters

External Documentation

See Delete a group in the API documentation for details.

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

Create a group.

Parameters:

data (dict) – the group document to create
query_params (dict, optional) – additional passthrough query parameters

External Documentation

See Create a group in the API documentation for details.

update_group(group_id: Union[UUID, str], data: dict[str, Any], *, query_params: Optional[dict[str, Any]] = None) → GlobusHTTPResponse[source]#

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

External Documentation

See Update a group in the API documentation for details.

get_group_policies(group_id: Union[UUID, str], *, query_params: Optional[dict[str, Any]] = None) → GlobusHTTPResponse[source]#

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

External Documentation

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

set_group_policies(group_id: Union[UUID, str], data: dict[str, Any] | globus_sdk.services.groups.data.GroupPolicies, *, query_params: Optional[dict[str, Any]] = None) → GlobusHTTPResponse[source]#

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

External Documentation

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

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

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

External Documentation

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

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

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

Examples

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

External Documentation

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

get_membership_fields(group_id: Union[UUID, str], *, query_params: Optional[dict[str, Any]] = None) → GlobusHTTPResponse[source]#

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

External Documentation

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

set_membership_fields(group_id: Union[UUID, str], data: dict[Any, str], *, query_params: Optional[dict[str, Any]] = None) → GlobusHTTPResponse[source]#

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

External Documentation

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

batch_membership_action(group_id: Union[UUID, str], actions: dict[str, Any] | globus_sdk.services.groups.data.BatchMembershipActions, *, query_params: Optional[dict[str, Any]] = None) → GlobusHTTPResponse[source]#

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

Examples

>>> 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)

External Documentation

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)[source]#

An enumeration.

managers = 'managers'#

members = 'members'#

class globus_sdk.GroupRequiredSignupFields(value)[source]#

An enumeration.

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)[source]#

An enumeration.

admin = 'admin'#

manager = 'manager'#

member = 'member'#

class globus_sdk.GroupVisibility(value)[source]#

An enumeration.

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)[source]#

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

accept_invites(identity_ids: Iterable[Union[UUID, str]]) → BatchMembershipActions[source]#: Accept invites for identities. The identities must belong to the identity set of authenticated user.

add_members(identity_ids: Iterable[Union[UUID, str]], *, role: Union[GroupRole, Literal['member', 'manager', 'admin']] = 'member') → BatchMembershipActions[source]#: Add a list of identities to a group with the given role.

approve_pending(identity_ids: Iterable[Union[UUID, str]]) → BatchMembershipActions[source]#: Approve a list of identities with pending join requests.

decline_invites(identity_ids: Iterable[Union[UUID, str]]) → BatchMembershipActions[source]#: Decline an invitation for a given set of identities.

invite_members(identity_ids: Iterable[Union[UUID, str]], *, role: Union[GroupRole, Literal['member', 'manager', 'admin']] = 'member') → BatchMembershipActions[source]#: Invite a list of identities to a group with the given role.

join(identity_ids: Iterable[Union[UUID, str]]) → BatchMembershipActions[source]#: Join a group with the given identities. The identities must be in the authenticated users identity set.

leave(identity_ids: Iterable[Union[UUID, str]]) → BatchMembershipActions[source]#: Leave a group that one of the identities in the authenticated user’s identity set is a member of.

reject_join_requests(identity_ids: Iterable[Union[UUID, str]]) → BatchMembershipActions[source]#: Reject a members that have requested to join the group.

remove_members(identity_ids: Iterable[Union[UUID, str]]) → BatchMembershipActions[source]#: Remove members from a group. This must be done as an admin or manager of the group.

request_join(identity_ids: Iterable[Union[UUID, str]]) → BatchMembershipActions[source]#: Request to join a 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: Union[GroupVisibility, Literal['authenticated', 'private']], group_members_visibility: Union[GroupMemberVisibility, Literal['members', 'managers']], join_requests: bool, signup_fields: Iterable[Union[GroupRequiredSignupFields, Literal['institution', 'current_project_name', 'address', 'city', 'state', 'country', 'address1', 'address2', 'zip', 'phone', 'department', 'field_of_science']]], authentication_assurance_timeout: Optional[int] = None)[source]#

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

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: Optional[GroupsClient] = None)[source]#

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: Union[UUID, str], identity_id: Union[UUID, str]) → GlobusHTTPResponse[source]#: Accept invite for an identity. The identity must belong to the identity set of the authenticated user.

add_member(group_id: Union[UUID, str], identity_id: Union[UUID, str], *, role: Union[GroupRole, Literal['member', 'manager', 'admin']] = 'member') → GlobusHTTPResponse[source]#: Add a list of identities to a group with the given role.

approve_pending(group_id: Union[UUID, str], identity_id: Union[UUID, str]) → GlobusHTTPResponse[source]#: Approve a list of identities with pending join requests.

create_group(name: str, description: str, *, parent_id: Optional[Union[UUID, str]] = None) → GlobusHTTPResponse[source]#: Create a group with the given name. If a parent id is included, the group will be a subgroup of the given parent group.

decline_invite(group_id: Union[UUID, str], identity_id: Union[UUID, str]) → GlobusHTTPResponse[source]#: Decline an invitation for a given identity.

invite_member(group_id: Union[UUID, str], identity_id: Union[UUID, str], *, role: Union[GroupRole, Literal['member', 'manager', 'admin']] = 'member') → GlobusHTTPResponse[source]#: Invite an identity to a group with the given role.

join(group_id: Union[UUID, str], identity_id: Union[UUID, str]) → GlobusHTTPResponse[source]#: Join a group with the given identity. The identity must be in the authenticated users identity set.

leave(group_id: Union[UUID, str], identity_id: Union[UUID, str]) → GlobusHTTPResponse[source]#: Leave a group that one of the identities in the authenticated user’s identity set is a member of.

reject_join_request(group_id: Union[UUID, str], identity_id: Union[UUID, str]) → GlobusHTTPResponse[source]#: Reject a member that has requested to join the group.

remove_member(group_id: Union[UUID, str], identity_id: Union[UUID, str]) → GlobusHTTPResponse[source]#: Remove members from a group. This must be done as an admin or manager of the group.

request_join(group_id: Union[UUID, str], identity_id: Union[UUID, str]) → GlobusHTTPResponse[source]#: Request to join a group.

set_group_policies(group_id: Union[UUID, str], *, is_high_assurance: bool, group_visibility: Union[GroupVisibility, Literal['authenticated', 'private']], group_members_visibility: Union[GroupMemberVisibility, Literal['members', 'managers']], join_requests: bool, signup_fields: Iterable[Union[GroupRequiredSignupFields, Literal['institution', 'current_project_name', 'address', 'city', 'state', 'country', 'address1', 'address2', 'zip', 'phone', 'department', 'field_of_science']]], authentication_assurance_timeout: Optional[int] = None) → GlobusHTTPResponse[source]#: Set the group policies for the given group.

Client Errors#

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

class globus_sdk.GroupsAPIError(r: Response, *args: Any, **kwargs: Any)[source]#

Bases: GlobusAPIError

Error class for the Globus Groups Service.