Merge pull request #1235 from Sage-Bionetworks/synpy-1633

[SYNPY-1633] Add membership_status to Team model and Deprecate Old Method

Author: linglp

docs/reference/experimental/async/team.md

@@ -17,6 +17,8 @@ at your own risk.
             - members_async
             - invite_async
             - open_invitations_async
+            - get_user_membership_status_async
 ---
 
 ::: synapseclient.models.TeamMember
+::: synapseclient.models.TeamMembershipStatus

docs/reference/experimental/sync/team.md

@@ -28,6 +28,8 @@ at your own risk.
             - members
             - invite
             - open_invitations
+            - get_user_membership_status
 ---
 
 ::: synapseclient.models.TeamMember
+::: synapseclient.models.TeamMembershipStatus

synapseclient/client.py

@@ -6020,7 +6020,12 @@ def get_team_open_invitations(
         open_requests = self._GET_paginated(request)
         return open_requests
 
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1633
+    @deprecated(
+        version="4.9.0",
+        reason="To be removed in 5.0.0. "
+        "Use the `get_user_membership_status` method on the `Team` class from `synapseclient.models` instead. "
+        "Check the docstring for the replacement function example.",
+    )
     def get_membership_status(self, userid, team):
         """Retrieve a user's Team Membership Status bundle.
         <https://rest-docs.synapse.org/rest/GET/team/id/member/principalId/membershipStatus.html>
@@ -6031,6 +6036,41 @@ def get_membership_status(self, userid, team):
 
         Returns:
             dict of TeamMembershipStatus
+
+        Example: Using this function (DEPRECATED)
+            &nbsp;
+            Getting a user's membership status for a team
+
+            ```python
+            from synapseclient import Synapse
+
+            # Login to Synapse
+            syn = Synapse()
+            syn.login()
+
+            status = syn.get_membership_status(userid="12345", team="67890")
+            print(status)
+            ```
+
+
+        Example: Migration to new method
+            &nbsp;
+
+            ```python
+            from synapseclient import Synapse
+            from synapseclient.models import Team
+
+            # Login to Synapse
+            syn = Synapse()
+            syn.login()
+
+            # Use synchronous version (recommended for most use cases)
+            team = Team.from_id(id="67890")
+            status = team.get_user_membership_status(
+                user_id="12345",
+            )
+            print(status)
+            ```
         """
         teamid = id_of(team)
         request = "/team/{team}/member/{user}/membershipStatus".format(

synapseclient/models/__init__.py

@@ -34,7 +34,7 @@
     TableUpdateTransaction,
     UploadToTableRequest,
 )
-from synapseclient.models.team import Team, TeamMember
+from synapseclient.models.team import Team, TeamMember, TeamMembershipStatus
 from synapseclient.models.user import UserGroupHeader, UserPreference, UserProfile
 from synapseclient.models.virtualtable import VirtualTable
 
@@ -50,6 +50,7 @@
     "Annotations",
     "Team",
     "TeamMember",
+    "TeamMembershipStatus",
     "UserProfile",
     "UserPreference",
     "UserGroupHeader",

synapseclient/models/protocols/team_protocol.py

@@ -6,7 +6,7 @@
 from synapseclient import Synapse
 
 if TYPE_CHECKING:
-    from synapseclient.models import Team, TeamMember
+    from synapseclient.models import Team, TeamMember, TeamMembershipStatus
 
 
 class TeamSynchronousProtocol(Protocol):
@@ -159,3 +159,53 @@ def open_invitations(
             List[dict]: A list of invitations.
         """
         return list({})
+
+    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
+            This example shows how to check a user's membership status in a team.
+            &nbsp;
+
+            ```python
+            from synapseclient import Synapse
+            from synapseclient.models import Team
+
+            syn = Synapse()
+            syn.login()
+
+            # Get a team by ID
+            team = Team.from_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/team.py

@@ -7,6 +7,7 @@
 from synapseclient.api import (
     create_team,
     delete_team,
+    get_membership_status,
     get_team,
     get_team_members,
     get_team_open_invitations,
@@ -56,6 +57,80 @@ def fill_from_dict(
         return self
 
 
+@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
+
+
 @dataclass
 @async_to_sync
 class Team(TeamSynchronousProtocol):
@@ -356,3 +431,57 @@ async def open_invitations_async(
             team=self.id, synapse_client=synapse_client
         )
         return list(invitations)
+
+    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(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)

tests/integration/synapseclient/models/async/test_team_async.py

@@ -143,3 +143,47 @@ async def test_team_membership_and_invitations(self) -> None:
 
         # Clean up
         await test_team.delete_async()
+
+    async def test_get_user_membership_status(self) -> None:
+        """Test getting user membership status for a team"""
+        # WHEN I create the team on Synapse
+        test_team = await self.team.create_async()
+
+        try:
+            # AND I get the membership status for the creator (who should be a member)
+            creator_status = await test_team.get_user_membership_status_async(
+                user_id=self.syn.getUserProfile().ownerId
+            )
+
+            # THEN the creator should have membership status indicating they are a member
+            assert creator_status.is_member is True
+            assert creator_status.team_id == str(test_team.id)
+            assert creator_status.has_open_invitation is False
+            assert creator_status.has_open_request is False
+            assert creator_status.can_join is True
+            assert creator_status.membership_approval_required is False
+            assert creator_status.has_unmet_access_requirement is False
+            assert creator_status.can_send_email is True
+
+            # WHEN I invite a test user to the team
+            invite = await test_team.invite_async(
+                user=self.TEST_USER,
+                message=self.TEST_MESSAGE,
+            )
+
+            # Check the invited user's status
+            invited_status = await test_team.get_user_membership_status_async(
+                user_id=self.syn.getUserProfile(self.TEST_USER).ownerId
+            )
+
+            # THEN the invited user should show they have an open invitation
+            assert invited_status is not None
+            assert invited_status.team_id == str(test_team.id)
+            assert invited_status.has_open_invitation is True
+            assert invited_status.membership_approval_required is True
+            assert invited_status.can_send_email is True
+            assert invited_status.is_member is False
+
+        finally:
+            # Clean up
+            await test_team.delete_async()

tests/integration/synapseclient/models/synchronous/test_team.py

@@ -143,3 +143,46 @@ async def test_team_membership_and_invitations(self) -> None:
 
         # Clean up
         test_team.delete()
+
+    async def test_team_membership_status(self) -> None:
+        """Test getting user membership status in a team"""
+        # GIVEN a team object
+
+        # WHEN I create the team on Synapse
+        test_team = self.team.create()
+
+        # AND I get the membership status for the creator (who should be a member)
+        creator_status = test_team.get_user_membership_status(
+            user_id=self.syn.getUserProfile().ownerId
+        )
+
+        # THEN the creator should have membership status indicating they are a member
+        assert creator_status.is_member is True
+        assert creator_status.team_id == str(test_team.id)
+        assert creator_status.has_open_invitation is False
+        assert creator_status.has_open_request is False
+        assert creator_status.can_join is True
+        assert creator_status.membership_approval_required is False
+        assert creator_status.has_unmet_access_requirement is False
+        assert creator_status.can_send_email is True
+
+        # WHEN I invite a test user to the team
+        invite = await test_team.invite_async(
+            user=self.TEST_USER,
+            message=self.TEST_MESSAGE,
+        )
+        # Check the invited user's status
+        invited_status = await test_team.get_user_membership_status_async(
+            user_id=self.syn.getUserProfile(self.TEST_USER).ownerId
+        )
+
+        # THEN the invited user should show they have an open invitation
+        assert invited_status is not None
+        assert invited_status.team_id == str(test_team.id)
+        assert invited_status.has_open_invitation is True
+        assert invited_status.membership_approval_required is True
+        assert invited_status.can_send_email is True
+        assert invited_status.is_member is False
+
+        # Clean up
+        test_team.delete()