[SYNPY-1426] Deprecate user and team services in Synapse client (#1212)

* Refactor user and team services in Synapse client

- Added asynchronous methods for retrieving user profiles by ID and username.
- Implemented a method to check if a user is certified.
- Deprecated several synchronous methods in the Synapse class, providing migration paths to new asynchronous methods in the UserProfile model.
- Updated the Team model to use new asynchronous API functions for team management (create, delete, get members, invite).
- Use UserGroupHeader to manage user group metadata.
- Enhanced documentation with migration examples for deprecated methods.
- Updated tests to reflect changes in error message formatting for non-existent teams.

Author: BryanFauble

docs/reference/experimental/async/team.md

@@ -18,3 +18,5 @@ at your own risk.
             - invite_async
             - open_invitations_async
 ---
+
+::: synapseclient.models.TeamMember

docs/reference/experimental/sync/team.md

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

docs/reference/rest_apis.md

@@ -12,5 +12,15 @@ favor of an auto-generated client derived from the
 [Synapse Open API Spec](https://rest-docs.synapse.org/rest/openapi/openapispecification.json).
 
 
-::: synapseclient.api.entity_bundle_services_v2
+::: synapseclient.api.agent_services
 ::: synapseclient.api.annotations
+::: synapseclient.api.api_client
+::: synapseclient.api.configuration_services
+::: synapseclient.api.entity_bundle_services_v2
+::: synapseclient.api.entity_factory
+::: synapseclient.api.entity_services
+::: synapseclient.api.file_services
+::: synapseclient.api.json_schema_services
+::: synapseclient.api.table_services
+::: synapseclient.api.team_services
+::: synapseclient.api.user_services

synapseclient/api/__init__.py

@@ -8,7 +8,7 @@
     update_session,
 )
 from .annotations import set_annotations, set_annotations_async
-from .api_client import rest_post_paginated_async
+from .api_client import rest_get_paginated_async, rest_post_paginated_async
 from .configuration_services import (
     get_client_authenticated_s3_profile,
     get_config_authentication,
@@ -66,8 +66,25 @@
     get_default_columns,
     post_columns,
 )
-from .team_services import post_team_list
-from .user_services import get_user_group_headers_batch
+from .team_services import (
+    create_team,
+    delete_membership_invitation,
+    delete_team,
+    find_team,
+    get_membership_status,
+    get_team,
+    get_team_members,
+    get_team_open_invitations,
+    invite_to_team,
+    post_team_list,
+    send_membership_invitation,
+)
+from .user_services import (
+    get_user_group_headers_batch,
+    get_user_profile_by_id,
+    get_user_profile_by_username,
+    is_user_certified,
+)
 
 __all__ = [
     # annotations
@@ -134,8 +151,22 @@
     "get_json_schema_derived_keys",
     # api client
     "rest_post_paginated_async",
+    "rest_get_paginated_async",
     # team_services
     "post_team_list",
+    "create_team",
+    "delete_team",
+    "get_team",
+    "find_team",
+    "get_team_members",
+    "send_membership_invitation",
+    "get_team_open_invitations",
+    "get_membership_status",
+    "delete_membership_invitation",
+    "invite_to_team",
     # user_services
     "get_user_group_headers_batch",
+    "get_user_profile_by_id",
+    "get_user_profile_by_username",
+    "is_user_certified",
 ]

synapseclient/api/api_client.py

@@ -1,3 +1,4 @@
+import sys
 from typing import TYPE_CHECKING, Any, AsyncGenerator, Dict, Optional
 
 import httpx
@@ -11,7 +12,7 @@ async def rest_post_paginated_async(
     body: Optional[Dict[str, Any]] = None,
     endpoint: Optional[str] = None,
     headers: Optional[httpx.Headers] = None,
-    retry_policy: Optional[Dict[str, Any]] = {},
+    retry_policy: Optional[Dict[str, Any]] = None,
     requests_session_async_synapse: Optional[httpx.AsyncClient] = None,
     *,
     synapse_client: Optional["Synapse"] = None,
@@ -34,6 +35,9 @@ async def rest_post_paginated_async(
     """
     from synapseclient import Synapse
 
+    if not retry_policy:
+        retry_policy = {}
+
     client = Synapse.get_client(synapse_client=synapse_client)
     next_page_token = None
     while True:
@@ -54,3 +58,60 @@ async def rest_post_paginated_async(
             yield item
         if next_page_token is None:
             break
+
+
+async def rest_get_paginated_async(
+    uri: str,
+    limit: int = 20,
+    offset: int = 0,
+    endpoint: Optional[str] = None,
+    headers: Optional[httpx.Headers] = None,
+    retry_policy: Optional[Dict[str, Any]] = None,
+    requests_session_async_synapse: Optional[httpx.AsyncClient] = None,
+    *,
+    synapse_client: Optional["Synapse"] = None,
+    **kwargs,
+) -> AsyncGenerator[Dict[str, str], None]:
+    """
+    Asynchronously yield items from a paginated GET endpoint.
+
+    Arguments:
+        uri: Endpoint URI for the GET request.
+        limit: How many records should be returned per request
+        offset: At what record offset from the first should iteration start
+        endpoint: Optional server endpoint override.
+        headers: Optional HTTP headers.
+        retry_policy: Optional retry settings.
+        requests_session_async_synapse: Optional async HTTPX client session.
+        kwargs: Additional keyword arguments for the request.
+        synapse_client: Optional Synapse client instance for authentication.
+    Yields:
+        Individual items from each page of the response.
+
+    The limit parameter is set at 20 by default. Using a larger limit results in fewer calls to the service, but if
+    responses are large enough to be a burden on the service they may be truncated.
+    """
+    from synapseclient import Synapse
+    from synapseclient.core import utils
+
+    if not retry_policy:
+        retry_policy = {}
+
+    client = Synapse.get_client(synapse_client=synapse_client)
+    prev_num_results = sys.maxsize
+    while prev_num_results > 0:
+        paginated_uri = utils._limit_and_offset(uri, limit=limit, offset=offset)
+        response = await client.rest_get_async(
+            uri=paginated_uri,
+            endpoint=endpoint,
+            headers=headers,
+            retry_policy=retry_policy,
+            requests_session_async_synapse=requests_session_async_synapse,
+            **kwargs,
+        )
+        results = response["results"] if "results" in response else response["children"]
+        prev_num_results = len(results)
+
+        for result in results:
+            offset += 1
+            yield result