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

arcade_slack/constants.py

@@ -0,0 +1,13 @@
+import os
+
+from arcade_slack.custom_types import PositiveInt
+
+MAX_PAGINATION_SIZE_LIMIT = 200
+
+MAX_PAGINATION_TIMEOUT_SECONDS = PositiveInt(
+    os.environ.get(
+        "MAX_PAGINATION_TIMEOUT_SECONDS",
+        os.environ.get("MAX_SLACK_PAGINATION_TIMEOUT_SECONDS", 30),
+    ),
+    name="MAX_PAGINATION_TIMEOUT_SECONDS or MAX_SLACK_PAGINATION_TIMEOUT_SECONDS",
+)

arcade_slack/critics.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+from arcade_evals import BinaryCritic
+
+
+class RelativeTimeBinaryCritic(BinaryCritic):
+    def evaluate(self, expected: Any, actual: Any) -> dict[str, float | bool]:
+        """
+        Evaluates whether the expected and actual relative time strings are equivalent after
+        casting.
+
+        Args:
+            expected: The expected value.
+            actual: The actual value to compare, cast to the type of expected.
+
+        Returns:
+            dict: A dictionary containing the match status and score.
+        """
+        try:
+            actual_casted = self.cast_actual(expected, actual)
+        except TypeError:
+            actual_casted = actual
+
+        expected_parts = tuple(map(int, expected.split(":")))
+        actual_parts = tuple(map(int, actual_casted.split(":")))
+
+        if len(expected_parts) != 3 or len(actual_parts) != 3:
+            return {"match": False, "score": 0.0}
+
+        exp_days, exp_hours, exp_minutes = expected_parts
+        act_days, act_hours, act_minutes = actual_parts
+
+        match = exp_days == act_days and exp_hours == act_hours and exp_minutes == act_minutes
+        return {"match": match, "score": self.weight if match else 0.0}

arcade_slack/custom_types.py

@@ -0,0 +1,26 @@
+from typing import NewType
+
+
+class PositiveInt(int):
+    def __new__(cls, value: str | int, name: str = "value") -> "PositiveInt":
+        def validate(val: int) -> int:
+            if val <= 0:
+                raise ValueError(f"{name} must be positive, got {val}")
+            return val
+
+        try:
+            value = int(value)
+        except ValueError:
+            raise ValueError(f"{name} must be a valid integer, got {value!r}")
+
+        validated_value = validate(value)
+        instance = super().__new__(cls, validated_value)
+        return instance
+
+
+SlackOffsetSecondsFromUTC = NewType("SlackOffsetSecondsFromUTC", int)  # observe it can be negative
+SlackPaginationNextCursor = str | None
+SlackUserFieldId = NewType("SlackUserFieldId", str)
+SlackUserId = NewType("SlackUserId", str)
+SlackTeamId = NewType("SlackTeamId", str)
+SlackTimestampStr = NewType("SlackTimestampStr", str)

arcade_slack/exceptions.py

@@ -0,0 +1,30 @@
+class SlackToolkitError(Exception):
+    """Base class for all Slack toolkit errors."""
+
+
+class PaginationTimeoutError(SlackToolkitError):
+    """Raised when a timeout occurs during pagination."""
+
+    def __init__(self, timeout_seconds: int):
+        self.timeout_seconds = timeout_seconds
+        super().__init__(f"The pagination process timed out after {timeout_seconds} seconds.")
+
+
+class ItemNotFoundError(SlackToolkitError):
+    """Raised when an item is not found."""
+
+
+class UsernameNotFoundError(SlackToolkitError):
+    """Raised when a user is not found by the username searched"""
+
+    def __init__(self, usernames_found: list[str], username_not_found: str) -> None:
+        self.usernames_found = usernames_found
+        self.username_not_found = username_not_found
+
+
+class ConversationNotFoundError(SlackToolkitError):
+    """Raised when a conversation is not found"""
+
+
+class DirectMessageConversationNotFoundError(ConversationNotFoundError):
+    """Raised when a direct message conversation searched is not found"""

arcade_slack/models.py

@@ -0,0 +1,206 @@
+from enum import Enum
+from typing import Literal, TypedDict
+
+from arcade_slack.custom_types import (
+    SlackOffsetSecondsFromUTC,
+    SlackPaginationNextCursor,
+    SlackTeamId,
+    SlackTimestampStr,
+    SlackUserFieldId,
+    SlackUserId,
+)
+
+
+class ConversationTypeSlackName(str, Enum):
+    PUBLIC_CHANNEL = "public_channel"  # Public channels are visible to all users in the workspace
+    PRIVATE_CHANNEL = "private_channel"  # Private channels are visible to only specific users
+    MPIM = "mpim"  # Multi-person direct message conversation
+    IM = "im"  # Two person direct message conversation
+
+
+class ConversationType(str, Enum):
+    PUBLIC_CHANNEL = "public_channel"
+    PRIVATE_CHANNEL = "private_channel"
+    MULTI_PERSON_DIRECT_MESSAGE = "multi_person_direct_message"
+    DIRECT_MESSAGE = "direct_message"
+
+
+"""
+About Slack dictionaries: Slack does not guarantee the presence of all fields for a given
+object. It will vary from endpoint to endpoint and even if the field is present, they say it may
+contain a None value or an empty string instead of the actual expected value.
+
+See, for example, the 'Common Fields' section of the user type definition at:
+https://api.slack.com/types/user#fields (https://archive.is/RUZdL)
+
+Because of that, our TypedDicts ended up having to be mostly total=False and most of the fields'
+type hints are Optional. Use Slack dictionary fields with caution. It's advisable to validate the
+value before using it and raise errors that are clear to understand, when appropriate.
+"""
+
+
+class SlackUserFieldData(TypedDict, total=False):
+    """Type definition for Slack user field data dictionary.
+
+    Slack type definition: https://api.slack.com/methods/users.profile.set#custom-profile
+    """
+
+    value: str | None
+    alt: bool | None
+
+
+class SlackStatusEmojiDisplayInfo(TypedDict, total=False):
+    """Type definition for Slack status emoji display info dictionary."""
+
+    emoji_name: str | None
+    display_url: str | None
+
+
+class SlackUserProfile(TypedDict, total=False):
+    """Type definition for Slack user profile dictionary.
+
+    Slack type definition: https://api.slack.com/types/user#profile (https://archive.is/RUZdL)
+    """
+
+    title: str | None
+    phone: str | None
+    skype: str | None
+    email: str | None
+    real_name: str | None
+    real_name_normalized: str | None
+    display_name: str | None
+    display_name_normalized: str | None
+    first_name: str | None
+    last_name: str | None
+    fields: list[dict[SlackUserFieldId, SlackUserFieldData]] | None
+    image_original: str | None
+    is_custom_image: bool | None
+    image_24: str | None
+    image_32: str | None
+    image_48: str | None
+    image_72: str | None
+    image_192: str | None
+    image_512: str | None
+    image_1024: str | None
+    status_emoji: str | None
+    status_emoji_display_info: list[SlackStatusEmojiDisplayInfo] | None
+    status_text: str | None
+    status_text_canonical: str | None
+    status_expiration: int | None
+    avatar_hash: str | None
+    start_date: str | None
+    pronouns: str | None
+    huddle_state: str | None
+    huddle_state_expiration: int | None
+    team: SlackTeamId | None
+
+
+class SlackUser(TypedDict, total=False):
+    """Type definition for Slack user dictionary.
+
+    Slack type definition: https://api.slack.com/types/user (https://archive.is/RUZdL)
+    """
+
+    id: SlackUserId
+    team_id: SlackTeamId
+    name: str | None
+    deleted: bool | None
+    color: str | None
+    real_name: str | None
+    tz: str | None
+    tz_label: str | None
+    tz_offset: SlackOffsetSecondsFromUTC | None
+    profile: SlackUserProfile | None
+    is_admin: bool | None
+    is_owner: bool | None
+    is_primary_owner: bool | None
+    is_restricted: bool | None
+    is_ultra_restricted: bool | None
+    is_bot: bool | None
+    is_app_user: bool | None
+    is_email_confirmed: bool | None
+    who_can_share_contact_card: str | None
+
+
+class SlackUserList(TypedDict, total=False):
+    """Type definition for the returned user list dictionary."""
+
+    members: list[SlackUser]
+
+
+class SlackConversationPurpose(TypedDict, total=False):
+    """Type definition for the Slack conversation purpose dictionary."""
+
+    value: str | None
+
+
+class SlackConversation(TypedDict, total=False):
+    """Type definition for the Slack conversation dictionary."""
+
+    id: str | None
+    name: str | None
+    is_private: bool | None
+    is_archived: bool | None
+    is_member: bool | None
+    is_channel: bool | None
+    is_group: bool | None
+    is_im: bool | None
+    is_mpim: bool | None
+    purpose: SlackConversationPurpose | None
+    num_members: int | None
+    user: SlackUser | None
+    is_user_deleted: bool | None
+
+
+class SlackMessage(TypedDict, total=True):
+    """Type definition for the Slack message dictionary."""
+
+    type: Literal["message"]
+    user: SlackUser
+    text: str
+    ts: SlackTimestampStr  # Slack timestamp as a string (e.g. "1234567890.123456")
+
+
+class Message(SlackMessage, total=False):
+    """Type definition for the message dictionary.
+
+    Having a human-readable datetime string is useful for LLMs when they need to display the
+    date/time for the user. If not, they'll try to convert the unix timestamp to a human-readable
+    date/time,which they don't usually do accurately.
+    """
+
+    datetime_timestamp: str  # Human-readable datetime string (e.g. "2025-01-22 12:00:00")
+
+
+class ConversationMetadata(TypedDict, total=False):
+    """Type definition for the conversation metadata dictionary."""
+
+    id: str | None
+    name: str | None
+    conversation_type: str | None
+    is_private: bool | None
+    is_archived: bool | None
+    is_member: bool | None
+    purpose: str | None
+    num_members: int | None
+    user: SlackUser | None
+    is_user_deleted: bool | None
+
+
+class BasicUserInfo(TypedDict, total=False):
+    """Type definition for the returned basic user info dictionary."""
+
+    id: str | None
+    name: str | None
+    is_bot: bool | None
+    email: str | None
+    display_name: str | None
+    real_name: str | None
+    timezone: str | None
+
+
+class SlackConversationsToolResponse(TypedDict, total=True):
+    """Type definition for the Slack conversations tool response dictionary."""
+
+    conversations: list[ConversationMetadata]
+    next_cursor: SlackPaginationNextCursor | None