Globus Groups

class globus_sdk.GroupsClient(*, environment=None, base_url=None, app=None, app_scopes=None, authorizer=None, app_name=None, transport_params=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

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

the scopes for this client may be present as a ScopeBuilder

property default_scope_requirements: list[Scope]

Scopes that will automatically be added to this client’s app’s scope_requirements during _finalize_app.

For clients with static scope requirements this can just be a static value. Clients with dynamic requirements should use @property and must return sane results while the Base Client is being initialized.

get_my_groups(*, query_params=None)[source]

Return a list of groups your identity belongs to.

Parameters:

query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

ArrayResponse

GET /v2/groups/my_groups

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

get_group(group_id, *, include=None, query_params=None)[source]

Get details about a specific group

Parameters:
  • group_id (UUID | str) – the ID of the group

  • include (None | str | Iterable[str]) – list of additional fields to include (allowed fields are memberships, my_memberships, policies, allowed_actions, and child_ids)

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /v2/groups/<group_id>

See Get Group in the API documentation for details.

get_group_by_subscription_id(subscription_id)[source]

Using a subscription ID, find the group which provides that subscription.

Parameters:

subscription_id (UUID | str) – the subscription ID of the group

Return type:

GlobusHTTPResponse

from globus_sdk import GroupsClient

groups = GroupsClient(...)
group_id = groups.get_group_by_subscription_id(subscription_id)["group_id"]
{
  "group_id": "f85c84a0-985b-11ef-a15a-0242ac110002",
  "subscription_id": "f85c8428-985b-11ef-a15a-0242ac110002",
  "subscription_info": {
    "is_high_assurance": true,
    "is_baa": false,
    "connectors": {
      "052be037-7dda-4d20-b163-3077314dc3e6": {
        "is_ha": true,
        "is_baa": false
      },
      "1b6374b0-f6a4-4cf7-a26f-f262d9c6ca72": {
        "is_ha": true,
        "is_baa": false
      },
      "28ef55da-1f97-11eb-bdfd-12704e0d6a4d": {
        "is_ha": true,
        "is_baa": false
      },
      "49b00fd6-63f1-48ae-b27f-d8af4589f876": {
        "is_ha": true,
        "is_baa": false
      },
      "56366b96-ac98-11e9-abac-9cb6d0d9fd63": {
        "is_ha": true,
        "is_baa": false
      },
      "7251f6c8-93c9-11eb-95ba-12704e0d6a4d": {
        "is_ha": true,
        "is_baa": false
      },
      "7643e831-5f6c-4b47-a07f-8ee90f401d23": {
        "is_ha": true,
        "is_baa": false
      },
      "7c100eae-40fe-11e9-95a3-9cb6d0d9fd63": {
        "is_ha": true,
        "is_baa": false
      },
      "7e3f3f5e-350c-4717-891a-2f451c24b0d4": {
        "is_ha": true,
        "is_baa": false
      },
      "9436da0c-a444-11eb-af93-12704e0d6a4d": {
        "is_ha": true,
        "is_baa": false
      },
      "976cf0cf-78c3-4aab-82d2-7c16adbcc281": {
        "is_ha": true,
        "is_baa": false
      },
      "e47b6920-ff57-11ea-8aaa-000c297ab3c2": {
        "is_ha": true,
        "is_baa": false
      },
      "fb656a17-0f69-4e59-95ff-d0a62ca7bdf5": {
        "is_ha": true,
        "is_baa": false
      }
    }
  }
}

GET /v2/subscription_info/<subscription_id>

See Get Group by Subscription ID in the API documentation for details.

delete_group(group_id, *, query_params=None)[source]

Delete a group.

Parameters:
  • group_id (UUID | str) – the ID of the group

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

DELETE /v2/groups/<group_id>

See Delete a Group in the API documentation for details.

create_group(data, *, query_params=None)[source]

Create a group.

Parameters:
  • data (dict[str, Any]) – the group document to create

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

POST /v2/groups

See Create a Group in the API documentation for details.

update_group(group_id, data, *, query_params=None)[source]

Update a given group.

Parameters:
  • group_id (UUID | str) – the ID of the group

  • data (dict[str, Any]) – the group document to use for update

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

PUT /v2/groups/<group_id>

See Update a Group in the API documentation for details.

get_group_policies(group_id, *, query_params=None)[source]

Get policies for the given group

Parameters:
  • group_id (UUID | str) – the ID of the group

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /v2/groups/<group_id>/policies

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

set_group_policies(group_id, data, *, query_params=None)[source]

Set policies for the group.

Parameters:
  • group_id (UUID | str) – the ID of the group

  • data (dict[str, Any] | GroupPolicies) – the group policy document to set

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

PUT /v2/groups/<group_id>/policies

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

get_identity_preferences(*, query_params=None)[source]

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

Parameters:

query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

GET /v2/preferences

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

set_identity_preferences(data, *, query_params=None)[source]

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

Parameters:
  • data (dict[str, Any]) – the identity set preferences document

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

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

PUT /v2/preferences

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

get_membership_fields(group_id, *, query_params=None)[source]

Get membership fields for your identities.

Parameters:
  • group_id (UUID | str) – the ID of the group

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

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, data, *, query_params=None)[source]

Set membership fields for your identities.

Parameters:
  • group_id (UUID | str) – the ID of the group

  • data (dict[Any, str]) – the membership fields document

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

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, actions, *, query_params=None)[source]

Execute a batch of actions against several group memberships.

Parameters:
  • group_id (UUID | str) – the ID of the group

  • actions (dict[str, Any] | BatchMembershipActions) – the batch of membership actions to perform, modifying, creating, and removing memberships in the group

  • query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

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)

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)[source]
managers = 'managers'
members = 'members'
class globus_sdk.GroupRequiredSignupFields(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
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)[source]
admin = 'admin'
manager = 'manager'
member = 'member'
class globus_sdk.GroupVisibility(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
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)[source]

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

Parameters:

identity_ids (Iterable[UUID | str]) – The identities for whom to accept invites

Return type:

BatchMembershipActions

add_members(identity_ids, *, role='member')[source]

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

Parameters:
  • identity_ids (Iterable[UUID | str]) – The identities to add to the group

  • role (GroupRole | Literal['member', 'manager', 'admin']) – The role for the new group members

Return type:

BatchMembershipActions

approve_pending(identity_ids)[source]

Approve a list of identities with pending join requests.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to approve as members of the group

Return type:

BatchMembershipActions

decline_invites(identity_ids)[source]

Decline an invitation for a given set of identities.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities for whom invitations should be declined

Return type:

BatchMembershipActions

invite_members(identity_ids, *, role='member')[source]

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

Parameters:
  • identity_ids (Iterable[UUID | str]) – The identities to invite to the group

  • role (GroupRole | Literal['member', 'manager', 'admin']) – The role for the invited group members

Return type:

BatchMembershipActions

join(identity_ids)[source]

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

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to use to join the group

Return type:

BatchMembershipActions

leave(identity_ids)[source]

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

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to remove from the group

Return type:

BatchMembershipActions

reject_join_requests(identity_ids)[source]

Reject identities which have requested to join the group.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to reject from the group

Return type:

BatchMembershipActions

remove_members(identity_ids)[source]

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

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to remove from the group

Return type:

BatchMembershipActions

request_join(identity_ids)[source]

Request to join a group.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to use to request membership in the group

Return type:

BatchMembershipActions

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, group_visibility, group_members_visibility, join_requests, signup_fields, authentication_assurance_timeout=MISSING)[source]

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.

Parameters:
  • is_high_assurance (bool) – Whether the group is high assurance or not

  • group_visibility (GroupVisibility | Literal['authenticated', 'private']) – The visibility of the group

  • group_members_visibility (GroupMemberVisibility | Literal['members', 'managers']) – The visibility of the group members

  • join_requests (bool) – Whether the group allows join requests or not

  • signup_fields (Iterable[GroupRequiredSignupFields | Literal['institution', 'current_project_name', 'address', 'city', 'state', 'country', 'address1', 'address2', 'zip', 'phone', 'department', 'field_of_science']]) – The fields required for signup in the group

  • authentication_assurance_timeout (int | None | utils.MissingType) – The session timeout for high assurance group policy enforcement

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=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(group_id, identity_id)[source]

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

Parameters:
  • group_id (UUID | str) – The ID of the group

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

Return type:

GlobusHTTPResponse

add_member(group_id, identity_id, *, role='member')[source]

Add an identity to a group with the given role.

Parameters:
  • group_id (UUID | str) – The ID of the group

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

  • role (GroupRole | Literal['member', 'manager', 'admin']) – The role for the new group member

Return type:

GlobusHTTPResponse

approve_pending(group_id, identity_id)[source]

Approve an identity with a pending join request.

Parameters:
  • group_id (UUID | str) – The ID of the group

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

Return type:

GlobusHTTPResponse

create_group(name, description, *, parent_id=None)[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.

Parameters:
  • name (str) – The name of the group

  • description (str) – A description of the group

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

Return type:

GlobusHTTPResponse

decline_invite(group_id, identity_id)[source]

Decline an invitation for a given identity.

Parameters:
  • group_id (UUID | str) – The ID of the group

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

Return type:

GlobusHTTPResponse

invite_member(group_id, identity_id, *, role='member')[source]

Invite an identity to a group with the given role.

Parameters:
  • group_id (UUID | str) – The ID of the group

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

  • role (GroupRole | Literal['member', 'manager', 'admin']) – The role for the invited group member

Return type:

GlobusHTTPResponse

join(group_id, identity_id)[source]

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

Parameters:
  • group_id (UUID | str) – The ID of the group

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

Return type:

GlobusHTTPResponse

leave(group_id, identity_id)[source]

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

Parameters:
  • group_id (UUID | str) – The ID of the group

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

Return type:

GlobusHTTPResponse

reject_join_request(group_id, identity_id)[source]

Reject a member that has requested to join the group.

Parameters:
  • group_id (UUID | str) – The ID of the group

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

Return type:

GlobusHTTPResponse

remove_member(group_id, identity_id)[source]

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

Parameters:
  • group_id (UUID | str) – The ID of the group

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

Return type:

GlobusHTTPResponse

request_join(group_id, identity_id)[source]

Request to join a group.

Parameters:
  • group_id (UUID | str) – The ID of the group

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

Return type:

GlobusHTTPResponse

set_group_policies(group_id, *, is_high_assurance, group_visibility, group_members_visibility, join_requests, signup_fields, authentication_assurance_timeout=None)[source]

Set the group policies for the given group.

Parameters:
  • group_id (UUID | str) – 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 (GroupVisibility | Literal['authenticated', 'private']) – The visibility of the group

  • group_members_visibility (GroupMemberVisibility | Literal['members', 'managers']) – The visibility of memberships within the group

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

  • signup_fields (Iterable[GroupRequiredSignupFields | Literal['institution', 'current_project_name', 'address', 'city', 'state', 'country', 'address1', 'address2', 'zip', 'phone', 'department', 'field_of_science']]) – The required fields for a user to sign up for the group

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

Return type:

GlobusHTTPResponse

Client Errors

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

class globus_sdk.GroupsAPIError(r, *args, **kwargs)[source]

Bases: GlobusAPIError

Error class for the Globus Groups Service.