tessl/pypi-globus-sdk

Python SDK for interacting with Globus web APIs including Transfer, Auth, and other research data management services

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Groups Service

Name: tessl/pypi-globus-sdk
Author: tessl

Group membership management, access control, and policy configuration for collaborative research with fine-grained permission controls. The Groups service enables creation and management of user groups for organizing access to Globus services and resources with sophisticated membership policies and authentication requirements.

Capabilities

Groups Client

Core client for low-level Groups service operations with comprehensive group management, membership control, and policy administration.

class GroupsClient(BaseClient):
    """
    Client for Globus Groups API operations.
    
    Provides low-level access to groups management including group creation,
    membership management, and policy configuration. For common operations,
    consider using GroupsManager for a simplified interface.
    """
    
    def __init__(
        self,
        *,
        app: GlobusApp | None = None,
        authorizer: GlobusAuthorizer | None = None,
        environment: str | None = None,
        base_url: str | None = None,
        **kwargs
    ) -> None: ...

Group Management Operations

Create, retrieve, update, and delete groups with comprehensive configuration options and metadata management.

def get_my_groups(
    self, 
    *, 
    query_params: dict[str, Any] | None = None
) -> ArrayResponse:
    """
    Get list of groups the authenticated user belongs to.
    
    Returns all groups where the user has any level of membership
    including member, manager, or admin roles.
    
    Parameters:
    - query_params: Additional query parameters
    
    Returns:
    ArrayResponse with list of group memberships
    """

def get_group(
    self,
    group_id: str | UUID,
    *,
    include: str | Iterable[str] | None = None,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Get detailed information about a specific group.
    
    Parameters:
    - group_id: UUID of the group to retrieve
    - include: Additional fields to include (memberships, my_memberships, 
      policies, allowed_actions, child_ids)
    - query_params: Additional query parameters
    
    Returns:
    GlobusHTTPResponse with complete group information
    """

def create_group(
    self,
    data: dict[str, Any],
    *,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Create a new group.
    
    Creates a group with specified name, description, and optional
    parent group for creating hierarchical group structures.
    
    Parameters:
    - data: Group creation data including name, description, parent_id
    - query_params: Additional parameters
    
    Returns:
    GlobusHTTPResponse with created group details
    """

def update_group(
    self,
    group_id: str | UUID,
    data: dict[str, Any],
    *,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Update group metadata and configuration.
    
    Modifies group properties including name, description, and
    other group-level settings.
    
    Parameters:
    - group_id: UUID of group to update
    - data: Updated group configuration
    - query_params: Additional parameters
    
    Returns:
    GlobusHTTPResponse confirming update
    """

def delete_group(
    self,
    group_id: str | UUID,
    *,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Delete a group.
    
    Permanently removes a group and all associated memberships.
    This operation cannot be undone.
    
    Parameters:
    - group_id: UUID of group to delete
    - query_params: Additional parameters
    
    Returns:
    GlobusHTTPResponse confirming deletion
    """

Membership Management

Manage group memberships including adding/removing members, role assignments, and batch operations for efficient membership administration.

def get_group_memberships(
    self,
    group_id: str | UUID,
    *,
    role: str | None = None,
    status: str | None = None,
    query_params: dict[str, Any] | None = None
) -> ArrayResponse:
    """
    Get list of group memberships with optional filtering.
    
    Parameters:
    - group_id: UUID of the group
    - role: Filter by membership role (member, manager, admin)
    - status: Filter by membership status (active, pending, etc.)
    - query_params: Additional parameters
    
    Returns:
    ArrayResponse with membership listings
    """

def add_member(
    self,
    group_id: str | UUID,
    identity_id: str,
    *,
    role: GroupRole | str = GroupRole.member,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Add a member to a group.
    
    Adds a user to the group with specified role. The user must
    have a valid Globus identity.
    
    Parameters:
    - group_id: UUID of the group
    - identity_id: Globus identity ID of user to add
    - role: Role to assign (member, manager, admin)
    - query_params: Additional parameters
    
    Returns:
    GlobusHTTPResponse confirming membership addition
    """

def remove_member(
    self,
    group_id: str | UUID,
    identity_id: str,
    *,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Remove a member from a group.
    
    Removes user's membership and all associated permissions
    within the group.
    
    Parameters:
    - group_id: UUID of the group
    - identity_id: Identity ID of user to remove
    - query_params: Additional parameters
    
    Returns:
    GlobusHTTPResponse confirming removal
    """

def update_member_role(
    self,
    group_id: str | UUID,
    identity_id: str,
    role: GroupRole | str,
    *,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Update a member's role within a group.
    
    Changes user's role and associated permissions within
    the group structure.
    
    Parameters:
    - group_id: UUID of the group
    - identity_id: Identity ID of user
    - role: New role to assign
    - query_params: Additional parameters
    
    Returns:
    GlobusHTTPResponse confirming role update
    """

def batch_membership_action(
    self,
    group_id: str | UUID,
    data: BatchMembershipActions | dict[str, Any],
    *,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Perform multiple membership operations in a single request.
    
    Efficiently add, remove, or update multiple members with
    a single API call for better performance.
    
    Parameters:
    - group_id: UUID of the group
    - data: Batch operations specification
    - query_params: Additional parameters
    
    Returns:
    GlobusHTTPResponse with results of batch operations
    """

Policy Configuration

Configure group policies for visibility, membership requirements, authentication assurance, and access controls.

def set_group_policies(
    self,
    group_id: str | UUID,
    data: GroupPolicies | dict[str, Any],
    *,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Set comprehensive group policies and access controls.
    
    Configures group visibility, membership requirements, join policies,
    and authentication assurance settings.
    
    Parameters:
    - group_id: UUID of the group
    - data: Policy configuration including visibility and requirements
    - query_params: Additional parameters
    
    Returns:
    GlobusHTTPResponse confirming policy updates
    """

def get_group_policies(
    self,
    group_id: str | UUID,
    *,
    query_params: dict[str, Any] | None = None
) -> GlobusHTTPResponse:
    """
    Get current group policies and configuration.
    
    Returns complete policy settings including visibility,
    membership requirements, and authentication settings.
    
    Parameters:
    - group_id: UUID of the group
    - query_params: Additional parameters
    
    Returns:
    GlobusHTTPResponse with policy configuration
    """

High-Level Groups Manager

Simplified interface for common group operations with convenient methods and type-safe parameters.

class GroupsManager:
    """
    High-level interface for common groups operations.
    
    Provides simplified methods for group creation, membership management,
    and policy configuration with convenient parameter handling and
    type hints for common use cases.
    """
    
    def __init__(self, client: GroupsClient | None = None) -> None: ...
    
    def create_group(
        self,
        name: str,
        description: str,
        *,
        parent_id: str | UUID | None = None
    ) -> GlobusHTTPResponse:
        """
        Create a group with simplified parameters.
        
        Parameters:
        - name: Group name
        - description: Group description
        - parent_id: Optional parent group for hierarchical structure
        
        Returns:
        GlobusHTTPResponse with created group details
        """
    
    def set_group_policies(
        self,
        group_id: str | UUID,
        *,
        is_high_assurance: bool,
        group_visibility: GroupVisibility | str,
        group_members_visibility: GroupMemberVisibility | str,
        join_requests: bool,
        signup_fields: Iterable[GroupRequiredSignupFields | str],
        authentication_assurance_timeout: int | None = None
    ) -> GlobusHTTPResponse:
        """
        Set group policies with type-safe parameters.
        
        Parameters:
        - group_id: UUID of the group
        - is_high_assurance: Whether group provides high assurance guarantee
        - group_visibility: Who can see the group (authenticated, private)
        - group_members_visibility: Who can see members (members, managers)
        - join_requests: Whether to allow join requests
        - signup_fields: Required fields for group signup
        - authentication_assurance_timeout: High assurance timeout in seconds
        
        Returns:
        GlobusHTTPResponse confirming policy update
        """
    
    def add_member(
        self,
        group_id: str | UUID,
        identity_id: str,
        *,
        role: GroupRole | str = GroupRole.member
    ) -> GlobusHTTPResponse:
        """Add member with simplified interface."""
    
    def remove_member(
        self, 
        group_id: str | UUID, 
        identity_id: str
    ) -> GlobusHTTPResponse:
        """Remove member with simplified interface."""
    
    def batch_add_members(
        self,
        group_id: str | UUID,
        identity_ids: Iterable[str],
        *,
        role: GroupRole | str = GroupRole.member
    ) -> GlobusHTTPResponse:
        """
        Add multiple members efficiently.
        
        Uses batch operations to add multiple users to a group
        with the same role assignment.
        
        Parameters:
        - group_id: UUID of the group
        - identity_ids: List of identity IDs to add
        - role: Role to assign to all users
        
        Returns:
        GlobusHTTPResponse with batch operation results
        """
    
    def batch_remove_members(
        self,
        group_id: str | UUID,
        identity_ids: Iterable[str]
    ) -> GlobusHTTPResponse:
        """
        Remove multiple members efficiently.
        
        Uses batch operations to remove multiple users from
        a group in a single API call.
        
        Parameters:
        - group_id: UUID of the group
        - identity_ids: List of identity IDs to remove
        
        Returns:
        GlobusHTTPResponse with batch operation results
        """

Data Classes and Enums

Type-safe data structures and enumerations for group configuration and membership management.

class GroupRole(Enum):
    """Enumeration of group membership roles."""
    member = "member"
    manager = "manager" 
    admin = "admin"

class GroupVisibility(Enum):
    """Enumeration of group visibility settings."""
    authenticated = "authenticated"  # Visible to all authenticated users
    private = "private"              # Visible only to members

class GroupMemberVisibility(Enum):
    """Enumeration of member visibility settings."""
    members = "members"     # All members can see membership list
    managers = "managers"   # Only managers/admins can see membership

class GroupRequiredSignupFields(Enum):
    """Enumeration of fields that can be required for group signup."""
    institution = "institution"
    current_project_name = "current_project_name"
    address = "address"
    city = "city"
    state = "state"
    country = "country"
    address1 = "address1"
    address2 = "address2"
    zip = "zip"
    phone = "phone"
    department = "department"

class GroupPolicies(PayloadWrapper):
    """
    Container for group policy configuration.
    
    Defines group behavior including visibility, membership requirements,
    authentication assurance, and join policies.
    """
    
    def __init__(
        self,
        *,
        is_high_assurance: bool | MissingType = MISSING,
        group_visibility: GroupVisibility | str | MissingType = MISSING,
        group_members_visibility: GroupMemberVisibility | str | MissingType = MISSING,
        join_requests: bool | MissingType = MISSING,
        signup_fields: (
            Iterable[GroupRequiredSignupFields | str] | MissingType
        ) = MISSING,
        authentication_assurance_timeout: int | MissingType = MISSING
    ) -> None: ...

class BatchMembershipActions(PayloadWrapper):
    """
    Container for batch membership operations.
    
    Defines multiple membership changes to be applied in a single
    operation for efficient group management.
    """
    
    def __init__(self) -> None: ...
    
    def add_members(
        self, 
        identity_ids: Iterable[str], 
        *, 
        role: GroupRole | str = GroupRole.member
    ) -> BatchMembershipActions:
        """Add multiple members with specified role."""
    
    def remove_members(self, identity_ids: Iterable[str]) -> BatchMembershipActions:
        """Remove multiple members."""
    
    def update_member_roles(
        self, 
        updates: dict[str, GroupRole | str]
    ) -> BatchMembershipActions:
        """Update roles for multiple members."""

Error Handling

Groups-specific error handling for membership and policy management operations.

class GroupsAPIError(GlobusAPIError):
    """
    Error class for Groups service API errors.
    
    Provides enhanced error handling for groups-specific error
    conditions including membership conflicts and policy violations.
    """

Common Usage Patterns

Basic Group Creation and Management

from globus_sdk import GroupsManager, GroupVisibility, GroupMemberVisibility

# Initialize manager (uses default GroupsClient)
groups_manager = GroupsManager()

# Create a research group
group_response = groups_manager.create_group(
    name="Climate Research Team",
    description="Collaborative group for climate data analysis research"
)
group_id = group_response["id"]

# Set group policies
groups_manager.set_group_policies(
    group_id,
    is_high_assurance=False,
    group_visibility=GroupVisibility.authenticated,
    group_members_visibility=GroupMemberVisibility.members,
    join_requests=True,
    signup_fields=["institution", "department"]
)

print(f"Created group: {group_id}")

Membership Management

# Add individual members
groups_manager.add_member(
    group_id,
    "user1@example.org",
    role=GroupRole.member
)

groups_manager.add_member(
    group_id,
    "admin@example.org", 
    role=GroupRole.admin
)

# Batch add multiple researchers
researcher_ids = [
    "researcher1@university.edu",
    "researcher2@university.edu", 
    "researcher3@university.edu"
]

groups_manager.batch_add_members(
    group_id,
    researcher_ids,
    role=GroupRole.member
)

# List group members
client = groups_manager.client
memberships = client.get_group_memberships(group_id)
for membership in memberships:
    print(f"{membership['identity_name']}: {membership['role']}")

Hierarchical Groups

# Create parent group for organization
org_group = groups_manager.create_group(
    name="Research Institute",
    description="Top-level organizational group"
)
org_group_id = org_group["id"]

# Create department subgroups
climate_group = groups_manager.create_group(
    name="Climate Department",
    description="Climate research department",
    parent_id=org_group_id
)

bio_group = groups_manager.create_group(
    name="Biology Department", 
    description="Biology research department",
    parent_id=org_group_id
)

# Members of subgroups inherit parent permissions
groups_manager.add_member(climate_group["id"], "climate_researcher@example.org")

High Assurance Groups

from globus_sdk import GroupRequiredSignupFields

# Create high-assurance group for sensitive data
secure_group = groups_manager.create_group(
    name="Secure Data Access",
    description="High assurance group for sensitive research data"
)

# Configure strict policies
groups_manager.set_group_policies(
    secure_group["id"],
    is_high_assurance=True,
    group_visibility=GroupVisibility.private,
    group_members_visibility=GroupMemberVisibility.managers,
    join_requests=False,  # No self-service joining
    signup_fields=[
        GroupRequiredSignupFields.institution,
        GroupRequiredSignupFields.department,
        GroupRequiredSignupFields.phone,
        GroupRequiredSignupFields.address
    ],
    authentication_assurance_timeout=3600  # 1 hour timeout
)

# Only admins can add members to high-assurance groups
groups_manager.add_member(
    secure_group["id"],
    "trusted_user@example.org",
    role=GroupRole.member
)

Batch Operations for Efficiency

from globus_sdk import BatchMembershipActions

# Large-scale membership changes
batch_actions = BatchMembershipActions()

# Add new cohort of students
new_students = [
    "student1@university.edu",
    "student2@university.edu", 
    # ... more students
]
batch_actions.add_members(new_students, role=GroupRole.member)

# Promote some existing members to managers
promotions = {
    "experienced_user1@university.edu": GroupRole.manager,
    "experienced_user2@university.edu": GroupRole.manager
}
batch_actions.update_member_roles(promotions)

# Remove graduated students
graduated_students = [
    "graduated1@university.edu",
    "graduated2@university.edu"
]
batch_actions.remove_members(graduated_students)

# Execute all changes in single operation
client = GroupsClient(authorizer=authorizer)
result = client.batch_membership_action(group_id, batch_actions)
print(f"Batch operation completed: {len(result['responses'])} changes")

Integration with Access Control

# Groups can be used for access control in other Globus services
from globus_sdk import TransferClient

# Use group for collection access control
transfer_client = TransferClient(authorizer=authorizer)

# The group ID can be used in GCS role assignments
group_urn = f"urn:globus:groups:id:{group_id}"

# Example: Grant group access to a collection (this would be done via GCS)
# gcs_client.create_role({
#     "collection": collection_id,
#     "principal": group_urn,
#     "principal_type": "group", 
#     "role": "reader"
# })

Monitoring and Administration

# Get my groups for user dashboard
my_groups = client.get_my_groups()
for group in my_groups:
    print(f"Group: {group['name']} (Role: {group['my_role']})")

# Get detailed group information including policies
group_details = client.get_group(
    group_id,
    include=["policies", "memberships", "allowed_actions"]
)

print(f"Group policies: {group_details['policies']}")
print(f"Member count: {len(group_details['memberships'])}")
print(f"Allowed actions: {group_details['allowed_actions']}")

# Check if user can perform specific actions
if "update_group" in group_details["allowed_actions"]:
    print("User can update this group")

Install with Tessl CLI