Team

Example Script

Working with teams

API Reference

synapseclient.models.Team dataclass

Bases: TeamSynchronousProtocol

Represents a Synapse Team. User definable fields are:

ATTRIBUTE	DESCRIPTION
id	The ID of the team TYPE: Optional[int]
name	The name of the team TYPE: Optional[str]
description	A short description of the team TYPE: Optional[str]
icon	A file handle ID for the icon image of the team TYPE: Optional[str]
can_public_join	True if members can join without an invitation or approval TYPE: Optional[bool]
can_request_membership	True if users can create a membership request to join TYPE: Optional[bool]
etag	Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date. TYPE: Optional[str]
created_on	The date this team was created TYPE: Optional[str]
modified_on	The date this team was last modified TYPE: Optional[str]
created_by	The ID of the user that created this team TYPE: Optional[str]
modified_by	The ID of the user that last modified this team TYPE: Optional[str]

Create a new team

  Create a new team on Synapse by storing a Team object with a name.

from synapseclient.models import Team
from synapseclient import Synapse

syn = Synapse()
syn.login()

team = Team(
    name="My Uniquely Named Team",
    description="A team for my project collaborators",
)
created_team = team.create()

Get a team by ID or name

  Retrieve an existing team using either its ID or its name.

from synapseclient.models import Team
from synapseclient import Synapse

syn = Synapse()
syn.login()

team_by_id = Team.from_id(id=123456)
team_by_name = Team.from_name(name="My Uniquely Named Team")

List the members of a team and invite a new one

  List current team members and send an invitation to a new user.

from synapseclient.models import Team
from synapseclient import Synapse

syn = Synapse()
syn.login()

team = Team.from_id(id=123456)
for member in team.members():
    print(member.member.user_name)

team.invite(user="my_username", message="Please join my team!")

Delete a team

  Delete a team you no longer need.

from synapseclient.models import Team
from synapseclient import Synapse

syn = Synapse()
syn.login()

team = Team.from_id(id=123456)
team.delete()

Source code in synapseclient/models/team.py

@dataclass
@async_to_sync
class Team(TeamSynchronousProtocol):
    """
    Represents a [Synapse Team](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/Team.html).
    User definable fields are:

    Attributes:
        id: The ID of the team
        name: The name of the team
        description: A short description of the team
        icon: A file handle ID for the icon image of the team
        can_public_join: True if members can join without an invitation or approval
        can_request_membership: True if users can create a membership request to join
        etag: Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle
            concurrent updates Since the E-Tag changes every time an entity is updated
            it is used to detect when a client's current representation of an entity
            is out-of-date.
        created_on: The date this team was created
        modified_on: The date this team was last modified
        created_by: The ID of the user that created this team
        modified_by: The ID of the user that last modified this team

    Example: Create a new team
         
        Create a new team on Synapse by storing a Team object with a name.
        ```python
        from synapseclient.models import Team
        from synapseclient import Synapse

        syn = Synapse()
        syn.login()

        team = Team(
            name="My Uniquely Named Team",
            description="A team for my project collaborators",
        )
        created_team = team.create()
        ```

    Example: Get a team by ID or name
         
        Retrieve an existing team using either its ID or its name.
        ```python
        from synapseclient.models import Team
        from synapseclient import Synapse

        syn = Synapse()
        syn.login()

        team_by_id = Team.from_id(id=123456)
        team_by_name = Team.from_name(name="My Uniquely Named Team")
        ```

    Example: List the members of a team and invite a new one
         
        List current team members and send an invitation to a new user.
        ```python
        from synapseclient.models import Team
        from synapseclient import Synapse

        syn = Synapse()
        syn.login()

        team = Team.from_id(id=123456)
        for member in team.members():
            print(member.member.user_name)

        team.invite(user="my_username", message="Please join my team!")
        ```

    Example: Delete a team
         
        Delete a team you no longer need.
        ```python
        from synapseclient.models import Team
        from synapseclient import Synapse

        syn = Synapse()
        syn.login()

        team = Team.from_id(id=123456)
        team.delete()
        ```
    """

    id: Optional[int] = None
    """The ID of the team"""

    name: Optional[str] = None
    """The name of the team"""

    description: Optional[str] = None
    """A short description of the team"""

    icon: Optional[str] = None
    """A file handle ID for the icon image of the team"""

    can_public_join: Optional[bool] = False
    """True if members can join without an invitation or approval"""

    can_request_membership: Optional[bool] = True
    """True if users can create a membership request to join"""

    etag: Optional[str] = None
    """
    Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle
    concurrent updates Since the E-Tag changes every time an entity is updated it is
    used to detect when a client's current representation of an entity is out-of-date.
    """

    created_on: Optional[str] = None
    """The date this team was created"""

    modified_on: Optional[str] = None
    """The date this team was last modified"""

    created_by: Optional[str] = None
    """The ID of the user that created this team"""

    modified_by: Optional[str] = None
    """The ID of the user that last modified this team"""

    def fill_from_dict(self, synapse_team: dict[str, str]) -> "Team":
        """
        Converts a response from the REST API into this dataclass.

        Arguments:
            synapse_team: The response from the REST API.

        Returns:
            The Team object.
        """
        self.id = (
            int(synapse_team.get("id", None)) if synapse_team.get("id", None) else None
        )
        self.name = synapse_team.get("name", None)
        self.description = synapse_team.get("description", None)
        self.icon = synapse_team.get("icon", None)
        self.can_public_join = synapse_team.get("canPublicJoin", False)
        self.can_request_membership = synapse_team.get("canRequestMembership", True)
        self.etag = synapse_team.get("etag", None)
        self.created_on = synapse_team.get("createdOn", None)
        self.modified_on = synapse_team.get("modifiedOn", None)
        self.created_by = synapse_team.get("createdBy", None)
        self.modified_by = synapse_team.get("modifiedBy", None)
        return self

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Team_Create: {self.name}"
    )
    async def create_async(self, *, synapse_client: Optional[Synapse] = None) -> "Team":
        """Creates a new team on Synapse.

        Arguments:
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            Team: The Team object.

        Example: Create a new team
             
            Create a new team on Synapse by storing a Team object with a name.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def create_team():
                team = await Team(
                    name="My Uniquely Named Team",
                    description="A team for my project collaborators",
                    can_public_join=False,
                ).create_async()
                return team

            new_team = asyncio.run(create_team())
            ```
        """
        trace.get_current_span().set_attributes(
            {
                "synapse.name": self.name or "",
                "synapse.id": self.id or "",
            }
        )
        team = await create_team(
            name=self.name,
            description=self.description,
            icon=self.icon,
            can_public_join=self.can_public_join,
            can_request_membership=self.can_request_membership,
            synapse_client=synapse_client,
        )
        self.fill_from_dict(synapse_team=team)
        return self

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Team_Delete: {self.id}"
    )
    async def delete_async(self, *, synapse_client: Optional[Synapse] = None) -> None:
        """Deletes a team from Synapse.

        Arguments:
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            None

        Example: Delete a team by ID
             
            Delete a team using its ID.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def delete_team():
                await Team(id=123456).delete_async()

            asyncio.run(delete_team())
            ```

        Example: Get and then delete a team
             
            If you do not have the ID of the team, you can first retrieve it from
            Synapse by name. That will populate the ID attribute in your Team object,
            at which point you can delete it.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def get_and_delete_team():
                team = await Team.from_name_async(name="My Uniquely Named Team")
                await team.delete_async()

            asyncio.run(get_and_delete_team())
            ```
        """
        await delete_team(id=self.id, synapse_client=synapse_client)

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Team_Get: {self.id if self.id else self.name}"
    )
    async def get_async(self, *, synapse_client: Optional[Synapse] = None) -> "Team":
        """
        Gets a Team from Synapse by ID or Name. If both are added to the Team instance
        it will use the ID.

        Arguments:
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Raises:
            ValueError: If the Team object has neither an id nor a name.

        Returns:
            Team: The Team object.

        Example: Get a team by ID
             
            Retrieve an existing team using its ID.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def get_team():
                team = await Team(id=123456).get_async()
                return team

            my_team = asyncio.run(get_team())
            ```

        Example: Get a team by name
             
            Retrieve an existing team using its name.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def get_team():
                team = await Team(name="My Uniquely Named Team").get_async()
                return team

            my_team = asyncio.run(get_team())
            ```
        """
        if self.id:
            api_team = await get_team(id=self.id, synapse_client=synapse_client)
            return self.fill_from_dict(api_team)
        elif self.name:
            api_team = await get_team(id=self.name, synapse_client=synapse_client)
            return self.fill_from_dict(api_team)
        raise ValueError("Team must have either an id or a name")

    @classmethod
    @otel_trace_method(
        method_to_trace_name=lambda cls, id, **kwargs: f"Team_From_Id: {id}"
    )
    async def from_id_async(
        cls, id: int, *, synapse_client: Optional[Synapse] = None
    ) -> "Team":
        """Gets Team object using its integer id.

        Arguments:
            id: The id of the team.
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            Team: The Team object.

        Example: Get a team by its ID
             
            Retrieve an existing team using its ID.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def get_team_by_id():
                team = await Team.from_id_async(id=123456)
                return team

            my_team = asyncio.run(get_team_by_id())
            ```
        """

        return await cls(id=id).get_async(synapse_client=synapse_client)

    @classmethod
    @otel_trace_method(
        method_to_trace_name=lambda cls, name, **kwargs: f"Team_From_Name: {name}"
    )
    async def from_name_async(
        cls, name: str, *, synapse_client: Optional[Synapse] = None
    ) -> "Team":
        """Gets Team object using its string name.

        *** You will be unable to retrieve a team by name immediately after its
        creation because the fragment service is eventually consistent. If you need to
        retrieve a team immediately following creation you should use the
        [from_id][synapseclient.models.Team.from_id] method. ***

        Arguments:
            name: The name of the team.
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            Team: The Team object.

        Example: Get a team by its name
             
            Retrieve an existing team using its name.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def get_team_by_name():
                team = await Team.from_name_async(name="My Uniquely Named Team")
                return team

            my_team = asyncio.run(get_team_by_name())
            ```
        """
        return await cls(name=name).get_async(synapse_client=synapse_client)

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Team_Members: {self.name}"
    )
    async def members_async(
        self, *, synapse_client: Optional[Synapse] = None
    ) -> List[TeamMember]:
        """
        Gets the TeamMembers associated with a team given the ID field on the
        Team instance.

        Arguments:
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            List[TeamMember]: A List of TeamMember objects.

        Example: List the members of a team
             
            List the current members of a team.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def list_team_members():
                team = await Team.from_id_async(id=123456)
                members = await team.members_async()
                for member in members:
                    print(f"{member.member.user_name} (admin: {member.is_admin})")
                return members

            team_members = asyncio.run(list_team_members())
            ```
        """
        team_members = await get_team_members(
            team=self.id, synapse_client=synapse_client
        )
        team_member_list = [
            TeamMember().fill_from_dict(synapse_team_member=member)
            for member in team_members
        ]
        return team_member_list

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Team_Invite: {self.name}"
    )
    async def invite_async(
        self,
        user: Union[str, int],
        message: str,
        force: bool = True,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> Union[Dict[str, str], None]:
        """Invites a user to a team given the ID field on the Team instance.

        Arguments:
            user: The username or ID of the user to invite.
            message: The message to send.
            force: If True, will send the invite even if the user is already a member
                or has an open invitation. If False, will not send the invite if the user
                is already a member or has an open invitation.
                Defaults to True.
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            The invite response or None if an invite was not sent.

        Example: Invite a user to a team
             
            Send an invitation for a user to join a team.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def invite_user():
                team = await Team.from_id_async(id=123456)
                invite = await team.invite_async(
                    user="my_username",
                    message="Please join my team!",
                )
                return invite

            asyncio.run(invite_user())
            ```
        """
        invite = await invite_to_team(
            team=self.id,
            user=user,
            message=message,
            force=force,
            synapse_client=synapse_client,
        )

        if invite:
            from synapseclient import Synapse

            client = Synapse.get_client(synapse_client=synapse_client)
            client.logger.info(
                f"Invited user {invite['inviteeId']} to team {invite['teamId']}"
            )

        return invite

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Team_Open_Invitations: {self.name}"
    )
    async def open_invitations_async(
        self, *, synapse_client: Optional[Synapse] = None
    ) -> List[Dict[str, str]]:
        """Gets all open invitations for a team given the ID field on the Team instance.

        Arguments:
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            List[dict]: A list of invitations.

        Example: List the open invitations for a team
             
            List all pending invitations for a team.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def list_open_invitations():
                team = await Team.from_id_async(id=123456)
                invitations = await team.open_invitations_async()
                return invitations

            open_invitations = asyncio.run(list_open_invitations())
            ```
        """
        invitations = await get_team_open_invitations(
            team=self.id, synapse_client=synapse_client
        )
        return list(invitations)

    @staticmethod
    async def delete_invitation_async(
        invitation_id: str, *, synapse_client: Optional[Synapse] = None
    ) -> None:
        """Deletes an open invitation to a team. Note: The client must be an
        administrator of the Team referenced by the invitation, or the invitee,
        to make this request.

        Arguments:
            invitation_id: The ID of the invitation to delete. This can be found
                on the invitations returned by
                [open_invitations][synapseclient.models.Team.open_invitations].
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            None

        Example: Delete an open invitation to a team
             
            Cancel a pending invitation to a team.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def delete_open_invitation():
                team = await Team.from_id_async(id=123456)
                open_invitations = await team.open_invitations_async()
                if not open_invitations:
                    print("No open invitations to delete.")
                    return

                # Delete the first open invitation
                await Team.delete_invitation_async(
                    invitation_id=open_invitations[0]["id"]
                )

            asyncio.run(delete_open_invitation())
            ```
        """
        await delete_membership_invitation(
            invitation_id=invitation_id, synapse_client=synapse_client
        )

    async def get_user_membership_status_async(
        self,
        user_id: str,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> TeamMembershipStatus:
        """Retrieve a user's Team Membership Status bundle for this team.

        Arguments:
            user_id: Synapse user ID
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            TeamMembershipStatus object

        Example: Check if a user is a member of a team
             
            This example shows how to check a user's membership status in a team.
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Team

            syn = Synapse()
            syn.login()

            async def check_membership():
                # Get a team by ID
                team = await Team.from_id_async(id=123456)

                # Check membership status for a specific user
                user_id = "3350396"  # Replace with actual user ID
                status = await team.get_user_membership_status_async(user_id)

                print(f"User ID: {status.user_id}")
                print(f"Is member: {status.is_member}")
                print(f"Can join: {status.can_join}")
                print(f"Has open invitation: {status.has_open_invitation}")
                print(f"Has open request: {status.has_open_request}")
                print(f"Membership approval required: {status.membership_approval_required}")

            asyncio.run(check_membership())
            ```
        """
        from synapseclient import Synapse

        client = Synapse.get_client(synapse_client=synapse_client)
        status = await get_membership_status(
            user_id=user_id, team=self.id, synapse_client=client
        )
        return TeamMembershipStatus().fill_from_dict(status)

Methods:

create

create(*, synapse_client: Optional[Synapse] = None) -> Team

Creates a new team on Synapse.

PARAMETER	DESCRIPTION
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
Team	The Team object. TYPE: Team

Create a new team

  Create a new team on Synapse by storing a Team object with a name.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team(
    name="My Uniquely Named Team",
    description="A team for my project collaborators",
    can_public_join=False,
).create()

Source code in synapseclient/models/protocols/team_protocol.py

def create(self, *, synapse_client: Optional[Synapse] = None) -> "Team":
    """Creates a new team on Synapse.

    Arguments:
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        Team: The Team object.

    Example: Create a new team
         
        Create a new team on Synapse by storing a Team object with a name.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team(
            name="My Uniquely Named Team",
            description="A team for my project collaborators",
            can_public_join=False,
        ).create()
        ```
    """
    return self

delete

delete(*, synapse_client: Optional[Synapse] = None) -> None

Deletes a team from Synapse.

PARAMETER	DESCRIPTION
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
None	None

Delete a team by ID

  Delete a team using its ID.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

Team(id=123456).delete()

Get and then delete a team

  If you do not have the ID of the team, you can first retrieve it from Synapse by name. That will populate the ID attribute in your Team object, at which point you can delete it.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team.from_name(name="My Uniquely Named Team")
team.delete()

Source code in synapseclient/models/protocols/team_protocol.py

def delete(self, *, synapse_client: Optional[Synapse] = None) -> None:
    """Deletes a team from Synapse.

    Arguments:
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        None

    Example: Delete a team by ID
         
        Delete a team using its ID.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        Team(id=123456).delete()
        ```

    Example: Get and then delete a team
         
        If you do not have the ID of the team, you can first retrieve it from
        Synapse by name. That will populate the ID attribute in your Team object,
        at which point you can delete it.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team.from_name(name="My Uniquely Named Team")
        team.delete()
        ```
    """
    return None

get

get(*, synapse_client: Optional[Synapse] = None) -> Team

Gets a Team from Synapse by ID or Name. If both are added to the Team instance it will use the ID.

PARAMETER	DESCRIPTION
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RAISES	DESCRIPTION
ValueError	If the Team object has neither an id nor a name.

RETURNS	DESCRIPTION
Team	The Team object. TYPE: Team

Get a team by ID

  Retrieve an existing team using its ID.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team(id=123456).get()

Get a team by name

  Retrieve an existing team using its name.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team(name="My Uniquely Named Team").get()

Source code in synapseclient/models/protocols/team_protocol.py

def get(self, *, synapse_client: Optional[Synapse] = None) -> "Team":
    """
    Gets a Team from Synapse by ID or Name. If both are added to the Team instance
    it will use the ID.

    Arguments:
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Raises:
        ValueError: If the Team object has neither an id nor a name.

    Returns:
        Team: The Team object.

    Example: Get a team by ID
         
        Retrieve an existing team using its ID.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team(id=123456).get()
        ```

    Example: Get a team by name
         
        Retrieve an existing team using its name.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team(name="My Uniquely Named Team").get()
        ```
    """
    return self

from_id classmethod

from_id(id: int, *, synapse_client: Optional[Synapse] = None) -> Team

Gets Team object using its integer id.

PARAMETER	DESCRIPTION
id	The id of the team. TYPE: int
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
Team	The Team object. TYPE: Team

Get a team by its ID

  Retrieve an existing team using its ID.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team.from_id(id=123456)

Source code in synapseclient/models/protocols/team_protocol.py

@classmethod
def from_id(cls, id: int, *, synapse_client: Optional[Synapse] = None) -> "Team":
    """Gets Team object using its integer id.

    Arguments:
        id: The id of the team.
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        Team: The Team object.

    Example: Get a team by its ID
         
        Retrieve an existing team using its ID.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team.from_id(id=123456)
        ```
    """
    from synapseclient.models.team import Team

    return Team()

from_name classmethod

from_name(name: str, *, synapse_client: Optional[Synapse] = None) -> Team

Gets Team object using its string name.

*** You will be unable to retrieve a team by name immediately after its creation because the fragment service is eventually consistent. If you need to retrieve a team immediately following creation you should use the from_id method. ***

PARAMETER	DESCRIPTION
name	The name of the team. TYPE: str
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
Team	The Team object. TYPE: Team

Get a team by its name

  Retrieve an existing team using its name.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team.from_name(name="My Uniquely Named Team")

Source code in synapseclient/models/protocols/team_protocol.py

@classmethod
def from_name(
    cls, name: str, *, synapse_client: Optional[Synapse] = None
) -> "Team":
    """Gets Team object using its string name.

    *** You will be unable to retrieve a team by name immediately after its
    creation because the fragment service is eventually consistent. If you need
    to retrieve a team immediately following creation you should use the
    [from_id][synapseclient.models.Team.from_id] method. ***

    Arguments:
        name: The name of the team.
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        Team: The Team object.

    Example: Get a team by its name
         
        Retrieve an existing team using its name.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team.from_name(name="My Uniquely Named Team")
        ```
    """
    from synapseclient.models.team import Team

    return Team()

members

members(*, synapse_client: Optional[Synapse] = None) -> List[TeamMember]

Gets the TeamMembers associated with a team given the ID field on the Team instance.

PARAMETER	DESCRIPTION
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
List[TeamMember]	List[TeamMember]: A List of TeamMember objects.

List the members of a team

  List the current members of a team.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team.from_id(id=123456)
for member in team.members():
    print(f"{member.member.user_name} (admin: {member.is_admin})")

Source code in synapseclient/models/protocols/team_protocol.py

def members(
    self, *, synapse_client: Optional[Synapse] = None
) -> List["TeamMember"]:
    """
    Gets the TeamMembers associated with a team given the ID field on the
    Team instance.

    Arguments:
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        List[TeamMember]: A List of TeamMember objects.

    Example: List the members of a team
         
        List the current members of a team.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team.from_id(id=123456)
        for member in team.members():
            print(f"{member.member.user_name} (admin: {member.is_admin})")
        ```
    """
    from synapseclient.models.team import TeamMember

    return [TeamMember()]

invite

invite(user: str, message: str, force: bool = True, *, synapse_client: Optional[Synapse] = None) -> Union[Dict[str, str], None]

Invites a user to a team given the ID field on the Team instance.

PARAMETER	DESCRIPTION
user	The username or ID of the user to invite. TYPE: str
message	The message to send. TYPE: str
force	If True, will send the invite even if the user is already a member or has an open invitation. If False, will not send the invite if the user is already a member or has an open invitation. Defaults to True. TYPE: bool DEFAULT: True
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
Union[Dict[str, str], None]	The invite response or None if an invite was not sent.

Invite a user to a team

  Send an invitation for a user to join a team.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team.from_id(id=123456)
team.invite(user="my_username", message="Please join my team!")

Source code in synapseclient/models/protocols/team_protocol.py

def invite(
    self,
    user: str,
    message: str,
    force: bool = True,
    *,
    synapse_client: Optional[Synapse] = None,
) -> Union[Dict[str, str], None]:
    """Invites a user to a team given the ID field on the Team instance.

    Arguments:
        user: The username or ID of the user to invite.
        message: The message to send.
        force: If True, will send the invite even if the user is already a member
            or has an open invitation. If False, will not send the invite if the user
            is already a member or has an open invitation.
            Defaults to True.
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        The invite response or None if an invite was not sent.

    Example: Invite a user to a team
         
        Send an invitation for a user to join a team.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team.from_id(id=123456)
        team.invite(user="my_username", message="Please join my team!")
        ```
    """
    return {}

open_invitations

open_invitations(*, synapse_client: Optional[Synapse] = None) -> List[Dict[str, str]]

Gets all open invitations for a team given the ID field on the Team instance.

PARAMETER	DESCRIPTION
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
List[Dict[str, str]]	List[dict]: A list of invitations.

List the open invitations for a team

  List all pending invitations for a team.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team.from_id(id=123456)
open_invitations = team.open_invitations()

Source code in synapseclient/models/protocols/team_protocol.py

def open_invitations(
    self, *, synapse_client: Optional[Synapse] = None
) -> List[Dict[str, str]]:
    """Gets all open invitations for a team given the ID field on the Team instance.

    Arguments:
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        List[dict]: A list of invitations.

    Example: List the open invitations for a team
         
        List all pending invitations for a team.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team.from_id(id=123456)
        open_invitations = team.open_invitations()
        ```
    """
    return list({})

delete_invitation staticmethod

delete_invitation(invitation_id: str, *, synapse_client: Optional[Synapse] = None) -> None

Deletes an open invitation to a team. Note: The client must be an administrator of the Team referenced by the invitation, or the invitee, to make this request.

PARAMETER	DESCRIPTION
invitation_id	The ID of the invitation to delete. This can be found on the invitations returned by open_invitations. TYPE: str
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
None	None

Delete an open invitation to a team

  Cancel a pending invitation to a team.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

team = Team.from_id(id=123456)
open_invitations = team.open_invitations()
if not open_invitations:
    print("No open invitations to delete.")
else:
    # Delete the first open invitation
    Team.delete_invitation(invitation_id=open_invitations[0]["id"])

Source code in synapseclient/models/protocols/team_protocol.py

@staticmethod
def delete_invitation(
    invitation_id: str, *, synapse_client: Optional[Synapse] = None
) -> None:
    """Deletes an open invitation to a team. Note: The client must be an
    administrator of the Team referenced by the invitation, or the invitee,
    to make this request.

    Arguments:
        invitation_id: The ID of the invitation to delete. This can be found
            on the invitations returned by
            [open_invitations][synapseclient.models.Team.open_invitations].
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        None

    Example: Delete an open invitation to a team
         
        Cancel a pending invitation to a team.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        team = Team.from_id(id=123456)
        open_invitations = team.open_invitations()
        if not open_invitations:
            print("No open invitations to delete.")
        else:
            # Delete the first open invitation
            Team.delete_invitation(invitation_id=open_invitations[0]["id"])
        ```
    """
    return None

get_user_membership_status

get_user_membership_status(user_id: str, *, synapse_client: Optional[Synapse] = None) -> TeamMembershipStatus

Retrieve a user's Team Membership Status bundle.

https://rest-docs.synapse.org/rest/GET/team/id/member/principalId/membershipStatus.html

PARAMETER	DESCRIPTION
user_id	The ID of the user whose membership status is being queried. TYPE: str
synapse_client	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
TeamMembershipStatus	TeamMembershipStatus object

Check if a user is a member of a team

  This example shows how to check a user's membership status in a team.

from synapseclient import Synapse
from synapseclient.models import Team

syn = Synapse()
syn.login()

# Get a team by ID
team = Team.from_id(id=123456)

# Check membership status for a specific user
user_id = "3350396"  # Replace with actual user ID
status = team.get_user_membership_status(user_id)

print(f"User ID: {status.user_id}")
print(f"Is member: {status.is_member}")
print(f"Can join: {status.can_join}")
print(f"Has open invitation: {status.has_open_invitation}")
print(f"Has open request: {status.has_open_request}")
print(f"Membership approval required: {status.membership_approval_required}")

Source code in synapseclient/models/protocols/team_protocol.py

def get_user_membership_status(
    self,
    user_id: str,
    *,
    synapse_client: Optional[Synapse] = None,
) -> "TeamMembershipStatus":
    """Retrieve a user's Team Membership Status bundle.

    <https://rest-docs.synapse.org/rest/GET/team/id/member/principalId/membershipStatus.html>

    Arguments:
        user_id: The ID of the user whose membership status is being queried.
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        TeamMembershipStatus object

    Example: Check if a user is a member of a team
        &nbsp;
        This example shows how to check a user's membership status in a team.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team

        syn = Synapse()
        syn.login()

        # Get a team by ID
        team = Team.from_id(id=123456)

        # Check membership status for a specific user
        user_id = "3350396"  # Replace with actual user ID
        status = team.get_user_membership_status(user_id)

        print(f"User ID: {status.user_id}")
        print(f"Is member: {status.is_member}")
        print(f"Can join: {status.can_join}")
        print(f"Has open invitation: {status.has_open_invitation}")
        print(f"Has open request: {status.has_open_request}")
        print(f"Membership approval required: {status.membership_approval_required}")
        ```
    """
    from synapseclient.models.team import TeamMembershipStatus

    return TeamMembershipStatus().fill_from_dict({})

---

synapseclient.models.TeamMember dataclass

Contains information about a user's membership in a Team. In practice the constructor is not called directly by the client.

ATTRIBUTE	DESCRIPTION
team_id	The ID of the team TYPE: Optional[int]
member	An object of type org.sagebionetworks.repo.model.UserGroupHeader describing the member TYPE: Optional[UserGroupHeader]
is_admin	Whether the given member is an administrator of the team TYPE: Optional[bool]

Source code in synapseclient/models/team.py

@dataclass
class TeamMember:
    """
    Contains information about a user's membership in a Team.
    In practice the constructor is not called directly by the client.

    Attributes:
        team_id: The ID of the team
        member: An object of type [org.sagebionetworks.repo.model.UserGroupHeader](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/UserGroupHeader.html)
                describing the member
        is_admin: Whether the given member is an administrator of the team
    """

    team_id: Optional[int] = None
    """The ID of the team"""

    member: Optional[UserGroupHeader] = None
    """An object of type [org.sagebionetworks.repo.model.UserGroupHeader](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/UserGroupHeader.html)"""

    is_admin: Optional[bool] = None
    """Whether the given member is an administrator of the team"""

    def fill_from_dict(self, synapse_team_member: dict[str, str]) -> "TeamMember":
        self.team_id = (
            int(synapse_team_member.get("teamId", None))
            if synapse_team_member.get("teamId", None)
            else None
        )
        self.member = UserGroupHeader().fill_from_dict(
            synapse_team_member.get("member", None)
        )
        self.is_admin = synapse_team_member.get("isAdmin", None)
        return self

Attributes

team_id class-attribute instance-attribute

team_id: Optional[int] = None

The ID of the team

member class-attribute instance-attribute

member: Optional[UserGroupHeader] = None

An object of type org.sagebionetworks.repo.model.UserGroupHeader

is_admin class-attribute instance-attribute

is_admin: Optional[bool] = None

Whether the given member is an administrator of the team

synapseclient.models.TeamMembershipStatus dataclass

Contains information about a user's membership status in a Team. Represents a Synapse TeamMembershipStatus. User definable fields are:

ATTRIBUTE	DESCRIPTION
team_id	The id of the Team. TYPE: Optional[str]
user_id	The principal id of the user. TYPE: Optional[str]
is_member	true if and only if the user is a member of the team TYPE: Optional[bool]
has_open_invitation	true if and only if the user has an open invitation to join the team TYPE: Optional[bool]
has_open_request	true if and only if the user has an open request to join the team TYPE: Optional[bool]
can_join	true if and only if the user requesting this status information can join the user to the team TYPE: Optional[bool]
membership_approval_required	true if and only if team admin approval is required for the user to join the team TYPE: Optional[bool]
has_unmet_access_requirement	true if and only if there is at least one unmet access requirement for the user on the team TYPE: Optional[bool]
can_send_email	true if and only if the user can send an email to the team TYPE: Optional[bool]

Source code in synapseclient/models/team.py

@dataclass
class TeamMembershipStatus:
    """
    Contains information about a user's membership status in a Team.
    Represents a [Synapse TeamMembershipStatus](<https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/TeamMembershipStatus.html>).
    User definable fields are:

    Attributes:
        team_id: The id of the Team.
        user_id: The principal id of the user.
        is_member: true if and only if the user is a member of the team
        has_open_invitation: true if and only if the user has an open invitation to join the team
        has_open_request: true if and only if the user has an open request to join the team
        can_join: true if and only if the user requesting this status information can join the user to the team
        membership_approval_required: true if and only if team admin approval is required for the user to join the team
        has_unmet_access_requirement: true if and only if there is at least one unmet access requirement for the user on the team
        can_send_email: true if and only if the user can send an email to the team
    """

    team_id: Optional[str] = None
    """The ID of the team"""

    user_id: Optional[str] = None
    """The ID of the user"""

    is_member: Optional[bool] = None
    """Whether the user is a member of the team"""

    has_open_invitation: Optional[bool] = None
    """Whether the user has an open invitation to join the team"""

    has_open_request: Optional[bool] = None
    """Whether the user has an open request to join the team"""

    can_join: Optional[bool] = None
    """Whether the user can join the team"""

    membership_approval_required: Optional[bool] = None
    """Whether membership approval is required for the team"""

    has_unmet_access_requirement: Optional[bool] = None
    """Whether the user has unmet access requirements"""

    can_send_email: Optional[bool] = None
    """Whether the user can send email to the team"""

    def fill_from_dict(
        self, membership_status_dict: Dict[str, Union[str, bool]]
    ) -> "TeamMembershipStatus":
        """
        Converts a response from the REST API into this dataclass.

        Arguments:
            membership_status_dict: The response from the REST API.

        Returns:
            The TeamMembershipStatus object.
        """
        self.team_id = membership_status_dict.get("teamId", None)
        self.user_id = membership_status_dict.get("userId", None)
        self.is_member = membership_status_dict.get("isMember", None)
        self.has_open_invitation = membership_status_dict.get("hasOpenInvitation", None)
        self.has_open_request = membership_status_dict.get("hasOpenRequest", None)
        self.can_join = membership_status_dict.get("canJoin", None)
        self.membership_approval_required = membership_status_dict.get(
            "membershipApprovalRequired", None
        )
        self.has_unmet_access_requirement = membership_status_dict.get(
            "hasUnmetAccessRequirement", None
        )
        self.can_send_email = membership_status_dict.get("canSendEmail", None)
        return self

Attributes

team_id class-attribute instance-attribute

team_id: Optional[str] = None

The ID of the team

user_id class-attribute instance-attribute

user_id: Optional[str] = None

The ID of the user

is_member class-attribute instance-attribute

is_member: Optional[bool] = None

Whether the user is a member of the team

has_open_invitation class-attribute instance-attribute

has_open_invitation: Optional[bool] = None

Whether the user has an open invitation to join the team

has_open_request class-attribute instance-attribute

has_open_request: Optional[bool] = None

Whether the user has an open request to join the team

can_join class-attribute instance-attribute

can_join: Optional[bool] = None

Whether the user can join the team

membership_approval_required class-attribute instance-attribute

membership_approval_required: Optional[bool] = None

Whether membership approval is required for the team

has_unmet_access_requirement class-attribute instance-attribute

has_unmet_access_requirement: Optional[bool] = None

Whether the user has unmet access requirements

can_send_email class-attribute instance-attribute

can_send_email: Optional[bool] = None

Whether the user can send email to the team