Docs: say_stream

docs/english/_sidebar.json

@@ -85,11 +85,7 @@
 			"tools/bolt-python/concepts/token-rotation"
 		]
 	},
-	{
-		"type": "category",
-		"label": "Experiments",
-		"items": ["tools/bolt-python/experiments"]
-	},
+	"tools/bolt-python/experiments",
 	{
 		"type": "category",
 		"label": "Legacy",

docs/english/experiments.md

@@ -8,6 +8,7 @@ We love feedback from our community, so we encourage you to explore and interact
 
 ## Available experiments
 * [Agent listener argument](#agent)
+* [`say_stream` utility](#say-stream)
 
 ## Agent listener argument {#agent}
 
@@ -31,4 +32,47 @@ def handle_mention(agent: BoltAgent):
 
 ### Limitations
 
-The `chat_stream()` method currently only works when the `thread_ts` field is available in the event context (DMs and threaded replies). Top-level channel messages do not have a `thread_ts` field, and the `ts` field is not yet provided to `BoltAgent`.
+The `chat_stream()` method currently only works when the `thread_ts` field is available in the event context (DMs and threaded replies). Top-level channel messages do not have a `thread_ts` field, and the `ts` field is not yet provided to `BoltAgent`.
+
+## `say_stream` utility {#say-stream}
+
+The `say_stream` utility is a listener argument available on `app.event` and `app.message` listeners. 
+
+The `say_stream` utility streamlines calling the Python Slack SDK's [`WebClient.chat_stream`](https://docs.slack.dev/tools/python-slack-sdk/reference/web/client.html#slack_sdk.web.client.WebClient.chat_stream) helper utility by sourcing parameter values from the relevant event payload.
+
+| Parameter | Value |
+|---|---| 
+| `channel_id` | Sourced from the event payload.
+| `thread_ts` | Sourced from the event payload. Falls back to the `ts` value if available.
+| `recipient_team_id` | Sourced from the event `team_id` (`enterprise_id` if the app is installed on an org).
+| `recipient_user_id` | Sourced from the `user_id` of the event.
+
+If neither a `channel_id` or `thread_ts` can be sourced, then the utility will merely be `None`.
+
+### Example {#example}
+
+```py
+import os
+
+from slack_bolt import App, SayStream
+from slack_bolt.adapter.socket_mode import SocketModeHandler
+from slack_sdk import WebClient
+
+app = App(token=os.environ.get("SLACK_BOT_TOKEN"))
+
+@app.event("app_mention")
+def handle_app_mention(client: WebClient, say_stream: SayStream):
+  stream = say_stream()
+  stream.append(markdown_text="Someone rang the bat signal!")
+  stream.stop()
+
+@app.message("")
+def handle_message(client: WebClient, say_stream: SayStream):
+  stream = say_stream()
+
+  stream.append(markdown_text="Let me consult my *vast knowledge database*...)
+  stream.stop()
+
+if __name__ == "__main__":
+  SocketModeHandler(app, os.environ.get("SLACK_APP_TOKEN")).start()
+```

slack_bolt/__init__.py

@@ -14,6 +14,7 @@
 from .context.fail import Fail
 from .context.respond import Respond
 from .context.say import Say
+from .context.say_stream import SayStream
 from .kwargs_injection import Args
 from .listener import Listener
 from .listener_matcher import CustomListenerMatcher
@@ -42,6 +43,7 @@
     "Fail",
     "Respond",
     "Say",
+    "SayStream",
     "Args",
     "Listener",
     "CustomListenerMatcher",

slack_bolt/async_app.py

@@ -59,13 +59,15 @@ async def command(ack, body, respond):
 from .context.set_suggested_prompts.async_set_suggested_prompts import AsyncSetSuggestedPrompts
 from .context.get_thread_context.async_get_thread_context import AsyncGetThreadContext
 from .context.save_thread_context.async_save_thread_context import AsyncSaveThreadContext
+from .context.say_stream.async_say_stream import AsyncSayStream
 
 __all__ = [
     "AsyncApp",
     "AsyncAck",
     "AsyncBoltContext",
     "AsyncRespond",
     "AsyncSay",
+    "AsyncSayStream",
     "AsyncListener",
     "AsyncCustomListenerMatcher",
     "AsyncBoltRequest",

slack_bolt/context/async_context.py

@@ -10,6 +10,7 @@
 from slack_bolt.context.get_thread_context.async_get_thread_context import AsyncGetThreadContext
 from slack_bolt.context.save_thread_context.async_save_thread_context import AsyncSaveThreadContext
 from slack_bolt.context.say.async_say import AsyncSay
+from slack_bolt.context.say_stream.async_say_stream import AsyncSayStream
 from slack_bolt.context.set_status.async_set_status import AsyncSetStatus
 from slack_bolt.context.set_suggested_prompts.async_set_suggested_prompts import AsyncSetSuggestedPrompts
 from slack_bolt.context.set_title.async_set_title import AsyncSetTitle
@@ -203,6 +204,10 @@ def set_suggested_prompts(self) -> Optional[AsyncSetSuggestedPrompts]:
     def get_thread_context(self) -> Optional[AsyncGetThreadContext]:
         return self.get("get_thread_context")
 
+    @property
+    def say_stream(self) -> Optional[AsyncSayStream]:
+        return self.get("say_stream")
+
     @property
     def save_thread_context(self) -> Optional[AsyncSaveThreadContext]:
         return self.get("save_thread_context")

slack_bolt/context/base_context.py

@@ -38,6 +38,7 @@ class BaseContext(dict):
         "set_status",
         "set_title",
         "set_suggested_prompts",
+        "say_stream",
     ]
     # Note that these items are not copyable, so when you add new items to this list,
     # you must modify ThreadListenerRunner/AsyncioListenerRunner's _build_lazy_request method to pass the values.

slack_bolt/context/context.py

@@ -10,6 +10,7 @@
 from slack_bolt.context.respond import Respond
 from slack_bolt.context.save_thread_context import SaveThreadContext
 from slack_bolt.context.say import Say
+from slack_bolt.context.say_stream import SayStream
 from slack_bolt.context.set_status import SetStatus
 from slack_bolt.context.set_suggested_prompts import SetSuggestedPrompts
 from slack_bolt.context.set_title import SetTitle
@@ -204,6 +205,10 @@ def set_suggested_prompts(self) -> Optional[SetSuggestedPrompts]:
     def get_thread_context(self) -> Optional[GetThreadContext]:
         return self.get("get_thread_context")
 
+    @property
+    def say_stream(self) -> Optional[SayStream]:
+        return self.get("say_stream")
+
     @property
     def save_thread_context(self) -> Optional[SaveThreadContext]:
         return self.get("save_thread_context")

slack_bolt/context/say_stream/__init__.py

@@ -0,0 +1,6 @@
+# Don't add async module imports here
+from .say_stream import SayStream
+
+__all__ = [
+    "SayStream",
+]

slack_bolt/context/say_stream/async_say_stream.py

@@ -0,0 +1,70 @@
+import warnings
+from typing import Optional
+
+from slack_sdk.web.async_client import AsyncWebClient
+from slack_sdk.web.async_chat_stream import AsyncChatStream
+
+from slack_bolt.warning import ExperimentalWarning
+
+
+class AsyncSayStream:
+    client: AsyncWebClient
+    channel: Optional[str]
+    recipient_team_id: Optional[str]
+    recipient_user_id: Optional[str]
+    thread_ts: Optional[str]
+
+    def __init__(
+        self,
+        *,
+        client: AsyncWebClient,
+        channel: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+    ):
+        self.client = client
+        self.channel = channel
+        self.recipient_team_id = recipient_team_id
+        self.recipient_user_id = recipient_user_id
+        self.thread_ts = thread_ts
+
+    async def __call__(
+        self,
+        *,
+        buffer_size: Optional[int] = None,
+        channel: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+        **kwargs,
+    ) -> AsyncChatStream:
+        warnings.warn(
+            "say_stream is experimental and may change in future versions.",
+            category=ExperimentalWarning,
+            stacklevel=2,
+        )
+
+        channel = channel or self.channel
+        thread_ts = thread_ts or self.thread_ts
+        if channel is None:
+            raise ValueError("say_stream without channel here is unsupported")
+        if thread_ts is None:
+            raise ValueError("say_stream without thread_ts here is unsupported")
+
+        if buffer_size is not None:
+            return await self.client.chat_stream(
+                buffer_size=buffer_size,
+                channel=channel,
+                recipient_team_id=recipient_team_id or self.recipient_team_id,
+                recipient_user_id=recipient_user_id or self.recipient_user_id,
+                thread_ts=thread_ts,
+                **kwargs,
+            )
+        return await self.client.chat_stream(
+            channel=channel,
+            recipient_team_id=recipient_team_id or self.recipient_team_id,
+            recipient_user_id=recipient_user_id or self.recipient_user_id,
+            thread_ts=thread_ts,
+            **kwargs,
+        )

slack_bolt/context/say_stream/say_stream.py

@@ -0,0 +1,70 @@
+import warnings
+from typing import Optional
+
+from slack_sdk import WebClient
+from slack_sdk.web.chat_stream import ChatStream
+
+from slack_bolt.warning import ExperimentalWarning
+
+
+class SayStream:
+    client: WebClient
+    channel: Optional[str]
+    recipient_team_id: Optional[str]
+    recipient_user_id: Optional[str]
+    thread_ts: Optional[str]
+
+    def __init__(
+        self,
+        *,
+        client: WebClient,
+        channel: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+    ):
+        self.client = client
+        self.channel = channel
+        self.recipient_team_id = recipient_team_id
+        self.recipient_user_id = recipient_user_id
+        self.thread_ts = thread_ts
+
+    def __call__(
+        self,
+        *,
+        buffer_size: Optional[int] = None,
+        channel: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+        **kwargs,
+    ) -> ChatStream:
+        warnings.warn(
+            "say_stream is experimental and may change in future versions.",
+            category=ExperimentalWarning,
+            stacklevel=2,
+        )
+
+        channel = channel or self.channel
+        thread_ts = thread_ts or self.thread_ts
+        if channel is None:
+            raise ValueError("say_stream without channel here is unsupported")
+        if thread_ts is None:
+            raise ValueError("say_stream without thread_ts here is unsupported")
+
+        if buffer_size is not None:
+            return self.client.chat_stream(
+                buffer_size=buffer_size,
+                channel=channel,
+                recipient_team_id=recipient_team_id or self.recipient_team_id,
+                recipient_user_id=recipient_user_id or self.recipient_user_id,
+                thread_ts=thread_ts,
+                **kwargs,
+            )
+        return self.client.chat_stream(
+            channel=channel,
+            recipient_team_id=recipient_team_id or self.recipient_team_id,
+            recipient_user_id=recipient_user_id or self.recipient_user_id,
+            thread_ts=thread_ts,
+            **kwargs,
+        )

slack_bolt/kwargs_injection/args.py

@@ -11,6 +11,7 @@
 from slack_bolt.agent.agent import BoltAgent
 from slack_bolt.context.save_thread_context import SaveThreadContext
 from slack_bolt.context.say import Say
+from slack_bolt.context.say_stream import SayStream
 from slack_bolt.context.set_status import SetStatus
 from slack_bolt.context.set_suggested_prompts import SetSuggestedPrompts
 from slack_bolt.context.set_title import SetTitle
@@ -105,6 +106,8 @@ def handle_buttons(args):
     """`save_thread_context()` utility function for AI Agents & Assistants"""
     agent: Optional[BoltAgent]
     """`agent` listener argument for AI Agents & Assistants"""
+    say_stream: Optional[SayStream]
+    """`say_stream()` utility function for AI Agents & Assistants"""
     # middleware
     next: Callable[[], None]
     """`next()` utility function, which tells the middleware chain that it can continue with the next one"""
@@ -139,6 +142,7 @@ def __init__(
         get_thread_context: Optional[GetThreadContext] = None,
         save_thread_context: Optional[SaveThreadContext] = None,
         agent: Optional[BoltAgent] = None,
+        say_stream: Optional[SayStream] = None,
         # As this method is not supposed to be invoked by bolt-python users,
         # the naming conflict with the built-in one affects
         # only the internals of this method
@@ -173,6 +177,7 @@ def __init__(
         self.get_thread_context = get_thread_context
         self.save_thread_context = save_thread_context
         self.agent = agent
+        self.say_stream = say_stream
 
         self.next: Callable[[], None] = next
         self.next_: Callable[[], None] = next

slack_bolt/kwargs_injection/async_args.py

@@ -10,6 +10,7 @@
 from slack_bolt.context.get_thread_context.async_get_thread_context import AsyncGetThreadContext
 from slack_bolt.context.save_thread_context.async_save_thread_context import AsyncSaveThreadContext
 from slack_bolt.context.say.async_say import AsyncSay
+from slack_bolt.context.say_stream.async_say_stream import AsyncSayStream
 from slack_bolt.context.set_status.async_set_status import AsyncSetStatus
 from slack_bolt.context.set_suggested_prompts.async_set_suggested_prompts import AsyncSetSuggestedPrompts
 from slack_bolt.context.set_title.async_set_title import AsyncSetTitle
@@ -104,6 +105,8 @@ async def handle_buttons(args):
     """`save_thread_context()` utility function for AI Agents & Assistants"""
     agent: Optional[AsyncBoltAgent]
     """`agent` listener argument for AI Agents & Assistants"""
+    say_stream: Optional[AsyncSayStream]
+    """`say_stream()` utility function for AI Agents & Assistants"""
     # middleware
     next: Callable[[], Awaitable[None]]
     """`next()` utility function, which tells the middleware chain that it can continue with the next one"""
@@ -138,6 +141,7 @@ def __init__(
         get_thread_context: Optional[AsyncGetThreadContext] = None,
         save_thread_context: Optional[AsyncSaveThreadContext] = None,
         agent: Optional[AsyncBoltAgent] = None,
+        say_stream: Optional[AsyncSayStream] = None,
         next: Callable[[], Awaitable[None]],
         **kwargs,  # noqa
     ):
@@ -169,6 +173,7 @@ def __init__(
         self.get_thread_context = get_thread_context
         self.save_thread_context = save_thread_context
         self.agent = agent
+        self.say_stream = say_stream
 
         self.next: Callable[[], Awaitable[None]] = next
         self.next_: Callable[[], Awaitable[None]] = next

slack_bolt/kwargs_injection/async_utils.py

@@ -60,6 +60,7 @@ def build_async_required_kwargs(
         "set_suggested_prompts": request.context.set_suggested_prompts,
         "get_thread_context": request.context.get_thread_context,
         "save_thread_context": request.context.save_thread_context,
+        "say_stream": request.context.say_stream,
         # middleware
         "next": next_func,
         "next_": next_func,  # for the middleware using Python's built-in `next()` function

slack_bolt/kwargs_injection/utils.py

@@ -59,6 +59,7 @@ def build_required_kwargs(
         "set_title": request.context.set_title,
         "set_suggested_prompts": request.context.set_suggested_prompts,
         "save_thread_context": request.context.save_thread_context,
+        "say_stream": request.context.say_stream,
         # middleware
         "next": next_func,
         "next_": next_func,  # for the middleware using Python's built-in `next()` function