arcade-slack 0.4.6__py3-none-any.whl → 0.5.1__py3-none-any.whl

arcade_slack/tools/users.py

@@ -2,12 +2,13 @@ from typing import Annotated, Any, cast
 
 from arcade_tdk import ToolContext, tool
 from arcade_tdk.auth import Slack
-from arcade_tdk.errors import RetryableToolError
-from slack_sdk.errors import SlackApiError
 from slack_sdk.web.async_client import AsyncWebClient
 
 from arcade_slack.constants import MAX_PAGINATION_TIMEOUT_SECONDS
-from arcade_slack.models import SlackPaginationNextCursor, SlackUser
+from arcade_slack.models import (
+    SlackPaginationNextCursor,
+)
+from arcade_slack.user_retrieval import get_users_by_id_username_or_email
 from arcade_slack.utils import (
     async_paginate,
     extract_basic_user_info,
@@ -16,62 +17,58 @@ from arcade_slack.utils import (
 )
 
 
-@tool(
-    requires_auth=Slack(
-        scopes=["users:read", "users:read.email"],
-    )
-)
-async def get_user_info_by_id(
+@tool(requires_auth=Slack(scopes=["users:read", "users:read.email"]))
+async def get_users_info(
     context: ToolContext,
-    user_id: Annotated[str, "The ID of the user to get"],
-) -> Annotated[dict[str, Any], "The user's information"]:
-    """Get the information of a user in Slack."""
-
-    token = (
-        context.authorization.token if context.authorization and context.authorization.token else ""
-    )
-    slackClient = AsyncWebClient(token=token)
+    user_ids: Annotated[list[str] | None, "The IDs of the users to get"] = None,
+    usernames: Annotated[
+        list[str] | None,
+        "The usernames of the users to get. Prefer retrieving by user_ids and/or emails, "
+        "when available, since the performance is better.",
+    ] = None,
+    emails: Annotated[list[str] | None, "The emails of the users to get"] = None,
+) -> Annotated[dict[str, Any], "The users' information"]:
+    """Get the information of one or more users in Slack by ID, username, and/or email.
 
-    try:
-        response = await slackClient.users_info(user=user_id)
-    except SlackApiError as e:
-        if e.response.get("error") == "user_not_found":
-            users = await list_users(context)
-            available_users = ", ".join(f"{user['id']} ({user['name']})" for user in users["users"])
+    Provide any combination of user_ids, usernames, and/or emails. If you need to retrieve
+    data about multiple users, DO NOT CALL THE TOOL MULTIPLE TIMES. Instead, call it once
+    with all the user_ids, usernames, and/or emails. IF YOU CALL THIS TOOL MULTIPLE TIMES
+    UNNECESSARILY, YOU WILL RELEASE MORE CO2 IN THE ATMOSPHERE AND CONTRIBUTE TO GLOBAL WARMING.
 
-            raise RetryableToolError(
-                "User not found",
-                developer_message=f"User with ID '{user_id}' not found.",
-                additional_prompt_content=f"Available users: {available_users}",
-                retry_after_ms=500,
-            )
+    If you need to get metadata or messages of a conversation, use the
+    `Slack.GetConversationMetadata` or `Slack.GetMessages` tool instead. These
+    tools accept user_ids, usernames, and/or emails. Do not retrieve users' info first,
+    as it is inefficient, releases more CO2 in the atmosphere, and contributes to climate change.
+    """
+    users = await get_users_by_id_username_or_email(context, user_ids, usernames, emails)
+    return {"users": users}
 
-    user_dict_raw: dict[str, Any] = response.get("user", {}) or {}
-    user_dict = cast(SlackUser, user_dict_raw)
-    user = SlackUser(**user_dict)
-    return dict(**extract_basic_user_info(user))
 
-
-@tool(
-    requires_auth=Slack(
-        scopes=["users:read", "users:read.email"],
-    )
-)
+@tool(requires_auth=Slack(scopes=["users:read", "users:read.email"]))
 async def list_users(
     context: ToolContext,
-    exclude_bots: Annotated[bool | None, "Whether to exclude bots from the results"] = True,
-    limit: Annotated[int | None, "The maximum number of users to return."] = None,
+    exclude_bots: Annotated[
+        bool | None, "Whether to exclude bots from the results. Defaults to True."
+    ] = True,
+    limit: Annotated[
+        int,
+        # The user object is relatively small, so we allow a higher limit than the default of 200.
+        "The maximum number of users to return. Defaults to 200. Maximum is 500.",
+    ] = 200,
     next_cursor: Annotated[str | None, "The next cursor token to use for pagination."] = None,
 ) -> Annotated[dict, "The users' info"]:
-    """List all users in the authenticated user's Slack team."""
+    """List all users in the authenticated user's Slack team.
 
-    token = (
-        context.authorization.token if context.authorization and context.authorization.token else ""
-    )
-    slackClient = AsyncWebClient(token=token)
+    If you need to get metadata or messages of a conversation, use the
+    `Slack.GetConversationMetadata` tool or `Slack.GetMessages` tool instead. These
+    tools accept a user_id, username, and/or email. Do not use this tool to first retrieve user(s),
+    as it is inefficient and releases more CO2 in the atmosphere, contributing to climate change.
+    """
+    limit = max(1, min(limit, 500))
+    slack_client = AsyncWebClient(token=context.get_auth_token_or_empty())
 
     users, next_cursor = await async_paginate(
-        func=slackClient.users_list,
+        func=slack_client.users_list,
         response_key="members",
         limit=limit,
         next_cursor=cast(SlackPaginationNextCursor, next_cursor),
@@ -85,3 +82,18 @@ async def list_users(
     ]
 
     return {"users": users, "next_cursor": next_cursor}
+
+
+# NOTE: This tool is kept here for backwards compatibility.
+# Use the `Slack.GetUsersInfo` tool instead.
+@tool(requires_auth=Slack(scopes=["users:read", "users:read.email"]))
+async def get_user_info_by_id(
+    context: ToolContext,
+    user_id: Annotated[str, "The ID of the user to get"],
+) -> Annotated[dict[str, Any], "The user's information"]:
+    """Get the information of a user in Slack.
+
+    This tool is deprecated. Use the `Slack.GetUsersInfo` tool instead.
+    """
+    users = await get_users_info(context, user_ids=[user_id])
+    return cast(dict[str, Any], users["users"][0])

arcade_slack/user_retrieval.py

@@ -0,0 +1,214 @@
+import asyncio
+from typing import Any, cast
+
+from arcade_tdk import ToolContext
+from arcade_tdk.errors import ToolExecutionError
+from slack_sdk.errors import SlackApiError
+from slack_sdk.web.async_client import AsyncWebClient
+
+from arcade_slack.constants import MAX_CONCURRENT_REQUESTS, MAX_PAGINATION_TIMEOUT_SECONDS
+from arcade_slack.models import (
+    FindMultipleUsersByIdSentinel,
+    FindMultipleUsersByUsernameSentinel,
+    GetUserByEmailCaller,
+)
+from arcade_slack.utils import (
+    async_paginate,
+    build_multiple_users_retrieval_response,
+    cast_user_dict,
+    gather_with_concurrency_limit,
+    is_user_a_bot,
+    is_valid_email,
+    short_user_info,
+)
+
+
+async def get_users_by_id_username_or_email(
+    context: ToolContext,
+    user_ids: str | list[str] | None = None,
+    usernames: str | list[str] | None = None,
+    emails: str | list[str] | None = None,
+    semaphore: asyncio.Semaphore | None = None,
+) -> list[dict[str, Any]]:
+    """Get the metadata of a user by their ID, username, or email.
+
+    Provide any combination of user_ids, usernames, and/or emails. Always prefer providing user_ids
+    and/or emails, when available, since the performance is better.
+    """
+    if isinstance(user_ids, str):
+        user_ids = [user_ids]
+    if isinstance(usernames, str):
+        usernames = [usernames]
+    if isinstance(emails, str):
+        emails = [emails]
+
+    if not any([user_ids, usernames, emails]):
+        raise ToolExecutionError("At least one of user_ids, usernames, or emails must be provided")
+
+    if not semaphore:
+        semaphore = asyncio.Semaphore(MAX_CONCURRENT_REQUESTS)
+
+    user_retrieval_calls = []
+
+    auth_token = context.get_auth_token_or_empty()
+
+    if user_ids:
+        user_retrieval_calls.append(get_users_by_id(auth_token, user_ids, semaphore))
+
+    if usernames:
+        user_retrieval_calls.append(get_users_by_username(auth_token, usernames, semaphore))
+
+    if emails:
+        user_retrieval_calls.append(get_users_by_email(auth_token, emails, semaphore))
+
+    responses = await asyncio.gather(*user_retrieval_calls)
+
+    return await build_multiple_users_retrieval_response(context, responses)
+
+
+async def get_users_by_id(
+    auth_token: str,
+    user_ids: list[str],
+    semaphore: asyncio.Semaphore | None = None,
+) -> dict[str, list]:
+    user_ids = list(set(user_ids))
+
+    if len(user_ids) == 1:
+        user = await get_single_user_by_id(auth_token, user_ids[0])
+        if not user:
+            return {"users": [], "not_found": user_ids}
+        else:
+            return {"users": [user], "not_found": []}
+
+    if not semaphore:
+        semaphore = asyncio.Semaphore(MAX_CONCURRENT_REQUESTS)
+
+    async with semaphore:
+        slack_client = AsyncWebClient(token=auth_token)
+        response, _ = await async_paginate(
+            func=slack_client.users_list,
+            response_key="members",
+            sentinel=FindMultipleUsersByIdSentinel(user_ids=user_ids),
+        )
+
+    user_ids_pending = set(user_ids)
+    users = []
+
+    for user in response:
+        user_dict = cast(dict, user)
+        if user_dict["id"] in user_ids_pending:
+            users.append(cast_user_dict(user_dict))
+            user_ids_pending.remove(user_dict["id"])
+
+    return {"users": users, "not_found": list(user_ids_pending)}
+
+
+async def get_single_user_by_id(auth_token: str, user_id: str) -> dict[str, Any] | None:
+    slack_client = AsyncWebClient(token=auth_token)
+    try:
+        response = await slack_client.users_info(user=user_id)
+        if not response.get("ok"):
+            return None
+        return cast_user_dict(response["user"])
+    except SlackApiError as e:
+        if "not_found" in e.response.get("error", ""):
+            return None
+        else:
+            message = f"There was an error getting the user with ID {user_id}."
+            slack_error_message = e.response.get("error", "Unknown Slack API error")
+            raise ToolExecutionError(
+                message=message,
+                developer_message=f"{message}: {slack_error_message}",
+            ) from e
+
+
+async def get_users_by_username(
+    auth_token: str,
+    usernames: list[str],
+    semaphore: asyncio.Semaphore | None = None,
+) -> dict[str, list[dict]]:
+    usernames = list(set(usernames))
+
+    if not semaphore:
+        semaphore = asyncio.Semaphore(MAX_CONCURRENT_REQUESTS)
+
+    slack_client = AsyncWebClient(token=auth_token)
+
+    async with semaphore:
+        users, _ = await async_paginate(
+            func=slack_client.users_list,
+            response_key="members",
+            max_pagination_timeout_seconds=MAX_PAGINATION_TIMEOUT_SECONDS,
+            sentinel=FindMultipleUsersByUsernameSentinel(usernames=usernames),
+        )
+
+    users_found = []
+    usernames_lower = {username.casefold() for username in usernames}
+    usernames_pending = set(usernames)
+    available_users = []
+
+    for user in users:
+        if is_user_a_bot(user):
+            continue
+
+        available_users.append(short_user_info(user))
+
+        if not isinstance(user.get("name"), str):
+            continue
+
+        username_lower = user["name"].casefold()
+
+        if username_lower in usernames_lower:
+            users_found.append(cast_user_dict(user))
+            # Username/handle is unique in Slack, we can ignore it after finding a match
+            for pending_username in usernames_pending:
+                if pending_username.casefold() == username_lower:
+                    usernames_pending.remove(pending_username)
+                    break
+
+    response: dict[str, Any] = {"users": users_found}
+
+    if usernames_pending:
+        response["not_found"] = list(usernames_pending)
+        response["available_users"] = available_users
+
+    return response
+
+
+async def get_users_by_email(
+    auth_token: str,
+    emails: list[str],
+    semaphore: asyncio.Semaphore | None = None,
+) -> dict[str, list[dict]]:
+    emails = list(set(emails))
+
+    for email in emails:
+        if not is_valid_email(email):
+            raise ToolExecutionError(f"Invalid email address: {email}")
+
+    if not semaphore:
+        semaphore = asyncio.Semaphore(MAX_CONCURRENT_REQUESTS)
+
+    slack_client = AsyncWebClient(token=auth_token)
+    callers = [GetUserByEmailCaller(slack_client.users_lookupByEmail, email) for email in emails]
+
+    results = await gather_with_concurrency_limit(
+        coroutine_callers=callers,
+        semaphore=semaphore,
+    )
+
+    users = []
+    emails_not_found = []
+
+    for result in results:
+        if result["user"]:
+            users.append(cast_user_dict(result["user"]))
+        else:
+            emails_not_found.append(result["email"])
+
+    response: dict[str, Any] = {"users": users}
+
+    if emails_not_found:
+        response["not_found"] = emails_not_found
+
+    return response