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:
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:
- Return type:
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.
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:
- Return type:
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:
- Return type:
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:
- Return type:
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:
- Return type:
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:
- Return type:
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:
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:
- Return type:
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:
- Return type:
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:
- Return type:
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:
- Return type:
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.
- add_members(identity_ids, *, role='member')[source]¶
Add a list of identities to a group with the given role.
- approve_pending(identity_ids)[source]¶
Approve a list of identities with pending join requests.
- decline_invites(identity_ids)[source]¶
Decline an invitation for a given set of identities.
- invite_members(identity_ids, *, role='member')[source]¶
Invite a list of identities to a group with the given role.
- join(identity_ids)[source]¶
Join a group with the given identities. The identities must be in the authenticated users identity set.
- leave(identity_ids)[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)[source]¶
Reject identities which have requested to join 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, 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:
- Return type:
- add_member(group_id, identity_id, *, role='member')[source]¶
Add an identity to a group with the given role.
- approve_pending(group_id, identity_id)[source]¶
Approve an identity with a pending join request.
- Parameters:
- Return type:
- 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:
- Return type:
- decline_invite(group_id, identity_id)[source]¶
Decline an invitation for a given identity.
- Parameters:
- Return type:
- invite_member(group_id, identity_id, *, role='member')[source]¶
Invite an identity to a group with the given role.
- join(group_id, identity_id)[source]¶
Join a group with the given identity. The identity must be in the authenticated users identity set.
- Parameters:
- Return type:
- 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:
- Return type:
- reject_join_request(group_id, identity_id)[source]¶
Reject a member that has requested to join the group.
- Parameters:
- Return type:
- 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:
- Return type:
- 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:
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.