Globus Groups¶

class globus_sdk.GroupsClient(*, environment: Optional[str] = None, base_url: Optional[str] = None, authorizer: Optional[globus_sdk.authorizers.base.GlobusAuthorizer] = None, app_name: Optional[str] = None, transport_params: Optional[Dict[str, Any]] = None)[source]¶

Bases: globus_sdk.client.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()

get_my_groups(*, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.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.UUID, str], *, include: Optional[Union[Iterable[str], str]] = None, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.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.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.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) → globus_sdk.response.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.UUID, str], data: Dict[str, Any], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.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.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.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.UUID, str], data: Union[Dict[str, Any], globus_sdk.services.groups.data.GroupPolicies], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.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) → globus_sdk.response.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) → globus_sdk.response.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.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.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.UUID, str], data: Dict[Any, str], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.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.UUID, str], actions: Union[Dict[str, Any], globus_sdk.services.groups.data.BatchMembershipActions], *, query_params: Optional[Dict[str, Any]] = None) → globus_sdk.response.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.UUID, str]]) → globus_sdk.services.groups.data.BatchMembershipActions[source]¶: Accept invites for identities. The identities must belong to the identity set of authenticated user.

add_members(identity_ids: Iterable[Union[uuid.UUID, str]], *, role: globus_sdk.services.groups.data.GroupRole = GroupRole.member) → globus_sdk.services.groups.data.BatchMembershipActions[source]¶: Add a list of identities to a group with the given role.

approve_pending(identity_ids: Iterable[Union[uuid.UUID, str]]) → globus_sdk.services.groups.data.BatchMembershipActions[source]¶: Approve a list of identities with pending join requests.

decline_invites(identity_ids: Iterable[Union[uuid.UUID, str]]) → globus_sdk.services.groups.data.BatchMembershipActions[source]¶: Decline an invitation for a given set of identities.

invite_members(identity_ids: Iterable[Union[uuid.UUID, str]], *, role: globus_sdk.services.groups.data.GroupRole = GroupRole.member) → globus_sdk.services.groups.data.BatchMembershipActions[source]¶: Invite a list of identities to a group with the given role.

join(identity_ids: Iterable[Union[uuid.UUID, str]]) → globus_sdk.services.groups.data.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.UUID, str]]) → globus_sdk.services.groups.data.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.UUID, str]]) → globus_sdk.services.groups.data.BatchMembershipActions[source]¶: Reject a members that have requested to join the group.

remove_members(identity_ids: Iterable[Union[uuid.UUID, str]]) → globus_sdk.services.groups.data.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.UUID, str]]) → globus_sdk.services.groups.data.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: globus_sdk.services.groups.data.GroupVisibility, group_members_visibility: globus_sdk.services.groups.data.GroupMemberVisibility, join_requests: bool, signup_fields: Iterable[globus_sdk.services.groups.data.GroupRequiredSignupFields], 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[globus_sdk.services.groups.client.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.UUID, str], identity_id: Union[uuid.UUID, str]) → globus_sdk.response.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.UUID, str], identity_id: Union[uuid.UUID, str], *, role: globus_sdk.services.groups.data.GroupRole = GroupRole.member) → globus_sdk.response.GlobusHTTPResponse[source]¶: Add a list of identities to a group with the given role.

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

create_group(name: str, description: str, *, parent_id: Optional[Union[uuid.UUID, str]] = None) → globus_sdk.response.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.UUID, str], identity_id: Union[uuid.UUID, str]) → globus_sdk.response.GlobusHTTPResponse[source]¶: Decline an invitation for a given identity.

invite_member(group_id: Union[uuid.UUID, str], identity_id: Union[uuid.UUID, str], *, role: globus_sdk.services.groups.data.GroupRole = GroupRole.member) → globus_sdk.response.GlobusHTTPResponse[source]¶: Invite an identity to a group with the given role.

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

leave(group_id: Union[uuid.UUID, str], identity_id: Union[uuid.UUID, str]) → globus_sdk.response.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.UUID, str], identity_id: Union[uuid.UUID, str]) → globus_sdk.response.GlobusHTTPResponse[source]¶: Reject a member that has requested to join the group.

remove_member(group_id: Union[uuid.UUID, str], identity_id: Union[uuid.UUID, str]) → globus_sdk.response.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.UUID, str], identity_id: Union[uuid.UUID, str]) → globus_sdk.response.GlobusHTTPResponse[source]¶: Request to join a group.

set_group_policies(group_id: Union[uuid.UUID, str], *, is_high_assurance: bool, group_visibility: globus_sdk.services.groups.data.GroupVisibility, group_members_visibility: globus_sdk.services.groups.data.GroupMemberVisibility, join_requests: bool, signup_fields: Iterable[globus_sdk.services.groups.data.GroupRequiredSignupFields], authentication_assurance_timeout: Optional[int] = None) → globus_sdk.response.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: requests.models.Response, *args: Any, **kwargs: Any)[source]¶

Bases: globus_sdk.exc.api.GlobusAPIError

Error class for the Globus Groups Service.