diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index 2b30be62b..93f251234 100644 --- a/.github/workflows/ci-build.yml +++ b/.github/workflows/ci-build.yml @@ -72,11 +72,9 @@ jobs: uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: ${{ env.LATEST_SUPPORTED_PY }} - # Regenerating also runs the MDX/acorn hazard gate inside the generator, - # so a stale tree or an unfenced code example both fail here. - - name: Regenerate the API reference + - name: Generate API reference run: ./scripts/generate_api_docs.sh - - name: Fail if the committed reference is out of date + - name: Verify committed reference is up to date run: git diff --exit-code -- docs/english/reference unittest: diff --git a/docs/english/_sidebar.json b/docs/english/_sidebar.json index 348c134d1..6dc97ce2d 100644 --- a/docs/english/_sidebar.json +++ b/docs/english/_sidebar.json @@ -6,10 +6,7 @@ "className": "sidebar-title" }, "tools/bolt-python/getting-started", - { - "type": "html", - "value": "
" - }, + { "type": "html", "value": "
" }, "tools/bolt-python/creating-an-app", { "type": "category", @@ -17,7 +14,7 @@ "link": { "type": "doc", "id": "tools/bolt-python/concepts/adding-agent-features" - }, + }, "items": [ "tools/bolt-python/concepts/adding-agent-features", "tools/bolt-python/concepts/using-the-assistant-class" @@ -103,14 +100,9 @@ { "type": "category", "label": "Legacy", - "items": [ - "tools/bolt-python/legacy/steps-from-apps" - ] - }, - { - "type": "html", - "value": "
" + "items": ["tools/bolt-python/legacy/steps-from-apps"] }, + { "type": "html", "value": "
" }, { "type": "category", "label": "Tutorials", @@ -124,24 +116,19 @@ "tools/bolt-python/tutorial/modals/modals" ] }, - { - "type": "html", - "value": "
" - }, + { "type": "html", "value": "
" }, { "type": "category", "label": "Reference", + "link": { + "type": "doc", + "id": "tools/bolt-python/reference/index" + }, "items": [ - { - "type": "autogenerated", - "dirName": "tools/bolt-python/reference" - } + { "type": "autogenerated", "dirName": "tools/bolt-python/reference" } ] }, - { - "type": "html", - "value": "
" - }, + { "type": "html", "value": "
" }, { "type": "category", "label": "日本語 (日本)", @@ -218,9 +205,7 @@ { "type": "category", "label": "レガシー（非推奨）", - "items": [ - "tools/bolt-python/ja-jp/legacy/steps-from-apps" - ] + "items": ["tools/bolt-python/ja-jp/legacy/steps-from-apps"] } ] } diff --git a/docs/english/reference/adapter/aiohttp/index.md b/docs/english/reference/adapter/aiohttp/index.md index 9e41cad68..87882ccd4 100644 --- a/docs/english/reference/adapter/aiohttp/index.md +++ b/docs/english/reference/adapter/aiohttp/index.md @@ -3,14 +3,4 @@ sidebar_label: aiohttp title: slack_bolt.adapter.aiohttp --- -#### to\_bolt\_request -```python -async def to_bolt_request(request: web.Request) -> AsyncBoltRequest -``` - -#### to\_aiohttp\_response - -```python -async def to_aiohttp_response(bolt_resp: BoltResponse) -> web.Response -``` diff --git a/docs/english/reference/adapter/asgi/aiohttp/index.md b/docs/english/reference/adapter/asgi/aiohttp/index.md index 83bf93ac8..e76fff38c 100644 --- a/docs/english/reference/adapter/asgi/aiohttp/index.md +++ b/docs/english/reference/adapter/asgi/aiohttp/index.md @@ -3,19 +3,13 @@ sidebar_label: aiohttp title: slack_bolt.adapter.asgi.aiohttp --- -## AsyncSlackRequestHandler Objects +## `AsyncSlackRequestHandler` ```python -class AsyncSlackRequestHandler(SlackRequestHandler) +AsyncSlackRequestHandler(app, path='/slack/events') ``` -#### app: `AsyncApp` - -#### \_\_init\_\_ - -```python -def __init__(app: AsyncApp, path: str = '/slack/events') -``` +Bases: SlackRequestHandler Setup Bolt as an ASGI web framework, this will make your application compatible with ASGI web servers. @@ -25,36 +19,17 @@ With the default settings, `http://localhost:3000/slack/events` Run Bolt with [uvicron](https://www.uvicorn.org/) ```python -# Python app = AsyncApp() api = SlackRequestHandler(app) +``` -# bash +```bash export SLACK_SIGNING_SECRET=*** export SLACK_BOT_TOKEN=xoxb-*** uvicorn app:api --port 3000 --log-level debug ``` +**Parameters:** -**Arguments**: - -- `app` _AsyncApp_ - Your bolt application -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) - -#### dispatch - -```python -async def dispatch(request: AsgiHttpRequest) -> BoltResponse -``` - -#### handle\_installation - -```python -async def handle_installation(request: AsgiHttpRequest) -> BoltResponse -``` - -#### handle\_callback - -```python -async def handle_callback(request: AsgiHttpRequest) -> BoltResponse -``` +- **app** (AsyncApp) – Your bolt application +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) diff --git a/docs/english/reference/adapter/asgi/async_handler.md b/docs/english/reference/adapter/asgi/async_handler.md index f0719db0e..2b8cd30d1 100644 --- a/docs/english/reference/adapter/asgi/async_handler.md +++ b/docs/english/reference/adapter/asgi/async_handler.md @@ -3,19 +3,13 @@ sidebar_label: async_handler title: slack_bolt.adapter.asgi.async_handler --- -## AsyncSlackRequestHandler Objects +## `AsyncSlackRequestHandler` ```python -class AsyncSlackRequestHandler(SlackRequestHandler) +AsyncSlackRequestHandler(app, path='/slack/events') ``` -#### app: `AsyncApp` - -#### \_\_init\_\_ - -```python -def __init__(app: AsyncApp, path: str = '/slack/events') -``` +Bases: SlackRequestHandler Setup Bolt as an ASGI web framework, this will make your application compatible with ASGI web servers. @@ -25,36 +19,17 @@ With the default settings, `http://localhost:3000/slack/events` Run Bolt with [uvicron](https://www.uvicorn.org/) ```python -# Python app = AsyncApp() api = SlackRequestHandler(app) +``` -# bash +```bash export SLACK_SIGNING_SECRET=*** export SLACK_BOT_TOKEN=xoxb-*** uvicorn app:api --port 3000 --log-level debug ``` +**Parameters:** -**Arguments**: - -- `app` _AsyncApp_ - Your bolt application -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) - -#### dispatch - -```python -async def dispatch(request: AsgiHttpRequest) -> BoltResponse -``` - -#### handle\_installation - -```python -async def handle_installation(request: AsgiHttpRequest) -> BoltResponse -``` - -#### handle\_callback - -```python -async def handle_callback(request: AsgiHttpRequest) -> BoltResponse -``` +- **app** (AsyncApp) – Your bolt application +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) diff --git a/docs/english/reference/adapter/asgi/base_handler.md b/docs/english/reference/adapter/asgi/base_handler.md index 34bb6ea0e..21285ef7c 100644 --- a/docs/english/reference/adapter/asgi/base_handler.md +++ b/docs/english/reference/adapter/asgi/base_handler.md @@ -3,36 +3,28 @@ sidebar_label: base_handler title: slack_bolt.adapter.asgi.base_handler --- -## BaseSlackRequestHandler Objects +## `BaseSlackRequestHandler` -```python -class BaseSlackRequestHandler() -``` - -#### app: `Union[App, AsyncApp]` - -#### path: `str` - -#### dispatch +### `dispatch` ```python -async def dispatch(request: AsgiHttpRequest) -> BoltResponse +dispatch(request) ``` Dispatches a request to the Bolt App. -#### handle\_installation +### `handle_callback` ```python -async def handle_installation(request: AsgiHttpRequest) -> BoltResponse +handle_callback(request) ``` -Handles installation of the OAuthFlow. +Handles the callback of the OAuthFlow. -#### handle\_callback +### `handle_installation` ```python -async def handle_callback(request: AsgiHttpRequest) -> BoltResponse +handle_installation(request) ``` -Handles the callback of the OAuthFlow. +Handles installation of the OAuthFlow. diff --git a/docs/english/reference/adapter/asgi/builtin/index.md b/docs/english/reference/adapter/asgi/builtin/index.md index 8c6526f5b..9abf83540 100644 --- a/docs/english/reference/adapter/asgi/builtin/index.md +++ b/docs/english/reference/adapter/asgi/builtin/index.md @@ -3,17 +3,13 @@ sidebar_label: builtin title: slack_bolt.adapter.asgi.builtin --- -## SlackRequestHandler Objects +## `SlackRequestHandler` ```python -class SlackRequestHandler(BaseSlackRequestHandler) +SlackRequestHandler(app, path='/slack/events') ``` -#### \_\_init\_\_ - -```python -def __init__(app: App, path: str = '/slack/events') -``` +Bases: BaseSlackRequestHandler Setup Bolt as an ASGI web framework, this will make your application compatible with ASGI web servers. @@ -23,36 +19,17 @@ With the default settings, `http://localhost:3000/slack/events` Run Bolt with [uvicron](https://www.uvicorn.org/) ```python -# Python app = App() api = SlackRequestHandler(app) +``` -# bash +```bash export SLACK_SIGNING_SECRET=*** export SLACK_BOT_TOKEN=xoxb-*** uvicorn app:api --port 3000 --log-level debug ``` +**Parameters:** -**Arguments**: - -- `app` _App_ - Your bolt application -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) - -#### dispatch - -```python -async def dispatch(request: AsgiHttpRequest) -> BoltResponse -``` - -#### handle\_installation - -```python -async def handle_installation(request: AsgiHttpRequest) -> BoltResponse -``` - -#### handle\_callback - -```python -async def handle_callback(request: AsgiHttpRequest) -> BoltResponse -``` +- **app** (App) – Your bolt application +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) diff --git a/docs/english/reference/adapter/asgi/http_request.md b/docs/english/reference/adapter/asgi/http_request.md index 6fc4a2c6d..883312260 100644 --- a/docs/english/reference/adapter/asgi/http_request.md +++ b/docs/english/reference/adapter/asgi/http_request.md @@ -3,28 +3,4 @@ sidebar_label: http_request title: slack_bolt.adapter.asgi.http_request --- -## AsgiHttpRequest Objects -```python -class AsgiHttpRequest() -``` - -#### \_\_init\_\_ - -```python -def __init__(scope: scope_type, receive: Callable) -``` - -#### raw\_headers: `Iterable[Tuple[bytes, bytes]]` - -#### get\_headers - -```python -def get_headers() -> Dict[str, Union[str, Sequence[str]]] -``` - -#### get\_raw\_body - -```python -async def get_raw_body() -> str -``` diff --git a/docs/english/reference/adapter/asgi/http_response.md b/docs/english/reference/adapter/asgi/http_response.md index 5c0ffe1ca..30ce5480e 100644 --- a/docs/english/reference/adapter/asgi/http_response.md +++ b/docs/english/reference/adapter/asgi/http_response.md @@ -3,32 +3,4 @@ sidebar_label: http_response title: slack_bolt.adapter.asgi.http_response --- -## AsgiHttpResponse Objects -```python -class AsgiHttpResponse() -``` - -#### \_\_init\_\_ - -```python -def __init__(status: int, headers: Dict[str, Sequence[str]] = {}, body: str = '') -``` - -#### status: `int` - -#### body: `bytes` - -#### raw\_headers: `List[Tuple[bytes, bytes]]` - -#### get\_response\_start - -```python -def get_response_start() -> Dict[str, Union[str, int, Iterable[Tuple[bytes, bytes]]]] -``` - -#### get\_response\_body - -```python -def get_response_body() -> Dict[str, Union[str, bytes, bool]] -``` diff --git a/docs/english/reference/adapter/asgi/index.md b/docs/english/reference/adapter/asgi/index.md index 069590f06..190e9936d 100644 --- a/docs/english/reference/adapter/asgi/index.md +++ b/docs/english/reference/adapter/asgi/index.md @@ -3,27 +3,13 @@ sidebar_label: asgi title: slack_bolt.adapter.asgi --- -## Submodules - -- [slack_bolt.adapter.asgi.aiohttp](/tools/bolt-python/reference/adapter/asgi/aiohttp) -- [slack_bolt.adapter.asgi.async_handler](/tools/bolt-python/reference/adapter/asgi/async_handler) -- [slack_bolt.adapter.asgi.base_handler](/tools/bolt-python/reference/adapter/asgi/base_handler) -- [slack_bolt.adapter.asgi.builtin](/tools/bolt-python/reference/adapter/asgi/builtin) -- [slack_bolt.adapter.asgi.http_request](/tools/bolt-python/reference/adapter/asgi/http_request) -- [slack_bolt.adapter.asgi.http_response](/tools/bolt-python/reference/adapter/asgi/http_response) -- [slack_bolt.adapter.asgi.utils](/tools/bolt-python/reference/adapter/asgi/utils) - -## SlackRequestHandler Objects +## `SlackRequestHandler` ```python -class SlackRequestHandler(BaseSlackRequestHandler) +SlackRequestHandler(app, path='/slack/events') ``` -#### \_\_init\_\_ - -```python -def __init__(app: App, path: str = '/slack/events') -``` +Bases: BaseSlackRequestHandler Setup Bolt as an ASGI web framework, this will make your application compatible with ASGI web servers. @@ -33,36 +19,27 @@ With the default settings, `http://localhost:3000/slack/events` Run Bolt with [uvicron](https://www.uvicorn.org/) ```python -# Python app = App() api = SlackRequestHandler(app) +``` -# bash +```bash export SLACK_SIGNING_SECRET=*** export SLACK_BOT_TOKEN=xoxb-*** uvicorn app:api --port 3000 --log-level debug ``` +**Parameters:** -**Arguments**: - -- `app` _App_ - Your bolt application -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) +- **app** (App) – Your bolt application +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) -#### dispatch - -```python -async def dispatch(request: AsgiHttpRequest) -> BoltResponse -``` - -#### handle\_installation - -```python -async def handle_installation(request: AsgiHttpRequest) -> BoltResponse -``` - -#### handle\_callback +## Submodules -```python -async def handle_callback(request: AsgiHttpRequest) -> BoltResponse -``` +- [slack_bolt.adapter.asgi.aiohttp](/tools/bolt-python/reference/adapter/asgi/aiohttp) +- [slack_bolt.adapter.asgi.async_handler](/tools/bolt-python/reference/adapter/asgi/async_handler) +- [slack_bolt.adapter.asgi.base_handler](/tools/bolt-python/reference/adapter/asgi/base_handler) +- [slack_bolt.adapter.asgi.builtin](/tools/bolt-python/reference/adapter/asgi/builtin) +- [slack_bolt.adapter.asgi.http_request](/tools/bolt-python/reference/adapter/asgi/http_request) +- [slack_bolt.adapter.asgi.http_response](/tools/bolt-python/reference/adapter/asgi/http_response) +- [slack_bolt.adapter.asgi.utils](/tools/bolt-python/reference/adapter/asgi/utils) diff --git a/docs/english/reference/adapter/asgi/utils.md b/docs/english/reference/adapter/asgi/utils.md index a9a25ebe6..40e26a7b1 100644 --- a/docs/english/reference/adapter/asgi/utils.md +++ b/docs/english/reference/adapter/asgi/utils.md @@ -3,8 +3,4 @@ sidebar_label: utils title: slack_bolt.adapter.asgi.utils --- -#### ENCODING -#### scope\_value\_type - -#### scope\_type diff --git a/docs/english/reference/adapter/aws_lambda/chalice_handler.md b/docs/english/reference/adapter/aws_lambda/chalice_handler.md index a647098c4..5a39bc0ca 100644 --- a/docs/english/reference/adapter/aws_lambda/chalice_handler.md +++ b/docs/english/reference/adapter/aws_lambda/chalice_handler.md @@ -3,44 +3,4 @@ sidebar_label: chalice_handler title: slack_bolt.adapter.aws_lambda.chalice_handler --- -## ChaliceSlackRequestHandler Objects -```python -class ChaliceSlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App, chalice: Chalice, lambda_client: Optional[BaseClient] = None) -``` - -#### clear\_all\_log\_handlers - -```python -def clear_all_log_handlers() -``` - -#### handle - -```python -def handle(request: Request) -``` - -#### to\_bolt\_request - -```python -def to_bolt_request(request: Request, body: str) -> BoltRequest -``` - -#### to\_chalice\_response - -```python -def to_chalice_response(resp: BoltResponse) -> Response -``` - -#### not\_found - -```python -def not_found() -> Response -``` diff --git a/docs/english/reference/adapter/aws_lambda/chalice_lazy_listener_runner.md b/docs/english/reference/adapter/aws_lambda/chalice_lazy_listener_runner.md index 96644a442..3b3eddcd1 100644 --- a/docs/english/reference/adapter/aws_lambda/chalice_lazy_listener_runner.md +++ b/docs/english/reference/adapter/aws_lambda/chalice_lazy_listener_runner.md @@ -3,20 +3,4 @@ sidebar_label: chalice_lazy_listener_runner title: slack_bolt.adapter.aws_lambda.chalice_lazy_listener_runner --- -## ChaliceLazyListenerRunner Objects -```python -class ChaliceLazyListenerRunner(LazyListenerRunner) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger, lambda_client: Optional[BaseClient] = None) -``` - -#### start - -```python -def start(function: Callable[..., None], request: BoltRequest) -> None -``` diff --git a/docs/english/reference/adapter/aws_lambda/handler.md b/docs/english/reference/adapter/aws_lambda/handler.md index 5de6c9992..50cc1f82f 100644 --- a/docs/english/reference/adapter/aws_lambda/handler.md +++ b/docs/english/reference/adapter/aws_lambda/handler.md @@ -3,44 +3,4 @@ sidebar_label: handler title: slack_bolt.adapter.aws_lambda.handler --- -## SlackRequestHandler Objects -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### clear\_all\_log\_handlers - -```python -def clear_all_log_handlers() -``` - -#### handle - -```python -def handle(event, context) -``` - -#### to\_bolt\_request - -```python -def to_bolt_request(event) -> BoltRequest -``` - -#### to\_aws\_response - -```python -def to_aws_response(resp: BoltResponse) -> Dict[str, Any] -``` - -#### not\_found - -```python -def not_found() -> Dict[str, Any] -``` diff --git a/docs/english/reference/adapter/aws_lambda/index.md b/docs/english/reference/adapter/aws_lambda/index.md index 8666da643..75f559ccc 100644 --- a/docs/english/reference/adapter/aws_lambda/index.md +++ b/docs/english/reference/adapter/aws_lambda/index.md @@ -12,27 +12,3 @@ title: slack_bolt.adapter.aws_lambda - [slack_bolt.adapter.aws_lambda.lambda_s3_oauth_flow](/tools/bolt-python/reference/adapter/aws_lambda/lambda_s3_oauth_flow) - [slack_bolt.adapter.aws_lambda.lazy_listener_runner](/tools/bolt-python/reference/adapter/aws_lambda/lazy_listener_runner) - [slack_bolt.adapter.aws_lambda.local_lambda_client](/tools/bolt-python/reference/adapter/aws_lambda/local_lambda_client) - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### clear\_all\_log\_handlers - -```python -def clear_all_log_handlers() -``` - -#### handle - -```python -def handle(event, context) -``` diff --git a/docs/english/reference/adapter/aws_lambda/lambda_s3_oauth_flow.md b/docs/english/reference/adapter/aws_lambda/lambda_s3_oauth_flow.md index b050e5dea..2b5cde54f 100644 --- a/docs/english/reference/adapter/aws_lambda/lambda_s3_oauth_flow.md +++ b/docs/english/reference/adapter/aws_lambda/lambda_s3_oauth_flow.md @@ -3,34 +3,4 @@ sidebar_label: lambda_s3_oauth_flow title: slack_bolt.adapter.aws_lambda.lambda_s3_oauth_flow --- -## LambdaS3OAuthFlow Objects -```python -class LambdaS3OAuthFlow(OAuthFlow) -``` - -#### \_\_init\_\_ - -```python -def __init__( - *, - client: Optional[WebClient] = None, - logger: Optional[Logger] = None, - settings: Optional[OAuthSettings] = None, - oauth_state_bucket_name: Optional[str] = None, - installation_bucket_name: Optional[str] = None) -``` - -#### client - -```python -@property -def client() -> WebClient -``` - -#### logger - -```python -@property -def logger() -> Logger -``` diff --git a/docs/english/reference/adapter/aws_lambda/lazy_listener_runner.md b/docs/english/reference/adapter/aws_lambda/lazy_listener_runner.md index f4b38941a..903771242 100644 --- a/docs/english/reference/adapter/aws_lambda/lazy_listener_runner.md +++ b/docs/english/reference/adapter/aws_lambda/lazy_listener_runner.md @@ -3,20 +3,4 @@ sidebar_label: lazy_listener_runner title: slack_bolt.adapter.aws_lambda.lazy_listener_runner --- -## LambdaLazyListenerRunner Objects -```python -class LambdaLazyListenerRunner(LazyListenerRunner) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger, lambda_client: Optional[Any] = None) -``` - -#### start - -```python -def start(function: Callable[..., None], request: BoltRequest) -> None -``` diff --git a/docs/english/reference/adapter/aws_lambda/local_lambda_client.md b/docs/english/reference/adapter/aws_lambda/local_lambda_client.md index 95a381253..4f6d6132a 100644 --- a/docs/english/reference/adapter/aws_lambda/local_lambda_client.md +++ b/docs/english/reference/adapter/aws_lambda/local_lambda_client.md @@ -3,25 +3,12 @@ sidebar_label: local_lambda_client title: slack_bolt.adapter.aws_lambda.local_lambda_client --- -## LocalLambdaClient Objects +## `LocalLambdaClient` ```python -class LocalLambdaClient(BaseClient) +LocalLambdaClient(app, config) ``` -Lambda client implementing `invoke` for use when running with Chalice CLI. - -#### \_\_init\_\_ - -```python -def __init__(app: Chalice, config: Config) -> None -``` +Bases: BaseClient -#### invoke - -```python -def invoke( - FunctionName: str, - InvocationType: str = 'Event', - Payload: str = '{}') -> InvokeResponse -``` +Lambda client implementing `invoke` for use when running with Chalice CLI. diff --git a/docs/english/reference/adapter/bottle/handler.md b/docs/english/reference/adapter/bottle/handler.md index 727a643fc..7f5733eac 100644 --- a/docs/english/reference/adapter/bottle/handler.md +++ b/docs/english/reference/adapter/bottle/handler.md @@ -3,32 +3,4 @@ sidebar_label: handler title: slack_bolt.adapter.bottle.handler --- -#### to\_bolt\_request -```python -def to_bolt_request(req: Request) -> BoltRequest -``` - -#### set\_response - -```python -def set_response(bolt_resp: BoltResponse, resp: Response) -> None -``` - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(req: Request, resp: Response) -> str -``` diff --git a/docs/english/reference/adapter/bottle/index.md b/docs/english/reference/adapter/bottle/index.md index 703afa1c9..610eb1db8 100644 --- a/docs/english/reference/adapter/bottle/index.md +++ b/docs/english/reference/adapter/bottle/index.md @@ -6,21 +6,3 @@ title: slack_bolt.adapter.bottle ## Submodules - [slack_bolt.adapter.bottle.handler](/tools/bolt-python/reference/adapter/bottle/handler) - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(req: Request, resp: Response) -> str -``` diff --git a/docs/english/reference/adapter/cherrypy/handler.md b/docs/english/reference/adapter/cherrypy/handler.md index cd477de29..4aa84d521 100644 --- a/docs/english/reference/adapter/cherrypy/handler.md +++ b/docs/english/reference/adapter/cherrypy/handler.md @@ -3,38 +3,4 @@ sidebar_label: handler title: slack_bolt.adapter.cherrypy.handler --- -#### build\_bolt\_request -```python -def build_bolt_request() -> BoltRequest -``` - -#### set\_response\_status\_and\_headers - -```python -def set_response_status_and_headers(bolt_resp: BoltResponse) -> None -``` - -#### slack\_in - -```python -def slack_in() -``` - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle() -> bytes -``` diff --git a/docs/english/reference/adapter/cherrypy/index.md b/docs/english/reference/adapter/cherrypy/index.md index 036c74acc..9e3d5c9c3 100644 --- a/docs/english/reference/adapter/cherrypy/index.md +++ b/docs/english/reference/adapter/cherrypy/index.md @@ -6,21 +6,3 @@ title: slack_bolt.adapter.cherrypy ## Submodules - [slack_bolt.adapter.cherrypy.handler](/tools/bolt-python/reference/adapter/cherrypy/handler) - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle() -> bytes -``` diff --git a/docs/english/reference/adapter/django/handler.md b/docs/english/reference/adapter/django/handler.md index e488ad8c7..5c6b06f79 100644 --- a/docs/english/reference/adapter/django/handler.md +++ b/docs/english/reference/adapter/django/handler.md @@ -3,84 +3,20 @@ sidebar_label: handler title: slack_bolt.adapter.django.handler --- -#### to\_bolt\_request +## `DjangoListenerCompletionHandler` -```python -def to_bolt_request(req: HttpRequest) -> BoltRequest -``` - -#### to\_django\_response - -```python -def to_django_response(bolt_resp: BoltResponse) -> HttpResponse -``` - -#### release\_thread\_local\_connections - -```python -def release_thread_local_connections(logger: Logger, execution_timing: str) -``` - -## DjangoListenerStartHandler Objects - -```python -class DjangoListenerStartHandler(ListenerStartHandler) -``` +Bases: ListenerCompletionHandler Django sets DB connections as a thread-local variable per thread. If the thread is not managed on the Django app side, the connections won't be released by Django. This handler releases the connections every time a ThreadListenerRunner execution completes. -#### handle - -```python -def handle(request: BoltRequest, response: Optional[BoltResponse]) -> None -``` - -## DjangoListenerCompletionHandler Objects +## `DjangoListenerStartHandler` -```python -class DjangoListenerCompletionHandler(ListenerCompletionHandler) -``` +Bases: ListenerStartHandler Django sets DB connections as a thread-local variable per thread. If the thread is not managed on the Django app side, the connections won't be released by Django. This handler releases the connections every time a ThreadListenerRunner execution completes. - -#### handle - -```python -def handle(request: BoltRequest, response: Optional[BoltResponse]) -> None -``` - -## DjangoThreadLazyListenerRunner Objects - -```python -class DjangoThreadLazyListenerRunner(ThreadLazyListenerRunner) -``` - -#### start - -```python -def start(function: Callable[..., None], request: BoltRequest) -> None -``` - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(req: HttpRequest) -> HttpResponse -``` diff --git a/docs/english/reference/adapter/django/index.md b/docs/english/reference/adapter/django/index.md index 2d0178e77..7b909c770 100644 --- a/docs/english/reference/adapter/django/index.md +++ b/docs/english/reference/adapter/django/index.md @@ -6,21 +6,3 @@ title: slack_bolt.adapter.django ## Submodules - [slack_bolt.adapter.django.handler](/tools/bolt-python/reference/adapter/django/handler) - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(req: HttpRequest) -> HttpResponse -``` diff --git a/docs/english/reference/adapter/falcon/async_resource.md b/docs/english/reference/adapter/falcon/async_resource.md index 6173d1104..72ce8936b 100644 --- a/docs/english/reference/adapter/falcon/async_resource.md +++ b/docs/english/reference/adapter/falcon/async_resource.md @@ -3,10 +3,10 @@ sidebar_label: async_resource title: slack_bolt.adapter.falcon.async_resource --- -## AsyncSlackAppResource Objects +## `AsyncSlackAppResource` ```python -class AsyncSlackAppResource() +AsyncSlackAppResource(app) ``` For use with ASGI Falcon Apps. @@ -21,21 +21,3 @@ import falcon app = falcon.asgi.App() app.add_route("/slack/events", AsyncSlackAppResource(app)) ``` - -#### \_\_init\_\_ - -```python -def __init__(app: AsyncApp) -``` - -#### on\_get - -```python -async def on_get(req: Request, resp: Response) -``` - -#### on\_post - -```python -async def on_post(req: Request, resp: Response) -``` diff --git a/docs/english/reference/adapter/falcon/index.md b/docs/english/reference/adapter/falcon/index.md index b8ca47980..5dec1584b 100644 --- a/docs/english/reference/adapter/falcon/index.md +++ b/docs/english/reference/adapter/falcon/index.md @@ -3,15 +3,10 @@ sidebar_label: falcon title: slack_bolt.adapter.falcon --- -## Submodules - -- [slack_bolt.adapter.falcon.async_resource](/tools/bolt-python/reference/adapter/falcon/async_resource) -- [slack_bolt.adapter.falcon.resource](/tools/bolt-python/reference/adapter/falcon/resource) - -## SlackAppResource Objects +## `SlackAppResource` ```python -class SlackAppResource() +SlackAppResource(app) ``` For use with WSGI Falcon Apps. @@ -27,20 +22,7 @@ api = application = falcon.API() api.add_route("/slack/events", SlackAppResource(app)) ``` -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### on\_get - -```python -def on_get(req: Request, resp: Response) -``` - -#### on\_post +## Submodules -```python -def on_post(req: Request, resp: Response) -``` +- [slack_bolt.adapter.falcon.async_resource](/tools/bolt-python/reference/adapter/falcon/async_resource) +- [slack_bolt.adapter.falcon.resource](/tools/bolt-python/reference/adapter/falcon/resource) diff --git a/docs/english/reference/adapter/falcon/resource.md b/docs/english/reference/adapter/falcon/resource.md index 1cd39ea82..1547a3956 100644 --- a/docs/english/reference/adapter/falcon/resource.md +++ b/docs/english/reference/adapter/falcon/resource.md @@ -3,10 +3,10 @@ sidebar_label: resource title: slack_bolt.adapter.falcon.resource --- -## SlackAppResource Objects +## `SlackAppResource` ```python -class SlackAppResource() +SlackAppResource(app) ``` For use with WSGI Falcon Apps. @@ -21,21 +21,3 @@ import falcon api = application = falcon.API() api.add_route("/slack/events", SlackAppResource(app)) ``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### on\_get - -```python -def on_get(req: Request, resp: Response) -``` - -#### on\_post - -```python -def on_post(req: Request, resp: Response) -``` diff --git a/docs/english/reference/adapter/fastapi/async_handler.md b/docs/english/reference/adapter/fastapi/async_handler.md index 75497e71b..5ad5ec3c1 100644 --- a/docs/english/reference/adapter/fastapi/async_handler.md +++ b/docs/english/reference/adapter/fastapi/async_handler.md @@ -3,22 +3,4 @@ sidebar_label: async_handler title: slack_bolt.adapter.fastapi.async_handler --- -## AsyncSlackRequestHandler Objects -```python -class AsyncSlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: AsyncApp) -``` - -#### handle - -```python -async def handle( - req: Request, - addition_context_properties: Optional[Dict[str, Any]] = None) -> Response -``` diff --git a/docs/english/reference/adapter/fastapi/index.md b/docs/english/reference/adapter/fastapi/index.md index 469bc7bb7..3605502f0 100644 --- a/docs/english/reference/adapter/fastapi/index.md +++ b/docs/english/reference/adapter/fastapi/index.md @@ -6,23 +6,3 @@ title: slack_bolt.adapter.fastapi ## Submodules - [slack_bolt.adapter.fastapi.async_handler](/tools/bolt-python/reference/adapter/fastapi/async_handler) - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -async def handle( - req: Request, - addition_context_properties: Optional[Dict[str, Any]] = None) -> Response -``` diff --git a/docs/english/reference/adapter/flask/handler.md b/docs/english/reference/adapter/flask/handler.md index 3657debd0..a68e66007 100644 --- a/docs/english/reference/adapter/flask/handler.md +++ b/docs/english/reference/adapter/flask/handler.md @@ -3,32 +3,4 @@ sidebar_label: handler title: slack_bolt.adapter.flask.handler --- -#### to\_bolt\_request -```python -def to_bolt_request(req: Request) -> BoltRequest -``` - -#### to\_flask\_response - -```python -def to_flask_response(bolt_resp: BoltResponse) -> Response -``` - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(req: Request) -> Response -``` diff --git a/docs/english/reference/adapter/flask/index.md b/docs/english/reference/adapter/flask/index.md index 80807da8a..d5db40abf 100644 --- a/docs/english/reference/adapter/flask/index.md +++ b/docs/english/reference/adapter/flask/index.md @@ -6,21 +6,3 @@ title: slack_bolt.adapter.flask ## Submodules - [slack_bolt.adapter.flask.handler](/tools/bolt-python/reference/adapter/flask/handler) - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(req: Request) -> Response -``` diff --git a/docs/english/reference/adapter/google_cloud_functions/handler.md b/docs/english/reference/adapter/google_cloud_functions/handler.md index 0d8807ba8..45ed53de4 100644 --- a/docs/english/reference/adapter/google_cloud_functions/handler.md +++ b/docs/english/reference/adapter/google_cloud_functions/handler.md @@ -3,32 +3,4 @@ sidebar_label: handler title: slack_bolt.adapter.google_cloud_functions.handler --- -## NoopLazyListenerRunner Objects -```python -class NoopLazyListenerRunner(LazyListenerRunner) -``` - -#### start - -```python -def start(function: Callable[..., None], request: BoltRequest) -> None -``` - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(req: Request) -> Response -``` diff --git a/docs/english/reference/adapter/google_cloud_functions/index.md b/docs/english/reference/adapter/google_cloud_functions/index.md index 56129e6dd..b4a15832a 100644 --- a/docs/english/reference/adapter/google_cloud_functions/index.md +++ b/docs/english/reference/adapter/google_cloud_functions/index.md @@ -6,21 +6,3 @@ title: slack_bolt.adapter.google_cloud_functions ## Submodules - [slack_bolt.adapter.google_cloud_functions.handler](/tools/bolt-python/reference/adapter/google_cloud_functions/handler) - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(req: Request) -> Response -``` diff --git a/docs/english/reference/adapter/pyramid/handler.md b/docs/english/reference/adapter/pyramid/handler.md index 614d2c19b..2c6178b1c 100644 --- a/docs/english/reference/adapter/pyramid/handler.md +++ b/docs/english/reference/adapter/pyramid/handler.md @@ -3,32 +3,4 @@ sidebar_label: handler title: slack_bolt.adapter.pyramid.handler --- -#### to\_bolt\_request -```python -def to_bolt_request(request: Request) -> BoltRequest -``` - -#### to\_pyramid\_response - -```python -def to_pyramid_response(bolt_resp: BoltResponse) -> Response -``` - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(request: Request) -> Response -``` diff --git a/docs/english/reference/adapter/pyramid/index.md b/docs/english/reference/adapter/pyramid/index.md index 013feb456..128204306 100644 --- a/docs/english/reference/adapter/pyramid/index.md +++ b/docs/english/reference/adapter/pyramid/index.md @@ -6,21 +6,3 @@ title: slack_bolt.adapter.pyramid ## Submodules - [slack_bolt.adapter.pyramid.handler](/tools/bolt-python/reference/adapter/pyramid/handler) - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -def handle(request: Request) -> Response -``` diff --git a/docs/english/reference/adapter/sanic/async_handler.md b/docs/english/reference/adapter/sanic/async_handler.md index f24dd05ee..d6494555c 100644 --- a/docs/english/reference/adapter/sanic/async_handler.md +++ b/docs/english/reference/adapter/sanic/async_handler.md @@ -3,36 +3,4 @@ sidebar_label: async_handler title: slack_bolt.adapter.sanic.async_handler --- -#### to\_async\_bolt\_request -```python -def to_async_bolt_request( - req: Request, - addition_context_properties: Optional[Dict[str, Any]] = None) -> AsyncBoltRequest -``` - -#### to\_sanic\_response - -```python -def to_sanic_response(bolt_resp: BoltResponse) -> HTTPResponse -``` - -## AsyncSlackRequestHandler Objects - -```python -class AsyncSlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: AsyncApp) -``` - -#### handle - -```python -async def handle( - req: Request, - addition_context_properties: Optional[Dict[str, Any]] = None) -> HTTPResponse -``` diff --git a/docs/english/reference/adapter/sanic/index.md b/docs/english/reference/adapter/sanic/index.md index fccec02f8..d8a7a47a4 100644 --- a/docs/english/reference/adapter/sanic/index.md +++ b/docs/english/reference/adapter/sanic/index.md @@ -6,23 +6,3 @@ title: slack_bolt.adapter.sanic ## Submodules - [slack_bolt.adapter.sanic.async_handler](/tools/bolt-python/reference/adapter/sanic/async_handler) - -## AsyncSlackRequestHandler Objects - -```python -class AsyncSlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: AsyncApp) -``` - -#### handle - -```python -async def handle( - req: Request, - addition_context_properties: Optional[Dict[str, Any]] = None) -> HTTPResponse -``` diff --git a/docs/english/reference/adapter/socket_mode/aiohttp/index.md b/docs/english/reference/adapter/socket_mode/aiohttp/index.md index f83c116a5..976ed4c23 100644 --- a/docs/english/reference/adapter/socket_mode/aiohttp/index.md +++ b/docs/english/reference/adapter/socket_mode/aiohttp/index.md @@ -5,74 +5,55 @@ title: slack_bolt.adapter.socket_mode.aiohttp [`aiohttp`](https://pypi.org/project/aiohttp/) based implementation / asyncio compatible. -## SocketModeHandler Objects +## `SocketModeHandler` ```python -class SocketModeHandler(AsyncBaseSocketModeHandler) +SocketModeHandler(app, app_token=None, logger=None, web_client=None, proxy=None, ping_interval=10) ``` -#### app: `App` +Bases: AsyncBaseSocketModeHandler -#### app\_token: `str` +Socket Mode adapter for Bolt apps. + +**Parameters:** -#### client: `SocketModeClient` +- **app** (App) – The Bolt app +- **app_token** (Optional[str]) – App-level token starting with `xapp-` +- **logger** (Optional[Logger]) – Custom logger +- **web_client** (Optional[AsyncWebClient]) – custom `slack_sdk.web.WebClient` instance +- **proxy** (Optional[str]) – HTTP proxy URL +- **ping_interval** (float) – The ping-pong internal (seconds) -#### \_\_init\_\_ +### `close_async` ```python -def __init__( - app: App, - app_token: Optional[str] = None, - logger: Optional[Logger] = None, - web_client: Optional[AsyncWebClient] = None, - proxy: Optional[str] = None, - ping_interval: float = 10) +close_async() ``` -Socket Mode adapter for Bolt apps. - -**Arguments**: - -- `app` _App_ - The Bolt app -- `app_token` _Optional[str]_ - App-level token starting with `xapp-` -- `logger` _Optional[Logger]_ - Custom logger -- `web_client` _Optional[AsyncWebClient]_ - custom `slack_sdk.web.WebClient` instance -- `proxy` _Optional[str]_ - HTTP proxy URL -- `ping_interval` _float_ - The ping-pong internal (seconds) +Disconnects from the Socket Mode server and cleans the resources this instance holds up. -#### handle +### `connect_async` ```python -async def handle(client: SocketModeClient, req: SocketModeRequest) -> None +connect_async() ``` -## AsyncSocketModeHandler Objects +Establishes a new connection with the Socket Mode server. + +### `disconnect_async` ```python -class AsyncSocketModeHandler(AsyncBaseSocketModeHandler) +disconnect_async() ``` -#### app: `AsyncApp` - -#### app\_token: `str` - -#### client: `SocketModeClient` +Disconnects the current WebSocket connection with the Socket Mode server. -#### \_\_init\_\_ +### `start_async` ```python -def __init__( - app: AsyncApp, - app_token: Optional[str] = None, - logger: Optional[Logger] = None, - web_client: Optional[AsyncWebClient] = None, - proxy: Optional[str] = None, - ping_interval: float = 10, - loop: Optional[AbstractEventLoop] = None) +start_async() ``` -#### handle +Establishes a new connection and then starts infinite sleep to prevent the termination of this process. -```python -async def handle(client: SocketModeClient, req: SocketModeRequest) -> None -``` +If you don't want to have the sleep, use `#connect()` method instead. diff --git a/docs/english/reference/adapter/socket_mode/async_base_handler.md b/docs/english/reference/adapter/socket_mode/async_base_handler.md index 9161b832d..8e0f030cd 100644 --- a/docs/english/reference/adapter/socket_mode/async_base_handler.md +++ b/docs/english/reference/adapter/socket_mode/async_base_handler.md @@ -5,57 +5,49 @@ title: slack_bolt.adapter.socket_mode.async_base_handler The base class of asyncio-based Socket Mode client implementation. -## AsyncBaseSocketModeHandler Objects +## `AsyncBaseSocketModeHandler` -```python -class AsyncBaseSocketModeHandler() -``` - -#### app: `Union[App, AsyncApp]` - -#### client: `AsyncBaseSocketModeClient` - -#### handle +### `close_async` ```python -async def handle(client: AsyncBaseSocketModeClient, req: SocketModeRequest) -> None +close_async() ``` -Handles Socket Mode envelope requests through a WebSocket connection. - -**Arguments**: - -- `client` _AsyncBaseSocketModeClient_ - this Socket Mode client instance -- `req` _SocketModeRequest_ - the request data +Disconnects from the Socket Mode server and cleans the resources this instance holds up. -#### connect\_async +### `connect_async` ```python -async def connect_async() +connect_async() ``` Establishes a new connection with the Socket Mode server. -#### disconnect\_async +### `disconnect_async` ```python -async def disconnect_async() +disconnect_async() ``` Disconnects the current WebSocket connection with the Socket Mode server. -#### close\_async +### `handle` ```python -async def close_async() +handle(client, req) ``` -Disconnects from the Socket Mode server and cleans the resources this instance holds up. +Handles Socket Mode envelope requests through a WebSocket connection. + +**Parameters:** + +- **client** (AsyncBaseSocketModeClient) – this Socket Mode client instance +- **req** (SocketModeRequest) – the request data -#### start\_async +### `start_async` ```python -async def start_async() +start_async() ``` Establishes a new connection and then starts infinite sleep to prevent the termination of this process. diff --git a/docs/english/reference/adapter/socket_mode/async_handler.md b/docs/english/reference/adapter/socket_mode/async_handler.md index 6f4503a26..57e0bc5bc 100644 --- a/docs/english/reference/adapter/socket_mode/async_handler.md +++ b/docs/english/reference/adapter/socket_mode/async_handler.md @@ -4,34 +4,3 @@ title: slack_bolt.adapter.socket_mode.async_handler --- Default implementation is the aiohttp-based one. - -## AsyncSocketModeHandler Objects - -```python -class AsyncSocketModeHandler(AsyncBaseSocketModeHandler) -``` - -#### app: `AsyncApp` - -#### app\_token: `str` - -#### client: `SocketModeClient` - -#### \_\_init\_\_ - -```python -def __init__( - app: AsyncApp, - app_token: Optional[str] = None, - logger: Optional[Logger] = None, - web_client: Optional[AsyncWebClient] = None, - proxy: Optional[str] = None, - ping_interval: float = 10, - loop: Optional[AbstractEventLoop] = None) -``` - -#### handle - -```python -async def handle(client: SocketModeClient, req: SocketModeRequest) -> None -``` diff --git a/docs/english/reference/adapter/socket_mode/async_internals.md b/docs/english/reference/adapter/socket_mode/async_internals.md index 532c00289..6f3a12ce8 100644 --- a/docs/english/reference/adapter/socket_mode/async_internals.md +++ b/docs/english/reference/adapter/socket_mode/async_internals.md @@ -4,19 +4,3 @@ title: slack_bolt.adapter.socket_mode.async_internals --- Internal functions. - -#### run\_async\_bolt\_app - -```python -async def run_async_bolt_app(app: AsyncApp, req: SocketModeRequest) -``` - -#### send\_async\_response - -```python -async def send_async_response( - client: AsyncBaseSocketModeClient, - req: SocketModeRequest, - bolt_resp: BoltResponse, - start_time: float) -``` diff --git a/docs/english/reference/adapter/socket_mode/base_handler.md b/docs/english/reference/adapter/socket_mode/base_handler.md index f2f6455ec..feff09550 100644 --- a/docs/english/reference/adapter/socket_mode/base_handler.md +++ b/docs/english/reference/adapter/socket_mode/base_handler.md @@ -7,57 +7,49 @@ The base class of Socket Mode client implementation. If you want to build asyncio-based ones, use `AsyncBaseSocketModeHandler` instead. -## BaseSocketModeHandler Objects +## `BaseSocketModeHandler` -```python -class BaseSocketModeHandler() -``` - -#### app: `App` - -#### client: `BaseSocketModeClient` - -#### handle +### `close` ```python -def handle(client: BaseSocketModeClient, req: SocketModeRequest) -> None +close() ``` -Handles Socket Mode envelope requests through a WebSocket connection. - -**Arguments**: - -- `client` _BaseSocketModeClient_ - this Socket Mode client instance -- `req` _SocketModeRequest_ - the request data +Disconnects from the Socket Mode server and cleans the resources this instance holds up. -#### connect +### `connect` ```python -def connect() +connect() ``` Establishes a new connection with the Socket Mode server. -#### disconnect +### `disconnect` ```python -def disconnect() +disconnect() ``` Disconnects the current WebSocket connection with the Socket Mode server. -#### close +### `handle` ```python -def close() +handle(client, req) ``` -Disconnects from the Socket Mode server and cleans the resources this instance holds up. +Handles Socket Mode envelope requests through a WebSocket connection. + +**Parameters:** + +- **client** (BaseSocketModeClient) – this Socket Mode client instance +- **req** (SocketModeRequest) – the request data -#### start +### `start` ```python -def start() +start() ``` Establishes a new connection and then blocks the current thread to prevent the termination of this process. diff --git a/docs/english/reference/adapter/socket_mode/builtin/index.md b/docs/english/reference/adapter/socket_mode/builtin/index.md index 7583f5591..c7eca72f4 100644 --- a/docs/english/reference/adapter/socket_mode/builtin/index.md +++ b/docs/english/reference/adapter/socket_mode/builtin/index.md @@ -5,57 +5,62 @@ title: slack_bolt.adapter.socket_mode.builtin The built-in implementation, which does not have any external dependencies. -## SocketModeHandler Objects +## `SocketModeHandler` ```python -class SocketModeHandler(BaseSocketModeHandler) +SocketModeHandler(app, app_token=None, logger=None, web_client=None, proxy=None, proxy_headers=None, auto_reconnect_enabled=True, trace_enabled=False, all_message_trace_enabled=False, ping_pong_trace_enabled=False, ping_interval=10, receive_buffer_size=1024, concurrency=10) ``` -#### app: `App` +Bases: BaseSocketModeHandler -#### app\_token: `str` +Socket Mode adapter for Bolt apps. + +**Parameters:** -#### client: `SocketModeClient` +- **app** (App) – The Bolt app +- **app_token** (Optional[str]) – App-level token starting with `xapp-` +- **logger** (Optional[Logger]) – Custom logger +- **web_client** (Optional[WebClient]) – custom `slack_sdk.web.WebClient` instance +- **proxy** (Optional[str]) – HTTP proxy URL +- **proxy_headers** (Optional[Dict[str, str]]) – Additional request header for proxy connections +- **auto_reconnect_enabled** (bool) – True if the auto-reconnect logic works +- **trace_enabled** (bool) – True if trace-level logging is enabled +- **all_message_trace_enabled** (bool) – True if trace-logging for all received WebSocket messages is enabled +- **ping_pong_trace_enabled** (bool) – True if trace-logging for all ping-pong communications +- **ping_interval** (float) – The ping-pong internal (seconds) +- **receive_buffer_size** (int) – The data length for a single socket recv operation +- **concurrency** (int) – The size of the underlying thread pool -#### \_\_init\_\_ +### `close` ```python -def __init__( - app: App, - app_token: Optional[str] = None, - logger: Optional[Logger] = None, - web_client: Optional[WebClient] = None, - proxy: Optional[str] = None, - proxy_headers: Optional[Dict[str, str]] = None, - auto_reconnect_enabled: bool = True, - trace_enabled: bool = False, - all_message_trace_enabled: bool = False, - ping_pong_trace_enabled: bool = False, - ping_interval: float = 10, - receive_buffer_size: int = 1024, - concurrency: int = 10) +close() ``` -Socket Mode adapter for Bolt apps. +Disconnects from the Socket Mode server and cleans the resources this instance holds up. -**Arguments**: +### `connect` -- `app` _App_ - The Bolt app -- `app_token` _Optional[str]_ - App-level token starting with `xapp-` -- `logger` _Optional[Logger]_ - Custom logger -- `web_client` _Optional[WebClient]_ - custom `slack_sdk.web.WebClient` instance -- `proxy` _Optional[str]_ - HTTP proxy URL -- `proxy_headers` _Optional[Dict[str, str]]_ - Additional request header for proxy connections -- `auto_reconnect_enabled` _bool_ - True if the auto-reconnect logic works -- `trace_enabled` _bool_ - True if trace-level logging is enabled -- `all_message_trace_enabled` _bool_ - True if trace-logging for all received WebSocket messages is enabled -- `ping_pong_trace_enabled` _bool_ - True if trace-logging for all ping-pong communications -- `ping_interval` _float_ - The ping-pong internal (seconds) -- `receive_buffer_size` _int_ - The data length for a single socket recv operation -- `concurrency` _int_ - The size of the underlying thread pool +```python +connect() +``` + +Establishes a new connection with the Socket Mode server. -#### handle +### `disconnect` ```python -def handle(client: SocketModeClient, req: SocketModeRequest) -> None +disconnect() ``` + +Disconnects the current WebSocket connection with the Socket Mode server. + +### `start` + +```python +start() +``` + +Establishes a new connection and then blocks the current thread to prevent the termination of this process. + +If you don't want to block the current thread, use `#connect()` method instead. diff --git a/docs/english/reference/adapter/socket_mode/index.md b/docs/english/reference/adapter/socket_mode/index.md index 34d36381f..af475ec10 100644 --- a/docs/english/reference/adapter/socket_mode/index.md +++ b/docs/english/reference/adapter/socket_mode/index.md @@ -10,69 +10,74 @@ Socket Mode adapter package provides the following implementations. If you don't * `slack_bolt.adapter.socket_mode.aiohttp` * `slack_bolt.adapter.socket_mode.websockets` -## Submodules - -- [slack_bolt.adapter.socket_mode.aiohttp](/tools/bolt-python/reference/adapter/socket_mode/aiohttp) -- [slack_bolt.adapter.socket_mode.async_base_handler](/tools/bolt-python/reference/adapter/socket_mode/async_base_handler) -- [slack_bolt.adapter.socket_mode.async_handler](/tools/bolt-python/reference/adapter/socket_mode/async_handler) -- [slack_bolt.adapter.socket_mode.async_internals](/tools/bolt-python/reference/adapter/socket_mode/async_internals) -- [slack_bolt.adapter.socket_mode.base_handler](/tools/bolt-python/reference/adapter/socket_mode/base_handler) -- [slack_bolt.adapter.socket_mode.builtin](/tools/bolt-python/reference/adapter/socket_mode/builtin) -- [slack_bolt.adapter.socket_mode.internals](/tools/bolt-python/reference/adapter/socket_mode/internals) -- [slack_bolt.adapter.socket_mode.websocket_client](/tools/bolt-python/reference/adapter/socket_mode/websocket_client) -- [slack_bolt.adapter.socket_mode.websockets](/tools/bolt-python/reference/adapter/socket_mode/websockets) - -## SocketModeHandler Objects +## `SocketModeHandler` ```python -class SocketModeHandler(BaseSocketModeHandler) +SocketModeHandler(app, app_token=None, logger=None, web_client=None, proxy=None, proxy_headers=None, auto_reconnect_enabled=True, trace_enabled=False, all_message_trace_enabled=False, ping_pong_trace_enabled=False, ping_interval=10, receive_buffer_size=1024, concurrency=10) ``` -#### app: `App` +Bases: BaseSocketModeHandler -#### app\_token: `str` +Socket Mode adapter for Bolt apps. -#### client: `SocketModeClient` +**Parameters:** -#### \_\_init\_\_ +- **app** (App) – The Bolt app +- **app_token** (Optional[str]) – App-level token starting with `xapp-` +- **logger** (Optional[Logger]) – Custom logger +- **web_client** (Optional[WebClient]) – custom `slack_sdk.web.WebClient` instance +- **proxy** (Optional[str]) – HTTP proxy URL +- **proxy_headers** (Optional[Dict[str, str]]) – Additional request header for proxy connections +- **auto_reconnect_enabled** (bool) – True if the auto-reconnect logic works +- **trace_enabled** (bool) – True if trace-level logging is enabled +- **all_message_trace_enabled** (bool) – True if trace-logging for all received WebSocket messages is enabled +- **ping_pong_trace_enabled** (bool) – True if trace-logging for all ping-pong communications +- **ping_interval** (float) – The ping-pong internal (seconds) +- **receive_buffer_size** (int) – The data length for a single socket recv operation +- **concurrency** (int) – The size of the underlying thread pool + +### `close` ```python -def __init__( - app: App, - app_token: Optional[str] = None, - logger: Optional[Logger] = None, - web_client: Optional[WebClient] = None, - proxy: Optional[str] = None, - proxy_headers: Optional[Dict[str, str]] = None, - auto_reconnect_enabled: bool = True, - trace_enabled: bool = False, - all_message_trace_enabled: bool = False, - ping_pong_trace_enabled: bool = False, - ping_interval: float = 10, - receive_buffer_size: int = 1024, - concurrency: int = 10) +close() ``` -Socket Mode adapter for Bolt apps. +Disconnects from the Socket Mode server and cleans the resources this instance holds up. -**Arguments**: +### `connect` -- `app` _App_ - The Bolt app -- `app_token` _Optional[str]_ - App-level token starting with `xapp-` -- `logger` _Optional[Logger]_ - Custom logger -- `web_client` _Optional[WebClient]_ - custom `slack_sdk.web.WebClient` instance -- `proxy` _Optional[str]_ - HTTP proxy URL -- `proxy_headers` _Optional[Dict[str, str]]_ - Additional request header for proxy connections -- `auto_reconnect_enabled` _bool_ - True if the auto-reconnect logic works -- `trace_enabled` _bool_ - True if trace-level logging is enabled -- `all_message_trace_enabled` _bool_ - True if trace-logging for all received WebSocket messages is enabled -- `ping_pong_trace_enabled` _bool_ - True if trace-logging for all ping-pong communications -- `ping_interval` _float_ - The ping-pong internal (seconds) -- `receive_buffer_size` _int_ - The data length for a single socket recv operation -- `concurrency` _int_ - The size of the underlying thread pool +```python +connect() +``` -#### handle +Establishes a new connection with the Socket Mode server. + +### `disconnect` ```python -def handle(client: SocketModeClient, req: SocketModeRequest) -> None +disconnect() ``` + +Disconnects the current WebSocket connection with the Socket Mode server. + +### `start` + +```python +start() +``` + +Establishes a new connection and then blocks the current thread to prevent the termination of this process. + +If you don't want to block the current thread, use `#connect()` method instead. + +## Submodules + +- [slack_bolt.adapter.socket_mode.aiohttp](/tools/bolt-python/reference/adapter/socket_mode/aiohttp) +- [slack_bolt.adapter.socket_mode.async_base_handler](/tools/bolt-python/reference/adapter/socket_mode/async_base_handler) +- [slack_bolt.adapter.socket_mode.async_handler](/tools/bolt-python/reference/adapter/socket_mode/async_handler) +- [slack_bolt.adapter.socket_mode.async_internals](/tools/bolt-python/reference/adapter/socket_mode/async_internals) +- [slack_bolt.adapter.socket_mode.base_handler](/tools/bolt-python/reference/adapter/socket_mode/base_handler) +- [slack_bolt.adapter.socket_mode.builtin](/tools/bolt-python/reference/adapter/socket_mode/builtin) +- [slack_bolt.adapter.socket_mode.internals](/tools/bolt-python/reference/adapter/socket_mode/internals) +- [slack_bolt.adapter.socket_mode.websocket_client](/tools/bolt-python/reference/adapter/socket_mode/websocket_client) +- [slack_bolt.adapter.socket_mode.websockets](/tools/bolt-python/reference/adapter/socket_mode/websockets) diff --git a/docs/english/reference/adapter/socket_mode/internals.md b/docs/english/reference/adapter/socket_mode/internals.md index 13811922c..063c7ddd9 100644 --- a/docs/english/reference/adapter/socket_mode/internals.md +++ b/docs/english/reference/adapter/socket_mode/internals.md @@ -4,26 +4,3 @@ title: slack_bolt.adapter.socket_mode.internals --- Internal functions. - -#### build\_headers - -```python -def build_headers( - req: SocketModeRequest) -> Optional[Dict[str, Union[str, Sequence[str]]]] -``` - -#### run\_bolt\_app - -```python -def run_bolt_app(app: App, req: SocketModeRequest) -``` - -#### send\_response - -```python -def send_response( - client: BaseSocketModeClient, - req: SocketModeRequest, - bolt_resp: BoltResponse, - start_time: float) -``` diff --git a/docs/english/reference/adapter/socket_mode/websocket_client/index.md b/docs/english/reference/adapter/socket_mode/websocket_client/index.md index f56183beb..bb0de3f32 100644 --- a/docs/english/reference/adapter/socket_mode/websocket_client/index.md +++ b/docs/english/reference/adapter/socket_mode/websocket_client/index.md @@ -5,53 +5,60 @@ title: slack_bolt.adapter.socket_mode.websocket_client [`websocket-client`](https://pypi.org/project/websocket-client/) based implementation. -## SocketModeHandler Objects +## `SocketModeHandler` ```python -class SocketModeHandler(BaseSocketModeHandler) +SocketModeHandler(app, app_token=None, logger=None, web_client=None, ping_interval=10, concurrency=10, http_proxy_host=None, http_proxy_port=None, http_proxy_auth=None, proxy_type=None, trace_enabled=False) ``` -#### app: `App` +Bases: BaseSocketModeHandler -#### app\_token: `str` +Socket Mode adapter for Bolt apps. + +**Parameters:** -#### client: `SocketModeClient` +- **app** (App) – The Bolt app +- **app_token** (Optional[str]) – App-level token starting with `xapp-` +- **logger** (Optional[Logger]) – Custom logger +- **web_client** (Optional[WebClient]) – custom `slack_sdk.web.WebClient` instance +- **ping_interval** (float) – The ping-pong internal (seconds) +- **concurrency** (int) – The size of the underlying thread pool +- **http_proxy_host** (Optional[str]) – HTTP proxy host +- **http_proxy_port** (Optional[int]) – HTTP proxy port +- **http_proxy_auth** (Optional[Tuple[str, str]]) – HTTP proxy authentication (username, password) +- **proxy_type** (Optional[str]) – Proxy type +- **trace_enabled** (bool) – True if trace-level logging is enabled -#### \_\_init\_\_ +### `close` ```python -def __init__( - app: App, - app_token: Optional[str] = None, - logger: Optional[Logger] = None, - web_client: Optional[WebClient] = None, - ping_interval: float = 10, - concurrency: int = 10, - http_proxy_host: Optional[str] = None, - http_proxy_port: Optional[int] = None, - http_proxy_auth: Optional[Tuple[str, str]] = None, - proxy_type: Optional[str] = None, - trace_enabled: bool = False) +close() ``` -Socket Mode adapter for Bolt apps. +Disconnects from the Socket Mode server and cleans the resources this instance holds up. -**Arguments**: +### `connect` -- `app` _App_ - The Bolt app -- `app_token` _Optional[str]_ - App-level token starting with `xapp-` -- `logger` _Optional[Logger]_ - Custom logger -- `web_client` _Optional[WebClient]_ - custom `slack_sdk.web.WebClient` instance -- `ping_interval` _float_ - The ping-pong internal (seconds) -- `concurrency` _int_ - The size of the underlying thread pool -- `http_proxy_host` _Optional[str]_ - HTTP proxy host -- `http_proxy_port` _Optional[int]_ - HTTP proxy port -- `http_proxy_auth` _Optional[Tuple[str, str]]_ - HTTP proxy authentication (username, password) -- `proxy_type` _Optional[str]_ - Proxy type -- `trace_enabled` _bool_ - True if trace-level logging is enabled +```python +connect() +``` + +Establishes a new connection with the Socket Mode server. -#### handle +### `disconnect` ```python -def handle(client: SocketModeClient, req: SocketModeRequest) -> None +disconnect() ``` + +Disconnects the current WebSocket connection with the Socket Mode server. + +### `start` + +```python +start() +``` + +Establishes a new connection and then blocks the current thread to prevent the termination of this process. + +If you don't want to block the current thread, use `#connect()` method instead. diff --git a/docs/english/reference/adapter/socket_mode/websockets/index.md b/docs/english/reference/adapter/socket_mode/websockets/index.md index aed36c234..2ba520fd9 100644 --- a/docs/english/reference/adapter/socket_mode/websockets/index.md +++ b/docs/english/reference/adapter/socket_mode/websockets/index.md @@ -5,28 +5,13 @@ title: slack_bolt.adapter.socket_mode.websockets [`websockets`](https://pypi.org/project/websockets/) based implementation / asyncio compatible. -## SocketModeHandler Objects +## `SocketModeHandler` ```python -class SocketModeHandler(AsyncBaseSocketModeHandler) +SocketModeHandler(app, app_token=None, logger=None, web_client=None, ping_interval=10) ``` -#### app: `App` - -#### app\_token: `str` - -#### client: `SocketModeClient` - -#### \_\_init\_\_ - -```python -def __init__( - app: App, - app_token: Optional[str] = None, - logger: Optional[Logger] = None, - web_client: Optional[AsyncWebClient] = None, - ping_interval: float = 10) -``` +Bases: AsyncBaseSocketModeHandler Socket Mode adapter for Bolt apps. @@ -34,45 +19,44 @@ Please note that this adapter does not support proxy configuration as the underlying websockets module does not support proxy-wired connections. If you use proxy, consider using one of the other Socket Mode adapters. -**Arguments**: +**Parameters:** -- `app` _App_ - The Bolt app -- `app_token` _Optional[str]_ - App-level token starting with `xapp-` -- `logger` _Optional[Logger]_ - Custom logger -- `web_client` _Optional[AsyncWebClient]_ - custom `slack_sdk.web.WebClient` instance -- `ping_interval` _float_ - The ping-pong internal (seconds) +- **app** (App) – The Bolt app +- **app_token** (Optional[str]) – App-level token starting with `xapp-` +- **logger** (Optional[Logger]) – Custom logger +- **web_client** (Optional[AsyncWebClient]) – custom `slack_sdk.web.WebClient` instance +- **ping_interval** (float) – The ping-pong internal (seconds) -#### handle +### `close_async` ```python -async def handle(client: SocketModeClient, req: SocketModeRequest) -> None +close_async() ``` -## AsyncSocketModeHandler Objects +Disconnects from the Socket Mode server and cleans the resources this instance holds up. + +### `connect_async` ```python -class AsyncSocketModeHandler(AsyncBaseSocketModeHandler) +connect_async() ``` -#### app: `AsyncApp` - -#### app\_token: `str` - -#### client: `SocketModeClient` +Establishes a new connection with the Socket Mode server. -#### \_\_init\_\_ +### `disconnect_async` ```python -def __init__( - app: AsyncApp, - app_token: Optional[str] = None, - logger: Optional[Logger] = None, - web_client: Optional[AsyncWebClient] = None, - ping_interval: float = 10) +disconnect_async() ``` -#### handle +Disconnects the current WebSocket connection with the Socket Mode server. + +### `start_async` ```python -async def handle(client: SocketModeClient, req: SocketModeRequest) -> None +start_async() ``` + +Establishes a new connection and then starts infinite sleep to prevent the termination of this process. + +If you don't want to have the sleep, use `#connect()` method instead. diff --git a/docs/english/reference/adapter/starlette/async_handler.md b/docs/english/reference/adapter/starlette/async_handler.md index 2ac2f00b3..0e5040183 100644 --- a/docs/english/reference/adapter/starlette/async_handler.md +++ b/docs/english/reference/adapter/starlette/async_handler.md @@ -3,37 +3,4 @@ sidebar_label: async_handler title: slack_bolt.adapter.starlette.async_handler --- -#### to\_async\_bolt\_request -```python -def to_async_bolt_request( - req: Request, - body: bytes, - addition_context_properties: Optional[Dict[str, Any]] = None) -> AsyncBoltRequest -``` - -#### to\_starlette\_response - -```python -def to_starlette_response(bolt_resp: BoltResponse) -> Response -``` - -## AsyncSlackRequestHandler Objects - -```python -class AsyncSlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: AsyncApp) -``` - -#### handle - -```python -async def handle( - req: Request, - addition_context_properties: Optional[Dict[str, Any]] = None) -> Response -``` diff --git a/docs/english/reference/adapter/starlette/handler.md b/docs/english/reference/adapter/starlette/handler.md index 206ccad91..8a824ba07 100644 --- a/docs/english/reference/adapter/starlette/handler.md +++ b/docs/english/reference/adapter/starlette/handler.md @@ -3,37 +3,4 @@ sidebar_label: handler title: slack_bolt.adapter.starlette.handler --- -#### to\_bolt\_request -```python -def to_bolt_request( - req: Request, - body: bytes, - addition_context_properties: Optional[Dict[str, Any]] = None) -> BoltRequest -``` - -#### to\_starlette\_response - -```python -def to_starlette_response(bolt_resp: BoltResponse) -> Response -``` - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -async def handle( - req: Request, - addition_context_properties: Optional[Dict[str, Any]] = None) -> Response -``` diff --git a/docs/english/reference/adapter/starlette/index.md b/docs/english/reference/adapter/starlette/index.md index fd29b9306..ebb125da9 100644 --- a/docs/english/reference/adapter/starlette/index.md +++ b/docs/english/reference/adapter/starlette/index.md @@ -7,23 +7,3 @@ title: slack_bolt.adapter.starlette - [slack_bolt.adapter.starlette.async_handler](/tools/bolt-python/reference/adapter/starlette/async_handler) - [slack_bolt.adapter.starlette.handler](/tools/bolt-python/reference/adapter/starlette/handler) - -## SlackRequestHandler Objects - -```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App) -``` - -#### handle - -```python -async def handle( - req: Request, - addition_context_properties: Optional[Dict[str, Any]] = None) -> Response -``` diff --git a/docs/english/reference/adapter/tornado/async_handler.md b/docs/english/reference/adapter/tornado/async_handler.md index cc9f21ff8..d3bd39ec3 100644 --- a/docs/english/reference/adapter/tornado/async_handler.md +++ b/docs/english/reference/adapter/tornado/async_handler.md @@ -3,44 +3,4 @@ sidebar_label: async_handler title: slack_bolt.adapter.tornado.async_handler --- -## AsyncSlackEventsHandler Objects -```python -class AsyncSlackEventsHandler(RequestHandler) -``` - -#### initialize - -```python -def initialize(app: AsyncApp) -``` - -#### post - -```python -async def post() -``` - -## AsyncSlackOAuthHandler Objects - -```python -class AsyncSlackOAuthHandler(RequestHandler) -``` - -#### initialize - -```python -def initialize(app: AsyncApp) -``` - -#### get - -```python -async def get() -``` - -#### to\_async\_bolt\_request - -```python -def to_async_bolt_request(req: HTTPServerRequest) -> AsyncBoltRequest -``` diff --git a/docs/english/reference/adapter/tornado/handler.md b/docs/english/reference/adapter/tornado/handler.md index a549c990c..66a9e25b5 100644 --- a/docs/english/reference/adapter/tornado/handler.md +++ b/docs/english/reference/adapter/tornado/handler.md @@ -3,50 +3,4 @@ sidebar_label: handler title: slack_bolt.adapter.tornado.handler --- -## SlackEventsHandler Objects -```python -class SlackEventsHandler(RequestHandler) -``` - -#### initialize - -```python -def initialize(app: App) -``` - -#### post - -```python -def post() -``` - -## SlackOAuthHandler Objects - -```python -class SlackOAuthHandler(RequestHandler) -``` - -#### initialize - -```python -def initialize(app: App) -``` - -#### get - -```python -def get() -``` - -#### to\_bolt\_request - -```python -def to_bolt_request(req: HTTPServerRequest) -> BoltRequest -``` - -#### set\_response - -```python -def set_response(self, bolt_resp) -> None -``` diff --git a/docs/english/reference/adapter/tornado/index.md b/docs/english/reference/adapter/tornado/index.md index 2877d5848..1789c6e4e 100644 --- a/docs/english/reference/adapter/tornado/index.md +++ b/docs/english/reference/adapter/tornado/index.md @@ -7,39 +7,3 @@ title: slack_bolt.adapter.tornado - [slack_bolt.adapter.tornado.async_handler](/tools/bolt-python/reference/adapter/tornado/async_handler) - [slack_bolt.adapter.tornado.handler](/tools/bolt-python/reference/adapter/tornado/handler) - -## SlackEventsHandler Objects - -```python -class SlackEventsHandler(RequestHandler) -``` - -#### initialize - -```python -def initialize(app: App) -``` - -#### post - -```python -def post() -``` - -## SlackOAuthHandler Objects - -```python -class SlackOAuthHandler(RequestHandler) -``` - -#### initialize - -```python -def initialize(app: App) -``` - -#### get - -```python -def get() -``` diff --git a/docs/english/reference/adapter/wsgi/handler.md b/docs/english/reference/adapter/wsgi/handler.md index 2da1ed217..98e07ce65 100644 --- a/docs/english/reference/adapter/wsgi/handler.md +++ b/docs/english/reference/adapter/wsgi/handler.md @@ -3,16 +3,10 @@ sidebar_label: handler title: slack_bolt.adapter.wsgi.handler --- -## SlackRequestHandler Objects +## `SlackRequestHandler` ```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App, path: str = '/slack/events') +SlackRequestHandler(app, path='/slack/events') ``` Setup Bolt as a WSGI web framework, this will make your application compatible with WSGI web servers. @@ -22,42 +16,21 @@ This can be used for production deployments. With the default settings, `http://localhost:3000/slack/events` Run Bolt with [gunicorn](https://gunicorn.org/) -# Python - app = App() - ```python +app = App() + api = SlackRequestHandler(app) ``` -# bash - export SLACK_SIGNING_SECRET=*** +```bash +export SLACK_SIGNING_SECRET=*** -```python export SLACK_BOT_TOKEN=xoxb-*** gunicorn app:api -b 0.0.0.0:3000 --log-level debug ``` +**Parameters:** -**Arguments**: - -- `app` _App_ - Your bolt application -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) - -#### dispatch - -```python -def dispatch(request: WsgiHttpRequest) -> BoltResponse -``` - -#### handle\_installation - -```python -def handle_installation(request: WsgiHttpRequest) -> BoltResponse -``` - -#### handle\_callback - -```python -def handle_callback(request: WsgiHttpRequest) -> BoltResponse -``` +- **app** (App) – Your bolt application +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) diff --git a/docs/english/reference/adapter/wsgi/http_request.md b/docs/english/reference/adapter/wsgi/http_request.md index 49bacefba..a9082c7e8 100644 --- a/docs/english/reference/adapter/wsgi/http_request.md +++ b/docs/english/reference/adapter/wsgi/http_request.md @@ -3,38 +3,12 @@ sidebar_label: http_request title: slack_bolt.adapter.wsgi.http_request --- -## WsgiHttpRequest Objects +## `WsgiHttpRequest` ```python -class WsgiHttpRequest() +WsgiHttpRequest(environ) ``` Extracts request information from the WSGI web server using the PEP 3333 standard. PEP 3333: https://peps.python.org/pep-3333/ - -#### \_\_init\_\_ - -```python -def __init__(environ: WSGIEnvironment) -``` - -#### method: `str` - -#### path: `str` - -#### query\_string: `str` - -#### protocol: `str` - -#### get\_headers - -```python -def get_headers() -> Dict[str, Union[str, Sequence[str]]] -``` - -#### get\_body - -```python -def get_body() -> str -``` diff --git a/docs/english/reference/adapter/wsgi/http_response.md b/docs/english/reference/adapter/wsgi/http_response.md index d6dee034c..146eaa39a 100644 --- a/docs/english/reference/adapter/wsgi/http_response.md +++ b/docs/english/reference/adapter/wsgi/http_response.md @@ -3,33 +3,12 @@ sidebar_label: http_response title: slack_bolt.adapter.wsgi.http_response --- -## WsgiHttpResponse Objects +## `WsgiHttpResponse` ```python -class WsgiHttpResponse() +WsgiHttpResponse(status, headers=None, body='') ``` Adapts bolt response information for the WSGI web server using the PEP 3333 standard. PEP 3333: https://peps.python.org/pep-3333/ - -#### \_\_init\_\_ - -```python -def __init__( - status: int, - headers: Optional[Dict[str, Sequence[str]]] = None, - body: str = '') -``` - -#### get\_headers - -```python -def get_headers() -> List[Tuple[str, str]] -``` - -#### get\_body - -```python -def get_body() -> Iterable[bytes] -``` diff --git a/docs/english/reference/adapter/wsgi/index.md b/docs/english/reference/adapter/wsgi/index.md index f88bb9ab3..b3c20d335 100644 --- a/docs/english/reference/adapter/wsgi/index.md +++ b/docs/english/reference/adapter/wsgi/index.md @@ -3,23 +3,10 @@ sidebar_label: wsgi title: slack_bolt.adapter.wsgi --- -## Submodules - -- [slack_bolt.adapter.wsgi.handler](/tools/bolt-python/reference/adapter/wsgi/handler) -- [slack_bolt.adapter.wsgi.http_request](/tools/bolt-python/reference/adapter/wsgi/http_request) -- [slack_bolt.adapter.wsgi.http_response](/tools/bolt-python/reference/adapter/wsgi/http_response) -- [slack_bolt.adapter.wsgi.internals](/tools/bolt-python/reference/adapter/wsgi/internals) - -## SlackRequestHandler Objects +## `SlackRequestHandler` ```python -class SlackRequestHandler() -``` - -#### \_\_init\_\_ - -```python -def __init__(app: App, path: str = '/slack/events') +SlackRequestHandler(app, path='/slack/events') ``` Setup Bolt as a WSGI web framework, this will make your application compatible with WSGI web servers. @@ -29,42 +16,28 @@ This can be used for production deployments. With the default settings, `http://localhost:3000/slack/events` Run Bolt with [gunicorn](https://gunicorn.org/) -# Python - app = App() - ```python +app = App() + api = SlackRequestHandler(app) ``` -# bash - export SLACK_SIGNING_SECRET=*** +```bash +export SLACK_SIGNING_SECRET=*** -```python export SLACK_BOT_TOKEN=xoxb-*** gunicorn app:api -b 0.0.0.0:3000 --log-level debug ``` +**Parameters:** -**Arguments**: - -- `app` _App_ - Your bolt application -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) - -#### dispatch - -```python -def dispatch(request: WsgiHttpRequest) -> BoltResponse -``` - -#### handle\_installation - -```python -def handle_installation(request: WsgiHttpRequest) -> BoltResponse -``` +- **app** (App) – Your bolt application +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) -#### handle\_callback +## Submodules -```python -def handle_callback(request: WsgiHttpRequest) -> BoltResponse -``` +- [slack_bolt.adapter.wsgi.handler](/tools/bolt-python/reference/adapter/wsgi/handler) +- [slack_bolt.adapter.wsgi.http_request](/tools/bolt-python/reference/adapter/wsgi/http_request) +- [slack_bolt.adapter.wsgi.http_response](/tools/bolt-python/reference/adapter/wsgi/http_response) +- [slack_bolt.adapter.wsgi.internals](/tools/bolt-python/reference/adapter/wsgi/internals) diff --git a/docs/english/reference/adapter/wsgi/internals.md b/docs/english/reference/adapter/wsgi/internals.md index 19433fb00..f76bc61e7 100644 --- a/docs/english/reference/adapter/wsgi/internals.md +++ b/docs/english/reference/adapter/wsgi/internals.md @@ -3,4 +3,4 @@ sidebar_label: internals title: slack_bolt.adapter.wsgi.internals --- -#### ENCODING + diff --git a/docs/english/reference/app/app.md b/docs/english/reference/app/app.md index 397e0133b..36ec8aa0c 100644 --- a/docs/english/reference/app/app.md +++ b/docs/english/reference/app/app.md @@ -4,42 +4,10 @@ title: slack_bolt.app.app slug: app --- -## App Objects - -```python -class App() -``` - -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: Optional[logging.Logger] = None, - name: Optional[str] = None, - process_before_response: bool = False, - raise_error_for_unhandled_request: bool = False, - signing_secret: Optional[str] = None, - token: Optional[str] = None, - token_verification_enabled: bool = True, - client: Optional[WebClient] = None, - before_authorize: Optional[Union[Middleware, Callable[..., Any]]] = None, - authorize: Optional[Callable[..., AuthorizeResult]] = None, - user_facing_authorize_error_message: Optional[str] = None, - installation_store: Optional[InstallationStore] = None, - installation_store_bot_only: Optional[bool] = None, - request_verification_enabled: bool = True, - ignoring_self_events_enabled: bool = True, - ignoring_self_assistant_message_events_enabled: bool = True, - ssl_check_enabled: bool = True, - url_verification_enabled: bool = True, - attaching_function_token_enabled: bool = True, - oauth_settings: Optional[OAuthSettings] = None, - oauth_flow: Optional[OAuthFlow] = None, - verification_token: Optional[str] = None, - listener_executor: Optional[Executor] = None, - assistant_thread_context_store: Optional[AssistantThreadContextStore] = None, - attaching_conversation_kwargs_enabled: bool = True) +## `App` + +```python +App(*, logger=None, name=None, process_before_response=False, raise_error_for_unhandled_request=False, signing_secret=None, token=None, token_verification_enabled=True, client=None, before_authorize=None, authorize=None, user_facing_authorize_error_message=None, installation_store=None, installation_store_bot_only=None, request_verification_enabled=True, ignoring_self_events_enabled=True, ignoring_self_assistant_message_events_enabled=True, ssl_check_enabled=True, url_verification_enabled=True, attaching_function_token_enabled=True, oauth_settings=None, oauth_flow=None, verification_token=None, listener_executor=None, assistant_thread_context_store=None, attaching_conversation_kwargs_enabled=True) ``` Bolt App that provides functionalities to register middleware/listeners. @@ -70,259 +38,210 @@ Refer to https://docs.slack.dev/tools/bolt-python/creating-an-app for details. If you would like to build an OAuth app for enabling the app to run with multiple workspaces, refer to https://docs.slack.dev/tools/bolt-python/concepts/authenticating-oauth to learn how to configure the app. -**Arguments**: - -- `logger` _Optional[logging.Logger]_ - The custom logger that can be used in this app. -- `name` _Optional[str]_ - The application name that will be used in logging. If absent, the source file name will be used. -- `process_before_response` _bool_ - True if this app runs on Function as a Service. (Default: False) -- `raise_error_for_unhandled_request` _bool_ - True if you want to raise exceptions for unhandled requests - and use @app.error listeners instead of - the built-in handler, which pints warning logs and returns 404 to Slack (Default: False) -- `signing_secret` _Optional[str]_ - The Signing Secret value used for verifying requests from Slack. -- `token` _Optional[str]_ - The bot/user access token required only for single-workspace app. -- `token_verification_enabled` _bool_ - Verifies the validity of the given token if True. -- `client` _Optional[WebClient]_ - The singleton `slack_sdk.WebClient` instance for this app. -- `before_authorize` _Optional[Union[Middleware, Callable[..., Any]]]_ - A global middleware that can be executed right before authorize function -- `authorize` _Optional[Callable[..., AuthorizeResult]]_ - The function to authorize an incoming request from Slack - by checking if there is a team/user in the installation data. -- `user_facing_authorize_error_message` _Optional[str]_ - The user-facing error message to display - when the app is installed but the installation is not managed by this app's installation store -- `installation_store` _Optional[InstallationStore]_ - The module offering save/find operations of installation data -- `installation_store_bot_only` _Optional[bool]_ - Use `InstallationStore#find_bot()` if True (Default: False) -- `request_verification_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `RequestVerification` is a built-in middleware that verifies the signature in HTTP Mode requests. - Make sure if it's safe enough when you turn a built-in middleware off. - We strongly recommend using RequestVerification for better security. - If you have a proxy that verifies request signature in front of the Bolt app, - it's totally fine to disable RequestVerification to avoid duplication of work. - Don't turn it off just for easiness of development. -- `ignoring_self_events_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `IgnoringSelfEvents` is a built-in middleware that enables Bolt apps to easily skip the events - generated by this app's bot user (this is useful for avoiding code error causing an infinite loop). -- `ignoring_self_assistant_message_events_enabled` _bool_ - False if you would like to disable the built-in middleware. - `IgnoringSelfEvents` for this app's bot user message events within an assistant thread - This is useful for avoiding code error causing an infinite loop; Default: True -- `url_verification_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `UrlVerification` is a built-in middleware that handles url_verification requests - that verify the endpoint for Events API in HTTP Mode requests. -- `attaching_function_token_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AttachingFunctionToken` is a built-in middleware that injects the just-in-time workflow-execution tokens - when your app receives `function_executed` or interactivity events scoped to a custom step. -- `ssl_check_enabled` _bool_ - bool = False if you would like to disable the built-in middleware (Default: True). - `SslCheck` is a built-in middleware that handles ssl_check requests from Slack. -- `oauth_settings` _Optional[OAuthSettings]_ - The settings related to Slack app installation flow (OAuth flow) -- `oauth_flow` _Optional[OAuthFlow]_ - Instantiated `slack_bolt.oauth.OAuthFlow`. This is always prioritized over oauth_settings. -- `verification_token` _Optional[str]_ - Deprecated verification mechanism. This can be used only for ssl_check requests. -- `listener_executor` _Optional[Executor]_ - Custom executor to run background tasks. If absent, the default `ThreadPoolExecutor` will - be used. -- `assistant_thread_context_store` _Optional[AssistantThreadContextStore]_ - Custom AssistantThreadContext store (Default: the built-in implementation, - which uses a parent message's metadata to store the latest context) -- `attaching_conversation_kwargs_enabled` _bool_ - False if you would like to disable the built-in - middleware (Default: True). `AttachingConversationKwargs` is a built-in middleware that attaches - conversation-specific listener arguments (such as `say`, `set_status`, `say_stream`, and - `set_suggested_prompts`) for assistant thread and direct message events. - -#### name - -```python -@property -def name() -> str -``` - -The name of this app (default: the filename). - -#### oauth\_flow - -```python -@property -def oauth_flow() -> Optional[OAuthFlow] +**Parameters:** + +- **logger** (Optional[Logger]) – The custom logger that can be used in this app. +- **name** (Optional[str]) – The application name that will be used in logging. If absent, the source file name will be used. +- **process_before_response** (bool) – True if this app runs on Function as a Service. (Default: False) +- **raise_error_for_unhandled_request** (bool) – True if you want to raise exceptions for unhandled requests +and use @app.error listeners instead of +the built-in handler, which pints warning logs and returns 404 to Slack (Default: False) +- **signing_secret** (Optional[str]) – The Signing Secret value used for verifying requests from Slack. +- **token** (Optional[str]) – The bot/user access token required only for single-workspace app. +- **token_verification_enabled** (bool) – Verifies the validity of the given token if True. +- **client** (Optional[WebClient]) – The singleton `slack_sdk.WebClient` instance for this app. +- **before_authorize** (Optional[Union[Middleware, Callable..., [Any]]]) – A global middleware that can be executed right before authorize function +- **authorize** (Optional[Callable..., [AuthorizeResult]]) – The function to authorize an incoming request from Slack +by checking if there is a team/user in the installation data. +- **user_facing_authorize_error_message** (Optional[str]) – The user-facing error message to display +when the app is installed but the installation is not managed by this app's installation store +- **installation_store** (Optional[InstallationStore]) – The module offering save/find operations of installation data +- **installation_store_bot_only** (Optional[bool]) – Use `InstallationStore#find_bot()` if True (Default: False) +- **request_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`RequestVerification` is a built-in middleware that verifies the signature in HTTP Mode requests. +Make sure if it's safe enough when you turn a built-in middleware off. +We strongly recommend using RequestVerification for better security. +If you have a proxy that verifies request signature in front of the Bolt app, +it's totally fine to disable RequestVerification to avoid duplication of work. +Don't turn it off just for easiness of development. +- **ignoring_self_events_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`IgnoringSelfEvents` is a built-in middleware that enables Bolt apps to easily skip the events +generated by this app's bot user (this is useful for avoiding code error causing an infinite loop). +- **ignoring_self_assistant_message_events_enabled** (bool) – False if you would like to disable the built-in middleware. +`IgnoringSelfEvents` for this app's bot user message events within an assistant thread +This is useful for avoiding code error causing an infinite loop; Default: True +- **url_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`UrlVerification` is a built-in middleware that handles url_verification requests +that verify the endpoint for Events API in HTTP Mode requests. +- **attaching_function_token_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AttachingFunctionToken` is a built-in middleware that injects the just-in-time workflow-execution tokens +when your app receives `function_executed` or interactivity events scoped to a custom step. +- **ssl_check_enabled** (bool) – bool = False if you would like to disable the built-in middleware (Default: True). +`SslCheck` is a built-in middleware that handles ssl_check requests from Slack. +- **oauth_settings** (Optional[OAuthSettings]) – The settings related to Slack app installation flow (OAuth flow) +- **oauth_flow** (Optional[OAuthFlow]) – Instantiated `slack_bolt.oauth.OAuthFlow`. This is always prioritized over oauth_settings. +- **verification_token** (Optional[str]) – Deprecated verification mechanism. This can be used only for ssl_check requests. +- **listener_executor** (Optional[Executor]) – Custom executor to run background tasks. If absent, the default `ThreadPoolExecutor` will +be used. +- **assistant_thread_context_store** (Optional[AssistantThreadContextStore]) – Custom AssistantThreadContext store (Default: the built-in implementation, +which uses a parent message's metadata to store the latest context) +- **attaching_conversation_kwargs_enabled** (bool) – False if you would like to disable the built-in +middleware (Default: True). `AttachingConversationKwargs` is a built-in middleware that attaches +conversation-specific listener arguments (such as `say`, `set_status`, `say_stream`, and +`set_suggested_prompts`) for assistant thread and direct message events. + +### `action` + +```python +action(constraints, matchers=None, middleware=None) ``` -Configured `OAuthFlow` object if exists. - -#### logger - -```python -@property -def logger() -> logging.Logger -``` - -The logger this app uses. - -#### client +Registers a new action listener. This method can be used as either a decorator or a method. ```python -@property -def client() -> WebClient -``` - -The singleton `slack_sdk.WebClient` instance in this app. - -#### installation\_store +# Use this method as a decorator +@app.action("approve_button") +def update_message(ack): + ack() -```python -@property -def installation_store() -> Optional[InstallationStore] +# Pass a function to this method +app.action("approve_button")(update_message) ``` -The `slack_sdk.oauth.InstallationStore` that can be used in the `authorize` middleware. +* Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for actions in `blocks`. +* Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for actions in `attachments`. +* Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for actions in dialogs. -#### listener\_runner +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -```python -@property -def listener_runner() -> ThreadListenerRunner -``` +**Parameters:** -The thread executor for asynchronously running listeners. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### process\_before\_response +### `attachment_action` ```python -@property -def process_before_response() -> bool +attachment_action(callback_id, matchers=None, middleware=None) ``` -#### start +Registers a new `interactive_message` action listener. -```python -def start( - port: int = 3000, - path: str = '/slack/events', - http_server_logger_enabled: bool = True) -> None -``` +Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for details. -Starts a web server for local development. +### `block_action` ```python -# With the default settings, `http://localhost:3000/slack/events` -# is available for handling incoming requests from Slack -app.start() +block_action(constraints, matchers=None, middleware=None) ``` -This method internally starts a Web server process built with the `http.server` module. -For production, consider using a production-ready WSGI server such as Gunicorn. - -**Arguments**: +Registers a new `block_actions` action listener. -- `port` _int_ - The port to listen on (Default: 3000) -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) -- `http_server_logger_enabled` _bool_ - The flag to enable http.server logging if True (Default: True) +Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for details. -#### dispatch +### `block_suggestion` ```python -def dispatch(req: BoltRequest) -> BoltResponse +block_suggestion(action_id, matchers=None, middleware=None) ``` -Applies all middleware and dispatches an incoming request from Slack to the right code path. - -**Arguments**: - -- `req` _BoltRequest_ - An incoming request from Slack - -**Returns**: - -- `BoltResponse` - The response generated by this Bolt app +Registers a new `block_suggestion` listener. -#### use +### `client` ```python -def use(*args) -> Optional[Callable] +client: WebClient ``` -Registers a new global middleware to this app. This method can be used as either a decorator or a method. - -Refer to `App#middleware()` method's docstring for details. +The singleton `slack_sdk.WebClient` instance in this app. -#### middleware +### `command` ```python -def middleware(*args) -> Optional[Callable] +command(command, matchers=None, middleware=None) ``` -Registers a new middleware to this app. +Registers a new slash command listener. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.middleware -def middleware_func(logger, body, next): - logger.info(f"request body: {body}") - next() +@app.command("/echo") +def repeat_text(ack, say, command): + # Acknowledge command request + ack() + say(f"{command['text']}") # Pass a function to this method -app.middleware(middleware_func) +app.command("/echo")(repeat_text) ``` -Refer to https://docs.slack.dev/tools/bolt-python/concepts/global-middleware for details. +Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details of Slash Commands. To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `*args` - A function that works as a global middleware. +- **command** (Union[str, Pattern]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### assistant +### `dialog_cancellation` ```python -def assistant(assistant: Assistant) -> Optional[Callable] +dialog_cancellation(callback_id, matchers=None, middleware=None) ``` -#### step +Registers a new `dialog_cancellation` listener. + +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. + +### `dialog_submission` ```python -def step( - callback_id: Union[str, Pattern, WorkflowStep, WorkflowStepBuilder], - edit: Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]] = None, - save: Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]] = None, - execute: Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]] = None) +dialog_submission(callback_id, matchers=None, middleware=None) ``` -Deprecated: register a new step from app listener. +Registers a new `dialog_submission` listener. -Steps from apps for legacy workflows are now deprecated. -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. -Registers a new step from app listener. +### `dialog_suggestion` -Unlike others, this method doesn't behave as a decorator. -If you want to register a step from app by a decorator, use `WorkflowStepBuilder`'s methods. +```python +dialog_suggestion(callback_id, matchers=None, middleware=None) +``` + +Registers a new `dialog_suggestion` listener. + +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. + +### `dispatch` ```python -# Create a new WorkflowStep instance -from slack_bolt.workflows.step import WorkflowStep -ws = WorkflowStep( - callback_id="add_task", - edit=edit, - save=save, - execute=execute, -) -# Pass Step to set up listeners -app.step(ws) +dispatch(req) ``` -Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details of steps from apps. +Applies all middleware and dispatches an incoming request from Slack to the right code path. -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. +**Parameters:** -For further information about WorkflowStep specific function arguments -such as `configure`, `update`, `complete`, and `fail`, -refer to `slack_bolt.workflows.step.utilities` API documents. +- **req** (BoltRequest) – An incoming request from Slack -**Arguments**: +**Returns:** -- `callback_id` _Union[str, Pattern, WorkflowStep, WorkflowStepBuilder]_ - The Callback ID for this step from app -- `edit` _Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]]_ - The function for displaying a modal in the Workflow Builder -- `save` _Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]]_ - The function for handling configuration in the Workflow Builder -- `execute` _Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]]_ - The function for handling the step execution +- BoltResponse – The response generated by this Bolt app -#### error +### `error` ```python -def error( - func: Callable[..., Optional[BoltResponse]]) -> Callable[..., Optional[BoltResponse]] +error(func) ``` Updates the global error handler. This method can be used as either a decorator or a method. @@ -340,18 +259,15 @@ app.error(custom_error_handler) To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `func` _Callable[..., Optional[BoltResponse]]_ - The function that is supposed to be executed - when getting an unhandled error in Bolt app. +- **func** (Callable..., [Optional[BoltResponse]]) – The function that is supposed to be executed +when getting an unhandled error in Bolt app. -#### event +### `event` ```python -def event( - event: Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +event(event, matchers=None, middleware=None) ``` Registers a new event listener. This method can be used as either a decorator or a method. @@ -373,22 +289,92 @@ Refer to https://docs.slack.dev/apis/events-api/ for details of Events API. To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** + +- **event** (Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]]) – The conditions that match a request payload. +If you pass a dict for this, you can have type, subtype in the constraint. +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `function` + +```python +function(callback_id, matchers=None, middleware=None, auto_acknowledge=True, ack_timeout=3) +``` + +Registers a new Function listener. + +This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.function("reverse") +def reverse_string(ack: Ack, inputs: dict, complete: Complete, fail: Fail): + try: + ack() + string_to_reverse = inputs["stringToReverse"] + complete(outputs={"reverseString": string_to_reverse[::-1]}) + except Exception as e: + fail(f"Cannot reverse string (error: {e})") + raise e + +# Pass a function to this method +app.function("reverse")(reverse_string) +``` + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **callback_id** (Union[str, Pattern]) – The callback id to identify the function +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. +- **auto_acknowledge** (bool) – Whether Bolt automatically acknowledges the function execution event on the +listener's behalf. When False, your listener must call `ack()` itself within `ack_timeout` +seconds (Default: True). +- **ack_timeout** (int) – The number of seconds to wait for the listener to call `ack()`. +Only takes effect when `auto_acknowledge` is False (Default: 3). + +### `global_shortcut` + +```python +global_shortcut(callback_id, matchers=None, middleware=None) +``` -- `event` _Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]]_ - The conditions that match a request payload. - If you pass a dict for this, you can have type, subtype in the constraint. -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +Registers a new global shortcut listener. -#### message +### `installation_store` ```python -def message( - keyword: Union[str, Pattern] = '', - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +installation_store: Optional[InstallationStore] +``` + +The `slack_sdk.oauth.InstallationStore` that can be used in the `authorize` middleware. + +### `listener_runner` + +```python +listener_runner: ThreadListenerRunner +``` + +The thread executor for asynchronously running listeners. + +### `logger` + +```python +logger: logging.Logger +``` + +The logger this app uses. + +### `message` + +```python +message(keyword='', matchers=None, middleware=None) ``` Registers a new message event listener. This method can be used as either a decorator or a method. @@ -410,104 +396,116 @@ Refer to https://docs.slack.dev/reference/events/message/ for details of `messag To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `keyword` _Union[str, Pattern]_ - The keyword to match -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **keyword** (Union[str, Pattern]) – The keyword to match +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### function +### `message_shortcut` ```python -def function( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None, - auto_acknowledge: bool = True, - ack_timeout: int = 3) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +message_shortcut(callback_id, matchers=None, middleware=None) ``` -Registers a new Function listener. +Registers a new message shortcut listener. + +### `middleware` + +```python +middleware(*args) +``` + +Registers a new middleware to this app. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.function("reverse") -def reverse_string(ack: Ack, inputs: dict, complete: Complete, fail: Fail): - try: - ack() - string_to_reverse = inputs["stringToReverse"] - complete(outputs={"reverseString": string_to_reverse[::-1]}) - except Exception as e: - fail(f"Cannot reverse string (error: {e})") - raise e +@app.middleware +def middleware_func(logger, body, next): + logger.info(f"request body: {body}") + next() # Pass a function to this method -app.function("reverse")(reverse_string) +app.middleware(middleware_func) ``` +Refer to https://docs.slack.dev/tools/bolt-python/concepts/global-middleware for details. + To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `callback_id` _Union[str, Pattern]_ - The callback id to identify the function -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. -- `auto_acknowledge` _bool_ - Whether Bolt automatically acknowledges the function execution event on the - listener's behalf. When False, your listener must call `ack()` itself within `ack_timeout` - seconds (Default: True). -- `ack_timeout` _int_ - The number of seconds to wait for the listener to call `ack()`. - Only takes effect when `auto_acknowledge` is False (Default: 3). +- ***args** – A function that works as a global middleware. -#### command +### `name` ```python -def command( - command: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +name: str ``` -Registers a new slash command listener. +The name of this app (default: the filename). + +### `oauth_flow` + +```python +oauth_flow: Optional[OAuthFlow] +``` + +Configured `OAuthFlow` object if exists. + +### `options` + +```python +options(constraints, matchers=None, middleware=None) +``` + +Registers a new options listener. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.command("/echo") -def repeat_text(ack, say, command): - # Acknowledge command request - ack() - say(f"{command['text']}") +@app.options("menu_selection") +def show_menu_options(ack): + options = [ + { + "text": {"type": "plain_text", "text": "Option 1"}, + "value": "1-1", + }, + { + "text": {"type": "plain_text", "text": "Option 2"}, + "value": "1-2", + }, + ] + ack(options=options) # Pass a function to this method -app.command("/echo")(repeat_text) +app.options("menu_selection")(show_menu_options) ``` -Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details of Slash Commands. +Refer to the following documents for details: + +* https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element#external_select +* https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element#external_multi_select To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `command` _Union[str, Pattern]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### shortcut +### `shortcut` ```python -def shortcut( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +shortcut(constraints, matchers=None, middleware=None) ``` Registers a new shortcut listener. @@ -536,130 +534,95 @@ Refer to https://docs.slack.dev/interactivity/implementing-shortcuts/ for detail To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload. -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload. +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### global\_shortcut +### `start` ```python -def global_shortcut( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +start(port=3000, path='/slack/events', http_server_logger_enabled=True) ``` -Registers a new global shortcut listener. - -#### message\_shortcut +Starts a web server for local development. ```python -def message_shortcut( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +# With the default settings, `http://localhost:3000/slack/events` +# is available for handling incoming requests from Slack +app.start() ``` -Registers a new message shortcut listener. +This method internally starts a Web server process built with the `http.server` module. +For production, consider using a production-ready WSGI server such as Gunicorn. -#### action +**Parameters:** -```python -def action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` +- **port** (int) – The port to listen on (Default: 3000) +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) +- **http_server_logger_enabled** (bool) – The flag to enable http.server logging if True (Default: True) -Registers a new action listener. This method can be used as either a decorator or a method. +### `step` ```python -# Use this method as a decorator -@app.action("approve_button") -def update_message(ack): - ack() - -# Pass a function to this method -app.action("approve_button")(update_message) +step(callback_id, edit=None, save=None, execute=None) ``` -* Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for actions in `blocks`. -* Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for actions in `attachments`. -* Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for actions in dialogs. - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. - -**Arguments**: - -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. - -#### block\_action - -```python -def block_action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` +Deprecated: register a new step from app listener. -Registers a new `block_actions` action listener. +Steps from apps for legacy workflows are now deprecated. +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for details. +Registers a new step from app listener. -#### attachment\_action +Unlike others, this method doesn't behave as a decorator. +If you want to register a step from app by a decorator, use `WorkflowStepBuilder`'s methods. ```python -def attachment_action( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +# Create a new WorkflowStep instance +from slack_bolt.workflows.step import WorkflowStep +ws = WorkflowStep( + callback_id="add_task", + edit=edit, + save=save, + execute=execute, +) +# Pass Step to set up listeners +app.step(ws) ``` -Registers a new `interactive_message` action listener. +Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details of steps from apps. -Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for details. +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -#### dialog\_submission +For further information about WorkflowStep specific function arguments +such as `configure`, `update`, `complete`, and `fail`, +refer to `slack_bolt.workflows.step.utilities` API documents. -```python -def dialog_submission( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` +**Parameters:** -Registers a new `dialog_submission` listener. +- **callback_id** (Union[str, Pattern, WorkflowStep, WorkflowStepBuilder]) – The Callback ID for this step from app +- **edit** (Optional[Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]]) – The function for displaying a modal in the Workflow Builder +- **save** (Optional[Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]]) – The function for handling configuration in the Workflow Builder +- **execute** (Optional[Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]]) – The function for handling the step execution -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. - -#### dialog\_cancellation +### `use` ```python -def dialog_cancellation( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +use(*args) ``` -Registers a new `dialog_cancellation` listener. +Registers a new global middleware to this app. This method can be used as either a decorator or a method. -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. +Refer to `App#middleware()` method's docstring for details. -#### view +### `view` ```python -def view( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +view(constraints, matchers=None, middleware=None) ``` Registers a new `view_submission`/`view_closed` event listener. @@ -692,146 +655,39 @@ Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### view\_submission +### `view_closed` ```python -def view_submission( - constraints: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` - -Registers a new `view_submission` listener. - -Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_submission for -details. - -#### view\_closed - -```python -def view_closed( - constraints: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +view_closed(constraints, matchers=None, middleware=None) ``` Registers a new `view_closed` listener. Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_closed for details. -#### options - -```python -def options( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` - -Registers a new options listener. - -This method can be used as either a decorator or a method. - -```python -# Use this method as a decorator -@app.options("menu_selection") -def show_menu_options(ack): - options = [ - { - "text": {"type": "plain_text", "text": "Option 1"}, - "value": "1-1", - }, - { - "text": {"type": "plain_text", "text": "Option 2"}, - "value": "1-2", - }, - ] - ack(options=options) - -# Pass a function to this method -app.options("menu_selection")(show_menu_options) -``` - -Refer to the following documents for details: - -* https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element#external_select -* https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element#external_multi_select - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. - -**Arguments**: - -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. - -#### block\_suggestion +### `view_submission` ```python -def block_suggestion( - action_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +view_submission(constraints, matchers=None, middleware=None) ``` -Registers a new `block_suggestion` listener. - -#### dialog\_suggestion - -```python -def dialog_suggestion( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` - -Registers a new `dialog_suggestion` listener. - -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. - -#### default\_tokens\_revoked\_event\_listener - -```python -def default_tokens_revoked_event_listener() -> Callable[..., Optional[BoltResponse]] -``` - -#### default\_app\_uninstalled\_event\_listener - -```python -def default_app_uninstalled_event_listener() -> Callable[..., Optional[BoltResponse]] -``` - -#### enable\_token\_revocation\_listeners - -```python -def enable_token_revocation_listeners() -> None -``` - -## SlackAppDevelopmentServer Objects +Registers a new `view_submission` listener. -```python -class SlackAppDevelopmentServer() -``` +Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_submission for +details. -#### \_\_init\_\_ +## `SlackAppDevelopmentServer` ```python -def __init__( - port: int, - path: str, - app: App, - oauth_flow: Optional[OAuthFlow] = None, - http_server_logger_enabled: bool = True) +SlackAppDevelopmentServer(port, path, app, oauth_flow=None, http_server_logger_enabled=True) ``` Slack App Development Server. @@ -844,18 +700,18 @@ is not recommended. Please consider using an adapter (refer to slack_bolt.adapte along with a production-grade server when running the app for end users. https://docs.python.org/3/library/http.server.html#http.server.HTTPServer -**Arguments**: +**Parameters:** -- `port` _int_ - the port number -- `path` _str_ - the path to receive incoming requests -- `app` _App_ - the `App` instance to execute -- `oauth_flow` _Optional[OAuthFlow]_ - the `OAuthFlow` instance to use for OAuth flow -- `http_server_logger_enabled` _bool_ - The flag to turn on/off http.server's logging +- **port** (int) – the port number +- **path** (str) – the path to receive incoming requests +- **app** (App) – the `App` instance to execute +- **oauth_flow** (Optional[OAuthFlow]) – the `OAuthFlow` instance to use for OAuth flow +- **http_server_logger_enabled** (bool) – The flag to turn on/off http.server's logging -#### start +### `start` ```python -def start() -> None +start() ``` Starts a new web server process. diff --git a/docs/english/reference/app/async_app.md b/docs/english/reference/app/async_app.md index a0ca092f6..4bbb21b29 100644 --- a/docs/english/reference/app/async_app.md +++ b/docs/english/reference/app/async_app.md @@ -3,40 +3,10 @@ sidebar_label: async_app title: slack_bolt.app.async_app --- -## AsyncApp Objects - -```python -class AsyncApp() -``` - -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: Optional[logging.Logger] = None, - name: Optional[str] = None, - process_before_response: bool = False, - raise_error_for_unhandled_request: bool = False, - signing_secret: Optional[str] = None, - token: Optional[str] = None, - client: Optional[AsyncWebClient] = None, - before_authorize: Optional[Union[AsyncMiddleware, Callable[..., Awaitable[Any]]]] = None, - authorize: Optional[Callable[..., Awaitable[AuthorizeResult]]] = None, - user_facing_authorize_error_message: Optional[str] = None, - installation_store: Optional[AsyncInstallationStore] = None, - installation_store_bot_only: Optional[bool] = None, - request_verification_enabled: bool = True, - ignoring_self_events_enabled: bool = True, - ignoring_self_assistant_message_events_enabled: bool = True, - ssl_check_enabled: bool = True, - url_verification_enabled: bool = True, - attaching_function_token_enabled: bool = True, - oauth_settings: Optional[AsyncOAuthSettings] = None, - oauth_flow: Optional[AsyncOAuthFlow] = None, - verification_token: Optional[str] = None, - assistant_thread_context_store: Optional[AsyncAssistantThreadContextStore] = None, - attaching_conversation_kwargs_enabled: bool = True) +## `AsyncApp` + +```python +AsyncApp(*, logger=None, name=None, process_before_response=False, raise_error_for_unhandled_request=False, signing_secret=None, token=None, client=None, before_authorize=None, authorize=None, user_facing_authorize_error_message=None, installation_store=None, installation_store_bot_only=None, request_verification_enabled=True, ignoring_self_events_enabled=True, ignoring_self_assistant_message_events_enabled=True, ssl_check_enabled=True, url_verification_enabled=True, attaching_function_token_enabled=True, oauth_settings=None, oauth_flow=None, verification_token=None, assistant_thread_context_store=None, attaching_conversation_kwargs_enabled=True) ``` Bolt App that provides functionalities to register middleware/listeners. @@ -67,292 +37,207 @@ Refer to https://docs.slack.dev/tools/bolt-python/concepts/async for details. If you would like to build an OAuth app for enabling the app to run with multiple workspaces, refer to https://docs.slack.dev/tools/bolt-python/concepts/authenticating-oauth to learn how to configure the app. -**Arguments**: - -- `logger` _Optional[logging.Logger]_ - The custom logger that can be used in this app. -- `name` _Optional[str]_ - The application name that will be used in logging. If absent, the source file name will be used. -- `process_before_response` _bool_ - True if this app runs on Function as a Service. (Default: False) -- `raise_error_for_unhandled_request` _bool_ - True if you want to raise exceptions for unhandled requests - and use @app.error listeners instead of - the built-in handler, which pints warning logs and returns 404 to Slack (Default: False) -- `signing_secret` _Optional[str]_ - The Signing Secret value used for verifying requests from Slack. -- `token` _Optional[str]_ - The bot/user access token required only for single-workspace app. -- `client` _Optional[AsyncWebClient]_ - The singleton `slack_sdk.web.async_client.AsyncWebClient` instance for this app. -- `before_authorize` _Optional[Union[AsyncMiddleware, Callable[..., Awaitable[Any]]]]_ - A global middleware that can be executed right before authorize function -- `authorize` _Optional[Callable[..., Awaitable[AuthorizeResult]]]_ - The function to authorize an incoming request from Slack - by checking if there is a team/user in the installation data. -- `user_facing_authorize_error_message` _Optional[str]_ - The user-facing error message to display - when the app is installed but the installation is not managed by this app's installation store -- `installation_store` _Optional[AsyncInstallationStore]_ - The module offering save/find operations of installation data -- `installation_store_bot_only` _Optional[bool]_ - Use `AsyncInstallationStore#async_find_bot()` if True (Default: False) -- `request_verification_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AsyncRequestVerification` is a built-in middleware that verifies the signature in HTTP Mode requests. - Make sure if it's safe enough when you turn a built-in middleware off. - We strongly recommend using RequestVerification for better security. - If you have a proxy that verifies request signature in front of the Bolt app, - it's totally fine to disable RequestVerification to avoid duplication of work. - Don't turn it off just for easiness of development. -- `ignoring_self_events_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AsyncIgnoringSelfEvents` is a built-in middleware that enables Bolt apps to easily skip the events - generated by this app's bot user (this is useful for avoiding code error causing an infinite loop). -- `ignoring_self_assistant_message_events_enabled` _bool_ - False if you would like to disable the built-in middleware. - `IgnoringSelfEvents` for this app's bot user message events within an assistant thread - This is useful for avoiding code error causing an infinite loop; Default: True -- `url_verification_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AsyncUrlVerification` is a built-in middleware that handles url_verification requests - that verify the endpoint for Events API in HTTP Mode requests. -- `ssl_check_enabled` _bool_ - bool = False if you would like to disable the built-in middleware (Default: True). - `AsyncSslCheck` is a built-in middleware that handles ssl_check requests from Slack. -- `attaching_function_token_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AsyncAttachingFunctionToken` is a built-in middleware that injects the just-in-time workflow-execution token - when your app receives `function_executed` or interactivity events scoped to a custom step. -- `oauth_settings` _Optional[AsyncOAuthSettings]_ - The settings related to Slack app installation flow (OAuth flow) -- `oauth_flow` _Optional[AsyncOAuthFlow]_ - Instantiated `slack_bolt.oauth.AsyncOAuthFlow`. This is always prioritized over oauth_settings. -- `verification_token` _Optional[str]_ - Deprecated verification mechanism. This can be used only for ssl_check requests. -- `assistant_thread_context_store` _Optional[AsyncAssistantThreadContextStore]_ - Custom AssistantThreadContext store (Default: the built-in implementation, - which uses a parent message's metadata to store the latest context) -- `attaching_conversation_kwargs_enabled` _bool_ - False if you would like to disable the built-in - middleware (Default: True). `AttachingConversationKwargs` is a built-in middleware that attaches - conversation-specific listener arguments (such as `say`, `set_status`, `say_stream`, and - `set_suggested_prompts`) for assistant thread and direct message events. - -#### name - -```python -@property -def name() -> str -``` - -The name of this app (default: the filename). - -#### oauth\_flow - -```python -@property -def oauth_flow() -> Optional[AsyncOAuthFlow] -``` - -Configured `OAuthFlow` object if exists. - -#### client - -```python -@property -def client() -> AsyncWebClient +**Parameters:** + +- **logger** (Optional[Logger]) – The custom logger that can be used in this app. +- **name** (Optional[str]) – The application name that will be used in logging. If absent, the source file name will be used. +- **process_before_response** (bool) – True if this app runs on Function as a Service. (Default: False) +- **raise_error_for_unhandled_request** (bool) – True if you want to raise exceptions for unhandled requests +and use @app.error listeners instead of +the built-in handler, which pints warning logs and returns 404 to Slack (Default: False) +- **signing_secret** (Optional[str]) – The Signing Secret value used for verifying requests from Slack. +- **token** (Optional[str]) – The bot/user access token required only for single-workspace app. +- **client** (Optional[AsyncWebClient]) – The singleton `slack_sdk.web.async_client.AsyncWebClient` instance for this app. +- **before_authorize** (Optional[Union[AsyncMiddleware, Callable..., [Awaitable[Any]]]]) – A global middleware that can be executed right before authorize function +- **authorize** (Optional[Callable..., [Awaitable[AuthorizeResult]]]) – The function to authorize an incoming request from Slack +by checking if there is a team/user in the installation data. +- **user_facing_authorize_error_message** (Optional[str]) – The user-facing error message to display +when the app is installed but the installation is not managed by this app's installation store +- **installation_store** (Optional[AsyncInstallationStore]) – The module offering save/find operations of installation data +- **installation_store_bot_only** (Optional[bool]) – Use `AsyncInstallationStore#async_find_bot()` if True (Default: False) +- **request_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AsyncRequestVerification` is a built-in middleware that verifies the signature in HTTP Mode requests. +Make sure if it's safe enough when you turn a built-in middleware off. +We strongly recommend using RequestVerification for better security. +If you have a proxy that verifies request signature in front of the Bolt app, +it's totally fine to disable RequestVerification to avoid duplication of work. +Don't turn it off just for easiness of development. +- **ignoring_self_events_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AsyncIgnoringSelfEvents` is a built-in middleware that enables Bolt apps to easily skip the events +generated by this app's bot user (this is useful for avoiding code error causing an infinite loop). +- **ignoring_self_assistant_message_events_enabled** (bool) – False if you would like to disable the built-in middleware. +`IgnoringSelfEvents` for this app's bot user message events within an assistant thread +This is useful for avoiding code error causing an infinite loop; Default: True +- **url_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AsyncUrlVerification` is a built-in middleware that handles url_verification requests +that verify the endpoint for Events API in HTTP Mode requests. +- **ssl_check_enabled** (bool) – bool = False if you would like to disable the built-in middleware (Default: True). +`AsyncSslCheck` is a built-in middleware that handles ssl_check requests from Slack. +- **attaching_function_token_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AsyncAttachingFunctionToken` is a built-in middleware that injects the just-in-time workflow-execution token +when your app receives `function_executed` or interactivity events scoped to a custom step. +- **oauth_settings** (Optional[AsyncOAuthSettings]) – The settings related to Slack app installation flow (OAuth flow) +- **oauth_flow** (Optional[AsyncOAuthFlow]) – Instantiated `slack_bolt.oauth.AsyncOAuthFlow`. This is always prioritized over oauth_settings. +- **verification_token** (Optional[str]) – Deprecated verification mechanism. This can be used only for ssl_check requests. +- **assistant_thread_context_store** (Optional[AsyncAssistantThreadContextStore]) – Custom AssistantThreadContext store (Default: the built-in implementation, +which uses a parent message's metadata to store the latest context) +- **attaching_conversation_kwargs_enabled** (bool) – False if you would like to disable the built-in +middleware (Default: True). `AttachingConversationKwargs` is a built-in middleware that attaches +conversation-specific listener arguments (such as `say`, `set_status`, `say_stream`, and +`set_suggested_prompts`) for assistant thread and direct message events. + +### `action` + +```python +action(constraints, matchers=None, middleware=None) ``` -The singleton `slack_sdk.web.async_client.AsyncWebClient` instance in this app. - -#### logger +Registers a new action listener. This method can be used as either a decorator or a method. ```python -@property -def logger() -> logging.Logger -``` - -The logger this app uses. - -#### installation\_store +# Use this method as a decorator +@app.action("approve_button") +async def update_message(ack): + await ack() -```python -@property -def installation_store() -> Optional[AsyncInstallationStore] +# Pass a function to this method +app.action("approve_button")(update_message) ``` -The `slack_sdk.oauth.AsyncInstallationStore` that can be used in the `authorize` middleware. +* Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for actions in `blocks`. +* Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for actions in `attachments`. +* Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for actions in dialogs. -#### listener\_runner +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -```python -@property -def listener_runner() -> AsyncioListenerRunner -``` +**Parameters:** -The asyncio-based executor for asynchronously running listeners. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### process\_before\_response +### `async_dispatch` ```python -@property -def process_before_response() -> bool +async_dispatch(req) ``` -#### server - -```python -def server( - port: int = 3000, - path: str = '/slack/events', - host: Optional[str] = None) -> AsyncSlackAppServer -``` +Applies all middleware and dispatches an incoming request from Slack to the right code path. -Configure a web server using AIOHTTP. +**Parameters:** -Refer to https://docs.aiohttp.org/ for more details about AIOHTTP. +- **req** (AsyncBoltRequest) – An incoming request from Slack. -**Arguments**: +**Returns:** -- `port` _int_ - The port to listen on (Default: 3000) -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) -- `host` _Optional[str]_ - The hostname to serve the web endpoints. (Default: 0.0.0.0) +- BoltResponse – The response generated by this Bolt app. -#### web\_app +### `attachment_action` ```python -def web_app(path: str = '/slack/events', port: int = 3000) -> web.Application +attachment_action(callback_id, matchers=None, middleware=None) ``` -Returns a `web.Application` instance for aiohttp-devtools users. - -```python -from slack_bolt.async_app import AsyncApp -app = AsyncApp() - -@app.event("app_mention") -async def event_test(body, say, logger): - logger.info(body) - await say("What's up?") - -def app_factory(): - return app.web_app() - -# adev runserver --port 3000 --app-factory app_factory async_app.py -``` - - -**Arguments**: +Registers a new `interactive_message` action listener. -- `path` _str_ - The path to receive incoming requests from Slack -- `port` _int_ - The port to listen on (Default: 3000) +Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for details. -#### start +### `block_action` ```python -def start( - port: int = 3000, - path: str = '/slack/events', - host: Optional[str] = None) -> None +block_action(constraints, matchers=None, middleware=None) ``` -Start a web server using AIOHTTP. - -Refer to https://docs.aiohttp.org/ for more details about AIOHTTP. - -**Arguments**: +Registers a new `block_actions` action listener. -- `port` _int_ - The port to listen on (Default: 3000) -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) -- `host` _Optional[str]_ - The hostname to serve the web endpoints. (Default: 0.0.0.0) +Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for details. -#### async\_dispatch +### `block_suggestion` ```python -async def async_dispatch(req: AsyncBoltRequest) -> BoltResponse +block_suggestion(action_id, matchers=None, middleware=None) ``` -Applies all middleware and dispatches an incoming request from Slack to the right code path. - -**Arguments**: - -- `req` _AsyncBoltRequest_ - An incoming request from Slack. - -**Returns**: - -- `BoltResponse` - The response generated by this Bolt app. +Registers a new `block_suggestion` listener. -#### use +### `client` ```python -def use(*args) -> Optional[Callable] +client: AsyncWebClient ``` -Refer to `AsyncApp#middleware()` method's docstring for details. +The singleton `slack_sdk.web.async_client.AsyncWebClient` instance in this app. -#### middleware +### `command` ```python -def middleware(*args) -> Optional[Callable] +command(command, matchers=None, middleware=None) ``` -Registers a new middleware to this app. +Registers a new slash command listener. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.middleware -async def middleware_func(logger, body, next): - logger.info(f"request body: {body}") - await next() +@app.command("/echo") +async def repeat_text(ack, say, command): + # Acknowledge command request + await ack() + await say(f"{command['text']}") # Pass a function to this method -app.middleware(middleware_func) +app.command("/echo")(repeat_text) ``` +Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details of Slash Commands. + To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `*args` - A function that works as a global middleware. +- **command** (Union[str, Pattern]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### assistant +### `dialog_cancellation` ```python -def assistant(assistant: AsyncAssistant) -> Optional[Callable] +dialog_cancellation(callback_id, matchers=None, middleware=None) ``` -#### step +Registers a new `dialog_cancellation` listener. + +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. + +### `dialog_submission` ```python -def step( - callback_id: Union[str, Pattern, AsyncWorkflowStep, AsyncWorkflowStepBuilder], - edit: Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]] = None, - save: Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]] = None, - execute: Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]] = None) +dialog_submission(callback_id, matchers=None, middleware=None) ``` -Deprecated: register a new step from app listener. - -Steps from apps for legacy workflows are now deprecated. -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ +Registers a new `dialog_submission` listener. -Registers a new step from app listener. +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. -Unlike others, this method doesn't behave as a decorator. -If you want to register a step from app by a decorator, use `AsyncWorkflowStepBuilder`'s methods. +### `dialog_suggestion` ```python -# Create a new WorkflowStep instance -from slack_bolt.workflows.async_step import AsyncWorkflowStep -ws = AsyncWorkflowStep( - callback_id="add_task", - edit=edit, - save=save, - execute=execute, -) -# Pass Step to set up listeners -app.step(ws) +dialog_suggestion(callback_id, matchers=None, middleware=None) ``` -Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details of steps from apps. - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -For further information about AsyncWorkflowStep specific function arguments -such as `configure`, `update`, `complete`, and `fail`, -refer to the `async` prefixed ones in `slack_bolt.workflows.step.utilities` API documents. - -**Arguments**: +Registers a new `dialog_suggestion` listener. -- `callback_id` _Union[str, Pattern, AsyncWorkflowStep, AsyncWorkflowStepBuilder]_ - The Callback ID for this step from app -- `edit` _Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]_ - The function for displaying a modal in the Workflow Builder -- `save` _Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]_ - The function for handling configuration in the Workflow Builder -- `execute` _Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]_ - The function for handling the step execution +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. -#### error +### `error` ```python -def error( - func: Callable[..., Awaitable[Optional[BoltResponse]]]) -> Callable[..., Awaitable[Optional[BoltResponse]]] +error(func) ``` Updates the global error handler. This method can be used as either a decorator or a method. @@ -370,18 +255,15 @@ app.error(custom_error_handler) To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `func` _Callable[..., Awaitable[Optional[BoltResponse]]]_ - The function that is supposed to be executed - when getting an unhandled error in Bolt app. +- **func** (Callable..., [Awaitable[Optional[BoltResponse]]]) – The function that is supposed to be executed +when getting an unhandled error in Bolt app. -#### event +### `event` ```python -def event( - event: Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +event(event, matchers=None, middleware=None) ``` Registers a new event listener. This method can be used as either a decorator or a method. @@ -403,22 +285,92 @@ Refer to https://docs.slack.dev/apis/events-api/ for details of Events API. To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** + +- **event** (Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]]) – The conditions that match a request payload. +If you pass a dict for this, you can have type, subtype in the constraint. +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `function` + +```python +function(callback_id, matchers=None, middleware=None, auto_acknowledge=True, ack_timeout=3) +``` + +Registers a new Function listener. + +This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.function("reverse") +async def reverse_string(ack: AsyncAck, inputs: dict, complete: AsyncComplete, fail: AsyncFail): + try: + await ack() + string_to_reverse = inputs["stringToReverse"] + await complete({"reverseString": string_to_reverse[::-1]}) + except Exception as e: + await fail(f"Cannot reverse string (error: {e})") + raise e + +# Pass a function to this method +app.function("reverse")(reverse_string) +``` + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. + +**Parameters:** + +- **callback_id** (Union[str, Pattern]) – The callback id to identify the function +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. +- **auto_acknowledge** (bool) – Whether Bolt automatically acknowledges the function execution event on the +listener's behalf. When False, your listener must call `ack()` itself within `ack_timeout` +seconds (Default: True). +- **ack_timeout** (int) – The number of seconds to wait for the listener to call `ack()`. +Only takes effect when `auto_acknowledge` is False (Default: 3). + +### `global_shortcut` + +```python +global_shortcut(callback_id, matchers=None, middleware=None) +``` + +Registers a new global shortcut listener. + +### `installation_store` + +```python +installation_store: Optional[AsyncInstallationStore] +``` -- `event` _Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]]_ - The conditions that match a request payload. - If you pass a dict for this, you can have type, subtype in the constraint. -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +The `slack_sdk.oauth.AsyncInstallationStore` that can be used in the `authorize` middleware. -#### message +### `listener_runner` ```python -def message( - keyword: Union[str, Pattern] = '', - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +listener_runner: AsyncioListenerRunner +``` + +The asyncio-based executor for asynchronously running listeners. + +### `logger` + +```python +logger: logging.Logger +``` + +The logger this app uses. + +### `message` + +```python +message(keyword='', matchers=None, middleware=None) ``` Registers a new message event listener. This method can be used as either a decorator or a method. @@ -440,104 +392,130 @@ Refer to https://docs.slack.dev/reference/events/message/ for details of `messag To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `keyword` _Union[str, Pattern]_ - The keyword to match -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **keyword** (Union[str, Pattern]) – The keyword to match +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### function +### `message_shortcut` ```python -def function( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None, - auto_acknowledge: bool = True, - ack_timeout: int = 3) -> Callable[..., Optional[Callable[..., Awaitable[BoltResponse]]]] +message_shortcut(callback_id, matchers=None, middleware=None) ``` -Registers a new Function listener. +Registers a new message shortcut listener. + +### `middleware` + +```python +middleware(*args) +``` + +Registers a new middleware to this app. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.function("reverse") -async def reverse_string(ack: AsyncAck, inputs: dict, complete: AsyncComplete, fail: AsyncFail): - try: - await ack() - string_to_reverse = inputs["stringToReverse"] - await complete({"reverseString": string_to_reverse[::-1]}) - except Exception as e: - await fail(f"Cannot reverse string (error: {e})") - raise e +@app.middleware +async def middleware_func(logger, body, next): + logger.info(f"request body: {body}") + await next() # Pass a function to this method -app.function("reverse")(reverse_string) +app.middleware(middleware_func) ``` To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `callback_id` _Union[str, Pattern]_ - The callback id to identify the function -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. -- `auto_acknowledge` _bool_ - Whether Bolt automatically acknowledges the function execution event on the - listener's behalf. When False, your listener must call `ack()` itself within `ack_timeout` - seconds (Default: True). -- `ack_timeout` _int_ - The number of seconds to wait for the listener to call `ack()`. - Only takes effect when `auto_acknowledge` is False (Default: 3). +- ***args** – A function that works as a global middleware. -#### command +### `name` ```python -def command( - command: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +name: str ``` -Registers a new slash command listener. +The name of this app (default: the filename). + +### `oauth_flow` + +```python +oauth_flow: Optional[AsyncOAuthFlow] +``` + +Configured `OAuthFlow` object if exists. + +### `options` + +```python +options(constraints, matchers=None, middleware=None) +``` + +Registers a new options listener. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.command("/echo") -async def repeat_text(ack, say, command): - # Acknowledge command request - await ack() - await say(f"{command['text']}") +@app.options("menu_selection") +async def show_menu_options(ack): + options = [ + { + "text": {"type": "plain_text", "text": "Option 1"}, + "value": "1-1", + }, + { + "text": {"type": "plain_text", "text": "Option 2"}, + "value": "1-2", + }, + ] + await ack(options=options) # Pass a function to this method -app.command("/echo")(repeat_text) +app.options("menu_selection")(show_menu_options) ``` -Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details of Slash Commands. +Refer to the following documents for details: + +* https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element#external_select +* https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element#external_multi_select To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** + +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `server` + +```python +server(port=3000, path='/slack/events', host=None) +``` + +Configure a web server using AIOHTTP. + +Refer to https://docs.aiohttp.org/ for more details about AIOHTTP. + +**Parameters:** -- `command` _Union[str, Pattern]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **port** (int) – The port to listen on (Default: 3000) +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) +- **host** (Optional[str]) – The hostname to serve the web endpoints. (Default: 0.0.0.0) -#### shortcut +### `shortcut` ```python -def shortcut( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +shortcut(constraints, matchers=None, middleware=None) ``` Registers a new shortcut listener. @@ -566,130 +544,85 @@ Refer to https://docs.slack.dev/interactivity/implementing-shortcuts/ for detail To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload. -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload. +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### global\_shortcut +### `start` ```python -def global_shortcut( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +start(port=3000, path='/slack/events', host=None) ``` -Registers a new global shortcut listener. +Start a web server using AIOHTTP. -#### message\_shortcut +Refer to https://docs.aiohttp.org/ for more details about AIOHTTP. -```python -def message_shortcut( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` +**Parameters:** -Registers a new message shortcut listener. +- **port** (int) – The port to listen on (Default: 3000) +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) +- **host** (Optional[str]) – The hostname to serve the web endpoints. (Default: 0.0.0.0) -#### action +### `step` ```python -def action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +step(callback_id, edit=None, save=None, execute=None) ``` -Registers a new action listener. This method can be used as either a decorator or a method. - -```python -# Use this method as a decorator -@app.action("approve_button") -async def update_message(ack): - await ack() - -# Pass a function to this method -app.action("approve_button")(update_message) -``` - -* Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for actions in `blocks`. -* Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for actions in `attachments`. -* Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for actions in dialogs. - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. - -**Arguments**: - -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. - -#### block\_action - -```python -def block_action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` +Deprecated: register a new step from app listener. -Registers a new `block_actions` action listener. +Steps from apps for legacy workflows are now deprecated. +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for details. +Registers a new step from app listener. -#### attachment\_action +Unlike others, this method doesn't behave as a decorator. +If you want to register a step from app by a decorator, use `AsyncWorkflowStepBuilder`'s methods. ```python -def attachment_action( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +# Create a new WorkflowStep instance +from slack_bolt.workflows.async_step import AsyncWorkflowStep +ws = AsyncWorkflowStep( + callback_id="add_task", + edit=edit, + save=save, + execute=execute, +) +# Pass Step to set up listeners +app.step(ws) ``` -Registers a new `interactive_message` action listener. - -Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for details. - -#### dialog\_submission +Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details of steps from apps. -```python -def dialog_submission( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. +For further information about AsyncWorkflowStep specific function arguments +such as `configure`, `update`, `complete`, and `fail`, +refer to the `async` prefixed ones in `slack_bolt.workflows.step.utilities` API documents. -Registers a new `dialog_submission` listener. +**Parameters:** -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. +- **callback_id** (Union[str, Pattern, AsyncWorkflowStep, AsyncWorkflowStepBuilder]) – The Callback ID for this step from app +- **edit** (Optional[Union[Callable..., [Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]) – The function for displaying a modal in the Workflow Builder +- **save** (Optional[Union[Callable..., [Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]) – The function for handling configuration in the Workflow Builder +- **execute** (Optional[Union[Callable..., [Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]) – The function for handling the step execution -#### dialog\_cancellation +### `use` ```python -def dialog_cancellation( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +use(*args) ``` -Registers a new `dialog_cancellation` listener. - -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. +Refer to `AsyncApp#middleware()` method's docstring for details. -#### view +### `view` ```python -def view( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +view(constraints, matchers=None, middleware=None) ``` Registers a new `view_submission`/`view_closed` event listener. @@ -722,129 +655,59 @@ Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### view\_submission +### `view_closed` ```python -def view_submission( - constraints: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` - -Registers a new `view_submission` listener. - -Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_submission for -details. - -#### view\_closed - -```python -def view_closed( - constraints: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +view_closed(constraints, matchers=None, middleware=None) ``` Registers a new `view_closed` listener. Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_closed for details. -#### options +### `view_submission` ```python -def options( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` - -Registers a new options listener. - -This method can be used as either a decorator or a method. - -```python -# Use this method as a decorator -@app.options("menu_selection") -async def show_menu_options(ack): - options = [ - { - "text": {"type": "plain_text", "text": "Option 1"}, - "value": "1-1", - }, - { - "text": {"type": "plain_text", "text": "Option 2"}, - "value": "1-2", - }, - ] - await ack(options=options) - -# Pass a function to this method -app.options("menu_selection")(show_menu_options) +view_submission(constraints, matchers=None, middleware=None) ``` -Refer to the following documents for details: - -* https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element#external_select -* https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element#external_multi_select - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. - -**Arguments**: +Registers a new `view_submission` listener. -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_submission for +details. -#### block\_suggestion +### `web_app` ```python -def block_suggestion( - action_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +web_app(path='/slack/events', port=3000) ``` -Registers a new `block_suggestion` listener. - -#### dialog\_suggestion +Returns a `web.Application` instance for aiohttp-devtools users. ```python -def dialog_suggestion( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` - -Registers a new `dialog_suggestion` listener. - -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. - -#### default\_tokens\_revoked\_event\_listener +from slack_bolt.async_app import AsyncApp +app = AsyncApp() -```python -def default_tokens_revoked_event_listener( -) -> Callable[..., Awaitable[Optional[BoltResponse]]] -``` +@app.event("app_mention") +async def event_test(body, say, logger): + logger.info(body) + await say("What's up?") -#### default\_app\_uninstalled\_event\_listener +def app_factory(): + return app.web_app() -```python -def default_app_uninstalled_event_listener( -) -> Callable[..., Awaitable[Optional[BoltResponse]]] +# adev runserver --port 3000 --app-factory app_factory async_app.py ``` -#### enable\_token\_revocation\_listeners +**Parameters:** -```python -def enable_token_revocation_listeners() -> None -``` +- **path** (str) – The path to receive incoming requests from Slack +- **port** (int) – The port to listen on (Default: 3000) diff --git a/docs/english/reference/app/async_server.md b/docs/english/reference/app/async_server.md index 9735d9adc..4c218e90f 100644 --- a/docs/english/reference/app/async_server.md +++ b/docs/english/reference/app/async_server.md @@ -3,55 +3,27 @@ sidebar_label: async_server title: slack_bolt.app.async_server --- -## AsyncSlackAppServer Objects +## `AsyncSlackAppServer` ```python -class AsyncSlackAppServer() -``` - -#### port: `int` - -#### path: `str` - -#### host: `str` - -#### bolt\_app: `AsyncApp` - -#### web\_app: `web.Application` - -#### \_\_init\_\_ - -```python -def __init__(port: int, path: str, app: AsyncApp, host: Optional[str] = None) +AsyncSlackAppServer(port, path, app, host=None) ``` Standalone AIOHTTP Web Server. Refer to https://docs.aiohttp.org/en/stable/web.html for details of AIOHTTP. -**Arguments**: +**Parameters:** -- `port` _int_ - The port to listen on -- `path` _str_ - The path to receive incoming requests from Slack -- `app` _AsyncApp_ - The `AsyncApp` instance that is used for processing requests -- `host` _Optional[str]_ - The hostname to serve the web endpoints. (Default: 0.0.0.0) - -#### handle\_get\_requests - -```python -async def handle_get_requests(request: web.Request) -> web.Response -``` - -#### handle\_post\_requests - -```python -async def handle_post_requests(request: web.Request) -> web.Response -``` +- **port** (int) – The port to listen on +- **path** (str) – The path to receive incoming requests from Slack +- **app** (AsyncApp) – The `AsyncApp` instance that is used for processing requests +- **host** (Optional[str]) – The hostname to serve the web endpoints. (Default: 0.0.0.0) -#### start +### `start` ```python -def start(host: Optional[str] = None) -> None +start(host=None) ``` Starts a new web server process. diff --git a/docs/english/reference/app/index.md b/docs/english/reference/app/index.md index 4f1feacb6..e8daeb330 100644 --- a/docs/english/reference/app/index.md +++ b/docs/english/reference/app/index.md @@ -9,48 +9,10 @@ For most use cases, we recommend using `slack_bolt.app.app`. If you already have knowledge about asyncio and prefer the programming model, you can use `slack_bolt.app.async_app` for building async apps. -## Submodules - -- [slack_bolt.app.app](/tools/bolt-python/reference/app/app) -- [slack_bolt.app.async_app](/tools/bolt-python/reference/app/async_app) -- [slack_bolt.app.async_server](/tools/bolt-python/reference/app/async_server) - -## App Objects +## `App` ```python -class App() -``` - -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: Optional[logging.Logger] = None, - name: Optional[str] = None, - process_before_response: bool = False, - raise_error_for_unhandled_request: bool = False, - signing_secret: Optional[str] = None, - token: Optional[str] = None, - token_verification_enabled: bool = True, - client: Optional[WebClient] = None, - before_authorize: Optional[Union[Middleware, Callable[..., Any]]] = None, - authorize: Optional[Callable[..., AuthorizeResult]] = None, - user_facing_authorize_error_message: Optional[str] = None, - installation_store: Optional[InstallationStore] = None, - installation_store_bot_only: Optional[bool] = None, - request_verification_enabled: bool = True, - ignoring_self_events_enabled: bool = True, - ignoring_self_assistant_message_events_enabled: bool = True, - ssl_check_enabled: bool = True, - url_verification_enabled: bool = True, - attaching_function_token_enabled: bool = True, - oauth_settings: Optional[OAuthSettings] = None, - oauth_flow: Optional[OAuthFlow] = None, - verification_token: Optional[str] = None, - listener_executor: Optional[Executor] = None, - assistant_thread_context_store: Optional[AssistantThreadContextStore] = None, - attaching_conversation_kwargs_enabled: bool = True) +App(*, logger=None, name=None, process_before_response=False, raise_error_for_unhandled_request=False, signing_secret=None, token=None, token_verification_enabled=True, client=None, before_authorize=None, authorize=None, user_facing_authorize_error_message=None, installation_store=None, installation_store_bot_only=None, request_verification_enabled=True, ignoring_self_events_enabled=True, ignoring_self_assistant_message_events_enabled=True, ssl_check_enabled=True, url_verification_enabled=True, attaching_function_token_enabled=True, oauth_settings=None, oauth_flow=None, verification_token=None, listener_executor=None, assistant_thread_context_store=None, attaching_conversation_kwargs_enabled=True) ``` Bolt App that provides functionalities to register middleware/listeners. @@ -81,259 +43,210 @@ Refer to https://docs.slack.dev/tools/bolt-python/creating-an-app for details. If you would like to build an OAuth app for enabling the app to run with multiple workspaces, refer to https://docs.slack.dev/tools/bolt-python/concepts/authenticating-oauth to learn how to configure the app. -**Arguments**: - -- `logger` _Optional[logging.Logger]_ - The custom logger that can be used in this app. -- `name` _Optional[str]_ - The application name that will be used in logging. If absent, the source file name will be used. -- `process_before_response` _bool_ - True if this app runs on Function as a Service. (Default: False) -- `raise_error_for_unhandled_request` _bool_ - True if you want to raise exceptions for unhandled requests - and use @app.error listeners instead of - the built-in handler, which pints warning logs and returns 404 to Slack (Default: False) -- `signing_secret` _Optional[str]_ - The Signing Secret value used for verifying requests from Slack. -- `token` _Optional[str]_ - The bot/user access token required only for single-workspace app. -- `token_verification_enabled` _bool_ - Verifies the validity of the given token if True. -- `client` _Optional[WebClient]_ - The singleton `slack_sdk.WebClient` instance for this app. -- `before_authorize` _Optional[Union[Middleware, Callable[..., Any]]]_ - A global middleware that can be executed right before authorize function -- `authorize` _Optional[Callable[..., AuthorizeResult]]_ - The function to authorize an incoming request from Slack - by checking if there is a team/user in the installation data. -- `user_facing_authorize_error_message` _Optional[str]_ - The user-facing error message to display - when the app is installed but the installation is not managed by this app's installation store -- `installation_store` _Optional[InstallationStore]_ - The module offering save/find operations of installation data -- `installation_store_bot_only` _Optional[bool]_ - Use `InstallationStore#find_bot()` if True (Default: False) -- `request_verification_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `RequestVerification` is a built-in middleware that verifies the signature in HTTP Mode requests. - Make sure if it's safe enough when you turn a built-in middleware off. - We strongly recommend using RequestVerification for better security. - If you have a proxy that verifies request signature in front of the Bolt app, - it's totally fine to disable RequestVerification to avoid duplication of work. - Don't turn it off just for easiness of development. -- `ignoring_self_events_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `IgnoringSelfEvents` is a built-in middleware that enables Bolt apps to easily skip the events - generated by this app's bot user (this is useful for avoiding code error causing an infinite loop). -- `ignoring_self_assistant_message_events_enabled` _bool_ - False if you would like to disable the built-in middleware. - `IgnoringSelfEvents` for this app's bot user message events within an assistant thread - This is useful for avoiding code error causing an infinite loop; Default: True -- `url_verification_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `UrlVerification` is a built-in middleware that handles url_verification requests - that verify the endpoint for Events API in HTTP Mode requests. -- `attaching_function_token_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AttachingFunctionToken` is a built-in middleware that injects the just-in-time workflow-execution tokens - when your app receives `function_executed` or interactivity events scoped to a custom step. -- `ssl_check_enabled` _bool_ - bool = False if you would like to disable the built-in middleware (Default: True). - `SslCheck` is a built-in middleware that handles ssl_check requests from Slack. -- `oauth_settings` _Optional[OAuthSettings]_ - The settings related to Slack app installation flow (OAuth flow) -- `oauth_flow` _Optional[OAuthFlow]_ - Instantiated `slack_bolt.oauth.OAuthFlow`. This is always prioritized over oauth_settings. -- `verification_token` _Optional[str]_ - Deprecated verification mechanism. This can be used only for ssl_check requests. -- `listener_executor` _Optional[Executor]_ - Custom executor to run background tasks. If absent, the default `ThreadPoolExecutor` will - be used. -- `assistant_thread_context_store` _Optional[AssistantThreadContextStore]_ - Custom AssistantThreadContext store (Default: the built-in implementation, - which uses a parent message's metadata to store the latest context) -- `attaching_conversation_kwargs_enabled` _bool_ - False if you would like to disable the built-in - middleware (Default: True). `AttachingConversationKwargs` is a built-in middleware that attaches - conversation-specific listener arguments (such as `say`, `set_status`, `say_stream`, and - `set_suggested_prompts`) for assistant thread and direct message events. - -#### name - -```python -@property -def name() -> str +**Parameters:** + +- **logger** (Optional[Logger]) – The custom logger that can be used in this app. +- **name** (Optional[str]) – The application name that will be used in logging. If absent, the source file name will be used. +- **process_before_response** (bool) – True if this app runs on Function as a Service. (Default: False) +- **raise_error_for_unhandled_request** (bool) – True if you want to raise exceptions for unhandled requests +and use @app.error listeners instead of +the built-in handler, which pints warning logs and returns 404 to Slack (Default: False) +- **signing_secret** (Optional[str]) – The Signing Secret value used for verifying requests from Slack. +- **token** (Optional[str]) – The bot/user access token required only for single-workspace app. +- **token_verification_enabled** (bool) – Verifies the validity of the given token if True. +- **client** (Optional[WebClient]) – The singleton `slack_sdk.WebClient` instance for this app. +- **before_authorize** (Optional[Union[Middleware, Callable..., [Any]]]) – A global middleware that can be executed right before authorize function +- **authorize** (Optional[Callable..., [AuthorizeResult]]) – The function to authorize an incoming request from Slack +by checking if there is a team/user in the installation data. +- **user_facing_authorize_error_message** (Optional[str]) – The user-facing error message to display +when the app is installed but the installation is not managed by this app's installation store +- **installation_store** (Optional[InstallationStore]) – The module offering save/find operations of installation data +- **installation_store_bot_only** (Optional[bool]) – Use `InstallationStore#find_bot()` if True (Default: False) +- **request_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`RequestVerification` is a built-in middleware that verifies the signature in HTTP Mode requests. +Make sure if it's safe enough when you turn a built-in middleware off. +We strongly recommend using RequestVerification for better security. +If you have a proxy that verifies request signature in front of the Bolt app, +it's totally fine to disable RequestVerification to avoid duplication of work. +Don't turn it off just for easiness of development. +- **ignoring_self_events_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`IgnoringSelfEvents` is a built-in middleware that enables Bolt apps to easily skip the events +generated by this app's bot user (this is useful for avoiding code error causing an infinite loop). +- **ignoring_self_assistant_message_events_enabled** (bool) – False if you would like to disable the built-in middleware. +`IgnoringSelfEvents` for this app's bot user message events within an assistant thread +This is useful for avoiding code error causing an infinite loop; Default: True +- **url_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`UrlVerification` is a built-in middleware that handles url_verification requests +that verify the endpoint for Events API in HTTP Mode requests. +- **attaching_function_token_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AttachingFunctionToken` is a built-in middleware that injects the just-in-time workflow-execution tokens +when your app receives `function_executed` or interactivity events scoped to a custom step. +- **ssl_check_enabled** (bool) – bool = False if you would like to disable the built-in middleware (Default: True). +`SslCheck` is a built-in middleware that handles ssl_check requests from Slack. +- **oauth_settings** (Optional[OAuthSettings]) – The settings related to Slack app installation flow (OAuth flow) +- **oauth_flow** (Optional[OAuthFlow]) – Instantiated `slack_bolt.oauth.OAuthFlow`. This is always prioritized over oauth_settings. +- **verification_token** (Optional[str]) – Deprecated verification mechanism. This can be used only for ssl_check requests. +- **listener_executor** (Optional[Executor]) – Custom executor to run background tasks. If absent, the default `ThreadPoolExecutor` will +be used. +- **assistant_thread_context_store** (Optional[AssistantThreadContextStore]) – Custom AssistantThreadContext store (Default: the built-in implementation, +which uses a parent message's metadata to store the latest context) +- **attaching_conversation_kwargs_enabled** (bool) – False if you would like to disable the built-in +middleware (Default: True). `AttachingConversationKwargs` is a built-in middleware that attaches +conversation-specific listener arguments (such as `say`, `set_status`, `say_stream`, and +`set_suggested_prompts`) for assistant thread and direct message events. + +### `action` + +```python +action(constraints, matchers=None, middleware=None) ``` -The name of this app (default: the filename). - -#### oauth\_flow - -```python -@property -def oauth_flow() -> Optional[OAuthFlow] -``` - -Configured `OAuthFlow` object if exists. - -#### logger - -```python -@property -def logger() -> logging.Logger -``` - -The logger this app uses. - -#### client +Registers a new action listener. This method can be used as either a decorator or a method. ```python -@property -def client() -> WebClient -``` - -The singleton `slack_sdk.WebClient` instance in this app. - -#### installation\_store +# Use this method as a decorator +@app.action("approve_button") +def update_message(ack): + ack() -```python -@property -def installation_store() -> Optional[InstallationStore] +# Pass a function to this method +app.action("approve_button")(update_message) ``` -The `slack_sdk.oauth.InstallationStore` that can be used in the `authorize` middleware. +* Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for actions in `blocks`. +* Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for actions in `attachments`. +* Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for actions in dialogs. -#### listener\_runner +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -```python -@property -def listener_runner() -> ThreadListenerRunner -``` +**Parameters:** -The thread executor for asynchronously running listeners. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### process\_before\_response +### `attachment_action` ```python -@property -def process_before_response() -> bool +attachment_action(callback_id, matchers=None, middleware=None) ``` -#### start +Registers a new `interactive_message` action listener. -```python -def start( - port: int = 3000, - path: str = '/slack/events', - http_server_logger_enabled: bool = True) -> None -``` +Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for details. -Starts a web server for local development. +### `block_action` ```python -# With the default settings, `http://localhost:3000/slack/events` -# is available for handling incoming requests from Slack -app.start() +block_action(constraints, matchers=None, middleware=None) ``` -This method internally starts a Web server process built with the `http.server` module. -For production, consider using a production-ready WSGI server such as Gunicorn. - -**Arguments**: +Registers a new `block_actions` action listener. -- `port` _int_ - The port to listen on (Default: 3000) -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) -- `http_server_logger_enabled` _bool_ - The flag to enable http.server logging if True (Default: True) +Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for details. -#### dispatch +### `block_suggestion` ```python -def dispatch(req: BoltRequest) -> BoltResponse +block_suggestion(action_id, matchers=None, middleware=None) ``` -Applies all middleware and dispatches an incoming request from Slack to the right code path. - -**Arguments**: - -- `req` _BoltRequest_ - An incoming request from Slack - -**Returns**: - -- `BoltResponse` - The response generated by this Bolt app +Registers a new `block_suggestion` listener. -#### use +### `client` ```python -def use(*args) -> Optional[Callable] +client: WebClient ``` -Registers a new global middleware to this app. This method can be used as either a decorator or a method. - -Refer to `App#middleware()` method's docstring for details. +The singleton `slack_sdk.WebClient` instance in this app. -#### middleware +### `command` ```python -def middleware(*args) -> Optional[Callable] +command(command, matchers=None, middleware=None) ``` -Registers a new middleware to this app. +Registers a new slash command listener. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.middleware -def middleware_func(logger, body, next): - logger.info(f"request body: {body}") - next() +@app.command("/echo") +def repeat_text(ack, say, command): + # Acknowledge command request + ack() + say(f"{command['text']}") # Pass a function to this method -app.middleware(middleware_func) +app.command("/echo")(repeat_text) ``` -Refer to https://docs.slack.dev/tools/bolt-python/concepts/global-middleware for details. +Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details of Slash Commands. To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `*args` - A function that works as a global middleware. +- **command** (Union[str, Pattern]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### assistant +### `dialog_cancellation` ```python -def assistant(assistant: Assistant) -> Optional[Callable] +dialog_cancellation(callback_id, matchers=None, middleware=None) ``` -#### step +Registers a new `dialog_cancellation` listener. + +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. + +### `dialog_submission` ```python -def step( - callback_id: Union[str, Pattern, WorkflowStep, WorkflowStepBuilder], - edit: Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]] = None, - save: Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]] = None, - execute: Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]] = None) +dialog_submission(callback_id, matchers=None, middleware=None) ``` -Deprecated: register a new step from app listener. +Registers a new `dialog_submission` listener. -Steps from apps for legacy workflows are now deprecated. -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. -Registers a new step from app listener. +### `dialog_suggestion` -Unlike others, this method doesn't behave as a decorator. -If you want to register a step from app by a decorator, use `WorkflowStepBuilder`'s methods. +```python +dialog_suggestion(callback_id, matchers=None, middleware=None) +``` + +Registers a new `dialog_suggestion` listener. + +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. + +### `dispatch` ```python -# Create a new WorkflowStep instance -from slack_bolt.workflows.step import WorkflowStep -ws = WorkflowStep( - callback_id="add_task", - edit=edit, - save=save, - execute=execute, -) -# Pass Step to set up listeners -app.step(ws) +dispatch(req) ``` -Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details of steps from apps. +Applies all middleware and dispatches an incoming request from Slack to the right code path. -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. +**Parameters:** -For further information about WorkflowStep specific function arguments -such as `configure`, `update`, `complete`, and `fail`, -refer to `slack_bolt.workflows.step.utilities` API documents. +- **req** (BoltRequest) – An incoming request from Slack -**Arguments**: +**Returns:** -- `callback_id` _Union[str, Pattern, WorkflowStep, WorkflowStepBuilder]_ - The Callback ID for this step from app -- `edit` _Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]]_ - The function for displaying a modal in the Workflow Builder -- `save` _Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]]_ - The function for handling configuration in the Workflow Builder -- `execute` _Optional[Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]]_ - The function for handling the step execution +- BoltResponse – The response generated by this Bolt app -#### error +### `error` ```python -def error( - func: Callable[..., Optional[BoltResponse]]) -> Callable[..., Optional[BoltResponse]] +error(func) ``` Updates the global error handler. This method can be used as either a decorator or a method. @@ -351,18 +264,15 @@ app.error(custom_error_handler) To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `func` _Callable[..., Optional[BoltResponse]]_ - The function that is supposed to be executed - when getting an unhandled error in Bolt app. +- **func** (Callable..., [Optional[BoltResponse]]) – The function that is supposed to be executed +when getting an unhandled error in Bolt app. -#### event +### `event` ```python -def event( - event: Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +event(event, matchers=None, middleware=None) ``` Registers a new event listener. This method can be used as either a decorator or a method. @@ -384,22 +294,92 @@ Refer to https://docs.slack.dev/apis/events-api/ for details of Events API. To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** + +- **event** (Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]]) – The conditions that match a request payload. +If you pass a dict for this, you can have type, subtype in the constraint. +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `function` + +```python +function(callback_id, matchers=None, middleware=None, auto_acknowledge=True, ack_timeout=3) +``` + +Registers a new Function listener. + +This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.function("reverse") +def reverse_string(ack: Ack, inputs: dict, complete: Complete, fail: Fail): + try: + ack() + string_to_reverse = inputs["stringToReverse"] + complete(outputs={"reverseString": string_to_reverse[::-1]}) + except Exception as e: + fail(f"Cannot reverse string (error: {e})") + raise e + +# Pass a function to this method +app.function("reverse")(reverse_string) +``` + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **callback_id** (Union[str, Pattern]) – The callback id to identify the function +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. +- **auto_acknowledge** (bool) – Whether Bolt automatically acknowledges the function execution event on the +listener's behalf. When False, your listener must call `ack()` itself within `ack_timeout` +seconds (Default: True). +- **ack_timeout** (int) – The number of seconds to wait for the listener to call `ack()`. +Only takes effect when `auto_acknowledge` is False (Default: 3). + +### `global_shortcut` + +```python +global_shortcut(callback_id, matchers=None, middleware=None) +``` + +Registers a new global shortcut listener. + +### `installation_store` + +```python +installation_store: Optional[InstallationStore] +``` + +The `slack_sdk.oauth.InstallationStore` that can be used in the `authorize` middleware. + +### `listener_runner` + +```python +listener_runner: ThreadListenerRunner +``` + +The thread executor for asynchronously running listeners. + +### `logger` + +```python +logger: logging.Logger +``` -- `event` _Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]]_ - The conditions that match a request payload. - If you pass a dict for this, you can have type, subtype in the constraint. -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +The logger this app uses. -#### message +### `message` ```python -def message( - keyword: Union[str, Pattern] = '', - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +message(keyword='', matchers=None, middleware=None) ``` Registers a new message event listener. This method can be used as either a decorator or a method. @@ -421,104 +401,116 @@ Refer to https://docs.slack.dev/reference/events/message/ for details of `messag To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `keyword` _Union[str, Pattern]_ - The keyword to match -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **keyword** (Union[str, Pattern]) – The keyword to match +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### function +### `message_shortcut` ```python -def function( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None, - auto_acknowledge: bool = True, - ack_timeout: int = 3) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +message_shortcut(callback_id, matchers=None, middleware=None) ``` -Registers a new Function listener. +Registers a new message shortcut listener. + +### `middleware` + +```python +middleware(*args) +``` + +Registers a new middleware to this app. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.function("reverse") -def reverse_string(ack: Ack, inputs: dict, complete: Complete, fail: Fail): - try: - ack() - string_to_reverse = inputs["stringToReverse"] - complete(outputs={"reverseString": string_to_reverse[::-1]}) - except Exception as e: - fail(f"Cannot reverse string (error: {e})") - raise e +@app.middleware +def middleware_func(logger, body, next): + logger.info(f"request body: {body}") + next() # Pass a function to this method -app.function("reverse")(reverse_string) +app.middleware(middleware_func) ``` +Refer to https://docs.slack.dev/tools/bolt-python/concepts/global-middleware for details. + To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `callback_id` _Union[str, Pattern]_ - The callback id to identify the function -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. -- `auto_acknowledge` _bool_ - Whether Bolt automatically acknowledges the function execution event on the - listener's behalf. When False, your listener must call `ack()` itself within `ack_timeout` - seconds (Default: True). -- `ack_timeout` _int_ - The number of seconds to wait for the listener to call `ack()`. - Only takes effect when `auto_acknowledge` is False (Default: 3). +- ***args** – A function that works as a global middleware. -#### command +### `name` ```python -def command( - command: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +name: str ``` -Registers a new slash command listener. +The name of this app (default: the filename). + +### `oauth_flow` + +```python +oauth_flow: Optional[OAuthFlow] +``` + +Configured `OAuthFlow` object if exists. + +### `options` + +```python +options(constraints, matchers=None, middleware=None) +``` + +Registers a new options listener. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.command("/echo") -def repeat_text(ack, say, command): - # Acknowledge command request - ack() - say(f"{command['text']}") +@app.options("menu_selection") +def show_menu_options(ack): + options = [ + { + "text": {"type": "plain_text", "text": "Option 1"}, + "value": "1-1", + }, + { + "text": {"type": "plain_text", "text": "Option 2"}, + "value": "1-2", + }, + ] + ack(options=options) # Pass a function to this method -app.command("/echo")(repeat_text) +app.options("menu_selection")(show_menu_options) ``` -Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details of Slash Commands. +Refer to the following documents for details: + +* https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element#external_select +* https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element#external_multi_select To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `command` _Union[str, Pattern]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### shortcut +### `shortcut` ```python -def shortcut( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +shortcut(constraints, matchers=None, middleware=None) ``` Registers a new shortcut listener. @@ -547,130 +539,95 @@ Refer to https://docs.slack.dev/interactivity/implementing-shortcuts/ for detail To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: +**Parameters:** -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload. -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload. +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### global\_shortcut +### `start` ```python -def global_shortcut( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +start(port=3000, path='/slack/events', http_server_logger_enabled=True) ``` -Registers a new global shortcut listener. - -#### message\_shortcut +Starts a web server for local development. ```python -def message_shortcut( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +# With the default settings, `http://localhost:3000/slack/events` +# is available for handling incoming requests from Slack +app.start() ``` -Registers a new message shortcut listener. +This method internally starts a Web server process built with the `http.server` module. +For production, consider using a production-ready WSGI server such as Gunicorn. -#### action +**Parameters:** -```python -def action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` +- **port** (int) – The port to listen on (Default: 3000) +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) +- **http_server_logger_enabled** (bool) – The flag to enable http.server logging if True (Default: True) -Registers a new action listener. This method can be used as either a decorator or a method. +### `step` ```python -# Use this method as a decorator -@app.action("approve_button") -def update_message(ack): - ack() - -# Pass a function to this method -app.action("approve_button")(update_message) +step(callback_id, edit=None, save=None, execute=None) ``` -* Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for actions in `blocks`. -* Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for actions in `attachments`. -* Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for actions in dialogs. - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. - -**Arguments**: - -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. - -#### block\_action - -```python -def block_action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` +Deprecated: register a new step from app listener. -Registers a new `block_actions` action listener. +Steps from apps for legacy workflows are now deprecated. +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for details. +Registers a new step from app listener. -#### attachment\_action +Unlike others, this method doesn't behave as a decorator. +If you want to register a step from app by a decorator, use `WorkflowStepBuilder`'s methods. ```python -def attachment_action( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +# Create a new WorkflowStep instance +from slack_bolt.workflows.step import WorkflowStep +ws = WorkflowStep( + callback_id="add_task", + edit=edit, + save=save, + execute=execute, +) +# Pass Step to set up listeners +app.step(ws) ``` -Registers a new `interactive_message` action listener. - -Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for details. +Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details of steps from apps. -#### dialog\_submission +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -```python -def dialog_submission( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` +For further information about WorkflowStep specific function arguments +such as `configure`, `update`, `complete`, and `fail`, +refer to `slack_bolt.workflows.step.utilities` API documents. -Registers a new `dialog_submission` listener. +**Parameters:** -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. +- **callback_id** (Union[str, Pattern, WorkflowStep, WorkflowStepBuilder]) – The Callback ID for this step from app +- **edit** (Optional[Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]]) – The function for displaying a modal in the Workflow Builder +- **save** (Optional[Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]]) – The function for handling configuration in the Workflow Builder +- **execute** (Optional[Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]]) – The function for handling the step execution -#### dialog\_cancellation +### `use` ```python -def dialog_cancellation( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +use(*args) ``` -Registers a new `dialog_cancellation` listener. +Registers a new global middleware to this app. This method can be used as either a decorator or a method. -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. +Refer to `App#middleware()` method's docstring for details. -#### view +### `view` ```python -def view( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +view(constraints, matchers=None, middleware=None) ``` Registers a new `view_submission`/`view_closed` event listener. @@ -703,127 +660,37 @@ Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. -**Arguments**: - -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. - -#### view\_submission +**Parameters:** -```python -def view_submission( - constraints: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` - -Registers a new `view_submission` listener. - -Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_submission for -details. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### view\_closed +### `view_closed` ```python -def view_closed( - constraints: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] +view_closed(constraints, matchers=None, middleware=None) ``` Registers a new `view_closed` listener. Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_closed for details. -#### options - -```python -def options( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` - -Registers a new options listener. - -This method can be used as either a decorator or a method. - -```python -# Use this method as a decorator -@app.options("menu_selection") -def show_menu_options(ack): - options = [ - { - "text": {"type": "plain_text", "text": "Option 1"}, - "value": "1-1", - }, - { - "text": {"type": "plain_text", "text": "Option 2"}, - "value": "1-2", - }, - ] - ack(options=options) - -# Pass a function to this method -app.options("menu_selection")(show_menu_options) -``` - -Refer to the following documents for details: - -* https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element#external_select -* https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element#external_multi_select - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. - -**Arguments**: - -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., bool]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, Middleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. - -#### block\_suggestion - -```python -def block_suggestion( - action_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` - -Registers a new `block_suggestion` listener. - -#### dialog\_suggestion - -```python -def dialog_suggestion( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., bool]]] = None, - middleware: Optional[Sequence[Union[Callable, Middleware]]] = None) -> Callable[..., Optional[Callable[..., Optional[BoltResponse]]]] -``` - -Registers a new `dialog_suggestion` listener. - -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. - -#### default\_tokens\_revoked\_event\_listener +### `view_submission` ```python -def default_tokens_revoked_event_listener() -> Callable[..., Optional[BoltResponse]] +view_submission(constraints, matchers=None, middleware=None) ``` -#### default\_app\_uninstalled\_event\_listener +Registers a new `view_submission` listener. -```python -def default_app_uninstalled_event_listener() -> Callable[..., Optional[BoltResponse]] -``` +Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_submission for +details. -#### enable\_token\_revocation\_listeners +## Submodules -```python -def enable_token_revocation_listeners() -> None -``` +- [slack_bolt.app.app](/tools/bolt-python/reference/app/app) +- [slack_bolt.app.async_app](/tools/bolt-python/reference/app/async_app) +- [slack_bolt.app.async_server](/tools/bolt-python/reference/app/async_server) diff --git a/docs/english/reference/async_app.md b/docs/english/reference/async_app.md index d8ea85f10..f088c63b9 100644 --- a/docs/english/reference/async_app.md +++ b/docs/english/reference/async_app.md @@ -49,40 +49,10 @@ Apps can be run the same way as the synchronous example above. If you'd prefer a Refer to `slack_bolt.app.async_app` for more details. -## AsyncApp Objects - -```python -class AsyncApp() -``` - -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: Optional[logging.Logger] = None, - name: Optional[str] = None, - process_before_response: bool = False, - raise_error_for_unhandled_request: bool = False, - signing_secret: Optional[str] = None, - token: Optional[str] = None, - client: Optional[AsyncWebClient] = None, - before_authorize: Optional[Union[AsyncMiddleware, Callable[..., Awaitable[Any]]]] = None, - authorize: Optional[Callable[..., Awaitable[AuthorizeResult]]] = None, - user_facing_authorize_error_message: Optional[str] = None, - installation_store: Optional[AsyncInstallationStore] = None, - installation_store_bot_only: Optional[bool] = None, - request_verification_enabled: bool = True, - ignoring_self_events_enabled: bool = True, - ignoring_self_assistant_message_events_enabled: bool = True, - ssl_check_enabled: bool = True, - url_verification_enabled: bool = True, - attaching_function_token_enabled: bool = True, - oauth_settings: Optional[AsyncOAuthSettings] = None, - oauth_flow: Optional[AsyncOAuthFlow] = None, - verification_token: Optional[str] = None, - assistant_thread_context_store: Optional[AsyncAssistantThreadContextStore] = None, - attaching_conversation_kwargs_enabled: bool = True) +## `AsyncApp` + +```python +AsyncApp(*, logger=None, name=None, process_before_response=False, raise_error_for_unhandled_request=False, signing_secret=None, token=None, client=None, before_authorize=None, authorize=None, user_facing_authorize_error_message=None, installation_store=None, installation_store_bot_only=None, request_verification_enabled=True, ignoring_self_events_enabled=True, ignoring_self_assistant_message_events_enabled=True, ssl_check_enabled=True, url_verification_enabled=True, attaching_function_token_enabled=True, oauth_settings=None, oauth_flow=None, verification_token=None, assistant_thread_context_store=None, attaching_conversation_kwargs_enabled=True) ``` Bolt App that provides functionalities to register middleware/listeners. @@ -113,292 +83,207 @@ Refer to https://docs.slack.dev/tools/bolt-python/concepts/async for details. If you would like to build an OAuth app for enabling the app to run with multiple workspaces, refer to https://docs.slack.dev/tools/bolt-python/concepts/authenticating-oauth to learn how to configure the app. -**Arguments**: - -- `logger` _Optional[logging.Logger]_ - The custom logger that can be used in this app. -- `name` _Optional[str]_ - The application name that will be used in logging. If absent, the source file name will be used. -- `process_before_response` _bool_ - True if this app runs on Function as a Service. (Default: False) -- `raise_error_for_unhandled_request` _bool_ - True if you want to raise exceptions for unhandled requests - and use @app.error listeners instead of - the built-in handler, which pints warning logs and returns 404 to Slack (Default: False) -- `signing_secret` _Optional[str]_ - The Signing Secret value used for verifying requests from Slack. -- `token` _Optional[str]_ - The bot/user access token required only for single-workspace app. -- `client` _Optional[AsyncWebClient]_ - The singleton `slack_sdk.web.async_client.AsyncWebClient` instance for this app. -- `before_authorize` _Optional[Union[AsyncMiddleware, Callable[..., Awaitable[Any]]]]_ - A global middleware that can be executed right before authorize function -- `authorize` _Optional[Callable[..., Awaitable[AuthorizeResult]]]_ - The function to authorize an incoming request from Slack - by checking if there is a team/user in the installation data. -- `user_facing_authorize_error_message` _Optional[str]_ - The user-facing error message to display - when the app is installed but the installation is not managed by this app's installation store -- `installation_store` _Optional[AsyncInstallationStore]_ - The module offering save/find operations of installation data -- `installation_store_bot_only` _Optional[bool]_ - Use `AsyncInstallationStore#async_find_bot()` if True (Default: False) -- `request_verification_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AsyncRequestVerification` is a built-in middleware that verifies the signature in HTTP Mode requests. - Make sure if it's safe enough when you turn a built-in middleware off. - We strongly recommend using RequestVerification for better security. - If you have a proxy that verifies request signature in front of the Bolt app, - it's totally fine to disable RequestVerification to avoid duplication of work. - Don't turn it off just for easiness of development. -- `ignoring_self_events_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AsyncIgnoringSelfEvents` is a built-in middleware that enables Bolt apps to easily skip the events - generated by this app's bot user (this is useful for avoiding code error causing an infinite loop). -- `ignoring_self_assistant_message_events_enabled` _bool_ - False if you would like to disable the built-in middleware. - `IgnoringSelfEvents` for this app's bot user message events within an assistant thread - This is useful for avoiding code error causing an infinite loop; Default: True -- `url_verification_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AsyncUrlVerification` is a built-in middleware that handles url_verification requests - that verify the endpoint for Events API in HTTP Mode requests. -- `ssl_check_enabled` _bool_ - bool = False if you would like to disable the built-in middleware (Default: True). - `AsyncSslCheck` is a built-in middleware that handles ssl_check requests from Slack. -- `attaching_function_token_enabled` _bool_ - False if you would like to disable the built-in middleware (Default: True). - `AsyncAttachingFunctionToken` is a built-in middleware that injects the just-in-time workflow-execution token - when your app receives `function_executed` or interactivity events scoped to a custom step. -- `oauth_settings` _Optional[AsyncOAuthSettings]_ - The settings related to Slack app installation flow (OAuth flow) -- `oauth_flow` _Optional[AsyncOAuthFlow]_ - Instantiated `slack_bolt.oauth.AsyncOAuthFlow`. This is always prioritized over oauth_settings. -- `verification_token` _Optional[str]_ - Deprecated verification mechanism. This can be used only for ssl_check requests. -- `assistant_thread_context_store` _Optional[AsyncAssistantThreadContextStore]_ - Custom AssistantThreadContext store (Default: the built-in implementation, - which uses a parent message's metadata to store the latest context) -- `attaching_conversation_kwargs_enabled` _bool_ - False if you would like to disable the built-in - middleware (Default: True). `AttachingConversationKwargs` is a built-in middleware that attaches - conversation-specific listener arguments (such as `say`, `set_status`, `say_stream`, and - `set_suggested_prompts`) for assistant thread and direct message events. - -#### name - -```python -@property -def name() -> str -``` - -The name of this app (default: the filename). - -#### oauth\_flow - -```python -@property -def oauth_flow() -> Optional[AsyncOAuthFlow] -``` - -Configured `OAuthFlow` object if exists. - -#### client - -```python -@property -def client() -> AsyncWebClient +**Parameters:** + +- **logger** (Optional[Logger]) – The custom logger that can be used in this app. +- **name** (Optional[str]) – The application name that will be used in logging. If absent, the source file name will be used. +- **process_before_response** (bool) – True if this app runs on Function as a Service. (Default: False) +- **raise_error_for_unhandled_request** (bool) – True if you want to raise exceptions for unhandled requests +and use @app.error listeners instead of +the built-in handler, which pints warning logs and returns 404 to Slack (Default: False) +- **signing_secret** (Optional[str]) – The Signing Secret value used for verifying requests from Slack. +- **token** (Optional[str]) – The bot/user access token required only for single-workspace app. +- **client** (Optional[AsyncWebClient]) – The singleton `slack_sdk.web.async_client.AsyncWebClient` instance for this app. +- **before_authorize** (Optional[Union[AsyncMiddleware, Callable..., [Awaitable[Any]]]]) – A global middleware that can be executed right before authorize function +- **authorize** (Optional[Callable..., [Awaitable[AuthorizeResult]]]) – The function to authorize an incoming request from Slack +by checking if there is a team/user in the installation data. +- **user_facing_authorize_error_message** (Optional[str]) – The user-facing error message to display +when the app is installed but the installation is not managed by this app's installation store +- **installation_store** (Optional[AsyncInstallationStore]) – The module offering save/find operations of installation data +- **installation_store_bot_only** (Optional[bool]) – Use `AsyncInstallationStore#async_find_bot()` if True (Default: False) +- **request_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AsyncRequestVerification` is a built-in middleware that verifies the signature in HTTP Mode requests. +Make sure if it's safe enough when you turn a built-in middleware off. +We strongly recommend using RequestVerification for better security. +If you have a proxy that verifies request signature in front of the Bolt app, +it's totally fine to disable RequestVerification to avoid duplication of work. +Don't turn it off just for easiness of development. +- **ignoring_self_events_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AsyncIgnoringSelfEvents` is a built-in middleware that enables Bolt apps to easily skip the events +generated by this app's bot user (this is useful for avoiding code error causing an infinite loop). +- **ignoring_self_assistant_message_events_enabled** (bool) – False if you would like to disable the built-in middleware. +`IgnoringSelfEvents` for this app's bot user message events within an assistant thread +This is useful for avoiding code error causing an infinite loop; Default: True +- **url_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AsyncUrlVerification` is a built-in middleware that handles url_verification requests +that verify the endpoint for Events API in HTTP Mode requests. +- **ssl_check_enabled** (bool) – bool = False if you would like to disable the built-in middleware (Default: True). +`AsyncSslCheck` is a built-in middleware that handles ssl_check requests from Slack. +- **attaching_function_token_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AsyncAttachingFunctionToken` is a built-in middleware that injects the just-in-time workflow-execution token +when your app receives `function_executed` or interactivity events scoped to a custom step. +- **oauth_settings** (Optional[AsyncOAuthSettings]) – The settings related to Slack app installation flow (OAuth flow) +- **oauth_flow** (Optional[AsyncOAuthFlow]) – Instantiated `slack_bolt.oauth.AsyncOAuthFlow`. This is always prioritized over oauth_settings. +- **verification_token** (Optional[str]) – Deprecated verification mechanism. This can be used only for ssl_check requests. +- **assistant_thread_context_store** (Optional[AsyncAssistantThreadContextStore]) – Custom AssistantThreadContext store (Default: the built-in implementation, +which uses a parent message's metadata to store the latest context) +- **attaching_conversation_kwargs_enabled** (bool) – False if you would like to disable the built-in +middleware (Default: True). `AttachingConversationKwargs` is a built-in middleware that attaches +conversation-specific listener arguments (such as `say`, `set_status`, `say_stream`, and +`set_suggested_prompts`) for assistant thread and direct message events. + +### `action` + +```python +action(constraints, matchers=None, middleware=None) ``` -The singleton `slack_sdk.web.async_client.AsyncWebClient` instance in this app. - -#### logger +Registers a new action listener. This method can be used as either a decorator or a method. ```python -@property -def logger() -> logging.Logger -``` - -The logger this app uses. - -#### installation\_store +# Use this method as a decorator +@app.action("approve_button") +async def update_message(ack): + await ack() -```python -@property -def installation_store() -> Optional[AsyncInstallationStore] +# Pass a function to this method +app.action("approve_button")(update_message) ``` -The `slack_sdk.oauth.AsyncInstallationStore` that can be used in the `authorize` middleware. - -#### listener\_runner - -```python -@property -def listener_runner() -> AsyncioListenerRunner -``` +* Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for actions in `blocks`. +* Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for actions in `attachments`. +* Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for actions in dialogs. -The asyncio-based executor for asynchronously running listeners. +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -#### process\_before\_response +**Parameters:** -```python -@property -def process_before_response() -> bool -``` +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### server +### `async_dispatch` ```python -def server( - port: int = 3000, - path: str = '/slack/events', - host: Optional[str] = None) -> AsyncSlackAppServer +async_dispatch(req) ``` -Configure a web server using AIOHTTP. - -Refer to https://docs.aiohttp.org/ for more details about AIOHTTP. +Applies all middleware and dispatches an incoming request from Slack to the right code path. -**Arguments**: +**Parameters:** -- `port` _int_ - The port to listen on (Default: 3000) -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) -- `host` _Optional[str]_ - The hostname to serve the web endpoints. (Default: 0.0.0.0) +- **req** (AsyncBoltRequest) – An incoming request from Slack. -#### web\_app +**Returns:** -```python -def web_app(path: str = '/slack/events', port: int = 3000) -> web.Application -``` +- BoltResponse – The response generated by this Bolt app. -Returns a `web.Application` instance for aiohttp-devtools users. +### `attachment_action` ```python -from slack_bolt.async_app import AsyncApp -app = AsyncApp() - -@app.event("app_mention") -async def event_test(body, say, logger): - logger.info(body) - await say("What's up?") - -def app_factory(): - return app.web_app() - -# adev runserver --port 3000 --app-factory app_factory async_app.py +attachment_action(callback_id, matchers=None, middleware=None) ``` +Registers a new `interactive_message` action listener. -**Arguments**: - -- `path` _str_ - The path to receive incoming requests from Slack -- `port` _int_ - The port to listen on (Default: 3000) +Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for details. -#### start +### `block_action` ```python -def start( - port: int = 3000, - path: str = '/slack/events', - host: Optional[str] = None) -> None +block_action(constraints, matchers=None, middleware=None) ``` -Start a web server using AIOHTTP. - -Refer to https://docs.aiohttp.org/ for more details about AIOHTTP. - -**Arguments**: +Registers a new `block_actions` action listener. -- `port` _int_ - The port to listen on (Default: 3000) -- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`) -- `host` _Optional[str]_ - The hostname to serve the web endpoints. (Default: 0.0.0.0) +Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for details. -#### async\_dispatch +### `block_suggestion` ```python -async def async_dispatch(req: AsyncBoltRequest) -> BoltResponse +block_suggestion(action_id, matchers=None, middleware=None) ``` -Applies all middleware and dispatches an incoming request from Slack to the right code path. - -**Arguments**: - -- `req` _AsyncBoltRequest_ - An incoming request from Slack. - -**Returns**: - -- `BoltResponse` - The response generated by this Bolt app. +Registers a new `block_suggestion` listener. -#### use +### `client` ```python -def use(*args) -> Optional[Callable] +client: AsyncWebClient ``` -Refer to `AsyncApp#middleware()` method's docstring for details. +The singleton `slack_sdk.web.async_client.AsyncWebClient` instance in this app. -#### middleware +### `command` ```python -def middleware(*args) -> Optional[Callable] +command(command, matchers=None, middleware=None) ``` -Registers a new middleware to this app. +Registers a new slash command listener. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.middleware -async def middleware_func(logger, body, next): - logger.info(f"request body: {body}") - await next() +@app.command("/echo") +async def repeat_text(ack, say, command): + # Acknowledge command request + await ack() + await say(f"{command['text']}") # Pass a function to this method -app.middleware(middleware_func) +app.command("/echo")(repeat_text) ``` +Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details of Slash Commands. + To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `*args` - A function that works as a global middleware. +- **command** (Union[str, Pattern]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### assistant +### `dialog_cancellation` ```python -def assistant(assistant: AsyncAssistant) -> Optional[Callable] +dialog_cancellation(callback_id, matchers=None, middleware=None) ``` -#### step +Registers a new `dialog_cancellation` listener. + +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. + +### `dialog_submission` ```python -def step( - callback_id: Union[str, Pattern, AsyncWorkflowStep, AsyncWorkflowStepBuilder], - edit: Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]] = None, - save: Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]] = None, - execute: Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]] = None) +dialog_submission(callback_id, matchers=None, middleware=None) ``` -Deprecated: register a new step from app listener. - -Steps from apps for legacy workflows are now deprecated. -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ +Registers a new `dialog_submission` listener. -Registers a new step from app listener. +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. -Unlike others, this method doesn't behave as a decorator. -If you want to register a step from app by a decorator, use `AsyncWorkflowStepBuilder`'s methods. +### `dialog_suggestion` ```python -# Create a new WorkflowStep instance -from slack_bolt.workflows.async_step import AsyncWorkflowStep -ws = AsyncWorkflowStep( - callback_id="add_task", - edit=edit, - save=save, - execute=execute, -) -# Pass Step to set up listeners -app.step(ws) +dialog_suggestion(callback_id, matchers=None, middleware=None) ``` -Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details of steps from apps. - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -For further information about AsyncWorkflowStep specific function arguments -such as `configure`, `update`, `complete`, and `fail`, -refer to the `async` prefixed ones in `slack_bolt.workflows.step.utilities` API documents. - -**Arguments**: +Registers a new `dialog_suggestion` listener. -- `callback_id` _Union[str, Pattern, AsyncWorkflowStep, AsyncWorkflowStepBuilder]_ - The Callback ID for this step from app -- `edit` _Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]_ - The function for displaying a modal in the Workflow Builder -- `save` _Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]_ - The function for handling configuration in the Workflow Builder -- `execute` _Optional[Union[Callable[..., Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]_ - The function for handling the step execution +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. -#### error +### `error` ```python -def error( - func: Callable[..., Awaitable[Optional[BoltResponse]]]) -> Callable[..., Awaitable[Optional[BoltResponse]]] +error(func) ``` Updates the global error handler. This method can be used as either a decorator or a method. @@ -416,18 +301,15 @@ app.error(custom_error_handler) To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `func` _Callable[..., Awaitable[Optional[BoltResponse]]]_ - The function that is supposed to be executed - when getting an unhandled error in Bolt app. +- **func** (Callable..., [Awaitable[Optional[BoltResponse]]]) – The function that is supposed to be executed +when getting an unhandled error in Bolt app. -#### event +### `event` ```python -def event( - event: Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +event(event, matchers=None, middleware=None) ``` Registers a new event listener. This method can be used as either a decorator or a method. @@ -449,60 +331,19 @@ Refer to https://docs.slack.dev/apis/events-api/ for details of Events API. To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: - -- `event` _Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]]_ - The conditions that match a request payload. - If you pass a dict for this, you can have type, subtype in the constraint. -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. - -#### message - -```python -def message( - keyword: Union[str, Pattern] = '', - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` - -Registers a new message event listener. This method can be used as either a decorator or a method. - -Check the `App#event` method's docstring for details. - -```python -# Use this method as a decorator -@app.message(":wave:") -async def say_hello(message, say): - user = message['user'] - await say(f"Hi there, <@{user}>!") - -# Pass a function to this method -app.message(":wave:")(say_hello) -``` - -Refer to https://docs.slack.dev/reference/events/message/ for details of `message` events. - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. - -**Arguments**: +**Parameters:** -- `keyword` _Union[str, Pattern]_ - The keyword to match -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **event** (Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]]) – The conditions that match a request payload. +If you pass a dict for this, you can have type, subtype in the constraint. +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### function +### `function` ```python -def function( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None, - auto_acknowledge: bool = True, - ack_timeout: int = 3) -> Callable[..., Optional[Callable[..., Awaitable[BoltResponse]]]] +function(callback_id, matchers=None, middleware=None, auto_acknowledge=True, ack_timeout=3) ``` Registers a new Function listener. @@ -527,1030 +368,807 @@ app.function("reverse")(reverse_string) To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `callback_id` _Union[str, Pattern]_ - The callback id to identify the function -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. -- `auto_acknowledge` _bool_ - Whether Bolt automatically acknowledges the function execution event on the - listener's behalf. When False, your listener must call `ack()` itself within `ack_timeout` - seconds (Default: True). -- `ack_timeout` _int_ - The number of seconds to wait for the listener to call `ack()`. - Only takes effect when `auto_acknowledge` is False (Default: 3). +- **callback_id** (Union[str, Pattern]) – The callback id to identify the function +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. +- **auto_acknowledge** (bool) – Whether Bolt automatically acknowledges the function execution event on the +listener's behalf. When False, your listener must call `ack()` itself within `ack_timeout` +seconds (Default: True). +- **ack_timeout** (int) – The number of seconds to wait for the listener to call `ack()`. +Only takes effect when `auto_acknowledge` is False (Default: 3). -#### command +### `global_shortcut` ```python -def command( - command: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +global_shortcut(callback_id, matchers=None, middleware=None) ``` -Registers a new slash command listener. +Registers a new global shortcut listener. -This method can be used as either a decorator or a method. +### `installation_store` ```python -# Use this method as a decorator -@app.command("/echo") -async def repeat_text(ack, say, command): - # Acknowledge command request - await ack() - await say(f"{command['text']}") +installation_store: Optional[AsyncInstallationStore] +``` -# Pass a function to this method -app.command("/echo")(repeat_text) +The `slack_sdk.oauth.AsyncInstallationStore` that can be used in the `authorize` middleware. + +### `listener_runner` + +```python +listener_runner: AsyncioListenerRunner ``` -Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details of Slash Commands. +The asyncio-based executor for asynchronously running listeners. -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. +### `logger` -**Arguments**: +```python +logger: logging.Logger +``` -- `command` _Union[str, Pattern]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +The logger this app uses. -#### shortcut +### `message` ```python -def shortcut( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +message(keyword='', matchers=None, middleware=None) ``` -Registers a new shortcut listener. +Registers a new message event listener. This method can be used as either a decorator or a method. -This method can be used as either a decorator or a method. +Check the `App#event` method's docstring for details. ```python # Use this method as a decorator -@app.shortcut("open_modal") -async def open_modal(ack, body, client): - # Acknowledge the command request - await ack() - # Call views_open with the built-in client - await client.views_open( - # Pass a valid trigger_id within 3 seconds of receiving it - trigger_id=body["trigger_id"], - # View payload - view={ ... } - ) +@app.message(":wave:") +async def say_hello(message, say): + user = message['user'] + await say(f"Hi there, <@{user}>!") # Pass a function to this method -app.shortcut("open_modal")(open_modal) +app.message(":wave:")(say_hello) ``` -Refer to https://docs.slack.dev/interactivity/implementing-shortcuts/ for details about Shortcuts. +Refer to https://docs.slack.dev/reference/events/message/ for details of `message` events. To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: - -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload. -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. - -#### global\_shortcut - -```python -def global_shortcut( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` +**Parameters:** -Registers a new global shortcut listener. +- **keyword** (Union[str, Pattern]) – The keyword to match +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### message\_shortcut +### `message_shortcut` ```python -def message_shortcut( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +message_shortcut(callback_id, matchers=None, middleware=None) ``` Registers a new message shortcut listener. -#### action +### `middleware` ```python -def action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +middleware(*args) ``` -Registers a new action listener. This method can be used as either a decorator or a method. +Registers a new middleware to this app. + +This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.action("approve_button") -async def update_message(ack): - await ack() +@app.middleware +async def middleware_func(logger, body, next): + logger.info(f"request body: {body}") + await next() # Pass a function to this method -app.action("approve_button")(update_message) +app.middleware(middleware_func) ``` -* Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for actions in `blocks`. -* Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for actions in `attachments`. -* Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for actions in dialogs. - To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- ***args** – A function that works as a global middleware. -#### block\_action +### `name` ```python -def block_action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +name: str ``` -Registers a new `block_actions` action listener. - -Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for details. +The name of this app (default: the filename). -#### attachment\_action +### `oauth_flow` ```python -def attachment_action( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +oauth_flow: Optional[AsyncOAuthFlow] ``` -Registers a new `interactive_message` action listener. - -Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for details. +Configured `OAuthFlow` object if exists. -#### dialog\_submission +### `options` ```python -def dialog_submission( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +options(constraints, matchers=None, middleware=None) ``` -Registers a new `dialog_submission` listener. - -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. +Registers a new options listener. -#### dialog\_cancellation +This method can be used as either a decorator or a method. ```python -def dialog_cancellation( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +# Use this method as a decorator +@app.options("menu_selection") +async def show_menu_options(ack): + options = [ + { + "text": {"type": "plain_text", "text": "Option 1"}, + "value": "1-1", + }, + { + "text": {"type": "plain_text", "text": "Option 2"}, + "value": "1-2", + }, + ] + await ack(options=options) + +# Pass a function to this method +app.options("menu_selection")(show_menu_options) ``` -Registers a new `dialog_cancellation` listener. +Refer to the following documents for details: -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. +* https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element#external_select +* https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element#external_multi_select -#### view +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -```python -def view( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` +**Parameters:** -Registers a new `view_submission`/`view_closed` event listener. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -This method can be used as either a decorator or a method. +### `server` ```python -# Use this method as a decorator -@app.view("view_1") -async def handle_submission(ack, body, client, view): - # Assume there's an input block with `block_c` as the block_id and `dreamy_input` - hopes_and_dreams = view["state"]["values"]["block_c"]["dreamy_input"] - user = body["user"]["id"] - # Validate the inputs - errors = {} - if hopes_and_dreams is not None and len(hopes_and_dreams) <= 5: - errors["block_c"] = "The value must be longer than 5 characters" - if len(errors) > 0: - await ack(response_action="errors", errors=errors) - return # Return early to display the validation errors to the user - # Acknowledge the view_submission event and close the modal - await ack() - # Do whatever you want with the input data - here we're saving it to a DB - -# Pass a function to this method -app.view("view_1")(handle_submission) +server(port=3000, path='/slack/events', host=None) ``` -Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload for details of payloads. - -To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. - -**Arguments**: - -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. - -#### view\_submission - -```python -def view_submission( - constraints: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` - -Registers a new `view_submission` listener. - -Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_submission for -details. - -#### view\_closed +Configure a web server using AIOHTTP. -```python -def view_closed( - constraints: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` +Refer to https://docs.aiohttp.org/ for more details about AIOHTTP. -Registers a new `view_closed` listener. +**Parameters:** -Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_closed for details. +- **port** (int) – The port to listen on (Default: 3000) +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) +- **host** (Optional[str]) – The hostname to serve the web endpoints. (Default: 0.0.0.0) -#### options +### `shortcut` ```python -def options( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +shortcut(constraints, matchers=None, middleware=None) ``` -Registers a new options listener. +Registers a new shortcut listener. This method can be used as either a decorator or a method. ```python # Use this method as a decorator -@app.options("menu_selection") -async def show_menu_options(ack): - options = [ - { - "text": {"type": "plain_text", "text": "Option 1"}, - "value": "1-1", - }, - { - "text": {"type": "plain_text", "text": "Option 2"}, - "value": "1-2", - }, - ] - await ack(options=options) +@app.shortcut("open_modal") +async def open_modal(ack, body, client): + # Acknowledge the command request + await ack() + # Call views_open with the built-in client + await client.views_open( + # Pass a valid trigger_id within 3 seconds of receiving it + trigger_id=body["trigger_id"], + # View payload + view={ ... } + ) # Pass a function to this method -app.options("menu_selection")(show_menu_options) +app.shortcut("open_modal")(open_modal) ``` -Refer to the following documents for details: - -* https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element#external_select -* https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element#external_multi_select +Refer to https://docs.slack.dev/interactivity/implementing-shortcuts/ for details about Shortcuts. To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -**Arguments**: +**Parameters:** -- `constraints` _Union[str, Pattern, Dict[str, Union[str, Pattern]]]_ - The conditions that match a request payload -- `matchers` _Optional[Sequence[Callable[..., Awaitable[bool]]]]_ - A list of listener matcher functions. - Only when all the matchers return True, the listener function can be invoked. -- `middleware` _Optional[Sequence[Union[Callable, AsyncMiddleware]]]_ - A list of lister middleware functions. - Only when all the middleware call `next()` method, the listener function can be invoked. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload. +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -#### block\_suggestion +### `start` ```python -def block_suggestion( - action_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] +start(port=3000, path='/slack/events', host=None) ``` -Registers a new `block_suggestion` listener. - -#### dialog\_suggestion +Start a web server using AIOHTTP. -```python -def dialog_suggestion( - callback_id: Union[str, Pattern], - matchers: Optional[Sequence[Callable[..., Awaitable[bool]]]] = None, - middleware: Optional[Sequence[Union[Callable, AsyncMiddleware]]] = None) -> Callable[..., Optional[Callable[..., Awaitable[Optional[BoltResponse]]]]] -``` +Refer to https://docs.aiohttp.org/ for more details about AIOHTTP. -Registers a new `dialog_suggestion` listener. +**Parameters:** -Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. +- **port** (int) – The port to listen on (Default: 3000) +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) +- **host** (Optional[str]) – The hostname to serve the web endpoints. (Default: 0.0.0.0) -#### default\_tokens\_revoked\_event\_listener +### `step` ```python -def default_tokens_revoked_event_listener( -) -> Callable[..., Awaitable[Optional[BoltResponse]]] +step(callback_id, edit=None, save=None, execute=None) ``` -#### default\_app\_uninstalled\_event\_listener - -```python -def default_app_uninstalled_event_listener( -) -> Callable[..., Awaitable[Optional[BoltResponse]]] -``` +Deprecated: register a new step from app listener. -#### enable\_token\_revocation\_listeners +Steps from apps for legacy workflows are now deprecated. +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -```python -def enable_token_revocation_listeners() -> None -``` +Registers a new step from app listener. -## AsyncAck Objects +Unlike others, this method doesn't behave as a decorator. +If you want to register a step from app by a decorator, use `AsyncWorkflowStepBuilder`'s methods. ```python -class AsyncAck() +# Create a new WorkflowStep instance +from slack_bolt.workflows.async_step import AsyncWorkflowStep +ws = AsyncWorkflowStep( + callback_id="add_task", + edit=edit, + save=save, + execute=execute, +) +# Pass Step to set up listeners +app.step(ws) ``` -#### response: `Optional[BoltResponse]` +Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details of steps from apps. + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. +For further information about AsyncWorkflowStep specific function arguments +such as `configure`, `update`, `complete`, and `fail`, +refer to the `async` prefixed ones in `slack_bolt.workflows.step.utilities` API documents. -#### \_\_init\_\_ +**Parameters:** -```python -def __init__() -``` +- **callback_id** (Union[str, Pattern, AsyncWorkflowStep, AsyncWorkflowStepBuilder]) – The Callback ID for this step from app +- **edit** (Optional[Union[Callable..., [Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]) – The function for displaying a modal in the Workflow Builder +- **save** (Optional[Union[Callable..., [Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]) – The function for handling configuration in the Workflow Builder +- **execute** (Optional[Union[Callable..., [Optional[BoltResponse]], AsyncListener, Sequence[Callable]]]) – The function for handling the step execution -## AsyncBoltContext Objects +### `use` ```python -class AsyncBoltContext(BaseContext) +use(*args) ``` -Context object associated with a request from Slack. +Refer to `AsyncApp#middleware()` method's docstring for details. -#### to\_copyable +### `view` ```python -def to_copyable() -> AsyncBoltContext +view(constraints, matchers=None, middleware=None) ``` -#### listener\_runner +Registers a new `view_submission`/`view_closed` event listener. + +This method can be used as either a decorator or a method. ```python -@property -def listener_runner() -> AsyncioListenerRunner +# Use this method as a decorator +@app.view("view_1") +async def handle_submission(ack, body, client, view): + # Assume there's an input block with `block_c` as the block_id and `dreamy_input` + hopes_and_dreams = view["state"]["values"]["block_c"]["dreamy_input"] + user = body["user"]["id"] + # Validate the inputs + errors = {} + if hopes_and_dreams is not None and len(hopes_and_dreams) <= 5: + errors["block_c"] = "The value must be longer than 5 characters" + if len(errors) > 0: + await ack(response_action="errors", errors=errors) + return # Return early to display the validation errors to the user + # Acknowledge the view_submission event and close the modal + await ack() + # Do whatever you want with the input data - here we're saving it to a DB + +# Pass a function to this method +app.view("view_1")(handle_submission) ``` -The properly configured listener_runner that is available for middleware/listeners. +Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload for details of payloads. -#### client +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.async_args`'s API document. -```python -@property -def client() -> AsyncWebClient -``` +**Parameters:** -The `AsyncWebClient` instance available for this request. +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [Awaitable[bool]]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, AsyncMiddleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. -```python -@app.event("app_mention") -async def handle_events(context): - await context.client.chat_postMessage( - channel=context.channel_id, - text="Thanks!", - ) +### `view_closed` -# You can access "client" this way too. -@app.event("app_mention") -async def handle_events(client, context): - await client.chat_postMessage( - channel=context.channel_id, - text="Thanks!", - ) +```python +view_closed(constraints, matchers=None, middleware=None) ``` +Registers a new `view_closed` listener. -**Returns**: - -- `AsyncWebClient` - `AsyncWebClient` instance +Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_closed for details. -#### ack +### `view_submission` ```python -@property -def ack() -> AsyncAck +view_submission(constraints, matchers=None, middleware=None) ``` -`ack()` function for this request. +Registers a new `view_submission` listener. -```python -@app.action("button") -async def handle_button_clicks(context): - await context.ack() +Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_submission for +details. -# You can access "ack" this way too. -@app.action("button") -async def handle_button_clicks(ack): - await ack() +### `web_app` + +```python +web_app(path='/slack/events', port=3000) ``` +Returns a `web.Application` instance for aiohttp-devtools users. -**Returns**: +```python +from slack_bolt.async_app import AsyncApp +app = AsyncApp() -- `AsyncAck` - Callable `ack()` function +@app.event("app_mention") +async def event_test(body, say, logger): + logger.info(body) + await say("What's up?") -#### say +def app_factory(): + return app.web_app() -```python -@property -def say() -> AsyncSay +# adev runserver --port 3000 --app-factory app_factory async_app.py ``` -`say()` function for this request. - -```python -@app.action("button") -async def handle_button_clicks(context): - await context.ack() - await context.say("Hi!") +**Parameters:** -# You can access "ack" this way too. -@app.action("button") -async def handle_button_clicks(ack, say): - await ack() - await say("Hi!") -``` +- **path** (str) – The path to receive incoming requests from Slack +- **port** (int) – The port to listen on (Default: 3000) +## `AsyncBoltContext` -**Returns**: +Bases: BaseContext -- `AsyncSay` - Callable `say()` function +Context object associated with a request from Slack. -#### respond +### `ack` ```python -@property -def respond() -> Optional[AsyncRespond] +ack: AsyncAck ``` -`respond()` function for this request. +`ack()` function for this request. ```python @app.action("button") async def handle_button_clicks(context): await context.ack() - await context.respond("Hi!") # You can access "ack" this way too. @app.action("button") -async def handle_button_clicks(ack, respond): +async def handle_button_clicks(ack): await ack() - await respond("Hi!") ``` +**Returns:** -**Returns**: - -- `Optional[AsyncRespond]` - Callable `respond()` function +- AsyncAck – Callable `ack()` function -#### complete +### `actor_enterprise_id` ```python -@property -def complete() -> AsyncComplete +actor_enterprise_id: Optional[str] ``` -`complete()` function for this request. +The action's actor's Enterprise Grid organization ID. -Once a custom function's state is set to complete, -any outputs the function returns will be passed along to the next step of its housing workflow, -or complete the workflow if the function is the last step in a workflow. Additionally, -any interactivity handlers associated to a function invocation will no longer be invocable. +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -```python -@app.function("reverse") -async def handle_button_clicks(ack, complete): - await ack() - await complete(outputs={"stringReverse":"olleh"}) +### `actor_team_id` -@app.function("reverse") -async def handle_button_clicks(context): - await context.ack() - await context.complete(outputs={"stringReverse":"olleh"}) +```python +actor_team_id: Optional[str] ``` +The action's actor's workspace ID. -**Returns**: +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -- `AsyncComplete` - Callable `complete()` function - -#### fail +### `actor_user_id` ```python -@property -def fail() -> AsyncFail +actor_user_id: Optional[str] ``` -`fail()` function for this request. +The action's actor's user ID. -Once a custom function's state is set to error, -its housing workflow will be interrupted and any provided error message will be passed -on to the end user through SlackBot. Additionally, any interactivity handlers associated -to a function invocation will no longer be invocable. +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -```python -@app.function("reverse") -async def handle_button_clicks(ack, fail): - await ack() - await fail(error="something went wrong") +### `authorize_result` -@app.function("reverse") -async def handle_button_clicks(context): - await context.ack() - await context.fail(error="something went wrong") +```python +authorize_result: Optional[AuthorizeResult] ``` +The authorize result resolved for this request. -**Returns**: - -- `AsyncFail` - Callable `fail()` function - -#### set\_title +### `bot_id` ```python -@property -def set_title() -> Optional[AsyncSetTitle] +bot_id: Optional[str] ``` -#### set\_status - -```python -@property -def set_status() -> Optional[AsyncSetStatus] -``` +The bot ID resolved for this request. -#### set\_suggested\_prompts +### `bot_token` ```python -@property -def set_suggested_prompts() -> Optional[AsyncSetSuggestedPrompts] +bot_token: Optional[str] ``` -#### get\_thread\_context - -```python -@property -def get_thread_context() -> Optional[AsyncGetThreadContext] -``` +The bot token resolved for this request. -#### say\_stream +### `bot_user_id` ```python -@property -def say_stream() -> Optional[AsyncSayStream] +bot_user_id: Optional[str] ``` -#### save\_thread\_context - -```python -@property -def save_thread_context() -> Optional[AsyncSaveThreadContext] -``` +The bot user ID resolved for this request. -## AsyncRespond Objects +### `channel_id` ```python -class AsyncRespond() +channel_id: Optional[str] ``` -#### response\_url: `Optional[str]` - -#### proxy: `Optional[str]` - -#### ssl: `Optional[SSLContext]` +The conversation ID associated with this request. -#### \_\_init\_\_ +### `client` ```python -def __init__( - *, - response_url: Optional[str], - proxy: Optional[str] = None, - ssl: Optional[SSLContext] = None) +client: AsyncWebClient ``` -## AsyncSay Objects +The `AsyncWebClient` instance available for this request. ```python -class AsyncSay() -``` - -#### client: `Optional[AsyncWebClient]` - -#### channel: `Optional[str]` - -#### thread\_ts: `Optional[str]` +@app.event("app_mention") +async def handle_events(context): + await context.client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", + ) -#### build\_metadata: `Optional[Callable[[], Awaitable[Union[Dict, Metadata]]]]` +# You can access "client" this way too. +@app.event("app_mention") +async def handle_events(client, context): + await client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", + ) +``` -#### \_\_init\_\_ +**Returns:** -```python -def __init__( - client: Optional[AsyncWebClient], - channel: Optional[str], - thread_ts: Optional[str] = None, - build_metadata: Optional[Callable[[], Awaitable[Union[Dict, Metadata]]]] = None) -``` +- AsyncWebClient – `AsyncWebClient` instance -## AsyncListener Objects +### `complete` ```python -class AsyncListener() +complete: AsyncComplete ``` -#### matchers: `Sequence[AsyncListenerMatcher]` +`complete()` function for this request. -#### middleware: `Sequence[AsyncMiddleware]` +Once a custom function's state is set to complete, +any outputs the function returns will be passed along to the next step of its housing workflow, +or complete the workflow if the function is the last step in a workflow. Additionally, +any interactivity handlers associated to a function invocation will no longer be invocable. -#### ack\_function: `Callable[..., Awaitable[BoltResponse]]` +```python +@app.function("reverse") +async def handle_button_clicks(ack, complete): + await ack() + await complete(outputs={"stringReverse":"olleh"}) -#### lazy\_functions: `Sequence[Callable[..., Awaitable[None]]]` +@app.function("reverse") +async def handle_button_clicks(context): + await context.ack() + await context.complete(outputs={"stringReverse":"olleh"}) +``` -#### auto\_acknowledgement: `bool` +**Returns:** -#### ack\_timeout: `int` +- AsyncComplete – Callable `complete()` function -#### async\_matches +### `enterprise_id` ```python -async def async_matches(*, req: AsyncBoltRequest, resp: BoltResponse) -> bool +enterprise_id: Optional[str] ``` -#### run\_async\_middleware +The Enterprise Grid Organization ID of this request. + +### `fail` ```python -async def run_async_middleware( - *, - req: AsyncBoltRequest, - resp: BoltResponse) -> Tuple[Optional[BoltResponse], bool] +fail: AsyncFail ``` -Runs an async middleware. - -**Arguments**: - -- `req` _AsyncBoltRequest_ - The incoming request -- `resp` _BoltResponse_ - The current response - -**Returns**: - -- `Tuple[Optional[BoltResponse], bool]` - A tuple of the processed response and a flag indicating termination +`fail()` function for this request. -#### run\_ack\_function +Once a custom function's state is set to error, +its housing workflow will be interrupted and any provided error message will be passed +on to the end user through SlackBot. Additionally, any interactivity handlers associated +to a function invocation will no longer be invocable. ```python -async def run_ack_function( - *, - request: AsyncBoltRequest, - response: BoltResponse) -> Optional[BoltResponse] -``` - -Runs all the registered middleware and then run the listener function. - -**Arguments**: +@app.function("reverse") +async def handle_button_clicks(ack, fail): + await ack() + await fail(error="something went wrong") -- `request` _AsyncBoltRequest_ - The incoming request -- `response` _BoltResponse_ - The current response +@app.function("reverse") +async def handle_button_clicks(context): + await context.ack() + await context.fail(error="something went wrong") +``` -**Returns**: +**Returns:** -- `Optional[BoltResponse]` - The processed response +- AsyncFail – Callable `fail()` function -## AsyncCustomListenerMatcher Objects +### `function_bot_access_token` ```python -class AsyncCustomListenerMatcher(AsyncListenerMatcher) +function_bot_access_token: Optional[str] ``` -#### app\_name: `str` - -#### func: `Callable[..., Awaitable[bool]]` - -#### arg\_names: `Sequence[str]` +The bot token resolved for this function request. -#### logger: `Logger` +Only available for `function_executed` and interactivity events scoped to a custom step. -#### \_\_init\_\_ +### `function_execution_id` ```python -def __init__( - *, - app_name: str, - func: Callable[..., Awaitable[bool]], - base_logger: Optional[Logger] = None) +function_execution_id: Optional[str] ``` -#### async\_matches +The `function_execution_id` associated with this request. -```python -async def async_matches(req: AsyncBoltRequest, resp: BoltResponse) -> bool -``` +Only available for `function_executed` and interactivity events scoped to a custom step. -## AsyncBoltRequest Objects +### `inputs` ```python -class AsyncBoltRequest() +inputs: Optional[Dict[str, Any]] ``` -#### raw\_body: `str` - -#### body: `Dict[str, Any]` - -#### query: `Dict[str, Sequence[str]]` - -#### headers: `Dict[str, Sequence[str]]` - -#### content\_type: `Optional[str]` +The `inputs` associated with this request. -#### context: `AsyncBoltContext` +Only available for `function_executed` and interactivity events scoped to a custom step. -#### lazy\_only: `bool` - -#### lazy\_function\_name: `Optional[str]` - -#### mode: `str` - -#### \_\_init\_\_ +### `is_enterprise_install` ```python -def __init__( - *, - body: Union[str, dict], - query: Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]] = None, - headers: Optional[Dict[str, Union[str, Sequence[str]]]] = None, - context: Optional[Dict[str, Any]] = None, - mode: str = 'http') +is_enterprise_install: Optional[bool] ``` -Request to a Bolt app. - -**Arguments**: - -- `body` _Union[str, dict]_ - The raw request body (only plain text is supported for "http" mode) -- `query` _Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]_ - The query string data in any data format. -- `headers` _Optional[Dict[str, Union[str, Sequence[str]]]]_ - The request headers. -- `context` _Optional[Dict[str, Any]]_ - The context in this request. -- `mode` _str_ - The mode used for this request. (either "http" or "socket_mode") +True if the request is associated with an Org-wide installation. -#### to\_copyable +### `listener_runner` ```python -def to_copyable() -> AsyncBoltRequest +listener_runner: AsyncioListenerRunner ``` -## AsyncAssistant Objects +The properly configured listener_runner that is available for middleware/listeners. + +### `logger` ```python -class AsyncAssistant(AsyncMiddleware) +logger: Logger ``` -#### thread\_context\_store: `Optional[AsyncAssistantThreadContextStore]` - -#### base\_logger: `Optional[logging.Logger]` +The properly configured logger that is available for middleware/listeners. -#### \_\_init\_\_ +### `matches` ```python -def __init__( - *, - app_name: str = 'assistant', - thread_context_store: Optional[AsyncAssistantThreadContextStore] = None, - logger: Optional[logging.Logger] = None) +matches: Optional[Tuple] ``` -#### thread\_started +Returns all the matched parts in message listener's regexp. -```python -def thread_started( - *args, - matchers: Optional[Union[Callable[..., bool], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### user\_message +### `respond` ```python -def user_message( - *args, - matchers: Optional[Union[Callable[..., bool], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) +respond: Optional[AsyncRespond] ``` -#### bot\_message +`respond()` function for this request. ```python -def bot_message( - *args, - matchers: Optional[Union[Callable[..., bool], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### thread\_context\_changed +@app.action("button") +async def handle_button_clicks(context): + await context.ack() + await context.respond("Hi!") -```python -def thread_context_changed( - *args, - matchers: Optional[Union[Callable[..., bool], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) +# You can access "ack" this way too. +@app.action("button") +async def handle_button_clicks(ack, respond): + await ack() + await respond("Hi!") ``` -#### default\_thread\_context\_changed +**Returns:** -```python -async def default_thread_context_changed( - save_thread_context: AsyncSaveThreadContext, - payload: dict) -``` +- Optional[AsyncRespond] – Callable `respond()` function -#### async\_process +### `response_url` ```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> Optional[BoltResponse] +response_url: Optional[str] ``` -#### build\_listener +The `response_url` associated with this request. + +### `say` ```python -def build_listener( - listener_or_functions: Union[AsyncListener, Callable, List[Callable]], - matchers: Optional[List[Union[AsyncListenerMatcher, Callable[..., Awaitable[bool]]]]] = None, - middleware: Optional[List[AsyncMiddleware]] = None, - base_logger: Optional[Logger] = None) -> AsyncListener +say: AsyncSay ``` -## AsyncSetStatus Objects +`say()` function for this request. ```python -class AsyncSetStatus() -``` +@app.action("button") +async def handle_button_clicks(context): + await context.ack() + await context.say("Hi!") -#### client: `AsyncWebClient` +# You can access "ack" this way too. +@app.action("button") +async def handle_button_clicks(ack, say): + await ack() + await say("Hi!") +``` -#### channel\_id: `str` +**Returns:** -#### thread\_ts: `str` +- AsyncSay – Callable `say()` function -#### \_\_init\_\_ +### `team_id` ```python -def __init__(client: AsyncWebClient, channel_id: str, thread_ts: str) +team_id: Optional[str] ``` -## AsyncSetTitle Objects +The Workspace ID of this request. + +### `thread_ts` ```python -class AsyncSetTitle() +thread_ts: Optional[str] ``` -#### client: `AsyncWebClient` - -#### channel\_id: `str` - -#### thread\_ts: `str` +The conversation thread's ID associated with this request. -#### \_\_init\_\_ +### `token` ```python -def __init__(client: AsyncWebClient, channel_id: str, thread_ts: str) +token: Optional[str] ``` -## AsyncSetSuggestedPrompts Objects +The (bot/user) token resolved for this request. + +### `user_id` ```python -class AsyncSetSuggestedPrompts() +user_id: Optional[str] ``` -#### client: `AsyncWebClient` - -#### channel\_id: `str` - -#### thread\_ts: `Optional[str]` +The user ID associated ith this request. -#### \_\_init\_\_ +### `user_token` ```python -def __init__(client: AsyncWebClient, channel_id: str, thread_ts: Optional[str] = None) +user_token: Optional[str] ``` -## AsyncGetThreadContext Objects +The user token resolved for this request. + +## `AsyncBoltRequest` ```python -class AsyncGetThreadContext() +AsyncBoltRequest(*, body, query=None, headers=None, context=None, mode='http') ``` -#### thread\_context\_store: `AsyncAssistantThreadContextStore` - -#### payload: `dict` +Request to a Bolt app. -#### channel\_id: `str` +**Parameters:** -#### thread\_ts: `str` +- **body** (Union[str, dict]) – The raw request body (only plain text is supported for "http" mode) +- **query** (Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]) – The query string data in any data format. +- **headers** (Optional[Dict[str, Union[str, Sequence[str]]]]) – The request headers. +- **context** (Optional[Dict[str, Any]]) – The context in this request. +- **mode** (str) – The mode used for this request. (either "http" or "socket_mode") -#### thread\_context\_loaded: `bool` +## `AsyncListener` -#### \_\_init\_\_ +### `run_ack_function` ```python -def __init__( - thread_context_store: AsyncAssistantThreadContextStore, - channel_id: str, - thread_ts: str, - payload: dict) +run_ack_function(*, request, response) ``` -## AsyncSaveThreadContext Objects - -```python -class AsyncSaveThreadContext() -``` +Runs all the registered middleware and then run the listener function. -#### thread\_context\_store: `AsyncAssistantThreadContextStore` +**Parameters:** -#### channel\_id: `str` +- **request** (AsyncBoltRequest) – The incoming request +- **response** (BoltResponse) – The current response -#### thread\_ts: `str` +**Returns:** -#### \_\_init\_\_ +- Optional[BoltResponse] – The processed response -```python -def __init__( - thread_context_store: AsyncAssistantThreadContextStore, - channel_id: str, - thread_ts: str) -``` - -## AsyncSayStream Objects +### `run_async_middleware` ```python -class AsyncSayStream() +run_async_middleware(*, req, resp) ``` -#### client: `AsyncWebClient` +Runs an async middleware. -#### channel: `Optional[str]` +**Parameters:** -#### recipient\_team\_id: `Optional[str]` +- **req** (AsyncBoltRequest) – The incoming request +- **resp** (BoltResponse) – The current response -#### recipient\_user\_id: `Optional[str]` +**Returns:** -#### thread\_ts: `Optional[str]` +- Tuple[Optional[BoltResponse], bool] – A tuple of the processed response and a flag indicating termination -#### \_\_init\_\_ +## `AsyncSayStream` ```python -def __init__( - *, - client: AsyncWebClient, - channel: Optional[str] = None, - recipient_team_id: Optional[str] = None, - recipient_user_id: Optional[str] = None, - thread_ts: Optional[str] = None) +AsyncSayStream(*, client, channel=None, recipient_team_id=None, recipient_user_id=None, thread_ts=None) ``` diff --git a/docs/english/reference/authorization/async_authorize.md b/docs/english/reference/authorization/async_authorize.md index bc8f94ff2..fc29ebe2e 100644 --- a/docs/english/reference/authorization/async_authorize.md +++ b/docs/english/reference/authorization/async_authorize.md @@ -3,69 +3,33 @@ sidebar_label: async_authorize title: slack_bolt.authorization.async_authorize --- -## AsyncAuthorize Objects +## `AsyncAuthorize` ```python -class AsyncAuthorize() +AsyncAuthorize() ``` This provides authorize function that returns AuthorizeResult for an incoming request from Slack. -#### \_\_init\_\_ +## `AsyncCallableAuthorize` ```python -def __init__() +AsyncCallableAuthorize(*, logger, func) ``` -## AsyncCallableAuthorize Objects - -```python -class AsyncCallableAuthorize(AsyncAuthorize) -``` +Bases: AsyncAuthorize When you pass the `authorize` argument in AsyncApp constructor, this `authorize` implementation will be used. -#### \_\_init\_\_ +## `AsyncInstallationStoreAuthorize` ```python -def __init__(*, logger: Logger, func: Callable[..., Awaitable[AuthorizeResult]]) +AsyncInstallationStoreAuthorize(*, logger, installation_store, client_id=None, client_secret=None, token_rotation_expiration_minutes=None, bot_only=False, cache_enabled=False, client=None, user_token_resolution='authed_user') ``` -## AsyncInstallationStoreAuthorize Objects - -```python -class AsyncInstallationStoreAuthorize(AsyncAuthorize) -``` +Bases: AsyncAuthorize If you use the OAuth flow settings, this authorize implementation will be used. As long as your own InstallationStore (or the built-in ones) works as you expect, you can expect that the authorize layer should work for you without any customization. - -#### authorize\_result\_cache: `Dict[str, AuthorizeResult]` - -#### bot\_only: `bool` - -#### user\_token\_resolution: `str` - -#### find\_installation\_available: `Optional[bool]` - -#### find\_bot\_available: `Optional[bool]` - -#### token\_rotator: `Optional[AsyncTokenRotator]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: Logger, - installation_store: AsyncInstallationStore, - client_id: Optional[str] = None, - client_secret: Optional[str] = None, - token_rotation_expiration_minutes: Optional[int] = None, - bot_only: bool = False, - cache_enabled: bool = False, - client: Optional[AsyncWebClient] = None, - user_token_resolution: str = 'authed_user') -``` diff --git a/docs/english/reference/authorization/async_authorize_args.md b/docs/english/reference/authorization/async_authorize_args.md index df35a1e87..f121f840f 100644 --- a/docs/english/reference/authorization/async_authorize_args.md +++ b/docs/english/reference/authorization/async_authorize_args.md @@ -3,40 +3,17 @@ sidebar_label: async_authorize_args title: slack_bolt.authorization.async_authorize_args --- -## AsyncAuthorizeArgs Objects +## `AsyncAuthorizeArgs` ```python -class AsyncAuthorizeArgs() -``` - -#### context: `AsyncBoltContext` - -#### logger: `Logger` - -#### client: `AsyncWebClient` - -#### enterprise\_id: `Optional[str]` - -#### team\_id: `Optional[str]` - -#### user\_id: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - context: AsyncBoltContext, - enterprise_id: Optional[str], - team_id: Optional[str], - user_id: Optional[str]) +AsyncAuthorizeArgs(*, context, enterprise_id, team_id, user_id) ``` The full list of the arguments passed to `authorize` function. -**Arguments**: +**Parameters:** -- `context` _AsyncBoltContext_ - The request context -- `enterprise_id` _Optional[str]_ - The Organization ID (Enterprise Grid) -- `team_id` _Optional[str]_ - The workspace ID -- `user_id` _Optional[str]_ - The request user ID +- **context** (AsyncBoltContext) – The request context +- **enterprise_id** (Optional[str]) – The Organization ID (Enterprise Grid) +- **team_id** (Optional[str]) – The workspace ID +- **user_id** (Optional[str]) – The request user ID diff --git a/docs/english/reference/authorization/authorize.md b/docs/english/reference/authorization/authorize.md index 1912932c4..039604922 100644 --- a/docs/english/reference/authorization/authorize.md +++ b/docs/english/reference/authorization/authorize.md @@ -3,69 +3,33 @@ sidebar_label: authorize title: slack_bolt.authorization.authorize --- -## Authorize Objects +## `Authorize` ```python -class Authorize() +Authorize() ``` This provides authorize function that returns AuthorizeResult for an incoming request from Slack. -#### \_\_init\_\_ +## `CallableAuthorize` ```python -def __init__() +CallableAuthorize(*, logger, func) ``` -## CallableAuthorize Objects - -```python -class CallableAuthorize(Authorize) -``` +Bases: Authorize When you pass the `authorize` argument in App constructor, this `authorize` implementation will be used. -#### \_\_init\_\_ +## `InstallationStoreAuthorize` ```python -def __init__(*, logger: Logger, func: Callable[..., AuthorizeResult]) +InstallationStoreAuthorize(*, logger, installation_store, client_id=None, client_secret=None, token_rotation_expiration_minutes=None, bot_only=False, cache_enabled=False, client=None, user_token_resolution='authed_user') ``` -## InstallationStoreAuthorize Objects - -```python -class InstallationStoreAuthorize(Authorize) -``` +Bases: Authorize If you use the OAuth flow settings, this `authorize` implementation will be used. As long as your own InstallationStore (or the built-in ones) works as you expect, you can expect that the `authorize` layer should work for you without any customization. - -#### authorize\_result\_cache: `Dict[str, AuthorizeResult]` - -#### bot\_only: `bool` - -#### user\_token\_resolution: `str` - -#### find\_installation\_available: `bool` - -#### find\_bot\_available: `bool` - -#### token\_rotator: `Optional[TokenRotator]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: Logger, - installation_store: InstallationStore, - client_id: Optional[str] = None, - client_secret: Optional[str] = None, - token_rotation_expiration_minutes: Optional[int] = None, - bot_only: bool = False, - cache_enabled: bool = False, - client: Optional[WebClient] = None, - user_token_resolution: str = 'authed_user') -``` diff --git a/docs/english/reference/authorization/authorize_args.md b/docs/english/reference/authorization/authorize_args.md index e5ae33a82..6be652aff 100644 --- a/docs/english/reference/authorization/authorize_args.md +++ b/docs/english/reference/authorization/authorize_args.md @@ -3,40 +3,17 @@ sidebar_label: authorize_args title: slack_bolt.authorization.authorize_args --- -## AuthorizeArgs Objects +## `AuthorizeArgs` ```python -class AuthorizeArgs() -``` - -#### context: `BoltContext` - -#### logger: `Logger` - -#### client: `WebClient` - -#### enterprise\_id: `Optional[str]` - -#### team\_id: `Optional[str]` - -#### user\_id: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - context: BoltContext, - enterprise_id: Optional[str], - team_id: Optional[str], - user_id: Optional[str]) +AuthorizeArgs(*, context, enterprise_id, team_id, user_id) ``` The full list of the arguments passed to `authorize` function. -**Arguments**: +**Parameters:** -- `context` _BoltContext_ - The request context -- `enterprise_id` _Optional[str]_ - The Organization ID (Enterprise Grid) -- `team_id` _Optional[str]_ - The workspace ID -- `user_id` _Optional[str]_ - The request user ID +- **context** (BoltContext) – The request context +- **enterprise_id** (Optional[str]) – The Organization ID (Enterprise Grid) +- **team_id** (Optional[str]) – The workspace ID +- **user_id** (Optional[str]) – The request user ID diff --git a/docs/english/reference/authorization/authorize_result.md b/docs/english/reference/authorization/authorize_result.md index f8a2aa33d..8e1678f30 100644 --- a/docs/english/reference/authorization/authorize_result.md +++ b/docs/english/reference/authorization/authorize_result.md @@ -3,83 +3,29 @@ sidebar_label: authorize_result title: slack_bolt.authorization.authorize_result --- -## AuthorizeResult Objects +## `AuthorizeResult` ```python -class AuthorizeResult(dict) +AuthorizeResult(*, enterprise_id, team_id, team=None, url=None, bot_user_id=None, bot_id=None, bot_token=None, bot_scopes=None, user_id=None, user=None, user_token=None, user_scopes=None) ``` -Authorize function call result. - -#### enterprise\_id: `Optional[str]` - -#### team\_id: `Optional[str]` - -#### team: `Optional[str]` - -#### url: `Optional[str]` - -#### bot\_id: `Optional[str]` - -#### bot\_user\_id: `Optional[str]` - -#### bot\_token: `Optional[str]` - -#### bot\_scopes: `Optional[Sequence[str]]` - -#### user\_id: `Optional[str]` - -#### user: `Optional[str]` +Bases: dict -#### user\_token: `Optional[str]` - -#### user\_scopes: `Optional[Sequence[str]]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - enterprise_id: Optional[str], - team_id: Optional[str], - team: Optional[str] = None, - url: Optional[str] = None, - bot_user_id: Optional[str] = None, - bot_id: Optional[str] = None, - bot_token: Optional[str] = None, - bot_scopes: Optional[Union[Sequence[str], str]] = None, - user_id: Optional[str] = None, - user: Optional[str] = None, - user_token: Optional[str] = None, - user_scopes: Optional[Union[Sequence[str], str]] = None) -``` +Authorize function call result. Initialize the authorize function call result. -**Arguments**: - -- `enterprise_id` _Optional[str]_ - Organization ID (Enterprise Grid) starting with `E` -- `team_id` _Optional[str]_ - Workspace ID starting with `T` -- `team` _Optional[str]_ - Workspace name -- `url` _Optional[str]_ - Workspace slack.com URL -- `bot_user_id` _Optional[str]_ - Bot user's User ID starting with either `U` or `W` -- `bot_id` _Optional[str]_ - Bot ID starting with `B` -- `bot_token` _Optional[str]_ - Bot user access token starting with `xoxb-` -- `bot_scopes` _Optional[Union[Sequence[str], str]]_ - The scopes associated with the bot token -- `user_id` _Optional[str]_ - The request user ID -- `user` _Optional[str]_ - The request user's name -- `user_token` _Optional[str]_ - User access token starting with `xoxp-` -- `user_scopes` _Optional[Union[Sequence[str], str]]_ - The scopes associated with the user token - -#### from\_auth\_test\_response - -```python -def from_auth_test_response( - *, - bot_token: Optional[str] = None, - user_token: Optional[str] = None, - bot_scopes: Optional[Union[Sequence[str], str]] = None, - user_scopes: Optional[Union[Sequence[str], str]] = None, - auth_test_response: Union[SlackResponse, AsyncSlackResponse], - user_auth_test_response: Optional[Union[SlackResponse, AsyncSlackResponse]] = None) -> AuthorizeResult -``` +**Parameters:** + +- **enterprise_id** (Optional[str]) – Organization ID (Enterprise Grid) starting with `E` +- **team_id** (Optional[str]) – Workspace ID starting with `T` +- **team** (Optional[str]) – Workspace name +- **url** (Optional[str]) – Workspace slack.com URL +- **bot_user_id** (Optional[str]) – Bot user's User ID starting with either `U` or `W` +- **bot_id** (Optional[str]) – Bot ID starting with `B` +- **bot_token** (Optional[str]) – Bot user access token starting with `xoxb-` +- **bot_scopes** (Optional[Union[Sequence[str], str]]) – The scopes associated with the bot token +- **user_id** (Optional[str]) – The request user ID +- **user** (Optional[str]) – The request user's name +- **user_token** (Optional[str]) – User access token starting with `xoxp-` +- **user_scopes** (Optional[Union[Sequence[str], str]]) – The scopes associated with the user token diff --git a/docs/english/reference/authorization/index.md b/docs/english/reference/authorization/index.md index 40fdc492d..795c34899 100644 --- a/docs/english/reference/authorization/index.md +++ b/docs/english/reference/authorization/index.md @@ -7,91 +7,37 @@ Authorization determines which Slack credentials should be available while proce Refer to https://docs.slack.dev/tools/bolt-python/concepts/authorization for details. -## Submodules - -- [slack_bolt.authorization.async_authorize](/tools/bolt-python/reference/authorization/async_authorize) -- [slack_bolt.authorization.async_authorize_args](/tools/bolt-python/reference/authorization/async_authorize_args) -- [slack_bolt.authorization.authorize](/tools/bolt-python/reference/authorization/authorize) -- [slack_bolt.authorization.authorize_args](/tools/bolt-python/reference/authorization/authorize_args) -- [slack_bolt.authorization.authorize_result](/tools/bolt-python/reference/authorization/authorize_result) - -## AuthorizeResult Objects +## `AuthorizeResult` ```python -class AuthorizeResult(dict) +AuthorizeResult(*, enterprise_id, team_id, team=None, url=None, bot_user_id=None, bot_id=None, bot_token=None, bot_scopes=None, user_id=None, user=None, user_token=None, user_scopes=None) ``` -Authorize function call result. - -#### enterprise\_id: `Optional[str]` - -#### team\_id: `Optional[str]` - -#### team: `Optional[str]` - -#### url: `Optional[str]` - -#### bot\_id: `Optional[str]` - -#### bot\_user\_id: `Optional[str]` - -#### bot\_token: `Optional[str]` - -#### bot\_scopes: `Optional[Sequence[str]]` +Bases: dict -#### user\_id: `Optional[str]` - -#### user: `Optional[str]` - -#### user\_token: `Optional[str]` - -#### user\_scopes: `Optional[Sequence[str]]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - enterprise_id: Optional[str], - team_id: Optional[str], - team: Optional[str] = None, - url: Optional[str] = None, - bot_user_id: Optional[str] = None, - bot_id: Optional[str] = None, - bot_token: Optional[str] = None, - bot_scopes: Optional[Union[Sequence[str], str]] = None, - user_id: Optional[str] = None, - user: Optional[str] = None, - user_token: Optional[str] = None, - user_scopes: Optional[Union[Sequence[str], str]] = None) -``` +Authorize function call result. Initialize the authorize function call result. -**Arguments**: - -- `enterprise_id` _Optional[str]_ - Organization ID (Enterprise Grid) starting with `E` -- `team_id` _Optional[str]_ - Workspace ID starting with `T` -- `team` _Optional[str]_ - Workspace name -- `url` _Optional[str]_ - Workspace slack.com URL -- `bot_user_id` _Optional[str]_ - Bot user's User ID starting with either `U` or `W` -- `bot_id` _Optional[str]_ - Bot ID starting with `B` -- `bot_token` _Optional[str]_ - Bot user access token starting with `xoxb-` -- `bot_scopes` _Optional[Union[Sequence[str], str]]_ - The scopes associated with the bot token -- `user_id` _Optional[str]_ - The request user ID -- `user` _Optional[str]_ - The request user's name -- `user_token` _Optional[str]_ - User access token starting with `xoxp-` -- `user_scopes` _Optional[Union[Sequence[str], str]]_ - The scopes associated with the user token +**Parameters:** + +- **enterprise_id** (Optional[str]) – Organization ID (Enterprise Grid) starting with `E` +- **team_id** (Optional[str]) – Workspace ID starting with `T` +- **team** (Optional[str]) – Workspace name +- **url** (Optional[str]) – Workspace slack.com URL +- **bot_user_id** (Optional[str]) – Bot user's User ID starting with either `U` or `W` +- **bot_id** (Optional[str]) – Bot ID starting with `B` +- **bot_token** (Optional[str]) – Bot user access token starting with `xoxb-` +- **bot_scopes** (Optional[Union[Sequence[str], str]]) – The scopes associated with the bot token +- **user_id** (Optional[str]) – The request user ID +- **user** (Optional[str]) – The request user's name +- **user_token** (Optional[str]) – User access token starting with `xoxp-` +- **user_scopes** (Optional[Union[Sequence[str], str]]) – The scopes associated with the user token -#### from\_auth\_test\_response +## Submodules -```python -def from_auth_test_response( - *, - bot_token: Optional[str] = None, - user_token: Optional[str] = None, - bot_scopes: Optional[Union[Sequence[str], str]] = None, - user_scopes: Optional[Union[Sequence[str], str]] = None, - auth_test_response: Union[SlackResponse, AsyncSlackResponse], - user_auth_test_response: Optional[Union[SlackResponse, AsyncSlackResponse]] = None) -> AuthorizeResult -``` +- [slack_bolt.authorization.async_authorize](/tools/bolt-python/reference/authorization/async_authorize) +- [slack_bolt.authorization.async_authorize_args](/tools/bolt-python/reference/authorization/async_authorize_args) +- [slack_bolt.authorization.authorize](/tools/bolt-python/reference/authorization/authorize) +- [slack_bolt.authorization.authorize_args](/tools/bolt-python/reference/authorization/authorize_args) +- [slack_bolt.authorization.authorize_result](/tools/bolt-python/reference/authorization/authorize_result) diff --git a/docs/english/reference/context/ack/ack.md b/docs/english/reference/context/ack/ack.md index c8ef3f5b9..e25f2ac3b 100644 --- a/docs/english/reference/context/ack/ack.md +++ b/docs/english/reference/context/ack/ack.md @@ -4,16 +4,4 @@ title: slack_bolt.context.ack.ack slug: ack --- -## Ack Objects -```python -class Ack() -``` - -#### response: `Optional[BoltResponse]` - -#### \_\_init\_\_ - -```python -def __init__() -``` diff --git a/docs/english/reference/context/ack/async_ack.md b/docs/english/reference/context/ack/async_ack.md index 5f8d84fca..e0a8db656 100644 --- a/docs/english/reference/context/ack/async_ack.md +++ b/docs/english/reference/context/ack/async_ack.md @@ -3,16 +3,4 @@ sidebar_label: async_ack title: slack_bolt.context.ack.async_ack --- -## AsyncAck Objects -```python -class AsyncAck() -``` - -#### response: `Optional[BoltResponse]` - -#### \_\_init\_\_ - -```python -def __init__() -``` diff --git a/docs/english/reference/context/ack/index.md b/docs/english/reference/context/ack/index.md index c46e6053c..d06649e56 100644 --- a/docs/english/reference/context/ack/index.md +++ b/docs/english/reference/context/ack/index.md @@ -8,17 +8,3 @@ title: slack_bolt.context.ack - [slack_bolt.context.ack.ack](/tools/bolt-python/reference/context/ack/ack) - [slack_bolt.context.ack.async_ack](/tools/bolt-python/reference/context/ack/async_ack) - [slack_bolt.context.ack.internals](/tools/bolt-python/reference/context/ack/internals) - -## Ack Objects - -```python -class Ack() -``` - -#### response: `Optional[BoltResponse]` - -#### \_\_init\_\_ - -```python -def __init__() -``` diff --git a/docs/english/reference/context/assistant/assistant_utilities.md b/docs/english/reference/context/assistant/assistant_utilities.md index 6fb13353e..5a8a13ff2 100644 --- a/docs/english/reference/context/assistant/assistant_utilities.md +++ b/docs/english/reference/context/assistant/assistant_utilities.md @@ -3,56 +3,4 @@ sidebar_label: assistant_utilities title: slack_bolt.context.assistant.assistant_utilities --- -## AssistantUtilities Objects -```python -class AssistantUtilities() -``` - -#### payload: `dict` - -#### client: `WebClient` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### thread\_context\_store: `AssistantThreadContextStore` - -#### \_\_init\_\_ - -```python -def __init__( - *, - payload: dict, - context: BoltContext, - thread_context_store: Optional[AssistantThreadContextStore] = None) -``` - -#### set\_title - -```python -@property -def set_title() -> SetTitle -``` - -#### say - -```python -@property -def say() -> Say -``` - -#### get\_thread\_context - -```python -@property -def get_thread_context() -> GetThreadContext -``` - -#### save\_thread\_context - -```python -@property -def save_thread_context() -> SaveThreadContext -``` diff --git a/docs/english/reference/context/assistant/async_assistant_utilities.md b/docs/english/reference/context/assistant/async_assistant_utilities.md index d5d0bd046..db307f344 100644 --- a/docs/english/reference/context/assistant/async_assistant_utilities.md +++ b/docs/english/reference/context/assistant/async_assistant_utilities.md @@ -3,56 +3,4 @@ sidebar_label: async_assistant_utilities title: slack_bolt.context.assistant.async_assistant_utilities --- -## AsyncAssistantUtilities Objects -```python -class AsyncAssistantUtilities() -``` - -#### payload: `dict` - -#### client: `AsyncWebClient` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### thread\_context\_store: `AsyncAssistantThreadContextStore` - -#### \_\_init\_\_ - -```python -def __init__( - *, - payload: dict, - context: AsyncBoltContext, - thread_context_store: Optional[AsyncAssistantThreadContextStore] = None) -``` - -#### set\_title - -```python -@property -def set_title() -> AsyncSetTitle -``` - -#### say - -```python -@property -def say() -> AsyncSay -``` - -#### get\_thread\_context - -```python -@property -def get_thread_context() -> AsyncGetThreadContext -``` - -#### save\_thread\_context - -```python -@property -def save_thread_context() -> AsyncSaveThreadContext -``` diff --git a/docs/english/reference/context/assistant/internals.md b/docs/english/reference/context/assistant/internals.md index 0b5d88e9b..ae403bc9a 100644 --- a/docs/english/reference/context/assistant/internals.md +++ b/docs/english/reference/context/assistant/internals.md @@ -3,10 +3,10 @@ sidebar_label: internals title: slack_bolt.context.assistant.internals --- -#### has\_channel\_id\_and\_thread\_ts +## `has_channel_id_and_thread_ts` ```python -def has_channel_id_and_thread_ts(payload: dict) -> bool +has_channel_id_and_thread_ts(payload) ``` Verifies if the given payload has both channel_id and thread_ts under assistant_thread property. diff --git a/docs/english/reference/context/assistant/thread_context/index.md b/docs/english/reference/context/assistant/thread_context/index.md index 9aa64ee48..7e321f12c 100644 --- a/docs/english/reference/context/assistant/thread_context/index.md +++ b/docs/english/reference/context/assistant/thread_context/index.md @@ -3,20 +3,4 @@ sidebar_label: thread_context title: slack_bolt.context.assistant.thread_context --- -## AssistantThreadContext Objects -```python -class AssistantThreadContext(dict) -``` - -#### enterprise\_id: `Optional[str]` - -#### team\_id: `Optional[str]` - -#### channel\_id: `str` - -#### \_\_init\_\_ - -```python -def __init__(payload: dict) -``` diff --git a/docs/english/reference/context/assistant/thread_context_store/async_store.md b/docs/english/reference/context/assistant/thread_context_store/async_store.md index 77ce5c62c..7456d47d8 100644 --- a/docs/english/reference/context/assistant/thread_context_store/async_store.md +++ b/docs/english/reference/context/assistant/thread_context_store/async_store.md @@ -3,20 +3,4 @@ sidebar_label: async_store title: slack_bolt.context.assistant.thread_context_store.async_store --- -## AsyncAssistantThreadContextStore Objects -```python -class AsyncAssistantThreadContextStore() -``` - -#### save - -```python -async def save(*, channel_id: str, thread_ts: str, context: Dict[str, str]) -> None -``` - -#### find - -```python -async def find(*, channel_id: str, thread_ts: str) -> Optional[AssistantThreadContext] -``` diff --git a/docs/english/reference/context/assistant/thread_context_store/default_async_store.md b/docs/english/reference/context/assistant/thread_context_store/default_async_store.md index a49c34e47..0a00d8f9e 100644 --- a/docs/english/reference/context/assistant/thread_context_store/default_async_store.md +++ b/docs/english/reference/context/assistant/thread_context_store/default_async_store.md @@ -3,30 +3,4 @@ sidebar_label: default_async_store title: slack_bolt.context.assistant.thread_context_store.default_async_store --- -## DefaultAsyncAssistantThreadContextStore Objects -```python -class DefaultAsyncAssistantThreadContextStore(AsyncAssistantThreadContextStore) -``` - -#### client: `AsyncWebClient` - -#### context: `AsyncBoltContext` - -#### \_\_init\_\_ - -```python -def __init__(context: AsyncBoltContext) -``` - -#### save - -```python -async def save(*, channel_id: str, thread_ts: str, context: Dict[str, str]) -> None -``` - -#### find - -```python -async def find(*, channel_id: str, thread_ts: str) -> Optional[AssistantThreadContext] -``` diff --git a/docs/english/reference/context/assistant/thread_context_store/default_store.md b/docs/english/reference/context/assistant/thread_context_store/default_store.md index 107f29805..fe046c4c6 100644 --- a/docs/english/reference/context/assistant/thread_context_store/default_store.md +++ b/docs/english/reference/context/assistant/thread_context_store/default_store.md @@ -3,30 +3,4 @@ sidebar_label: default_store title: slack_bolt.context.assistant.thread_context_store.default_store --- -## DefaultAssistantThreadContextStore Objects -```python -class DefaultAssistantThreadContextStore(AssistantThreadContextStore) -``` - -#### client: `WebClient` - -#### context: `BoltContext` - -#### \_\_init\_\_ - -```python -def __init__(context: BoltContext) -``` - -#### save - -```python -def save(*, channel_id: str, thread_ts: str, context: Dict[str, str]) -> None -``` - -#### find - -```python -def find(*, channel_id: str, thread_ts: str) -> Optional[AssistantThreadContext] -``` diff --git a/docs/english/reference/context/assistant/thread_context_store/file/index.md b/docs/english/reference/context/assistant/thread_context_store/file/index.md index cb56ee10b..b9165d437 100644 --- a/docs/english/reference/context/assistant/thread_context_store/file/index.md +++ b/docs/english/reference/context/assistant/thread_context_store/file/index.md @@ -3,26 +3,4 @@ sidebar_label: file title: slack_bolt.context.assistant.thread_context_store.file --- -## FileAssistantThreadContextStore Objects -```python -class FileAssistantThreadContextStore(AssistantThreadContextStore) -``` - -#### \_\_init\_\_ - -```python -def __init__(base_dir: str = str(Path.home()) + '/.bolt-app-assistant-thread-contexts') -``` - -#### save - -```python -def save(*, channel_id: str, thread_ts: str, context: Dict[str, str]) -> None -``` - -#### find - -```python -def find(*, channel_id: str, thread_ts: str) -> Optional[AssistantThreadContext] -``` diff --git a/docs/english/reference/context/assistant/thread_context_store/store.md b/docs/english/reference/context/assistant/thread_context_store/store.md index 491fbc849..c2e98f996 100644 --- a/docs/english/reference/context/assistant/thread_context_store/store.md +++ b/docs/english/reference/context/assistant/thread_context_store/store.md @@ -3,20 +3,4 @@ sidebar_label: store title: slack_bolt.context.assistant.thread_context_store.store --- -## AssistantThreadContextStore Objects -```python -class AssistantThreadContextStore() -``` - -#### save - -```python -def save(*, channel_id: str, thread_ts: str, context: Dict[str, str]) -> None -``` - -#### find - -```python -def find(*, channel_id: str, thread_ts: str) -> Optional[AssistantThreadContext] -``` diff --git a/docs/english/reference/context/async_context.md b/docs/english/reference/context/async_context.md index 5379854e6..4d9e0bc7b 100644 --- a/docs/english/reference/context/async_context.md +++ b/docs/english/reference/context/async_context.md @@ -3,144 +3,141 @@ sidebar_label: async_context title: slack_bolt.context.async_context --- -## AsyncBoltContext Objects +## `AsyncBoltContext` -```python -class AsyncBoltContext(BaseContext) -``` +Bases: BaseContext Context object associated with a request from Slack. -#### to\_copyable +### `ack` ```python -def to_copyable() -> AsyncBoltContext +ack: AsyncAck ``` -#### listener\_runner +`ack()` function for this request. ```python -@property -def listener_runner() -> AsyncioListenerRunner +@app.action("button") +async def handle_button_clicks(context): + await context.ack() + +# You can access "ack" this way too. +@app.action("button") +async def handle_button_clicks(ack): + await ack() ``` -The properly configured listener_runner that is available for middleware/listeners. +**Returns:** + +- AsyncAck – Callable `ack()` function -#### client +### `actor_enterprise_id` ```python -@property -def client() -> AsyncWebClient +actor_enterprise_id: Optional[str] ``` -The `AsyncWebClient` instance available for this request. +The action's actor's Enterprise Grid organization ID. -```python -@app.event("app_mention") -async def handle_events(context): - await context.client.chat_postMessage( - channel=context.channel_id, - text="Thanks!", - ) +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -# You can access "client" this way too. -@app.event("app_mention") -async def handle_events(client, context): - await client.chat_postMessage( - channel=context.channel_id, - text="Thanks!", - ) -``` +### `actor_team_id` +```python +actor_team_id: Optional[str] +``` -**Returns**: +The action's actor's workspace ID. -- `AsyncWebClient` - `AsyncWebClient` instance +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -#### ack +### `actor_user_id` ```python -@property -def ack() -> AsyncAck +actor_user_id: Optional[str] ``` -`ack()` function for this request. +The action's actor's user ID. -```python -@app.action("button") -async def handle_button_clicks(context): - await context.ack() +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -# You can access "ack" this way too. -@app.action("button") -async def handle_button_clicks(ack): - await ack() +### `authorize_result` + +```python +authorize_result: Optional[AuthorizeResult] ``` +The authorize result resolved for this request. -**Returns**: +### `bot_id` + +```python +bot_id: Optional[str] +``` -- `AsyncAck` - Callable `ack()` function +The bot ID resolved for this request. -#### say +### `bot_token` ```python -@property -def say() -> AsyncSay +bot_token: Optional[str] ``` -`say()` function for this request. +The bot token resolved for this request. -```python -@app.action("button") -async def handle_button_clicks(context): - await context.ack() - await context.say("Hi!") +### `bot_user_id` -# You can access "ack" this way too. -@app.action("button") -async def handle_button_clicks(ack, say): - await ack() - await say("Hi!") +```python +bot_user_id: Optional[str] ``` +The bot user ID resolved for this request. + +### `channel_id` -**Returns**: +```python +channel_id: Optional[str] +``` -- `AsyncSay` - Callable `say()` function +The conversation ID associated with this request. -#### respond +### `client` ```python -@property -def respond() -> Optional[AsyncRespond] +client: AsyncWebClient ``` -`respond()` function for this request. +The `AsyncWebClient` instance available for this request. ```python -@app.action("button") -async def handle_button_clicks(context): - await context.ack() - await context.respond("Hi!") +@app.event("app_mention") +async def handle_events(context): + await context.client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", + ) -# You can access "ack" this way too. -@app.action("button") -async def handle_button_clicks(ack, respond): - await ack() - await respond("Hi!") +# You can access "client" this way too. +@app.event("app_mention") +async def handle_events(client, context): + await client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", + ) ``` +**Returns:** -**Returns**: - -- `Optional[AsyncRespond]` - Callable `respond()` function +- AsyncWebClient – `AsyncWebClient` instance -#### complete +### `complete` ```python -@property -def complete() -> AsyncComplete +complete: AsyncComplete ``` `complete()` function for this request. @@ -162,16 +159,22 @@ async def handle_button_clicks(context): await context.complete(outputs={"stringReverse":"olleh"}) ``` +**Returns:** + +- AsyncComplete – Callable `complete()` function -**Returns**: +### `enterprise_id` -- `AsyncComplete` - Callable `complete()` function +```python +enterprise_id: Optional[str] +``` -#### fail +The Enterprise Grid Organization ID of this request. + +### `fail` ```python -@property -def fail() -> AsyncFail +fail: AsyncFail ``` `fail()` function for this request. @@ -193,49 +196,166 @@ async def handle_button_clicks(context): await context.fail(error="something went wrong") ``` +**Returns:** + +- AsyncFail – Callable `fail()` function + +### `function_bot_access_token` + +```python +function_bot_access_token: Optional[str] +``` + +The bot token resolved for this function request. + +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `function_execution_id` + +```python +function_execution_id: Optional[str] +``` + +The `function_execution_id` associated with this request. + +Only available for `function_executed` and interactivity events scoped to a custom step. -**Returns**: +### `inputs` + +```python +inputs: Optional[Dict[str, Any]] +``` + +The `inputs` associated with this request. + +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `is_enterprise_install` + +```python +is_enterprise_install: Optional[bool] +``` -- `AsyncFail` - Callable `fail()` function +True if the request is associated with an Org-wide installation. -#### set\_title +### `listener_runner` ```python -@property -def set_title() -> Optional[AsyncSetTitle] +listener_runner: AsyncioListenerRunner ``` -#### set\_status +The properly configured listener_runner that is available for middleware/listeners. + +### `logger` ```python -@property -def set_status() -> Optional[AsyncSetStatus] +logger: Logger ``` -#### set\_suggested\_prompts +The properly configured logger that is available for middleware/listeners. + +### `matches` ```python -@property -def set_suggested_prompts() -> Optional[AsyncSetSuggestedPrompts] +matches: Optional[Tuple] ``` -#### get\_thread\_context +Returns all the matched parts in message listener's regexp. + +### `respond` ```python -@property -def get_thread_context() -> Optional[AsyncGetThreadContext] +respond: Optional[AsyncRespond] ``` -#### say\_stream +`respond()` function for this request. ```python -@property -def say_stream() -> Optional[AsyncSayStream] +@app.action("button") +async def handle_button_clicks(context): + await context.ack() + await context.respond("Hi!") + +# You can access "ack" this way too. +@app.action("button") +async def handle_button_clicks(ack, respond): + await ack() + await respond("Hi!") ``` -#### save\_thread\_context +**Returns:** + +- Optional[AsyncRespond] – Callable `respond()` function + +### `response_url` ```python -@property -def save_thread_context() -> Optional[AsyncSaveThreadContext] +response_url: Optional[str] ``` + +The `response_url` associated with this request. + +### `say` + +```python +say: AsyncSay +``` + +`say()` function for this request. + +```python +@app.action("button") +async def handle_button_clicks(context): + await context.ack() + await context.say("Hi!") + +# You can access "ack" this way too. +@app.action("button") +async def handle_button_clicks(ack, say): + await ack() + await say("Hi!") +``` + +**Returns:** + +- AsyncSay – Callable `say()` function + +### `team_id` + +```python +team_id: Optional[str] +``` + +The Workspace ID of this request. + +### `thread_ts` + +```python +thread_ts: Optional[str] +``` + +The conversation thread's ID associated with this request. + +### `token` + +```python +token: Optional[str] +``` + +The (bot/user) token resolved for this request. + +### `user_id` + +```python +user_id: Optional[str] +``` + +The user ID associated ith this request. + +### `user_token` + +```python +user_token: Optional[str] +``` + +The user token resolved for this request. diff --git a/docs/english/reference/context/base_context.md b/docs/english/reference/context/base_context.md index db5a6879e..590461cd0 100644 --- a/docs/english/reference/context/base_context.md +++ b/docs/english/reference/context/base_context.md @@ -3,226 +3,191 @@ sidebar_label: base_context title: slack_bolt.context.base_context --- -## BaseContext Objects +## `BaseContext` -```python -class BaseContext(dict) -``` +Bases: dict Context object associated with a request from Slack. -#### copyable\_standard\_property\_names - -#### non\_copyable\_standard\_property\_names - -#### standard\_property\_names - -#### logger +### `actor_enterprise_id` ```python -@property -def logger() -> Logger +actor_enterprise_id: Optional[str] ``` -The properly configured logger that is available for middleware/listeners. +The action's actor's Enterprise Grid organization ID. + +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -#### token +### `actor_team_id` ```python -@property -def token() -> Optional[str] +actor_team_id: Optional[str] ``` -The (bot/user) token resolved for this request. +The action's actor's workspace ID. + +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -#### enterprise\_id +### `actor_user_id` ```python -@property -def enterprise_id() -> Optional[str] +actor_user_id: Optional[str] ``` -The Enterprise Grid Organization ID of this request. +The action's actor's user ID. + +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -#### is\_enterprise\_install +### `authorize_result` ```python -@property -def is_enterprise_install() -> Optional[bool] +authorize_result: Optional[AuthorizeResult] ``` -True if the request is associated with an Org-wide installation. +The authorize result resolved for this request. -#### team\_id +### `bot_id` ```python -@property -def team_id() -> Optional[str] +bot_id: Optional[str] ``` -The Workspace ID of this request. +The bot ID resolved for this request. -#### user\_id +### `bot_token` ```python -@property -def user_id() -> Optional[str] +bot_token: Optional[str] ``` -The user ID associated ith this request. +The bot token resolved for this request. -#### actor\_enterprise\_id +### `bot_user_id` ```python -@property -def actor_enterprise_id() -> Optional[str] +bot_user_id: Optional[str] ``` -The action's actor's Enterprise Grid organization ID. - -Note that this property is especially useful for handling events in Slack Connect channels. -That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. +The bot user ID resolved for this request. -#### actor\_team\_id +### `channel_id` ```python -@property -def actor_team_id() -> Optional[str] +channel_id: Optional[str] ``` -The action's actor's workspace ID. - -Note that this property is especially useful for handling events in Slack Connect channels. -That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. +The conversation ID associated with this request. -#### actor\_user\_id +### `enterprise_id` ```python -@property -def actor_user_id() -> Optional[str] +enterprise_id: Optional[str] ``` -The action's actor's user ID. - -Note that this property is especially useful for handling events in Slack Connect channels. -That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. +The Enterprise Grid Organization ID of this request. -#### channel\_id +### `function_bot_access_token` ```python -@property -def channel_id() -> Optional[str] +function_bot_access_token: Optional[str] ``` -The conversation ID associated with this request. +The bot token resolved for this function request. + +Only available for `function_executed` and interactivity events scoped to a custom step. -#### thread\_ts +### `function_execution_id` ```python -@property -def thread_ts() -> Optional[str] +function_execution_id: Optional[str] ``` -The conversation thread's ID associated with this request. +The `function_execution_id` associated with this request. -#### response\_url +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `inputs` ```python -@property -def response_url() -> Optional[str] +inputs: Optional[Dict[str, Any]] ``` -The `response_url` associated with this request. +The `inputs` associated with this request. + +Only available for `function_executed` and interactivity events scoped to a custom step. -#### matches +### `is_enterprise_install` ```python -@property -def matches() -> Optional[Tuple] +is_enterprise_install: Optional[bool] ``` -Returns all the matched parts in message listener's regexp. +True if the request is associated with an Org-wide installation. -#### function\_execution\_id +### `logger` ```python -@property -def function_execution_id() -> Optional[str] +logger: Logger ``` -The `function_execution_id` associated with this request. - -Only available for `function_executed` and interactivity events scoped to a custom step. +The properly configured logger that is available for middleware/listeners. -#### inputs +### `matches` ```python -@property -def inputs() -> Optional[Dict[str, Any]] +matches: Optional[Tuple] ``` -The `inputs` associated with this request. - -Only available for `function_executed` and interactivity events scoped to a custom step. +Returns all the matched parts in message listener's regexp. -#### authorize\_result +### `response_url` ```python -@property -def authorize_result() -> Optional[AuthorizeResult] +response_url: Optional[str] ``` -The authorize result resolved for this request. +The `response_url` associated with this request. -#### function\_bot\_access\_token +### `team_id` ```python -@property -def function_bot_access_token() -> Optional[str] +team_id: Optional[str] ``` -The bot token resolved for this function request. - -Only available for `function_executed` and interactivity events scoped to a custom step. +The Workspace ID of this request. -#### bot\_token +### `thread_ts` ```python -@property -def bot_token() -> Optional[str] +thread_ts: Optional[str] ``` -The bot token resolved for this request. +The conversation thread's ID associated with this request. -#### bot\_id +### `token` ```python -@property -def bot_id() -> Optional[str] +token: Optional[str] ``` -The bot ID resolved for this request. +The (bot/user) token resolved for this request. -#### bot\_user\_id +### `user_id` ```python -@property -def bot_user_id() -> Optional[str] +user_id: Optional[str] ``` -The bot user ID resolved for this request. +The user ID associated ith this request. -#### user\_token +### `user_token` ```python -@property -def user_token() -> Optional[str] +user_token: Optional[str] ``` The user token resolved for this request. - -#### set\_authorize\_result - -```python -def set_authorize_result(authorize_result: AuthorizeResult) -``` diff --git a/docs/english/reference/context/complete/async_complete.md b/docs/english/reference/context/complete/async_complete.md index ee982f1ae..7564b3f7a 100644 --- a/docs/english/reference/context/complete/async_complete.md +++ b/docs/english/reference/context/complete/async_complete.md @@ -3,30 +3,20 @@ sidebar_label: async_complete title: slack_bolt.context.complete.async_complete --- -## AsyncComplete Objects +## `AsyncComplete` ```python -class AsyncComplete() +AsyncComplete(client, function_execution_id) ``` -#### client: `AsyncWebClient` - -#### function\_execution\_id: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__(client: AsyncWebClient, function_execution_id: Optional[str]) -``` - -#### has\_been\_called +### `has_been_called` ```python -def has_been_called() -> bool +has_been_called() ``` Check if this complete function has been called. -**Returns**: +**Returns:** -- `bool` - True if the complete function has been called, False otherwise. +- **bool** (bool) – True if the complete function has been called, False otherwise. diff --git a/docs/english/reference/context/complete/complete.md b/docs/english/reference/context/complete/complete.md index 3660d34f0..19f6a3237 100644 --- a/docs/english/reference/context/complete/complete.md +++ b/docs/english/reference/context/complete/complete.md @@ -4,30 +4,20 @@ title: slack_bolt.context.complete.complete slug: complete --- -## Complete Objects +## `Complete` ```python -class Complete() +Complete(client, function_execution_id) ``` -#### client: `WebClient` - -#### function\_execution\_id: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__(client: WebClient, function_execution_id: Optional[str]) -``` - -#### has\_been\_called +### `has_been_called` ```python -def has_been_called() -> bool +has_been_called() ``` Check if this complete function has been called. -**Returns**: +**Returns:** -- `bool` - True if the complete function has been called, False otherwise. +- **bool** (bool) – True if the complete function has been called, False otherwise. diff --git a/docs/english/reference/context/complete/index.md b/docs/english/reference/context/complete/index.md index 756072e10..fb9571d2f 100644 --- a/docs/english/reference/context/complete/index.md +++ b/docs/english/reference/context/complete/index.md @@ -3,35 +3,25 @@ sidebar_label: complete title: slack_bolt.context.complete --- -## Submodules - -- [slack_bolt.context.complete.async_complete](/tools/bolt-python/reference/context/complete/async_complete) -- [slack_bolt.context.complete.complete](/tools/bolt-python/reference/context/complete/complete) - -## Complete Objects +## `Complete` ```python -class Complete() +Complete(client, function_execution_id) ``` -#### client: `WebClient` - -#### function\_execution\_id: `Optional[str]` - -#### \_\_init\_\_ +### `has_been_called` ```python -def __init__(client: WebClient, function_execution_id: Optional[str]) +has_been_called() ``` -#### has\_been\_called +Check if this complete function has been called. -```python -def has_been_called() -> bool -``` +**Returns:** -Check if this complete function has been called. +- **bool** (bool) – True if the complete function has been called, False otherwise. -**Returns**: +## Submodules -- `bool` - True if the complete function has been called, False otherwise. +- [slack_bolt.context.complete.async_complete](/tools/bolt-python/reference/context/complete/async_complete) +- [slack_bolt.context.complete.complete](/tools/bolt-python/reference/context/complete/complete) diff --git a/docs/english/reference/context/context.md b/docs/english/reference/context/context.md index df8b1a7fe..3b17fe29b 100644 --- a/docs/english/reference/context/context.md +++ b/docs/english/reference/context/context.md @@ -4,144 +4,141 @@ title: slack_bolt.context.context slug: context --- -## BoltContext Objects +## `BoltContext` -```python -class BoltContext(BaseContext) -``` +Bases: BaseContext Context object associated with a request from Slack. -#### to\_copyable +### `ack` ```python -def to_copyable() -> BoltContext +ack: Ack ``` -#### listener\_runner +`ack()` function for this request. ```python -@property -def listener_runner() -> ThreadListenerRunner +@app.action("button") +def handle_button_clicks(context): + context.ack() + +# You can access "ack" this way too. +@app.action("button") +def handle_button_clicks(ack): + ack() ``` -The properly configured listener_runner that is available for middleware/listeners. +**Returns:** + +- Ack – Callable `ack()` function -#### client +### `actor_enterprise_id` ```python -@property -def client() -> WebClient +actor_enterprise_id: Optional[str] ``` -The `WebClient` instance available for this request. +The action's actor's Enterprise Grid organization ID. -```python -@app.event("app_mention") -def handle_events(context): - context.client.chat_postMessage( - channel=context.channel_id, - text="Thanks!", - ) +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -# You can access "client" this way too. -@app.event("app_mention") -def handle_events(client, context): - client.chat_postMessage( - channel=context.channel_id, - text="Thanks!", - ) -``` +### `actor_team_id` +```python +actor_team_id: Optional[str] +``` -**Returns**: +The action's actor's workspace ID. -- `WebClient` - `WebClient` instance +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -#### ack +### `actor_user_id` ```python -@property -def ack() -> Ack +actor_user_id: Optional[str] ``` -`ack()` function for this request. +The action's actor's user ID. -```python -@app.action("button") -def handle_button_clicks(context): - context.ack() +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -# You can access "ack" this way too. -@app.action("button") -def handle_button_clicks(ack): - ack() +### `authorize_result` + +```python +authorize_result: Optional[AuthorizeResult] ``` +The authorize result resolved for this request. -**Returns**: +### `bot_id` + +```python +bot_id: Optional[str] +``` -- `Ack` - Callable `ack()` function +The bot ID resolved for this request. -#### say +### `bot_token` ```python -@property -def say() -> Say +bot_token: Optional[str] ``` -`say()` function for this request. +The bot token resolved for this request. -```python -@app.action("button") -def handle_button_clicks(context): - context.ack() - context.say("Hi!") +### `bot_user_id` -# You can access "ack" this way too. -@app.action("button") -def handle_button_clicks(ack, say): - ack() - say("Hi!") +```python +bot_user_id: Optional[str] ``` +The bot user ID resolved for this request. + +### `channel_id` -**Returns**: +```python +channel_id: Optional[str] +``` -- `Say` - Callable `say()` function +The conversation ID associated with this request. -#### respond +### `client` ```python -@property -def respond() -> Optional[Respond] +client: WebClient ``` -`respond()` function for this request. +The `WebClient` instance available for this request. ```python -@app.action("button") -def handle_button_clicks(context): - context.ack() - context.respond("Hi!") +@app.event("app_mention") +def handle_events(context): + context.client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", + ) -# You can access "ack" this way too. -@app.action("button") -def handle_button_clicks(ack, respond): - ack() - respond("Hi!") +# You can access "client" this way too. +@app.event("app_mention") +def handle_events(client, context): + client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", + ) ``` +**Returns:** -**Returns**: - -- `Optional[Respond]` - Callable `respond()` function +- WebClient – `WebClient` instance -#### complete +### `complete` ```python -@property -def complete() -> Complete +complete: Complete ``` `complete()` function for this request. @@ -163,16 +160,22 @@ def handle_button_clicks(context): context.complete(outputs={"stringReverse":"olleh"}) ``` +**Returns:** + +- Complete – Callable `complete()` function -**Returns**: +### `enterprise_id` -- `Complete` - Callable `complete()` function +```python +enterprise_id: Optional[str] +``` -#### fail +The Enterprise Grid Organization ID of this request. + +### `fail` ```python -@property -def fail() -> Fail +fail: Fail ``` `fail()` function for this request. @@ -194,49 +197,166 @@ def handle_button_clicks(context): context.fail(error="something went wrong") ``` +**Returns:** + +- Fail – Callable `fail()` function + +### `function_bot_access_token` + +```python +function_bot_access_token: Optional[str] +``` + +The bot token resolved for this function request. + +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `function_execution_id` + +```python +function_execution_id: Optional[str] +``` + +The `function_execution_id` associated with this request. + +Only available for `function_executed` and interactivity events scoped to a custom step. -**Returns**: +### `inputs` + +```python +inputs: Optional[Dict[str, Any]] +``` + +The `inputs` associated with this request. + +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `is_enterprise_install` + +```python +is_enterprise_install: Optional[bool] +``` -- `Fail` - Callable `fail()` function +True if the request is associated with an Org-wide installation. -#### set\_title +### `listener_runner` ```python -@property -def set_title() -> Optional[SetTitle] +listener_runner: ThreadListenerRunner ``` -#### set\_status +The properly configured listener_runner that is available for middleware/listeners. + +### `logger` ```python -@property -def set_status() -> Optional[SetStatus] +logger: Logger ``` -#### set\_suggested\_prompts +The properly configured logger that is available for middleware/listeners. + +### `matches` ```python -@property -def set_suggested_prompts() -> Optional[SetSuggestedPrompts] +matches: Optional[Tuple] ``` -#### get\_thread\_context +Returns all the matched parts in message listener's regexp. + +### `respond` ```python -@property -def get_thread_context() -> Optional[GetThreadContext] +respond: Optional[Respond] ``` -#### say\_stream +`respond()` function for this request. ```python -@property -def say_stream() -> Optional[SayStream] +@app.action("button") +def handle_button_clicks(context): + context.ack() + context.respond("Hi!") + +# You can access "ack" this way too. +@app.action("button") +def handle_button_clicks(ack, respond): + ack() + respond("Hi!") ``` -#### save\_thread\_context +**Returns:** + +- Optional[Respond] – Callable `respond()` function + +### `response_url` ```python -@property -def save_thread_context() -> Optional[SaveThreadContext] +response_url: Optional[str] ``` + +The `response_url` associated with this request. + +### `say` + +```python +say: Say +``` + +`say()` function for this request. + +```python +@app.action("button") +def handle_button_clicks(context): + context.ack() + context.say("Hi!") + +# You can access "ack" this way too. +@app.action("button") +def handle_button_clicks(ack, say): + ack() + say("Hi!") +``` + +**Returns:** + +- Say – Callable `say()` function + +### `team_id` + +```python +team_id: Optional[str] +``` + +The Workspace ID of this request. + +### `thread_ts` + +```python +thread_ts: Optional[str] +``` + +The conversation thread's ID associated with this request. + +### `token` + +```python +token: Optional[str] +``` + +The (bot/user) token resolved for this request. + +### `user_id` + +```python +user_id: Optional[str] +``` + +The user ID associated ith this request. + +### `user_token` + +```python +user_token: Optional[str] +``` + +The user token resolved for this request. diff --git a/docs/english/reference/context/fail/async_fail.md b/docs/english/reference/context/fail/async_fail.md index 8924e0a45..bf1e1c100 100644 --- a/docs/english/reference/context/fail/async_fail.md +++ b/docs/english/reference/context/fail/async_fail.md @@ -3,30 +3,20 @@ sidebar_label: async_fail title: slack_bolt.context.fail.async_fail --- -## AsyncFail Objects +## `AsyncFail` ```python -class AsyncFail() +AsyncFail(client, function_execution_id) ``` -#### client: `AsyncWebClient` - -#### function\_execution\_id: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__(client: AsyncWebClient, function_execution_id: Optional[str]) -``` - -#### has\_been\_called +### `has_been_called` ```python -def has_been_called() -> bool +has_been_called() ``` Check if this fail function has been called. -**Returns**: +**Returns:** -- `bool` - True if the fail function has been called, False otherwise. +- **bool** (bool) – True if the fail function has been called, False otherwise. diff --git a/docs/english/reference/context/fail/fail.md b/docs/english/reference/context/fail/fail.md index 6d0dcd169..fd7be3c48 100644 --- a/docs/english/reference/context/fail/fail.md +++ b/docs/english/reference/context/fail/fail.md @@ -4,30 +4,20 @@ title: slack_bolt.context.fail.fail slug: fail --- -## Fail Objects +## `Fail` ```python -class Fail() +Fail(client, function_execution_id) ``` -#### client: `WebClient` - -#### function\_execution\_id: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__(client: WebClient, function_execution_id: Optional[str]) -``` - -#### has\_been\_called +### `has_been_called` ```python -def has_been_called() -> bool +has_been_called() ``` Check if this fail function has been called. -**Returns**: +**Returns:** -- `bool` - True if the fail function has been called, False otherwise. +- **bool** (bool) – True if the fail function has been called, False otherwise. diff --git a/docs/english/reference/context/fail/index.md b/docs/english/reference/context/fail/index.md index b09e7a710..20437d850 100644 --- a/docs/english/reference/context/fail/index.md +++ b/docs/english/reference/context/fail/index.md @@ -3,35 +3,25 @@ sidebar_label: fail title: slack_bolt.context.fail --- -## Submodules - -- [slack_bolt.context.fail.async_fail](/tools/bolt-python/reference/context/fail/async_fail) -- [slack_bolt.context.fail.fail](/tools/bolt-python/reference/context/fail/fail) - -## Fail Objects +## `Fail` ```python -class Fail() +Fail(client, function_execution_id) ``` -#### client: `WebClient` - -#### function\_execution\_id: `Optional[str]` - -#### \_\_init\_\_ +### `has_been_called` ```python -def __init__(client: WebClient, function_execution_id: Optional[str]) +has_been_called() ``` -#### has\_been\_called +Check if this fail function has been called. -```python -def has_been_called() -> bool -``` +**Returns:** -Check if this fail function has been called. +- **bool** (bool) – True if the fail function has been called, False otherwise. -**Returns**: +## Submodules -- `bool` - True if the fail function has been called, False otherwise. +- [slack_bolt.context.fail.async_fail](/tools/bolt-python/reference/context/fail/async_fail) +- [slack_bolt.context.fail.fail](/tools/bolt-python/reference/context/fail/fail) diff --git a/docs/english/reference/context/get_thread_context/async_get_thread_context.md b/docs/english/reference/context/get_thread_context/async_get_thread_context.md index bcdf17dd6..17345e511 100644 --- a/docs/english/reference/context/get_thread_context/async_get_thread_context.md +++ b/docs/english/reference/context/get_thread_context/async_get_thread_context.md @@ -3,28 +3,4 @@ sidebar_label: async_get_thread_context title: slack_bolt.context.get_thread_context.async_get_thread_context --- -## AsyncGetThreadContext Objects -```python -class AsyncGetThreadContext() -``` - -#### thread\_context\_store: `AsyncAssistantThreadContextStore` - -#### payload: `dict` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### thread\_context\_loaded: `bool` - -#### \_\_init\_\_ - -```python -def __init__( - thread_context_store: AsyncAssistantThreadContextStore, - channel_id: str, - thread_ts: str, - payload: dict) -``` diff --git a/docs/english/reference/context/get_thread_context/get_thread_context.md b/docs/english/reference/context/get_thread_context/get_thread_context.md index 40c64f686..832987ad1 100644 --- a/docs/english/reference/context/get_thread_context/get_thread_context.md +++ b/docs/english/reference/context/get_thread_context/get_thread_context.md @@ -4,28 +4,4 @@ title: slack_bolt.context.get_thread_context.get_thread_context slug: get_thread_context --- -## GetThreadContext Objects -```python -class GetThreadContext() -``` - -#### thread\_context\_store: `AssistantThreadContextStore` - -#### payload: `dict` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### thread\_context\_loaded: `bool` - -#### \_\_init\_\_ - -```python -def __init__( - thread_context_store: AssistantThreadContextStore, - channel_id: str, - thread_ts: str, - payload: dict) -``` diff --git a/docs/english/reference/context/get_thread_context/index.md b/docs/english/reference/context/get_thread_context/index.md index 8d5f92375..35443e851 100644 --- a/docs/english/reference/context/get_thread_context/index.md +++ b/docs/english/reference/context/get_thread_context/index.md @@ -7,29 +7,3 @@ title: slack_bolt.context.get_thread_context - [slack_bolt.context.get_thread_context.async_get_thread_context](/tools/bolt-python/reference/context/get_thread_context/async_get_thread_context) - [slack_bolt.context.get_thread_context.get_thread_context](/tools/bolt-python/reference/context/get_thread_context/get_thread_context) - -## GetThreadContext Objects - -```python -class GetThreadContext() -``` - -#### thread\_context\_store: `AssistantThreadContextStore` - -#### payload: `dict` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### thread\_context\_loaded: `bool` - -#### \_\_init\_\_ - -```python -def __init__( - thread_context_store: AssistantThreadContextStore, - channel_id: str, - thread_ts: str, - payload: dict) -``` diff --git a/docs/english/reference/context/index.md b/docs/english/reference/context/index.md index dedca40ba..8e7cf5c8d 100644 --- a/docs/english/reference/context/index.md +++ b/docs/english/reference/context/index.md @@ -10,162 +10,141 @@ like `user_id`, `team_id`, `channel_id`, and `enterprise_id`. Refer to https://docs.slack.dev/tools/bolt-python/concepts/context for details. -## Submodules +## `BoltContext` -- [slack_bolt.context.ack](/tools/bolt-python/reference/context/ack) -- [slack_bolt.context.assistant](/tools/bolt-python/reference/context/assistant) -- [slack_bolt.context.async_context](/tools/bolt-python/reference/context/async_context) -- [slack_bolt.context.base_context](/tools/bolt-python/reference/context/base_context) -- [slack_bolt.context.complete](/tools/bolt-python/reference/context/complete) -- [slack_bolt.context.context](/tools/bolt-python/reference/context/context) -- [slack_bolt.context.fail](/tools/bolt-python/reference/context/fail) -- [slack_bolt.context.get_thread_context](/tools/bolt-python/reference/context/get_thread_context) -- [slack_bolt.context.respond](/tools/bolt-python/reference/context/respond) -- [slack_bolt.context.save_thread_context](/tools/bolt-python/reference/context/save_thread_context) -- [slack_bolt.context.say](/tools/bolt-python/reference/context/say) -- [slack_bolt.context.say_stream](/tools/bolt-python/reference/context/say_stream) -- [slack_bolt.context.set_status](/tools/bolt-python/reference/context/set_status) -- [slack_bolt.context.set_suggested_prompts](/tools/bolt-python/reference/context/set_suggested_prompts) -- [slack_bolt.context.set_title](/tools/bolt-python/reference/context/set_title) - -## BoltContext Objects - -```python -class BoltContext(BaseContext) -``` +Bases: BaseContext Context object associated with a request from Slack. -#### to\_copyable +### `ack` ```python -def to_copyable() -> BoltContext +ack: Ack ``` -#### listener\_runner +`ack()` function for this request. ```python -@property -def listener_runner() -> ThreadListenerRunner +@app.action("button") +def handle_button_clicks(context): + context.ack() + +# You can access "ack" this way too. +@app.action("button") +def handle_button_clicks(ack): + ack() ``` -The properly configured listener_runner that is available for middleware/listeners. +**Returns:** + +- Ack – Callable `ack()` function -#### client +### `actor_enterprise_id` ```python -@property -def client() -> WebClient +actor_enterprise_id: Optional[str] ``` -The `WebClient` instance available for this request. +The action's actor's Enterprise Grid organization ID. -```python -@app.event("app_mention") -def handle_events(context): - context.client.chat_postMessage( - channel=context.channel_id, - text="Thanks!", - ) +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -# You can access "client" this way too. -@app.event("app_mention") -def handle_events(client, context): - client.chat_postMessage( - channel=context.channel_id, - text="Thanks!", - ) -``` +### `actor_team_id` +```python +actor_team_id: Optional[str] +``` -**Returns**: +The action's actor's workspace ID. -- `WebClient` - `WebClient` instance +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -#### ack +### `actor_user_id` ```python -@property -def ack() -> Ack +actor_user_id: Optional[str] ``` -`ack()` function for this request. +The action's actor's user ID. -```python -@app.action("button") -def handle_button_clicks(context): - context.ack() +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. -# You can access "ack" this way too. -@app.action("button") -def handle_button_clicks(ack): - ack() +### `authorize_result` + +```python +authorize_result: Optional[AuthorizeResult] ``` +The authorize result resolved for this request. -**Returns**: +### `bot_id` -- `Ack` - Callable `ack()` function +```python +bot_id: Optional[str] +``` -#### say +The bot ID resolved for this request. + +### `bot_token` ```python -@property -def say() -> Say +bot_token: Optional[str] ``` -`say()` function for this request. +The bot token resolved for this request. -```python -@app.action("button") -def handle_button_clicks(context): - context.ack() - context.say("Hi!") +### `bot_user_id` -# You can access "ack" this way too. -@app.action("button") -def handle_button_clicks(ack, say): - ack() - say("Hi!") +```python +bot_user_id: Optional[str] ``` +The bot user ID resolved for this request. + +### `channel_id` -**Returns**: +```python +channel_id: Optional[str] +``` -- `Say` - Callable `say()` function +The conversation ID associated with this request. -#### respond +### `client` ```python -@property -def respond() -> Optional[Respond] +client: WebClient ``` -`respond()` function for this request. +The `WebClient` instance available for this request. ```python -@app.action("button") -def handle_button_clicks(context): - context.ack() - context.respond("Hi!") +@app.event("app_mention") +def handle_events(context): + context.client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", + ) -# You can access "ack" this way too. -@app.action("button") -def handle_button_clicks(ack, respond): - ack() - respond("Hi!") +# You can access "client" this way too. +@app.event("app_mention") +def handle_events(client, context): + client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", + ) ``` +**Returns:** -**Returns**: - -- `Optional[Respond]` - Callable `respond()` function +- WebClient – `WebClient` instance -#### complete +### `complete` ```python -@property -def complete() -> Complete +complete: Complete ``` `complete()` function for this request. @@ -187,16 +166,22 @@ def handle_button_clicks(context): context.complete(outputs={"stringReverse":"olleh"}) ``` +**Returns:** -**Returns**: +- Complete – Callable `complete()` function -- `Complete` - Callable `complete()` function +### `enterprise_id` + +```python +enterprise_id: Optional[str] +``` -#### fail +The Enterprise Grid Organization ID of this request. + +### `fail` ```python -@property -def fail() -> Fail +fail: Fail ``` `fail()` function for this request. @@ -218,49 +203,184 @@ def handle_button_clicks(context): context.fail(error="something went wrong") ``` +**Returns:** + +- Fail – Callable `fail()` function -**Returns**: +### `function_bot_access_token` -- `Fail` - Callable `fail()` function +```python +function_bot_access_token: Optional[str] +``` -#### set\_title +The bot token resolved for this function request. + +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `function_execution_id` ```python -@property -def set_title() -> Optional[SetTitle] +function_execution_id: Optional[str] ``` -#### set\_status +The `function_execution_id` associated with this request. + +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `inputs` ```python -@property -def set_status() -> Optional[SetStatus] +inputs: Optional[Dict[str, Any]] ``` -#### set\_suggested\_prompts +The `inputs` associated with this request. + +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `is_enterprise_install` ```python -@property -def set_suggested_prompts() -> Optional[SetSuggestedPrompts] +is_enterprise_install: Optional[bool] ``` -#### get\_thread\_context +True if the request is associated with an Org-wide installation. + +### `listener_runner` ```python -@property -def get_thread_context() -> Optional[GetThreadContext] +listener_runner: ThreadListenerRunner ``` -#### say\_stream +The properly configured listener_runner that is available for middleware/listeners. + +### `logger` ```python -@property -def say_stream() -> Optional[SayStream] +logger: Logger ``` -#### save\_thread\_context +The properly configured logger that is available for middleware/listeners. + +### `matches` ```python -@property -def save_thread_context() -> Optional[SaveThreadContext] +matches: Optional[Tuple] ``` + +Returns all the matched parts in message listener's regexp. + +### `respond` + +```python +respond: Optional[Respond] +``` + +`respond()` function for this request. + +```python +@app.action("button") +def handle_button_clicks(context): + context.ack() + context.respond("Hi!") + +# You can access "ack" this way too. +@app.action("button") +def handle_button_clicks(ack, respond): + ack() + respond("Hi!") +``` + +**Returns:** + +- Optional[Respond] – Callable `respond()` function + +### `response_url` + +```python +response_url: Optional[str] +``` + +The `response_url` associated with this request. + +### `say` + +```python +say: Say +``` + +`say()` function for this request. + +```python +@app.action("button") +def handle_button_clicks(context): + context.ack() + context.say("Hi!") + +# You can access "ack" this way too. +@app.action("button") +def handle_button_clicks(ack, say): + ack() + say("Hi!") +``` + +**Returns:** + +- Say – Callable `say()` function + +### `team_id` + +```python +team_id: Optional[str] +``` + +The Workspace ID of this request. + +### `thread_ts` + +```python +thread_ts: Optional[str] +``` + +The conversation thread's ID associated with this request. + +### `token` + +```python +token: Optional[str] +``` + +The (bot/user) token resolved for this request. + +### `user_id` + +```python +user_id: Optional[str] +``` + +The user ID associated ith this request. + +### `user_token` + +```python +user_token: Optional[str] +``` + +The user token resolved for this request. + +## Submodules + +- [slack_bolt.context.ack](/tools/bolt-python/reference/context/ack) +- [slack_bolt.context.assistant](/tools/bolt-python/reference/context/assistant) +- [slack_bolt.context.async_context](/tools/bolt-python/reference/context/async_context) +- [slack_bolt.context.base_context](/tools/bolt-python/reference/context/base_context) +- [slack_bolt.context.complete](/tools/bolt-python/reference/context/complete) +- [slack_bolt.context.context](/tools/bolt-python/reference/context/context) +- [slack_bolt.context.fail](/tools/bolt-python/reference/context/fail) +- [slack_bolt.context.get_thread_context](/tools/bolt-python/reference/context/get_thread_context) +- [slack_bolt.context.respond](/tools/bolt-python/reference/context/respond) +- [slack_bolt.context.save_thread_context](/tools/bolt-python/reference/context/save_thread_context) +- [slack_bolt.context.say](/tools/bolt-python/reference/context/say) +- [slack_bolt.context.say_stream](/tools/bolt-python/reference/context/say_stream) +- [slack_bolt.context.set_status](/tools/bolt-python/reference/context/set_status) +- [slack_bolt.context.set_suggested_prompts](/tools/bolt-python/reference/context/set_suggested_prompts) +- [slack_bolt.context.set_title](/tools/bolt-python/reference/context/set_title) diff --git a/docs/english/reference/context/respond/async_respond.md b/docs/english/reference/context/respond/async_respond.md index 606e33495..49e5369c3 100644 --- a/docs/english/reference/context/respond/async_respond.md +++ b/docs/english/reference/context/respond/async_respond.md @@ -3,24 +3,4 @@ sidebar_label: async_respond title: slack_bolt.context.respond.async_respond --- -## AsyncRespond Objects -```python -class AsyncRespond() -``` - -#### response\_url: `Optional[str]` - -#### proxy: `Optional[str]` - -#### ssl: `Optional[SSLContext]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - response_url: Optional[str], - proxy: Optional[str] = None, - ssl: Optional[SSLContext] = None) -``` diff --git a/docs/english/reference/context/respond/index.md b/docs/english/reference/context/respond/index.md index e6d911a31..d490634f8 100644 --- a/docs/english/reference/context/respond/index.md +++ b/docs/english/reference/context/respond/index.md @@ -8,25 +8,3 @@ title: slack_bolt.context.respond - [slack_bolt.context.respond.async_respond](/tools/bolt-python/reference/context/respond/async_respond) - [slack_bolt.context.respond.internals](/tools/bolt-python/reference/context/respond/internals) - [slack_bolt.context.respond.respond](/tools/bolt-python/reference/context/respond/respond) - -## Respond Objects - -```python -class Respond() -``` - -#### response\_url: `Optional[str]` - -#### proxy: `Optional[str]` - -#### ssl: `Optional[SSLContext]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - response_url: Optional[str], - proxy: Optional[str] = None, - ssl: Optional[SSLContext] = None) -``` diff --git a/docs/english/reference/context/respond/respond.md b/docs/english/reference/context/respond/respond.md index b210c12a2..ee4aa7260 100644 --- a/docs/english/reference/context/respond/respond.md +++ b/docs/english/reference/context/respond/respond.md @@ -4,24 +4,4 @@ title: slack_bolt.context.respond.respond slug: respond --- -## Respond Objects -```python -class Respond() -``` - -#### response\_url: `Optional[str]` - -#### proxy: `Optional[str]` - -#### ssl: `Optional[SSLContext]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - response_url: Optional[str], - proxy: Optional[str] = None, - ssl: Optional[SSLContext] = None) -``` diff --git a/docs/english/reference/context/save_thread_context/async_save_thread_context.md b/docs/english/reference/context/save_thread_context/async_save_thread_context.md index 43694625e..277177169 100644 --- a/docs/english/reference/context/save_thread_context/async_save_thread_context.md +++ b/docs/english/reference/context/save_thread_context/async_save_thread_context.md @@ -3,23 +3,4 @@ sidebar_label: async_save_thread_context title: slack_bolt.context.save_thread_context.async_save_thread_context --- -## AsyncSaveThreadContext Objects -```python -class AsyncSaveThreadContext() -``` - -#### thread\_context\_store: `AsyncAssistantThreadContextStore` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### \_\_init\_\_ - -```python -def __init__( - thread_context_store: AsyncAssistantThreadContextStore, - channel_id: str, - thread_ts: str) -``` diff --git a/docs/english/reference/context/save_thread_context/index.md b/docs/english/reference/context/save_thread_context/index.md index 8410a7db8..8ba46eea8 100644 --- a/docs/english/reference/context/save_thread_context/index.md +++ b/docs/english/reference/context/save_thread_context/index.md @@ -7,24 +7,3 @@ title: slack_bolt.context.save_thread_context - [slack_bolt.context.save_thread_context.async_save_thread_context](/tools/bolt-python/reference/context/save_thread_context/async_save_thread_context) - [slack_bolt.context.save_thread_context.save_thread_context](/tools/bolt-python/reference/context/save_thread_context/save_thread_context) - -## SaveThreadContext Objects - -```python -class SaveThreadContext() -``` - -#### thread\_context\_store: `AssistantThreadContextStore` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### \_\_init\_\_ - -```python -def __init__( - thread_context_store: AssistantThreadContextStore, - channel_id: str, - thread_ts: str) -``` diff --git a/docs/english/reference/context/save_thread_context/save_thread_context.md b/docs/english/reference/context/save_thread_context/save_thread_context.md index 3223b355a..a6aec850b 100644 --- a/docs/english/reference/context/save_thread_context/save_thread_context.md +++ b/docs/english/reference/context/save_thread_context/save_thread_context.md @@ -4,23 +4,4 @@ title: slack_bolt.context.save_thread_context.save_thread_context slug: save_thread_context --- -## SaveThreadContext Objects -```python -class SaveThreadContext() -``` - -#### thread\_context\_store: `AssistantThreadContextStore` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### \_\_init\_\_ - -```python -def __init__( - thread_context_store: AssistantThreadContextStore, - channel_id: str, - thread_ts: str) -``` diff --git a/docs/english/reference/context/say/async_say.md b/docs/english/reference/context/say/async_say.md index 9d461bcb8..b32f56e2a 100644 --- a/docs/english/reference/context/say/async_say.md +++ b/docs/english/reference/context/say/async_say.md @@ -3,26 +3,4 @@ sidebar_label: async_say title: slack_bolt.context.say.async_say --- -## AsyncSay Objects -```python -class AsyncSay() -``` - -#### client: `Optional[AsyncWebClient]` - -#### channel: `Optional[str]` - -#### thread\_ts: `Optional[str]` - -#### build\_metadata: `Optional[Callable[[], Awaitable[Union[Dict, Metadata]]]]` - -#### \_\_init\_\_ - -```python -def __init__( - client: Optional[AsyncWebClient], - channel: Optional[str], - thread_ts: Optional[str] = None, - build_metadata: Optional[Callable[[], Awaitable[Union[Dict, Metadata]]]] = None) -``` diff --git a/docs/english/reference/context/say/index.md b/docs/english/reference/context/say/index.md index ee6f647d8..67ffdb551 100644 --- a/docs/english/reference/context/say/index.md +++ b/docs/english/reference/context/say/index.md @@ -8,30 +8,3 @@ title: slack_bolt.context.say - [slack_bolt.context.say.async_say](/tools/bolt-python/reference/context/say/async_say) - [slack_bolt.context.say.internals](/tools/bolt-python/reference/context/say/internals) - [slack_bolt.context.say.say](/tools/bolt-python/reference/context/say/say) - -## Say Objects - -```python -class Say() -``` - -#### client: `Optional[WebClient]` - -#### channel: `Optional[str]` - -#### thread\_ts: `Optional[str]` - -#### metadata: `Optional[Union[Dict, Metadata]]` - -#### build\_metadata: `Optional[Callable[[], Optional[Union[Dict, Metadata]]]]` - -#### \_\_init\_\_ - -```python -def __init__( - client: Optional[WebClient], - channel: Optional[str], - thread_ts: Optional[str] = None, - metadata: Optional[Union[Dict, Metadata]] = None, - build_metadata: Optional[Callable[[], Optional[Union[Dict, Metadata]]]] = None) -``` diff --git a/docs/english/reference/context/say/say.md b/docs/english/reference/context/say/say.md index 8bbaddd9b..f0b94466b 100644 --- a/docs/english/reference/context/say/say.md +++ b/docs/english/reference/context/say/say.md @@ -4,29 +4,4 @@ title: slack_bolt.context.say.say slug: say --- -## Say Objects -```python -class Say() -``` - -#### client: `Optional[WebClient]` - -#### channel: `Optional[str]` - -#### thread\_ts: `Optional[str]` - -#### metadata: `Optional[Union[Dict, Metadata]]` - -#### build\_metadata: `Optional[Callable[[], Optional[Union[Dict, Metadata]]]]` - -#### \_\_init\_\_ - -```python -def __init__( - client: Optional[WebClient], - channel: Optional[str], - thread_ts: Optional[str] = None, - metadata: Optional[Union[Dict, Metadata]] = None, - build_metadata: Optional[Callable[[], Optional[Union[Dict, Metadata]]]] = None) -``` diff --git a/docs/english/reference/context/say_stream/async_say_stream.md b/docs/english/reference/context/say_stream/async_say_stream.md index f6c4954b6..a1bd26bbd 100644 --- a/docs/english/reference/context/say_stream/async_say_stream.md +++ b/docs/english/reference/context/say_stream/async_say_stream.md @@ -3,30 +3,8 @@ sidebar_label: async_say_stream title: slack_bolt.context.say_stream.async_say_stream --- -## AsyncSayStream Objects +## `AsyncSayStream` ```python -class AsyncSayStream() -``` - -#### client: `AsyncWebClient` - -#### channel: `Optional[str]` - -#### recipient\_team\_id: `Optional[str]` - -#### recipient\_user\_id: `Optional[str]` - -#### thread\_ts: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - client: AsyncWebClient, - channel: Optional[str] = None, - recipient_team_id: Optional[str] = None, - recipient_user_id: Optional[str] = None, - thread_ts: Optional[str] = None) +AsyncSayStream(*, client, channel=None, recipient_team_id=None, recipient_user_id=None, thread_ts=None) ``` diff --git a/docs/english/reference/context/say_stream/index.md b/docs/english/reference/context/say_stream/index.md index aed711da9..a4fa245ac 100644 --- a/docs/english/reference/context/say_stream/index.md +++ b/docs/english/reference/context/say_stream/index.md @@ -3,35 +3,13 @@ sidebar_label: say_stream title: slack_bolt.context.say_stream --- -## Submodules - -- [slack_bolt.context.say_stream.async_say_stream](/tools/bolt-python/reference/context/say_stream/async_say_stream) -- [slack_bolt.context.say_stream.say_stream](/tools/bolt-python/reference/context/say_stream/say_stream) - -## SayStream Objects +## `SayStream` ```python -class SayStream() +SayStream(*, client, channel=None, recipient_team_id=None, recipient_user_id=None, thread_ts=None) ``` -#### client: `WebClient` - -#### channel: `Optional[str]` - -#### recipient\_team\_id: `Optional[str]` - -#### recipient\_user\_id: `Optional[str]` - -#### thread\_ts: `Optional[str]` - -#### \_\_init\_\_ +## Submodules -```python -def __init__( - *, - client: WebClient, - channel: Optional[str] = None, - recipient_team_id: Optional[str] = None, - recipient_user_id: Optional[str] = None, - thread_ts: Optional[str] = None) -``` +- [slack_bolt.context.say_stream.async_say_stream](/tools/bolt-python/reference/context/say_stream/async_say_stream) +- [slack_bolt.context.say_stream.say_stream](/tools/bolt-python/reference/context/say_stream/say_stream) diff --git a/docs/english/reference/context/say_stream/say_stream.md b/docs/english/reference/context/say_stream/say_stream.md index e78c8394f..87f3bc276 100644 --- a/docs/english/reference/context/say_stream/say_stream.md +++ b/docs/english/reference/context/say_stream/say_stream.md @@ -4,30 +4,8 @@ title: slack_bolt.context.say_stream.say_stream slug: say_stream --- -## SayStream Objects +## `SayStream` ```python -class SayStream() -``` - -#### client: `WebClient` - -#### channel: `Optional[str]` - -#### recipient\_team\_id: `Optional[str]` - -#### recipient\_user\_id: `Optional[str]` - -#### thread\_ts: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - client: WebClient, - channel: Optional[str] = None, - recipient_team_id: Optional[str] = None, - recipient_user_id: Optional[str] = None, - thread_ts: Optional[str] = None) +SayStream(*, client, channel=None, recipient_team_id=None, recipient_user_id=None, thread_ts=None) ``` diff --git a/docs/english/reference/context/set_status/async_set_status.md b/docs/english/reference/context/set_status/async_set_status.md index 5886090d5..d4918d3f5 100644 --- a/docs/english/reference/context/set_status/async_set_status.md +++ b/docs/english/reference/context/set_status/async_set_status.md @@ -3,20 +3,4 @@ sidebar_label: async_set_status title: slack_bolt.context.set_status.async_set_status --- -## AsyncSetStatus Objects -```python -class AsyncSetStatus() -``` - -#### client: `AsyncWebClient` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### \_\_init\_\_ - -```python -def __init__(client: AsyncWebClient, channel_id: str, thread_ts: str) -``` diff --git a/docs/english/reference/context/set_status/index.md b/docs/english/reference/context/set_status/index.md index e6df8ffee..d7e708193 100644 --- a/docs/english/reference/context/set_status/index.md +++ b/docs/english/reference/context/set_status/index.md @@ -7,21 +7,3 @@ title: slack_bolt.context.set_status - [slack_bolt.context.set_status.async_set_status](/tools/bolt-python/reference/context/set_status/async_set_status) - [slack_bolt.context.set_status.set_status](/tools/bolt-python/reference/context/set_status/set_status) - -## SetStatus Objects - -```python -class SetStatus() -``` - -#### client: `WebClient` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### \_\_init\_\_ - -```python -def __init__(client: WebClient, channel_id: str, thread_ts: str) -``` diff --git a/docs/english/reference/context/set_status/set_status.md b/docs/english/reference/context/set_status/set_status.md index 70308efbd..5d984c8ae 100644 --- a/docs/english/reference/context/set_status/set_status.md +++ b/docs/english/reference/context/set_status/set_status.md @@ -4,20 +4,4 @@ title: slack_bolt.context.set_status.set_status slug: set_status --- -## SetStatus Objects -```python -class SetStatus() -``` - -#### client: `WebClient` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### \_\_init\_\_ - -```python -def __init__(client: WebClient, channel_id: str, thread_ts: str) -``` diff --git a/docs/english/reference/context/set_suggested_prompts/async_set_suggested_prompts.md b/docs/english/reference/context/set_suggested_prompts/async_set_suggested_prompts.md index 061926f3c..b6788651a 100644 --- a/docs/english/reference/context/set_suggested_prompts/async_set_suggested_prompts.md +++ b/docs/english/reference/context/set_suggested_prompts/async_set_suggested_prompts.md @@ -3,20 +3,4 @@ sidebar_label: async_set_suggested_prompts title: slack_bolt.context.set_suggested_prompts.async_set_suggested_prompts --- -## AsyncSetSuggestedPrompts Objects -```python -class AsyncSetSuggestedPrompts() -``` - -#### client: `AsyncWebClient` - -#### channel\_id: `str` - -#### thread\_ts: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__(client: AsyncWebClient, channel_id: str, thread_ts: Optional[str] = None) -``` diff --git a/docs/english/reference/context/set_suggested_prompts/index.md b/docs/english/reference/context/set_suggested_prompts/index.md index 860d92c11..9fd57f089 100644 --- a/docs/english/reference/context/set_suggested_prompts/index.md +++ b/docs/english/reference/context/set_suggested_prompts/index.md @@ -7,21 +7,3 @@ title: slack_bolt.context.set_suggested_prompts - [slack_bolt.context.set_suggested_prompts.async_set_suggested_prompts](/tools/bolt-python/reference/context/set_suggested_prompts/async_set_suggested_prompts) - [slack_bolt.context.set_suggested_prompts.set_suggested_prompts](/tools/bolt-python/reference/context/set_suggested_prompts/set_suggested_prompts) - -## SetSuggestedPrompts Objects - -```python -class SetSuggestedPrompts() -``` - -#### client: `WebClient` - -#### channel\_id: `str` - -#### thread\_ts: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__(client: WebClient, channel_id: str, thread_ts: Optional[str] = None) -``` diff --git a/docs/english/reference/context/set_suggested_prompts/set_suggested_prompts.md b/docs/english/reference/context/set_suggested_prompts/set_suggested_prompts.md index d8ea84fea..e93509e3c 100644 --- a/docs/english/reference/context/set_suggested_prompts/set_suggested_prompts.md +++ b/docs/english/reference/context/set_suggested_prompts/set_suggested_prompts.md @@ -4,20 +4,4 @@ title: slack_bolt.context.set_suggested_prompts.set_suggested_prompts slug: set_suggested_prompts --- -## SetSuggestedPrompts Objects -```python -class SetSuggestedPrompts() -``` - -#### client: `WebClient` - -#### channel\_id: `str` - -#### thread\_ts: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__(client: WebClient, channel_id: str, thread_ts: Optional[str] = None) -``` diff --git a/docs/english/reference/context/set_title/async_set_title.md b/docs/english/reference/context/set_title/async_set_title.md index 2b3fa124a..7613af9cb 100644 --- a/docs/english/reference/context/set_title/async_set_title.md +++ b/docs/english/reference/context/set_title/async_set_title.md @@ -3,20 +3,4 @@ sidebar_label: async_set_title title: slack_bolt.context.set_title.async_set_title --- -## AsyncSetTitle Objects -```python -class AsyncSetTitle() -``` - -#### client: `AsyncWebClient` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### \_\_init\_\_ - -```python -def __init__(client: AsyncWebClient, channel_id: str, thread_ts: str) -``` diff --git a/docs/english/reference/context/set_title/index.md b/docs/english/reference/context/set_title/index.md index 56b593c75..6ffb7ba6e 100644 --- a/docs/english/reference/context/set_title/index.md +++ b/docs/english/reference/context/set_title/index.md @@ -7,21 +7,3 @@ title: slack_bolt.context.set_title - [slack_bolt.context.set_title.async_set_title](/tools/bolt-python/reference/context/set_title/async_set_title) - [slack_bolt.context.set_title.set_title](/tools/bolt-python/reference/context/set_title/set_title) - -## SetTitle Objects - -```python -class SetTitle() -``` - -#### client: `WebClient` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### \_\_init\_\_ - -```python -def __init__(client: WebClient, channel_id: str, thread_ts: str) -``` diff --git a/docs/english/reference/context/set_title/set_title.md b/docs/english/reference/context/set_title/set_title.md index a749267b2..f82cf35f0 100644 --- a/docs/english/reference/context/set_title/set_title.md +++ b/docs/english/reference/context/set_title/set_title.md @@ -4,20 +4,4 @@ title: slack_bolt.context.set_title.set_title slug: set_title --- -## SetTitle Objects -```python -class SetTitle() -``` - -#### client: `WebClient` - -#### channel\_id: `str` - -#### thread\_ts: `str` - -#### \_\_init\_\_ - -```python -def __init__(client: WebClient, channel_id: str, thread_ts: str) -``` diff --git a/docs/english/reference/error/index.md b/docs/english/reference/error/index.md index 20ae702f2..abba3b3c6 100644 --- a/docs/english/reference/error/index.md +++ b/docs/english/reference/error/index.md @@ -5,34 +5,8 @@ title: slack_bolt.error Bolt specific error types. -## BoltError Objects +## `BoltError` -```python -class BoltError(Exception) -``` +Bases: Exception General class in a Bolt app. - -## BoltUnhandledRequestError Objects - -```python -class BoltUnhandledRequestError(BoltError) -``` - -#### request: `BoltRequest` - -#### body: `dict` - -#### current\_response: `Optional[BoltResponse]` - -#### last\_global\_middleware\_name: `Optional[str]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - request: Union[BoltRequest, AsyncBoltRequest], - current_response: Optional[BoltResponse], - last_global_middleware_name: Optional[str] = None) -``` diff --git a/docs/english/reference/index.md b/docs/english/reference/index.md index 760cc16f2..54a4a41e0 100644 --- a/docs/english/reference/index.md +++ b/docs/english/reference/index.md @@ -1,6 +1,7 @@ --- sidebar_label: slack_bolt title: slack_bolt +sidebar_position: 1 --- A Python framework to build Slack apps in a flash with the latest platform features. Read the [getting started guide](https://docs.slack.dev/tools/bolt-python/creating-an-app) and look at our [code examples](https://github.com/slackapi/bolt-python/tree/main/examples) to learn how to build apps using Bolt. @@ -9,308 +10,1438 @@ A Python framework to build Slack apps in a flash with the latest platform featu * GitHub repository: https://github.com/slackapi/bolt-python * The class representing a Bolt app: `slack_bolt.app.app` -## Submodules +## `App` + +```python +App(*, logger=None, name=None, process_before_response=False, raise_error_for_unhandled_request=False, signing_secret=None, token=None, token_verification_enabled=True, client=None, before_authorize=None, authorize=None, user_facing_authorize_error_message=None, installation_store=None, installation_store_bot_only=None, request_verification_enabled=True, ignoring_self_events_enabled=True, ignoring_self_assistant_message_events_enabled=True, ssl_check_enabled=True, url_verification_enabled=True, attaching_function_token_enabled=True, oauth_settings=None, oauth_flow=None, verification_token=None, listener_executor=None, assistant_thread_context_store=None, attaching_conversation_kwargs_enabled=True) +``` + +Bolt App that provides functionalities to register middleware/listeners. + +```python +import os +from slack_bolt import App + +# Initializes your app with your bot token and signing secret +app = App( + token=os.environ.get("SLACK_BOT_TOKEN"), + signing_secret=os.environ.get("SLACK_SIGNING_SECRET") +) + +# Listens to incoming messages that contain "hello" +@app.message("hello") +def message_hello(message, say): + # say() sends a message to the channel where the event was triggered + say(f"Hey there <@{message['user']}>!") + +# Start your app +if __name__ == "__main__": + app.start(port=int(os.environ.get("PORT", 3000))) +``` + +Refer to https://docs.slack.dev/tools/bolt-python/creating-an-app for details. + +If you would like to build an OAuth app for enabling the app to run with multiple workspaces, +refer to https://docs.slack.dev/tools/bolt-python/concepts/authenticating-oauth to learn how to configure the app. + +**Parameters:** + +- **logger** (Optional[Logger]) – The custom logger that can be used in this app. +- **name** (Optional[str]) – The application name that will be used in logging. If absent, the source file name will be used. +- **process_before_response** (bool) – True if this app runs on Function as a Service. (Default: False) +- **raise_error_for_unhandled_request** (bool) – True if you want to raise exceptions for unhandled requests +and use @app.error listeners instead of +the built-in handler, which pints warning logs and returns 404 to Slack (Default: False) +- **signing_secret** (Optional[str]) – The Signing Secret value used for verifying requests from Slack. +- **token** (Optional[str]) – The bot/user access token required only for single-workspace app. +- **token_verification_enabled** (bool) – Verifies the validity of the given token if True. +- **client** (Optional[WebClient]) – The singleton `slack_sdk.WebClient` instance for this app. +- **before_authorize** (Optional[Union[Middleware, Callable..., [Any]]]) – A global middleware that can be executed right before authorize function +- **authorize** (Optional[Callable..., [AuthorizeResult]]) – The function to authorize an incoming request from Slack +by checking if there is a team/user in the installation data. +- **user_facing_authorize_error_message** (Optional[str]) – The user-facing error message to display +when the app is installed but the installation is not managed by this app's installation store +- **installation_store** (Optional[InstallationStore]) – The module offering save/find operations of installation data +- **installation_store_bot_only** (Optional[bool]) – Use `InstallationStore#find_bot()` if True (Default: False) +- **request_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`RequestVerification` is a built-in middleware that verifies the signature in HTTP Mode requests. +Make sure if it's safe enough when you turn a built-in middleware off. +We strongly recommend using RequestVerification for better security. +If you have a proxy that verifies request signature in front of the Bolt app, +it's totally fine to disable RequestVerification to avoid duplication of work. +Don't turn it off just for easiness of development. +- **ignoring_self_events_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`IgnoringSelfEvents` is a built-in middleware that enables Bolt apps to easily skip the events +generated by this app's bot user (this is useful for avoiding code error causing an infinite loop). +- **ignoring_self_assistant_message_events_enabled** (bool) – False if you would like to disable the built-in middleware. +`IgnoringSelfEvents` for this app's bot user message events within an assistant thread +This is useful for avoiding code error causing an infinite loop; Default: True +- **url_verification_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`UrlVerification` is a built-in middleware that handles url_verification requests +that verify the endpoint for Events API in HTTP Mode requests. +- **attaching_function_token_enabled** (bool) – False if you would like to disable the built-in middleware (Default: True). +`AttachingFunctionToken` is a built-in middleware that injects the just-in-time workflow-execution tokens +when your app receives `function_executed` or interactivity events scoped to a custom step. +- **ssl_check_enabled** (bool) – bool = False if you would like to disable the built-in middleware (Default: True). +`SslCheck` is a built-in middleware that handles ssl_check requests from Slack. +- **oauth_settings** (Optional[OAuthSettings]) – The settings related to Slack app installation flow (OAuth flow) +- **oauth_flow** (Optional[OAuthFlow]) – Instantiated `slack_bolt.oauth.OAuthFlow`. This is always prioritized over oauth_settings. +- **verification_token** (Optional[str]) – Deprecated verification mechanism. This can be used only for ssl_check requests. +- **listener_executor** (Optional[Executor]) – Custom executor to run background tasks. If absent, the default `ThreadPoolExecutor` will +be used. +- **assistant_thread_context_store** (Optional[AssistantThreadContextStore]) – Custom AssistantThreadContext store (Default: the built-in implementation, +which uses a parent message's metadata to store the latest context) +- **attaching_conversation_kwargs_enabled** (bool) – False if you would like to disable the built-in +middleware (Default: True). `AttachingConversationKwargs` is a built-in middleware that attaches +conversation-specific listener arguments (such as `say`, `set_status`, `say_stream`, and +`set_suggested_prompts`) for assistant thread and direct message events. + +### `action` + +```python +action(constraints, matchers=None, middleware=None) +``` + +Registers a new action listener. This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.action("approve_button") +def update_message(ack): + ack() + +# Pass a function to this method +app.action("approve_button")(update_message) +``` + +* Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for actions in `blocks`. +* Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for actions in `attachments`. +* Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for actions in dialogs. + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `attachment_action` + +```python +attachment_action(callback_id, matchers=None, middleware=None) +``` + +Registers a new `interactive_message` action listener. + +Refer to https://docs.slack.dev/legacy/legacy-messaging/legacy-message-buttons/ for details. + +### `block_action` + +```python +block_action(constraints, matchers=None, middleware=None) +``` + +Registers a new `block_actions` action listener. + +Refer to https://docs.slack.dev/reference/interaction-payloads/block_actions-payload/ for details. + +### `block_suggestion` + +```python +block_suggestion(action_id, matchers=None, middleware=None) +``` + +Registers a new `block_suggestion` listener. + +### `client` + +```python +client: WebClient +``` + +The singleton `slack_sdk.WebClient` instance in this app. + +### `command` + +```python +command(command, matchers=None, middleware=None) +``` + +Registers a new slash command listener. + +This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.command("/echo") +def repeat_text(ack, say, command): + # Acknowledge command request + ack() + say(f"{command['text']}") + +# Pass a function to this method +app.command("/echo")(repeat_text) +``` + +Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details of Slash Commands. + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **command** (Union[str, Pattern]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `dialog_cancellation` + +```python +dialog_cancellation(callback_id, matchers=None, middleware=None) +``` + +Registers a new `dialog_cancellation` listener. + +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. + +### `dialog_submission` + +```python +dialog_submission(callback_id, matchers=None, middleware=None) +``` + +Registers a new `dialog_submission` listener. + +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. + +### `dialog_suggestion` + +```python +dialog_suggestion(callback_id, matchers=None, middleware=None) +``` + +Registers a new `dialog_suggestion` listener. + +Refer to https://docs.slack.dev/legacy/legacy-dialogs/ for details. + +### `dispatch` + +```python +dispatch(req) +``` + +Applies all middleware and dispatches an incoming request from Slack to the right code path. + +**Parameters:** + +- **req** (BoltRequest) – An incoming request from Slack + +**Returns:** + +- BoltResponse – The response generated by this Bolt app + +### `error` + +```python +error(func) +``` + +Updates the global error handler. This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.error +def custom_error_handler(error, body, logger): + logger.exception(f"Error: {error}") + logger.info(f"Request body: {body}") + +# Pass a function to this method +app.error(custom_error_handler) +``` + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **func** (Callable..., [Optional[BoltResponse]]) – The function that is supposed to be executed +when getting an unhandled error in Bolt app. + +### `event` + +```python +event(event, matchers=None, middleware=None) +``` + +Registers a new event listener. This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.event("team_join") +def ask_for_introduction(event, say): + welcome_channel_id = "C12345" + user_id = event["user"] + text = f"Welcome to the team, <@{user_id}>! :tada: You can introduce yourself in this channel." + say(text=text, channel=welcome_channel_id) + +# Pass a function to this method +app.event("team_join")(ask_for_introduction) +``` + +Refer to https://docs.slack.dev/apis/events-api/ for details of Events API. + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **event** (Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]]) – The conditions that match a request payload. +If you pass a dict for this, you can have type, subtype in the constraint. +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `function` + +```python +function(callback_id, matchers=None, middleware=None, auto_acknowledge=True, ack_timeout=3) +``` + +Registers a new Function listener. + +This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.function("reverse") +def reverse_string(ack: Ack, inputs: dict, complete: Complete, fail: Fail): + try: + ack() + string_to_reverse = inputs["stringToReverse"] + complete(outputs={"reverseString": string_to_reverse[::-1]}) + except Exception as e: + fail(f"Cannot reverse string (error: {e})") + raise e + +# Pass a function to this method +app.function("reverse")(reverse_string) +``` + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **callback_id** (Union[str, Pattern]) – The callback id to identify the function +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. +- **auto_acknowledge** (bool) – Whether Bolt automatically acknowledges the function execution event on the +listener's behalf. When False, your listener must call `ack()` itself within `ack_timeout` +seconds (Default: True). +- **ack_timeout** (int) – The number of seconds to wait for the listener to call `ack()`. +Only takes effect when `auto_acknowledge` is False (Default: 3). + +### `global_shortcut` + +```python +global_shortcut(callback_id, matchers=None, middleware=None) +``` + +Registers a new global shortcut listener. + +### `installation_store` + +```python +installation_store: Optional[InstallationStore] +``` + +The `slack_sdk.oauth.InstallationStore` that can be used in the `authorize` middleware. + +### `listener_runner` + +```python +listener_runner: ThreadListenerRunner +``` + +The thread executor for asynchronously running listeners. + +### `logger` + +```python +logger: logging.Logger +``` + +The logger this app uses. + +### `message` + +```python +message(keyword='', matchers=None, middleware=None) +``` + +Registers a new message event listener. This method can be used as either a decorator or a method. + +Check the `App#event` method's docstring for details. + +```python +# Use this method as a decorator +@app.message(":wave:") +def say_hello(message, say): + user = message['user'] + say(f"Hi there, <@{user}>!") + +# Pass a function to this method +app.message(":wave:")(say_hello) +``` + +Refer to https://docs.slack.dev/reference/events/message/ for details of `message` events. + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **keyword** (Union[str, Pattern]) – The keyword to match +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `message_shortcut` + +```python +message_shortcut(callback_id, matchers=None, middleware=None) +``` + +Registers a new message shortcut listener. + +### `middleware` + +```python +middleware(*args) +``` + +Registers a new middleware to this app. + +This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.middleware +def middleware_func(logger, body, next): + logger.info(f"request body: {body}") + next() + +# Pass a function to this method +app.middleware(middleware_func) +``` + +Refer to https://docs.slack.dev/tools/bolt-python/concepts/global-middleware for details. + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- ***args** – A function that works as a global middleware. + +### `name` + +```python +name: str +``` + +The name of this app (default: the filename). + +### `oauth_flow` + +```python +oauth_flow: Optional[OAuthFlow] +``` + +Configured `OAuthFlow` object if exists. + +### `options` + +```python +options(constraints, matchers=None, middleware=None) +``` + +Registers a new options listener. + +This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.options("menu_selection") +def show_menu_options(ack): + options = [ + { + "text": {"type": "plain_text", "text": "Option 1"}, + "value": "1-1", + }, + { + "text": {"type": "plain_text", "text": "Option 2"}, + "value": "1-2", + }, + ] + ack(options=options) + +# Pass a function to this method +app.options("menu_selection")(show_menu_options) +``` + +Refer to the following documents for details: + +* https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element#external_select +* https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element#external_multi_select + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `shortcut` + +```python +shortcut(constraints, matchers=None, middleware=None) +``` + +Registers a new shortcut listener. + +This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.shortcut("open_modal") +def open_modal(ack, body, client): + # Acknowledge the command request + ack() + # Call views_open with the built-in client + client.views_open( + # Pass a valid trigger_id within 3 seconds of receiving it + trigger_id=body["trigger_id"], + # View payload + view={ ... } + ) + +# Pass a function to this method +app.shortcut("open_modal")(open_modal) +``` + +Refer to https://docs.slack.dev/interactivity/implementing-shortcuts/ for details about Shortcuts. + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload. +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `start` + +```python +start(port=3000, path='/slack/events', http_server_logger_enabled=True) +``` + +Starts a web server for local development. + +```python +# With the default settings, `http://localhost:3000/slack/events` +# is available for handling incoming requests from Slack +app.start() +``` + +This method internally starts a Web server process built with the `http.server` module. +For production, consider using a production-ready WSGI server such as Gunicorn. + +**Parameters:** + +- **port** (int) – The port to listen on (Default: 3000) +- **path** (str) – The path to handle request from Slack (Default: `/slack/events`) +- **http_server_logger_enabled** (bool) – The flag to enable http.server logging if True (Default: True) + +### `step` + +```python +step(callback_id, edit=None, save=None, execute=None) +``` + +Deprecated: register a new step from app listener. + +Steps from apps for legacy workflows are now deprecated. +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ + +Registers a new step from app listener. + +Unlike others, this method doesn't behave as a decorator. +If you want to register a step from app by a decorator, use `WorkflowStepBuilder`'s methods. + +```python +# Create a new WorkflowStep instance +from slack_bolt.workflows.step import WorkflowStep +ws = WorkflowStep( + callback_id="add_task", + edit=edit, + save=save, + execute=execute, +) +# Pass Step to set up listeners +app.step(ws) +``` + +Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details of steps from apps. + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +For further information about WorkflowStep specific function arguments +such as `configure`, `update`, `complete`, and `fail`, +refer to `slack_bolt.workflows.step.utilities` API documents. + +**Parameters:** + +- **callback_id** (Union[str, Pattern, WorkflowStep, WorkflowStepBuilder]) – The Callback ID for this step from app +- **edit** (Optional[Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]]) – The function for displaying a modal in the Workflow Builder +- **save** (Optional[Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]]) – The function for handling configuration in the Workflow Builder +- **execute** (Optional[Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]]) – The function for handling the step execution + +### `use` + +```python +use(*args) +``` + +Registers a new global middleware to this app. This method can be used as either a decorator or a method. + +Refer to `App#middleware()` method's docstring for details. + +### `view` + +```python +view(constraints, matchers=None, middleware=None) +``` + +Registers a new `view_submission`/`view_closed` event listener. + +This method can be used as either a decorator or a method. + +```python +# Use this method as a decorator +@app.view("view_1") +def handle_submission(ack, body, client, view): + # Assume there's an input block with `block_c` as the block_id and `dreamy_input` + hopes_and_dreams = view["state"]["values"]["block_c"]["dreamy_input"] + user = body["user"]["id"] + # Validate the inputs + errors = {} + if hopes_and_dreams is not None and len(hopes_and_dreams) <= 5: + errors["block_c"] = "The value must be longer than 5 characters" + if len(errors) > 0: + ack(response_action="errors", errors=errors) + return # Return early to display the validation errors to the user + # Acknowledge the view_submission event and close the modal + ack() + # Do whatever you want with the input data - here we're saving it to a DB + +# Pass a function to this method +app.view("view_1")(handle_submission) +``` + +Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload for details of payloads. + +To learn available arguments for middleware/listeners, see `slack_bolt.kwargs_injection.args`'s API document. + +**Parameters:** + +- **constraints** (Union[str, Pattern, Dict[str, Union[str, Pattern]]]) – The conditions that match a request payload +- **matchers** (Optional[Sequence[Callable..., [bool]]]) – A list of listener matcher functions. +Only when all the matchers return True, the listener function can be invoked. +- **middleware** (Optional[Sequence[Union[Callable, Middleware]]]) – A list of lister middleware functions. +Only when all the middleware call `next()` method, the listener function can be invoked. + +### `view_closed` + +```python +view_closed(constraints, matchers=None, middleware=None) +``` + +Registers a new `view_closed` listener. + +Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_closed for details. + +### `view_submission` + +```python +view_submission(constraints, matchers=None, middleware=None) +``` + +Registers a new `view_submission` listener. + +Refer to https://docs.slack.dev/reference/interaction-payloads/view-interactions-payload/#view_submission for +details. + +## `Args` + +```python +Args(*, logger, client, req, resp, context, body, payload, options=None, shortcut=None, action=None, view=None, command=None, event=None, message=None, ack, say, respond, complete, fail, set_status=None, set_title=None, set_suggested_prompts=None, get_thread_context=None, save_thread_context=None, say_stream=None, next, **kwargs) +``` + +All the arguments in this class are available in any middleware / listeners. + +You can inject the named variables in the argument list in arbitrary order. + +```python +@app.action("link_button") +def handle_buttons(ack, respond, logger, context, body, client): + logger.info(f"request body: {body}") + ack() + if context.channel_id is not None: + respond("Hi!") + client.views_open( + trigger_id=body["trigger_id"], + view={ ... } + ) +``` + +Alternatively, you can include a parameter named `args` and it will be injected with an instance of this class. + +```python +@app.action("link_button") +def handle_buttons(args): + args.logger.info(f"request body: {args.body}") + args.ack() + if args.context.channel_id is not None: + args.respond("Hi!") + args.client.views_open( + trigger_id=args.body["trigger_id"], + view={ ... } + ) +``` + +### `ack` + +```python +ack: Ack = ack +``` + +`ack()` utility function, which returns acknowledgement to the Slack servers + +### `action` + +```python +action: Optional[Dict[str, Any]] = action +``` + +An alias for payload in an `@app.action` listener + +### `body` + +```python +body: Dict[str, Any] = body +``` + +Parsed request body data + +### `client` + +```python +client: WebClient = client +``` + +`slack_sdk.web.WebClient` instance with a valid token + +### `command` + +```python +command: Optional[Dict[str, Any]] = command +``` + +An alias for payload in an `@app.command` listener + +### `complete` + +```python +complete: Complete = complete +``` + +`complete()` utility function, signals a successful completion of the custom function + +### `context` + +```python +context: BoltContext = context +``` + +Context data associated with the incoming request + +### `event` + +```python +event: Optional[Dict[str, Any]] = event +``` + +An alias for payload in an `@app.event` listener + +### `fail` + +```python +fail: Fail = fail +``` -- [slack_bolt.adapter](/tools/bolt-python/reference/adapter) -- [slack_bolt.app](/tools/bolt-python/reference/app) -- [slack_bolt.async_app](/tools/bolt-python/reference/async_app) -- [slack_bolt.authorization](/tools/bolt-python/reference/authorization) -- [slack_bolt.context](/tools/bolt-python/reference/context) -- [slack_bolt.error](/tools/bolt-python/reference/error) -- [slack_bolt.kwargs_injection](/tools/bolt-python/reference/kwargs_injection) -- [slack_bolt.lazy_listener](/tools/bolt-python/reference/lazy_listener) -- [slack_bolt.listener](/tools/bolt-python/reference/listener) -- [slack_bolt.listener_matcher](/tools/bolt-python/reference/listener_matcher) -- [slack_bolt.logger](/tools/bolt-python/reference/logger) -- [slack_bolt.middleware](/tools/bolt-python/reference/middleware) -- [slack_bolt.oauth](/tools/bolt-python/reference/oauth) -- [slack_bolt.request](/tools/bolt-python/reference/request) -- [slack_bolt.response](/tools/bolt-python/reference/response) -- [slack_bolt.util](/tools/bolt-python/reference/util) -- [slack_bolt.version](/tools/bolt-python/reference/version) -- [slack_bolt.workflows](/tools/bolt-python/reference/workflows) +`fail()` utility function, signal that the custom function failed to complete -## App Objects +### `get_thread_context` ```python -class App() +get_thread_context: Optional[GetThreadContext] = get_thread_context ``` -## BoltContext Objects +`get_thread_context()` utility function for AI Agents & Assistants + +### `logger` ```python -class BoltContext(BaseContext) +logger: logging.Logger = logger ``` -Context object associated with a request from Slack. +Logger instance -## Ack Objects +### `message` ```python -class Ack() +message: Optional[Dict[str, Any]] = message ``` -## Complete Objects +An alias for payload in an `@app.message` listener + +### `next` ```python -class Complete() +next: Callable[[], None] = next ``` -## Fail Objects +`next()` utility function, which tells the middleware chain that it can continue with the next one + +### `next_` ```python -class Fail() +next_: Callable[[], None] = next ``` -## Respond Objects +An alias of `next()` for avoiding the Python built-in method overrides in middleware functions + +### `options` ```python -class Respond() +options: Optional[Dict[str, Any]] = options ``` -## Say Objects +An alias for payload in an `@app.options` listener + +### `payload` ```python -class Say() +payload: Dict[str, Any] = payload ``` -## SayStream Objects +The unwrapped core data in the request body + +### `req` ```python -class SayStream() +req: BoltRequest = req ``` -## Args Objects +Incoming request from Slack + +### `request` ```python -class Args() +request: BoltRequest = req ``` -All the arguments in this class are available in any middleware / listeners. +Incoming request from Slack -You can inject the named variables in the argument list in arbitrary order. +### `resp` ```python -@app.action("link_button") -def handle_buttons(ack, respond, logger, context, body, client): - logger.info(f"request body: {body}") +resp: BoltResponse = resp +``` + +Response representation + +### `respond` + +```python +respond: Respond = respond +``` + +`respond()` utility function, which utilizes the associated `response_url` + +### `response` + +```python +response: BoltResponse = resp +``` + +Response representation + +### `save_thread_context` + +```python +save_thread_context: Optional[SaveThreadContext] = save_thread_context +``` + +`save_thread_context()` utility function for AI Agents & Assistants + +### `say` + +```python +say: Say = say +``` + +`say()` utility function, which calls `chat.postMessage` API with the associated channel ID + +### `say_stream` + +```python +say_stream: Optional[SayStream] = say_stream +``` + +`say_stream()` utility function for conversations, AI Agents & Assistants + +### `set_status` + +```python +set_status: Optional[SetStatus] = set_status +``` + +`set_status()` utility function for AI Agents & Assistants + +### `set_suggested_prompts` + +```python +set_suggested_prompts: Optional[SetSuggestedPrompts] = set_suggested_prompts +``` + +`set_suggested_prompts()` utility function for AI Agents & Assistants + +### `set_title` + +```python +set_title: Optional[SetTitle] = set_title +``` + +`set_title()` utility function for AI Agents & Assistants + +### `shortcut` + +```python +shortcut: Optional[Dict[str, Any]] = shortcut +``` + +An alias for payload in an `@app.shortcut` listener + +### `view` + +```python +view: Optional[Dict[str, Any]] = view +``` + +An alias for payload in an `@app.view` listener + +## `BoltContext` + +Bases: BaseContext + +Context object associated with a request from Slack. + +### `ack` + +```python +ack: Ack +``` + +`ack()` function for this request. + +```python +@app.action("button") +def handle_button_clicks(context): + context.ack() + +# You can access "ack" this way too. +@app.action("button") +def handle_button_clicks(ack): ack() - if context.channel_id is not None: - respond("Hi!") - client.views_open( - trigger_id=body["trigger_id"], - view={ ... } - ) ``` -Alternatively, you can include a parameter named `args` and it will be injected with an instance of this class. +**Returns:** + +- Ack – Callable `ack()` function + +### `actor_enterprise_id` ```python -@app.action("link_button") -def handle_buttons(args): - args.logger.info(f"request body: {args.body}") - args.ack() - if args.context.channel_id is not None: - args.respond("Hi!") - args.client.views_open( - trigger_id=args.body["trigger_id"], - view={ ... } +actor_enterprise_id: Optional[str] +``` + +The action's actor's Enterprise Grid organization ID. + +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. + +### `actor_team_id` + +```python +actor_team_id: Optional[str] +``` + +The action's actor's workspace ID. + +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. + +### `actor_user_id` + +```python +actor_user_id: Optional[str] +``` + +The action's actor's user ID. + +Note that this property is especially useful for handling events in Slack Connect channels. +That being said, it's not guaranteed to have a valid ID for all events due to server-side inconsistency. + +### `authorize_result` + +```python +authorize_result: Optional[AuthorizeResult] +``` + +The authorize result resolved for this request. + +### `bot_id` + +```python +bot_id: Optional[str] +``` + +The bot ID resolved for this request. + +### `bot_token` + +```python +bot_token: Optional[str] +``` + +The bot token resolved for this request. + +### `bot_user_id` + +```python +bot_user_id: Optional[str] +``` + +The bot user ID resolved for this request. + +### `channel_id` + +```python +channel_id: Optional[str] +``` + +The conversation ID associated with this request. + +### `client` + +```python +client: WebClient +``` + +The `WebClient` instance available for this request. + +```python +@app.event("app_mention") +def handle_events(context): + context.client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", + ) + +# You can access "client" this way too. +@app.event("app_mention") +def handle_events(client, context): + client.chat_postMessage( + channel=context.channel_id, + text="Thanks!", ) ``` +**Returns:** + +- WebClient – `WebClient` instance + +### `complete` + +```python +complete: Complete +``` + +`complete()` function for this request. + +Once a custom function's state is set to complete, +any outputs the function returns will be passed along to the next step of its housing workflow, +or complete the workflow if the function is the last step in a workflow. Additionally, +any interactivity handlers associated to a function invocation will no longer be invocable. + +```python +@app.function("reverse") +def handle_button_clicks(ack, complete): + ack() + complete(outputs={"stringReverse":"olleh"}) + +@app.function("reverse") +def handle_button_clicks(context): + context.ack() + context.complete(outputs={"stringReverse":"olleh"}) +``` + +**Returns:** -## Listener Objects +- Complete – Callable `complete()` function + +### `enterprise_id` + +```python +enterprise_id: Optional[str] +``` + +The Enterprise Grid Organization ID of this request. + +### `fail` ```python -class Listener() +fail: Fail ``` -## CustomListenerMatcher Objects +`fail()` function for this request. + +Once a custom function's state is set to error, +its housing workflow will be interrupted and any provided error message will be passed +on to the end user through SlackBot. Additionally, any interactivity handlers associated +to a function invocation will no longer be invocable. ```python -class CustomListenerMatcher(ListenerMatcher) +@app.function("reverse") +def handle_button_clicks(ack, fail): + ack() + fail(error="something went wrong") + +@app.function("reverse") +def handle_button_clicks(context): + context.ack() + context.fail(error="something went wrong") ``` -## BoltRequest Objects +**Returns:** + +- Fail – Callable `fail()` function + +### `function_bot_access_token` ```python -class BoltRequest() +function_bot_access_token: Optional[str] ``` -## BoltResponse Objects +The bot token resolved for this function request. + +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `function_execution_id` ```python -class BoltResponse() +function_execution_id: Optional[str] ``` -## Assistant Objects +The `function_execution_id` associated with this request. + +Only available for `function_executed` and interactivity events scoped to a custom step. + +### `inputs` ```python -class Assistant(Middleware) +inputs: Optional[Dict[str, Any]] ``` -#### thread\_context\_store: `Optional[AssistantThreadContextStore]` +The `inputs` associated with this request. + +Only available for `function_executed` and interactivity events scoped to a custom step. -#### base\_logger: `Optional[logging.Logger]` +### `is_enterprise_install` -#### \_\_init\_\_ +```python +is_enterprise_install: Optional[bool] +``` + +True if the request is associated with an Org-wide installation. + +### `listener_runner` ```python -def __init__( - *, - app_name: str = 'assistant', - thread_context_store: Optional[AssistantThreadContextStore] = None, - logger: Optional[logging.Logger] = None) +listener_runner: ThreadListenerRunner ``` -#### thread\_started +The properly configured listener_runner that is available for middleware/listeners. + +### `logger` ```python -def thread_started( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) +logger: Logger ``` -#### user\_message +The properly configured logger that is available for middleware/listeners. + +### `matches` ```python -def user_message( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) +matches: Optional[Tuple] ``` -#### bot\_message +Returns all the matched parts in message listener's regexp. + +### `respond` ```python -def bot_message( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) +respond: Optional[Respond] ``` -#### thread\_context\_changed +`respond()` function for this request. ```python -def thread_context_changed( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) +@app.action("button") +def handle_button_clicks(context): + context.ack() + context.respond("Hi!") + +# You can access "ack" this way too. +@app.action("button") +def handle_button_clicks(ack, respond): + ack() + respond("Hi!") ``` -#### default\_thread\_context\_changed +**Returns:** + +- Optional[Respond] – Callable `respond()` function + +### `response_url` ```python -def default_thread_context_changed( - save_thread_context: SaveThreadContext, - payload: dict) +response_url: Optional[str] ``` -#### process +The `response_url` associated with this request. + +### `say` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> Optional[BoltResponse] +say: Say ``` -#### build\_listener +`say()` function for this request. ```python -def build_listener( - listener_or_functions: Union[Listener, Callable, List[Callable]], - matchers: Optional[List[Union[ListenerMatcher, Callable[..., bool]]]] = None, - middleware: Optional[List[Middleware]] = None, - base_logger: Optional[Logger] = None) -> Listener +@app.action("button") +def handle_button_clicks(context): + context.ack() + context.say("Hi!") + +# You can access "ack" this way too. +@app.action("button") +def handle_button_clicks(ack, say): + ack() + say("Hi!") ``` -## AssistantThreadContext Objects +**Returns:** + +- Say – Callable `say()` function + +### `team_id` ```python -class AssistantThreadContext(dict) +team_id: Optional[str] ``` -#### enterprise\_id: `Optional[str]` +The Workspace ID of this request. -#### team\_id: `Optional[str]` +### `thread_ts` + +```python +thread_ts: Optional[str] +``` -#### channel\_id: `str` +The conversation thread's ID associated with this request. -#### \_\_init\_\_ +### `token` ```python -def __init__(payload: dict) +token: Optional[str] ``` -## AssistantThreadContextStore Objects +The (bot/user) token resolved for this request. + +### `user_id` ```python -class AssistantThreadContextStore() +user_id: Optional[str] ``` -#### save +The user ID associated ith this request. + +### `user_token` ```python -def save(*, channel_id: str, thread_ts: str, context: Dict[str, str]) -> None +user_token: Optional[str] ``` -#### find +The user token resolved for this request. + +## `BoltRequest` ```python -def find(*, channel_id: str, thread_ts: str) -> Optional[AssistantThreadContext] +BoltRequest(*, body, query=None, headers=None, context=None, mode='http') ``` -## FileAssistantThreadContextStore Objects +Request to a Bolt app. + +**Parameters:** + +- **body** (Union[str, dict]) – The raw request body (only plain text is supported for "http" mode) +- **query** (Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]) – The query string data in any data format. +- **headers** (Optional[Dict[str, Union[str, Sequence[str]]]]) – The request headers. +- **context** (Optional[Dict[str, Any]]) – The context in this request. +- **mode** (str) – The mode used for this request. (either "http" or "socket_mode") + +## `BoltResponse` ```python -class FileAssistantThreadContextStore(AssistantThreadContextStore) +BoltResponse(*, status, body='', headers=None) ``` -#### \_\_init\_\_ +The response from a Bolt app. + +**Parameters:** + +- **status** (int) – HTTP status code +- **body** (Union[str, dict]) – The response body (dict and str are supported) +- **headers** (Optional[Dict[str, Union[str, Sequence[str]]]]) – The response headers. + +## `Complete` ```python -def __init__(base_dir: str = str(Path.home()) + '/.bolt-app-assistant-thread-contexts') +Complete(client, function_execution_id) ``` -#### save +### `has_been_called` ```python -def save(*, channel_id: str, thread_ts: str, context: Dict[str, str]) -> None +has_been_called() ``` -#### find +Check if this complete function has been called. + +**Returns:** + +- **bool** (bool) – True if the complete function has been called, False otherwise. + +## `Fail` ```python -def find(*, channel_id: str, thread_ts: str) -> Optional[AssistantThreadContext] +Fail(client, function_execution_id) ``` -## SetStatus Objects +### `has_been_called` ```python -class SetStatus() +has_been_called() ``` -## SetTitle Objects +Check if this fail function has been called. + +**Returns:** + +- **bool** (bool) – True if the fail function has been called, False otherwise. + +## `Listener` + +### `run_ack_function` ```python -class SetTitle() +run_ack_function(*, request, response) ``` -## SetSuggestedPrompts Objects +Runs all the registered middleware and then run the listener function. + +**Parameters:** + +- **request** (BoltRequest) – The incoming request +- **response** (BoltResponse) – The current response + +**Returns:** + +- Optional[BoltResponse] – The processed response + +### `run_middleware` ```python -class SetSuggestedPrompts() +run_middleware(*, req, resp) ``` -## SaveThreadContext Objects +Runs a middleware. + +**Parameters:** + +- **req** (BoltRequest) – The incoming request +- **resp** (BoltResponse) – The current response + +**Returns:** + +- Tuple[Optional[BoltResponse], bool] – A tuple of the processed response and a flag indicating termination + +## `SayStream` ```python -class SaveThreadContext() +SayStream(*, client, channel=None, recipient_team_id=None, recipient_user_id=None, thread_ts=None) ``` + +## Submodules + +- [slack_bolt.adapter](/tools/bolt-python/reference/adapter) +- [slack_bolt.app](/tools/bolt-python/reference/app) +- [slack_bolt.async_app](/tools/bolt-python/reference/async_app) +- [slack_bolt.authorization](/tools/bolt-python/reference/authorization) +- [slack_bolt.context](/tools/bolt-python/reference/context) +- [slack_bolt.error](/tools/bolt-python/reference/error) +- [slack_bolt.kwargs_injection](/tools/bolt-python/reference/kwargs_injection) +- [slack_bolt.lazy_listener](/tools/bolt-python/reference/lazy_listener) +- [slack_bolt.listener](/tools/bolt-python/reference/listener) +- [slack_bolt.listener_matcher](/tools/bolt-python/reference/listener_matcher) +- [slack_bolt.logger](/tools/bolt-python/reference/logger) +- [slack_bolt.middleware](/tools/bolt-python/reference/middleware) +- [slack_bolt.oauth](/tools/bolt-python/reference/oauth) +- [slack_bolt.request](/tools/bolt-python/reference/request) +- [slack_bolt.response](/tools/bolt-python/reference/response) +- [slack_bolt.util](/tools/bolt-python/reference/util) +- [slack_bolt.version](/tools/bolt-python/reference/version) +- [slack_bolt.workflows](/tools/bolt-python/reference/workflows) diff --git a/docs/english/reference/kwargs_injection/args.md b/docs/english/reference/kwargs_injection/args.md index c47ccc6a5..086da65a9 100644 --- a/docs/english/reference/kwargs_injection/args.md +++ b/docs/english/reference/kwargs_injection/args.md @@ -3,10 +3,10 @@ sidebar_label: args title: slack_bolt.kwargs_injection.args --- -## Args Objects +## `Args` ```python -class Args() +Args(*, logger, client, req, resp, context, body, payload, options=None, shortcut=None, action=None, view=None, command=None, event=None, message=None, ack, say, respond, complete, fail, set_status=None, set_title=None, set_suggested_prompts=None, get_thread_context=None, save_thread_context=None, say_stream=None, next, **kwargs) ``` All the arguments in this class are available in any middleware / listeners. @@ -41,153 +41,234 @@ def handle_buttons(args): ) ``` +### `ack` -#### client: `WebClient` +```python +ack: Ack = ack +``` -`slack_sdk.web.WebClient` instance with a valid token +`ack()` utility function, which returns acknowledgement to the Slack servers -#### logger: `logging.Logger` +### `action` -Logger instance +```python +action: Optional[Dict[str, Any]] = action +``` -#### req: `BoltRequest` +An alias for payload in an `@app.action` listener -Incoming request from Slack +### `body` -#### resp: `BoltResponse` +```python +body: Dict[str, Any] = body +``` -Response representation +Parsed request body data -#### request: `BoltRequest` +### `client` -Incoming request from Slack +```python +client: WebClient = client +``` -#### response: `BoltResponse` +`slack_sdk.web.WebClient` instance with a valid token -Response representation +### `command` -#### context: `BoltContext` +```python +command: Optional[Dict[str, Any]] = command +``` -Context data associated with the incoming request +An alias for payload in an `@app.command` listener -#### body: `Dict[str, Any]` +### `complete` -Parsed request body data +```python +complete: Complete = complete +``` -#### payload: `Dict[str, Any]` +`complete()` utility function, signals a successful completion of the custom function -The unwrapped core data in the request body +### `context` -#### options: `Optional[Dict[str, Any]]` +```python +context: BoltContext = context +``` -An alias for payload in an `@app.options` listener +Context data associated with the incoming request -#### shortcut: `Optional[Dict[str, Any]]` +### `event` -An alias for payload in an `@app.shortcut` listener +```python +event: Optional[Dict[str, Any]] = event +``` -#### action: `Optional[Dict[str, Any]]` +An alias for payload in an `@app.event` listener -An alias for payload in an `@app.action` listener +### `fail` -#### view: `Optional[Dict[str, Any]]` +```python +fail: Fail = fail +``` -An alias for payload in an `@app.view` listener +`fail()` utility function, signal that the custom function failed to complete -#### command: `Optional[Dict[str, Any]]` +### `get_thread_context` -An alias for payload in an `@app.command` listener +```python +get_thread_context: Optional[GetThreadContext] = get_thread_context +``` -#### event: `Optional[Dict[str, Any]]` +`get_thread_context()` utility function for AI Agents & Assistants -An alias for payload in an `@app.event` listener +### `logger` + +```python +logger: logging.Logger = logger +``` + +Logger instance + +### `message` -#### message: `Optional[Dict[str, Any]]` +```python +message: Optional[Dict[str, Any]] = message +``` An alias for payload in an `@app.message` listener -#### ack: `Ack` +### `next` -`ack()` utility function, which returns acknowledgement to the Slack servers +```python +next: Callable[[], None] = next +``` -#### say: `Say` +`next()` utility function, which tells the middleware chain that it can continue with the next one -`say()` utility function, which calls `chat.postMessage` API with the associated channel ID +### `next_` -#### respond: `Respond` +```python +next_: Callable[[], None] = next +``` -`respond()` utility function, which utilizes the associated `response_url` +An alias of `next()` for avoiding the Python built-in method overrides in middleware functions -#### complete: `Complete` +### `options` -`complete()` utility function, signals a successful completion of the custom function +```python +options: Optional[Dict[str, Any]] = options +``` + +An alias for payload in an `@app.options` listener -#### fail: `Fail` +### `payload` -`fail()` utility function, signal that the custom function failed to complete +```python +payload: Dict[str, Any] = payload +``` -#### set\_status: `Optional[SetStatus]` +The unwrapped core data in the request body -`set_status()` utility function for AI Agents & Assistants +### `req` -#### set\_title: `Optional[SetTitle]` +```python +req: BoltRequest = req +``` -`set_title()` utility function for AI Agents & Assistants +Incoming request from Slack -#### set\_suggested\_prompts: `Optional[SetSuggestedPrompts]` +### `request` -`set_suggested_prompts()` utility function for AI Agents & Assistants +```python +request: BoltRequest = req +``` -#### get\_thread\_context: `Optional[GetThreadContext]` +Incoming request from Slack -`get_thread_context()` utility function for AI Agents & Assistants +### `resp` + +```python +resp: BoltResponse = resp +``` + +Response representation -#### save\_thread\_context: `Optional[SaveThreadContext]` +### `respond` + +```python +respond: Respond = respond +``` + +`respond()` utility function, which utilizes the associated `response_url` + +### `response` + +```python +response: BoltResponse = resp +``` + +Response representation + +### `save_thread_context` + +```python +save_thread_context: Optional[SaveThreadContext] = save_thread_context +``` `save_thread_context()` utility function for AI Agents & Assistants -#### say\_stream: `Optional[SayStream]` +### `say` + +```python +say: Say = say +``` + +`say()` utility function, which calls `chat.postMessage` API with the associated channel ID + +### `say_stream` + +```python +say_stream: Optional[SayStream] = say_stream +``` `say_stream()` utility function for conversations, AI Agents & Assistants -#### next: `Callable[[], None]` +### `set_status` -`next()` utility function, which tells the middleware chain that it can continue with the next one +```python +set_status: Optional[SetStatus] = set_status +``` -#### next\_: `Callable[[], None]` +`set_status()` utility function for AI Agents & Assistants -An alias of `next()` for avoiding the Python built-in method overrides in middleware functions +### `set_suggested_prompts` + +```python +set_suggested_prompts: Optional[SetSuggestedPrompts] = set_suggested_prompts +``` + +`set_suggested_prompts()` utility function for AI Agents & Assistants + +### `set_title` + +```python +set_title: Optional[SetTitle] = set_title +``` -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: logging.Logger, - client: WebClient, - req: BoltRequest, - resp: BoltResponse, - context: BoltContext, - body: Dict[str, Any], - payload: Dict[str, Any], - options: Optional[Dict[str, Any]] = None, - shortcut: Optional[Dict[str, Any]] = None, - action: Optional[Dict[str, Any]] = None, - view: Optional[Dict[str, Any]] = None, - command: Optional[Dict[str, Any]] = None, - event: Optional[Dict[str, Any]] = None, - message: Optional[Dict[str, Any]] = None, - ack: Ack, - say: Say, - respond: Respond, - complete: Complete, - fail: Fail, - set_status: Optional[SetStatus] = None, - set_title: Optional[SetTitle] = None, - set_suggested_prompts: Optional[SetSuggestedPrompts] = None, - get_thread_context: Optional[GetThreadContext] = None, - save_thread_context: Optional[SaveThreadContext] = None, - say_stream: Optional[SayStream] = None, - next: Callable[[], None], - **kwargs) +`set_title()` utility function for AI Agents & Assistants + +### `shortcut` + +```python +shortcut: Optional[Dict[str, Any]] = shortcut ``` + +An alias for payload in an `@app.shortcut` listener + +### `view` + +```python +view: Optional[Dict[str, Any]] = view +``` + +An alias for payload in an `@app.view` listener diff --git a/docs/english/reference/kwargs_injection/async_args.md b/docs/english/reference/kwargs_injection/async_args.md index 2ae53a62a..b3581b5c2 100644 --- a/docs/english/reference/kwargs_injection/async_args.md +++ b/docs/english/reference/kwargs_injection/async_args.md @@ -3,10 +3,10 @@ sidebar_label: async_args title: slack_bolt.kwargs_injection.async_args --- -## AsyncArgs Objects +## `AsyncArgs` ```python -class AsyncArgs() +AsyncArgs(*, logger, client, req, resp, context, body, payload, options=None, shortcut=None, action=None, view=None, command=None, event=None, message=None, ack, say, respond, complete, fail, set_status=None, set_title=None, set_suggested_prompts=None, get_thread_context=None, save_thread_context=None, say_stream=None, next, **kwargs) ``` All the arguments in this class are available in any middleware / listeners. @@ -41,153 +41,234 @@ async def handle_buttons(args): ) ``` +### `ack` -#### logger: `Logger` +```python +ack: AsyncAck = ack +``` -Logger instance +`ack()` utility function, which returns acknowledgement to the Slack servers -#### client: `AsyncWebClient` +### `action` -`slack_sdk.web.async_client.AsyncWebClient` instance with a valid token +```python +action: Optional[Dict[str, Any]] = action +``` -#### req: `AsyncBoltRequest` +An alias for payload in an `@app.action` listener -Incoming request from Slack +### `body` -#### resp: `BoltResponse` +```python +body: Dict[str, Any] = body +``` -Response representation +Parsed request body data -#### request: `AsyncBoltRequest` +### `client` -Incoming request from Slack +```python +client: AsyncWebClient = client +``` -#### response: `BoltResponse` +`slack_sdk.web.async_client.AsyncWebClient` instance with a valid token -Response representation +### `command` -#### context: `AsyncBoltContext` +```python +command: Optional[Dict[str, Any]] = command +``` -Context data associated with the incoming request +An alias for payload in an `@app.command` listener -#### body: `Dict[str, Any]` +### `complete` -Parsed request body data +```python +complete: AsyncComplete = complete +``` -#### payload: `Dict[str, Any]` +`complete()` utility function, signals a successful completion of the custom function -The unwrapped core data in the request body +### `context` -#### options: `Optional[Dict[str, Any]]` +```python +context: AsyncBoltContext = context +``` -An alias for payload in an `@app.options` listener +Context data associated with the incoming request -#### shortcut: `Optional[Dict[str, Any]]` +### `event` -An alias for payload in an `@app.shortcut` listener +```python +event: Optional[Dict[str, Any]] = event +``` -#### action: `Optional[Dict[str, Any]]` +An alias for payload in an `@app.event` listener -An alias for payload in an `@app.action` listener +### `fail` -#### view: `Optional[Dict[str, Any]]` +```python +fail: AsyncFail = fail +``` -An alias for payload in an `@app.view` listener +`fail()` utility function, signal that the custom function failed to complete -#### command: `Optional[Dict[str, Any]]` +### `get_thread_context` -An alias for payload in an `@app.command` listener +```python +get_thread_context: Optional[AsyncGetThreadContext] = get_thread_context +``` -#### event: `Optional[Dict[str, Any]]` +`get_thread_context()` utility function for AI Agents & Assistants -An alias for payload in an `@app.event` listener +### `logger` + +```python +logger: Logger = logger +``` + +Logger instance + +### `message` -#### message: `Optional[Dict[str, Any]]` +```python +message: Optional[Dict[str, Any]] = message +``` An alias for payload in an `@app.message` listener -#### ack: `AsyncAck` +### `next` -`ack()` utility function, which returns acknowledgement to the Slack servers +```python +next: Callable[[], Awaitable[None]] = next +``` -#### say: `AsyncSay` +`next()` utility function, which tells the middleware chain that it can continue with the next one -`say()` utility function, which calls chat.postMessage API with the associated channel ID +### `next_` -#### respond: `AsyncRespond` +```python +next_: Callable[[], Awaitable[None]] = next +``` -`respond()` utility function, which utilizes the associated `response_url` +An alias of `next()` for avoiding the Python built-in method overrides in middleware functions -#### complete: `AsyncComplete` +### `options` -`complete()` utility function, signals a successful completion of the custom function +```python +options: Optional[Dict[str, Any]] = options +``` + +An alias for payload in an `@app.options` listener -#### fail: `AsyncFail` +### `payload` -`fail()` utility function, signal that the custom function failed to complete +```python +payload: Dict[str, Any] = payload +``` -#### set\_status: `Optional[AsyncSetStatus]` +The unwrapped core data in the request body -`set_status()` utility function for AI Agents & Assistants +### `req` -#### set\_title: `Optional[AsyncSetTitle]` +```python +req: AsyncBoltRequest = req +``` -`set_title()` utility function for AI Agents & Assistants +Incoming request from Slack -#### set\_suggested\_prompts: `Optional[AsyncSetSuggestedPrompts]` +### `request` -`set_suggested_prompts()` utility function for AI Agents & Assistants +```python +request: AsyncBoltRequest = req +``` -#### get\_thread\_context: `Optional[AsyncGetThreadContext]` +Incoming request from Slack -`get_thread_context()` utility function for AI Agents & Assistants +### `resp` + +```python +resp: BoltResponse = resp +``` + +Response representation -#### save\_thread\_context: `Optional[AsyncSaveThreadContext]` +### `respond` + +```python +respond: AsyncRespond = respond +``` + +`respond()` utility function, which utilizes the associated `response_url` + +### `response` + +```python +response: BoltResponse = resp +``` + +Response representation + +### `save_thread_context` + +```python +save_thread_context: Optional[AsyncSaveThreadContext] = save_thread_context +``` `save_thread_context()` utility function for AI Agents & Assistants -#### say\_stream: `Optional[AsyncSayStream]` +### `say` + +```python +say: AsyncSay = say +``` + +`say()` utility function, which calls chat.postMessage API with the associated channel ID + +### `say_stream` + +```python +say_stream: Optional[AsyncSayStream] = say_stream +``` `say_stream()` utility function for AI Agents & Assistants -#### next: `Callable[[], Awaitable[None]]` +### `set_status` -`next()` utility function, which tells the middleware chain that it can continue with the next one +```python +set_status: Optional[AsyncSetStatus] = set_status +``` -#### next\_: `Callable[[], Awaitable[None]]` +`set_status()` utility function for AI Agents & Assistants -An alias of `next()` for avoiding the Python built-in method overrides in middleware functions +### `set_suggested_prompts` + +```python +set_suggested_prompts: Optional[AsyncSetSuggestedPrompts] = set_suggested_prompts +``` + +`set_suggested_prompts()` utility function for AI Agents & Assistants + +### `set_title` + +```python +set_title: Optional[AsyncSetTitle] = set_title +``` -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: Logger, - client: AsyncWebClient, - req: AsyncBoltRequest, - resp: BoltResponse, - context: AsyncBoltContext, - body: Dict[str, Any], - payload: Dict[str, Any], - options: Optional[Dict[str, Any]] = None, - shortcut: Optional[Dict[str, Any]] = None, - action: Optional[Dict[str, Any]] = None, - view: Optional[Dict[str, Any]] = None, - command: Optional[Dict[str, Any]] = None, - event: Optional[Dict[str, Any]] = None, - message: Optional[Dict[str, Any]] = None, - ack: AsyncAck, - say: AsyncSay, - respond: AsyncRespond, - complete: AsyncComplete, - fail: AsyncFail, - set_status: Optional[AsyncSetStatus] = None, - set_title: Optional[AsyncSetTitle] = None, - set_suggested_prompts: Optional[AsyncSetSuggestedPrompts] = None, - get_thread_context: Optional[AsyncGetThreadContext] = None, - save_thread_context: Optional[AsyncSaveThreadContext] = None, - say_stream: Optional[AsyncSayStream] = None, - next: Callable[[], Awaitable[None]], - **kwargs) +`set_title()` utility function for AI Agents & Assistants + +### `shortcut` + +```python +shortcut: Optional[Dict[str, Any]] = shortcut ``` + +An alias for payload in an `@app.shortcut` listener + +### `view` + +```python +view: Optional[Dict[str, Any]] = view +``` + +An alias for payload in an `@app.view` listener diff --git a/docs/english/reference/kwargs_injection/async_utils.md b/docs/english/reference/kwargs_injection/async_utils.md index a1a772abf..369d29652 100644 --- a/docs/english/reference/kwargs_injection/async_utils.md +++ b/docs/english/reference/kwargs_injection/async_utils.md @@ -3,17 +3,4 @@ sidebar_label: async_utils title: slack_bolt.kwargs_injection.async_utils --- -#### build\_async\_required\_kwargs -```python -def build_async_required_kwargs( - *, - logger: logging.Logger, - required_arg_names: MutableSequence[str], - request: AsyncBoltRequest, - response: Optional[BoltResponse], - next_func: Optional[Callable[[], None]] = None, - this_func: Optional[Callable] = None, - error: Optional[Exception] = None, - next_keys_required: bool = True) -> Dict[str, Any] -``` diff --git a/docs/english/reference/kwargs_injection/index.md b/docs/english/reference/kwargs_injection/index.md index 84f3c123e..9b8e333da 100644 --- a/docs/english/reference/kwargs_injection/index.md +++ b/docs/english/reference/kwargs_injection/index.md @@ -8,17 +8,10 @@ For middleware/listener arguments, Bolt does flexible data injection in accordan To learn the available arguments, check `slack_bolt.kwargs_injection.args`'s API document. For steps from apps, checking `slack_bolt.workflows.step.utilities` as well should be helpful. -## Submodules - -- [slack_bolt.kwargs_injection.args](/tools/bolt-python/reference/kwargs_injection/args) -- [slack_bolt.kwargs_injection.async_args](/tools/bolt-python/reference/kwargs_injection/async_args) -- [slack_bolt.kwargs_injection.async_utils](/tools/bolt-python/reference/kwargs_injection/async_utils) -- [slack_bolt.kwargs_injection.utils](/tools/bolt-python/reference/kwargs_injection/utils) - -## Args Objects +## `Args` ```python -class Args() +Args(*, logger, client, req, resp, context, body, payload, options=None, shortcut=None, action=None, view=None, command=None, event=None, message=None, ack, say, respond, complete, fail, set_status=None, set_title=None, set_suggested_prompts=None, get_thread_context=None, save_thread_context=None, say_stream=None, next, **kwargs) ``` All the arguments in this class are available in any middleware / listeners. @@ -53,168 +46,241 @@ def handle_buttons(args): ) ``` +### `ack` -#### client: `WebClient` +```python +ack: Ack = ack +``` -`slack_sdk.web.WebClient` instance with a valid token +`ack()` utility function, which returns acknowledgement to the Slack servers -#### logger: `logging.Logger` +### `action` -Logger instance +```python +action: Optional[Dict[str, Any]] = action +``` -#### req: `BoltRequest` +An alias for payload in an `@app.action` listener -Incoming request from Slack +### `body` -#### resp: `BoltResponse` +```python +body: Dict[str, Any] = body +``` -Response representation +Parsed request body data -#### request: `BoltRequest` +### `client` -Incoming request from Slack +```python +client: WebClient = client +``` -#### response: `BoltResponse` +`slack_sdk.web.WebClient` instance with a valid token -Response representation +### `command` -#### context: `BoltContext` +```python +command: Optional[Dict[str, Any]] = command +``` -Context data associated with the incoming request +An alias for payload in an `@app.command` listener -#### body: `Dict[str, Any]` +### `complete` -Parsed request body data +```python +complete: Complete = complete +``` -#### payload: `Dict[str, Any]` +`complete()` utility function, signals a successful completion of the custom function -The unwrapped core data in the request body +### `context` -#### options: `Optional[Dict[str, Any]]` +```python +context: BoltContext = context +``` -An alias for payload in an `@app.options` listener +Context data associated with the incoming request -#### shortcut: `Optional[Dict[str, Any]]` +### `event` -An alias for payload in an `@app.shortcut` listener +```python +event: Optional[Dict[str, Any]] = event +``` -#### action: `Optional[Dict[str, Any]]` +An alias for payload in an `@app.event` listener -An alias for payload in an `@app.action` listener +### `fail` -#### view: `Optional[Dict[str, Any]]` +```python +fail: Fail = fail +``` -An alias for payload in an `@app.view` listener +`fail()` utility function, signal that the custom function failed to complete -#### command: `Optional[Dict[str, Any]]` +### `get_thread_context` -An alias for payload in an `@app.command` listener +```python +get_thread_context: Optional[GetThreadContext] = get_thread_context +``` -#### event: `Optional[Dict[str, Any]]` +`get_thread_context()` utility function for AI Agents & Assistants -An alias for payload in an `@app.event` listener +### `logger` + +```python +logger: logging.Logger = logger +``` + +Logger instance -#### message: `Optional[Dict[str, Any]]` +### `message` + +```python +message: Optional[Dict[str, Any]] = message +``` An alias for payload in an `@app.message` listener -#### ack: `Ack` +### `next` -`ack()` utility function, which returns acknowledgement to the Slack servers +```python +next: Callable[[], None] = next +``` + +`next()` utility function, which tells the middleware chain that it can continue with the next one -#### say: `Say` +### `next_` -`say()` utility function, which calls `chat.postMessage` API with the associated channel ID +```python +next_: Callable[[], None] = next +``` -#### respond: `Respond` +An alias of `next()` for avoiding the Python built-in method overrides in middleware functions -`respond()` utility function, which utilizes the associated `response_url` +### `options` -#### complete: `Complete` +```python +options: Optional[Dict[str, Any]] = options +``` -`complete()` utility function, signals a successful completion of the custom function +An alias for payload in an `@app.options` listener -#### fail: `Fail` +### `payload` -`fail()` utility function, signal that the custom function failed to complete +```python +payload: Dict[str, Any] = payload +``` -#### set\_status: `Optional[SetStatus]` +The unwrapped core data in the request body -`set_status()` utility function for AI Agents & Assistants +### `req` -#### set\_title: `Optional[SetTitle]` +```python +req: BoltRequest = req +``` -`set_title()` utility function for AI Agents & Assistants +Incoming request from Slack -#### set\_suggested\_prompts: `Optional[SetSuggestedPrompts]` +### `request` -`set_suggested_prompts()` utility function for AI Agents & Assistants +```python +request: BoltRequest = req +``` -#### get\_thread\_context: `Optional[GetThreadContext]` +Incoming request from Slack -`get_thread_context()` utility function for AI Agents & Assistants +### `resp` + +```python +resp: BoltResponse = resp +``` + +Response representation + +### `respond` -#### save\_thread\_context: `Optional[SaveThreadContext]` +```python +respond: Respond = respond +``` + +`respond()` utility function, which utilizes the associated `response_url` + +### `response` + +```python +response: BoltResponse = resp +``` + +Response representation + +### `save_thread_context` + +```python +save_thread_context: Optional[SaveThreadContext] = save_thread_context +``` `save_thread_context()` utility function for AI Agents & Assistants -#### say\_stream: `Optional[SayStream]` +### `say` + +```python +say: Say = say +``` + +`say()` utility function, which calls `chat.postMessage` API with the associated channel ID + +### `say_stream` + +```python +say_stream: Optional[SayStream] = say_stream +``` `say_stream()` utility function for conversations, AI Agents & Assistants -#### next: `Callable[[], None]` +### `set_status` -`next()` utility function, which tells the middleware chain that it can continue with the next one +```python +set_status: Optional[SetStatus] = set_status +``` -#### next\_: `Callable[[], None]` +`set_status()` utility function for AI Agents & Assistants -An alias of `next()` for avoiding the Python built-in method overrides in middleware functions +### `set_suggested_prompts` -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: logging.Logger, - client: WebClient, - req: BoltRequest, - resp: BoltResponse, - context: BoltContext, - body: Dict[str, Any], - payload: Dict[str, Any], - options: Optional[Dict[str, Any]] = None, - shortcut: Optional[Dict[str, Any]] = None, - action: Optional[Dict[str, Any]] = None, - view: Optional[Dict[str, Any]] = None, - command: Optional[Dict[str, Any]] = None, - event: Optional[Dict[str, Any]] = None, - message: Optional[Dict[str, Any]] = None, - ack: Ack, - say: Say, - respond: Respond, - complete: Complete, - fail: Fail, - set_status: Optional[SetStatus] = None, - set_title: Optional[SetTitle] = None, - set_suggested_prompts: Optional[SetSuggestedPrompts] = None, - get_thread_context: Optional[GetThreadContext] = None, - save_thread_context: Optional[SaveThreadContext] = None, - say_stream: Optional[SayStream] = None, - next: Callable[[], None], - **kwargs) -``` - -#### build\_required\_kwargs - -```python -def build_required_kwargs( - *, - logger: logging.Logger, - required_arg_names: MutableSequence[str], - request: BoltRequest, - response: Optional[BoltResponse], - next_func: Optional[Callable[[], None]] = None, - this_func: Optional[Callable] = None, - error: Optional[Exception] = None, - next_keys_required: bool = True) -> Dict[str, Any] +```python +set_suggested_prompts: Optional[SetSuggestedPrompts] = set_suggested_prompts ``` + +`set_suggested_prompts()` utility function for AI Agents & Assistants + +### `set_title` + +```python +set_title: Optional[SetTitle] = set_title +``` + +`set_title()` utility function for AI Agents & Assistants + +### `shortcut` + +```python +shortcut: Optional[Dict[str, Any]] = shortcut +``` + +An alias for payload in an `@app.shortcut` listener + +### `view` + +```python +view: Optional[Dict[str, Any]] = view +``` + +An alias for payload in an `@app.view` listener + +## Submodules + +- [slack_bolt.kwargs_injection.args](/tools/bolt-python/reference/kwargs_injection/args) +- [slack_bolt.kwargs_injection.async_args](/tools/bolt-python/reference/kwargs_injection/async_args) +- [slack_bolt.kwargs_injection.async_utils](/tools/bolt-python/reference/kwargs_injection/async_utils) +- [slack_bolt.kwargs_injection.utils](/tools/bolt-python/reference/kwargs_injection/utils) diff --git a/docs/english/reference/kwargs_injection/utils.md b/docs/english/reference/kwargs_injection/utils.md index 359c27274..2e3eb0f09 100644 --- a/docs/english/reference/kwargs_injection/utils.md +++ b/docs/english/reference/kwargs_injection/utils.md @@ -3,17 +3,4 @@ sidebar_label: utils title: slack_bolt.kwargs_injection.utils --- -#### build\_required\_kwargs -```python -def build_required_kwargs( - *, - logger: logging.Logger, - required_arg_names: MutableSequence[str], - request: BoltRequest, - response: Optional[BoltResponse], - next_func: Optional[Callable[[], None]] = None, - this_func: Optional[Callable] = None, - error: Optional[Exception] = None, - next_keys_required: bool = True) -> Dict[str, Any] -``` diff --git a/docs/english/reference/lazy_listener/async_internals.md b/docs/english/reference/lazy_listener/async_internals.md index c3e827f57..c9dbb3ef7 100644 --- a/docs/english/reference/lazy_listener/async_internals.md +++ b/docs/english/reference/lazy_listener/async_internals.md @@ -3,11 +3,4 @@ sidebar_label: async_internals title: slack_bolt.lazy_listener.async_internals --- -#### to\_runnable\_function -```python -async def to_runnable_function( - internal_func: Callable[..., Awaitable[None]], - logger: Logger, - request: AsyncBoltRequest) -``` diff --git a/docs/english/reference/lazy_listener/async_runner.md b/docs/english/reference/lazy_listener/async_runner.md index d0fe904c8..9adfc9620 100644 --- a/docs/english/reference/lazy_listener/async_runner.md +++ b/docs/english/reference/lazy_listener/async_runner.md @@ -3,38 +3,30 @@ sidebar_label: async_runner title: slack_bolt.lazy_listener.async_runner --- -## AsyncLazyListenerRunner Objects +## `AsyncLazyListenerRunner` -```python -class AsyncLazyListenerRunner() -``` - -#### logger: `Logger` - -#### start +### `run` ```python -def start(function: Callable[..., Awaitable[None]], request: AsyncBoltRequest) -> None +run(function, request) ``` -Starts a new lazy listener execution. +Synchronously run the function with a given request data. -**Arguments**: +**Parameters:** -- `function` _Callable[..., Awaitable[None]]_ - The function to run. -- `request` _AsyncBoltRequest_ - The request to pass to the function. The object must be thread-safe. +- **function** (Callable..., [Awaitable[None]]) – The function to run. +- **request** (AsyncBoltRequest) – The request to pass to the function. The object must be thread-safe. -#### run +### `start` ```python -async def run( - function: Callable[..., Awaitable[None]], - request: AsyncBoltRequest) -> None +start(function, request) ``` -Synchronously run the function with a given request data. +Starts a new lazy listener execution. -**Arguments**: +**Parameters:** -- `function` _Callable[..., Awaitable[None]]_ - The function to run. -- `request` _AsyncBoltRequest_ - The request to pass to the function. The object must be thread-safe. +- **function** (Callable..., [Awaitable[None]]) – The function to run. +- **request** (AsyncBoltRequest) – The request to pass to the function. The object must be thread-safe. diff --git a/docs/english/reference/lazy_listener/asyncio_runner.md b/docs/english/reference/lazy_listener/asyncio_runner.md index 71f586c56..68fc713e3 100644 --- a/docs/english/reference/lazy_listener/asyncio_runner.md +++ b/docs/english/reference/lazy_listener/asyncio_runner.md @@ -3,22 +3,4 @@ sidebar_label: asyncio_runner title: slack_bolt.lazy_listener.asyncio_runner --- -## AsyncioLazyListenerRunner Objects -```python -class AsyncioLazyListenerRunner(AsyncLazyListenerRunner) -``` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger) -``` - -#### start - -```python -def start(function: Callable[..., Awaitable[None]], request: AsyncBoltRequest) -> None -``` diff --git a/docs/english/reference/lazy_listener/index.md b/docs/english/reference/lazy_listener/index.md index 16bba61b6..69c0b4856 100644 --- a/docs/english/reference/lazy_listener/index.md +++ b/docs/english/reference/lazy_listener/index.md @@ -28,65 +28,39 @@ app.command("/start-process")( Refer to https://docs.slack.dev/tools/bolt-python/concepts/lazy-listeners for more details. -## Submodules +## `LazyListenerRunner` -- [slack_bolt.lazy_listener.async_internals](/tools/bolt-python/reference/lazy_listener/async_internals) -- [slack_bolt.lazy_listener.async_runner](/tools/bolt-python/reference/lazy_listener/async_runner) -- [slack_bolt.lazy_listener.asyncio_runner](/tools/bolt-python/reference/lazy_listener/asyncio_runner) -- [slack_bolt.lazy_listener.internals](/tools/bolt-python/reference/lazy_listener/internals) -- [slack_bolt.lazy_listener.runner](/tools/bolt-python/reference/lazy_listener/runner) -- [slack_bolt.lazy_listener.thread_runner](/tools/bolt-python/reference/lazy_listener/thread_runner) - -## LazyListenerRunner Objects +### `run` ```python -class LazyListenerRunner() -``` - -#### logger: `Logger` - -#### start - -```python -def start(function: Callable[..., None], request: BoltRequest) -> None -``` - -Starts a new lazy listener execution. - -**Arguments**: - -- `function` _Callable[..., None]_ - The function to run. -- `request` _BoltRequest_ - The request to pass to the function. The object must be thread-safe. - -#### run - -```python -def run(function: Callable[..., None], request: BoltRequest) -> None +run(function, request) ``` Synchronously runs the function with a given request data. -**Arguments**: +**Parameters:** -- `function` _Callable[..., None]_ - The function to run. -- `request` _BoltRequest_ - The request to pass to the function. The object must be thread-safe. +- **function** (Callable[..., None]) – The function to run. +- **request** (BoltRequest) – The request to pass to the function. The object must be thread-safe. -## ThreadLazyListenerRunner Objects +### `start` ```python -class ThreadLazyListenerRunner(LazyListenerRunner) +start(function, request) ``` -#### logger: `Logger` +Starts a new lazy listener execution. -#### \_\_init\_\_ +**Parameters:** -```python -def __init__(logger: Logger, executor: Executor) -``` +- **function** (Callable[..., None]) – The function to run. +- **request** (BoltRequest) – The request to pass to the function. The object must be thread-safe. -#### start +## Submodules -```python -def start(function: Callable[..., None], request: BoltRequest) -> None -``` +- [slack_bolt.lazy_listener.async_internals](/tools/bolt-python/reference/lazy_listener/async_internals) +- [slack_bolt.lazy_listener.async_runner](/tools/bolt-python/reference/lazy_listener/async_runner) +- [slack_bolt.lazy_listener.asyncio_runner](/tools/bolt-python/reference/lazy_listener/asyncio_runner) +- [slack_bolt.lazy_listener.internals](/tools/bolt-python/reference/lazy_listener/internals) +- [slack_bolt.lazy_listener.runner](/tools/bolt-python/reference/lazy_listener/runner) +- [slack_bolt.lazy_listener.thread_runner](/tools/bolt-python/reference/lazy_listener/thread_runner) diff --git a/docs/english/reference/lazy_listener/internals.md b/docs/english/reference/lazy_listener/internals.md index 0c6399765..6fd5a3f05 100644 --- a/docs/english/reference/lazy_listener/internals.md +++ b/docs/english/reference/lazy_listener/internals.md @@ -3,11 +3,4 @@ sidebar_label: internals title: slack_bolt.lazy_listener.internals --- -#### build\_runnable\_function -```python -def build_runnable_function( - func: Callable[..., None], - logger: Logger, - request: BoltRequest) -> Callable[[], None] -``` diff --git a/docs/english/reference/lazy_listener/runner.md b/docs/english/reference/lazy_listener/runner.md index 132251b21..d875dcda2 100644 --- a/docs/english/reference/lazy_listener/runner.md +++ b/docs/english/reference/lazy_listener/runner.md @@ -3,36 +3,30 @@ sidebar_label: runner title: slack_bolt.lazy_listener.runner --- -## LazyListenerRunner Objects +## `LazyListenerRunner` -```python -class LazyListenerRunner() -``` - -#### logger: `Logger` - -#### start +### `run` ```python -def start(function: Callable[..., None], request: BoltRequest) -> None +run(function, request) ``` -Starts a new lazy listener execution. +Synchronously runs the function with a given request data. -**Arguments**: +**Parameters:** -- `function` _Callable[..., None]_ - The function to run. -- `request` _BoltRequest_ - The request to pass to the function. The object must be thread-safe. +- **function** (Callable[..., None]) – The function to run. +- **request** (BoltRequest) – The request to pass to the function. The object must be thread-safe. -#### run +### `start` ```python -def run(function: Callable[..., None], request: BoltRequest) -> None +start(function, request) ``` -Synchronously runs the function with a given request data. +Starts a new lazy listener execution. -**Arguments**: +**Parameters:** -- `function` _Callable[..., None]_ - The function to run. -- `request` _BoltRequest_ - The request to pass to the function. The object must be thread-safe. +- **function** (Callable[..., None]) – The function to run. +- **request** (BoltRequest) – The request to pass to the function. The object must be thread-safe. diff --git a/docs/english/reference/lazy_listener/thread_runner.md b/docs/english/reference/lazy_listener/thread_runner.md index 0b8e2e8af..270c46a0c 100644 --- a/docs/english/reference/lazy_listener/thread_runner.md +++ b/docs/english/reference/lazy_listener/thread_runner.md @@ -3,22 +3,4 @@ sidebar_label: thread_runner title: slack_bolt.lazy_listener.thread_runner --- -## ThreadLazyListenerRunner Objects -```python -class ThreadLazyListenerRunner(LazyListenerRunner) -``` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger, executor: Executor) -``` - -#### start - -```python -def start(function: Callable[..., None], request: BoltRequest) -> None -``` diff --git a/docs/english/reference/listener/async_builtins.md b/docs/english/reference/listener/async_builtins.md index eae0be0f0..4b650ed13 100644 --- a/docs/english/reference/listener/async_builtins.md +++ b/docs/english/reference/listener/async_builtins.md @@ -3,30 +3,10 @@ sidebar_label: async_builtins title: slack_bolt.listener.async_builtins --- -## AsyncTokenRevocationListeners Objects +## `AsyncTokenRevocationListeners` ```python -class AsyncTokenRevocationListeners() +AsyncTokenRevocationListeners(installation_store) ``` Listener functions to handle token revocation / uninstallation events. - -#### installation\_store: `AsyncInstallationStore` - -#### \_\_init\_\_ - -```python -def __init__(installation_store: AsyncInstallationStore) -``` - -#### handle\_tokens\_revoked\_events - -```python -async def handle_tokens_revoked_events(event: dict, context: AsyncBoltContext) -> None -``` - -#### handle\_app\_uninstalled\_events - -```python -async def handle_app_uninstalled_events(context: AsyncBoltContext) -> None -``` diff --git a/docs/english/reference/listener/async_listener.md b/docs/english/reference/listener/async_listener.md index 3971da968..b0d5f944d 100644 --- a/docs/english/reference/listener/async_listener.md +++ b/docs/english/reference/listener/async_listener.md @@ -3,116 +3,38 @@ sidebar_label: async_listener title: slack_bolt.listener.async_listener --- -## AsyncListener Objects +## `AsyncListener` -```python -class AsyncListener() -``` - -#### matchers: `Sequence[AsyncListenerMatcher]` - -#### middleware: `Sequence[AsyncMiddleware]` - -#### ack\_function: `Callable[..., Awaitable[BoltResponse]]` - -#### lazy\_functions: `Sequence[Callable[..., Awaitable[None]]]` - -#### auto\_acknowledgement: `bool` - -#### ack\_timeout: `int` - -#### async\_matches +### `run_ack_function` ```python -async def async_matches(*, req: AsyncBoltRequest, resp: BoltResponse) -> bool -``` - -#### run\_async\_middleware - -```python -async def run_async_middleware( - *, - req: AsyncBoltRequest, - resp: BoltResponse) -> Tuple[Optional[BoltResponse], bool] -``` - -Runs an async middleware. - -**Arguments**: - -- `req` _AsyncBoltRequest_ - The incoming request -- `resp` _BoltResponse_ - The current response - -**Returns**: - -- `Tuple[Optional[BoltResponse], bool]` - A tuple of the processed response and a flag indicating termination - -#### run\_ack\_function - -```python -async def run_ack_function( - *, - request: AsyncBoltRequest, - response: BoltResponse) -> Optional[BoltResponse] +run_ack_function(*, request, response) ``` Runs all the registered middleware and then run the listener function. -**Arguments**: +**Parameters:** -- `request` _AsyncBoltRequest_ - The incoming request -- `response` _BoltResponse_ - The current response +- **request** (AsyncBoltRequest) – The incoming request +- **response** (BoltResponse) – The current response -**Returns**: +**Returns:** -- `Optional[BoltResponse]` - The processed response +- Optional[BoltResponse] – The processed response -## AsyncCustomListener Objects +### `run_async_middleware` ```python -class AsyncCustomListener(AsyncListener) +run_async_middleware(*, req, resp) ``` -#### app\_name: `str` - -#### ack\_function: `Callable[..., Awaitable[Optional[BoltResponse]]]` - -#### lazy\_functions: `Sequence[Callable[..., Awaitable[None]]]` - -#### matchers: `Sequence[AsyncListenerMatcher]` - -#### middleware: `Sequence[AsyncMiddleware]` - -#### auto\_acknowledgement: `bool` - -#### ack\_timeout: `int` - -#### arg\_names: `MutableSequence[str]` +Runs an async middleware. -#### logger: `Logger` +**Parameters:** -#### \_\_init\_\_ +- **req** (AsyncBoltRequest) – The incoming request +- **resp** (BoltResponse) – The current response -```python -def __init__( - *, - app_name: str, - ack_function: Callable[..., Awaitable[Optional[BoltResponse]]], - lazy_functions: Sequence[Callable[..., Awaitable[None]]], - matchers: Sequence[AsyncListenerMatcher], - middleware: Sequence[AsyncMiddleware], - auto_acknowledgement: bool = False, - ack_timeout: int = 3, - base_logger: Optional[Logger] = None) -``` - -#### run\_ack\_function - -```python -async def run_ack_function( - *, - request: AsyncBoltRequest, - response: BoltResponse) -> Optional[BoltResponse] -``` +**Returns:** -#### builtin\_async\_listener\_classes +- Tuple[Optional[BoltResponse], bool] – A tuple of the processed response and a flag indicating termination diff --git a/docs/english/reference/listener/async_listener_completion_handler.md b/docs/english/reference/listener/async_listener_completion_handler.md index 05c082390..dca94bf2d 100644 --- a/docs/english/reference/listener/async_listener_completion_handler.md +++ b/docs/english/reference/listener/async_listener_completion_handler.md @@ -3,57 +3,17 @@ sidebar_label: async_listener_completion_handler title: slack_bolt.listener.async_listener_completion_handler --- -## AsyncListenerCompletionHandler Objects +## `AsyncListenerCompletionHandler` -```python -class AsyncListenerCompletionHandler() -``` - -#### handle +### `handle` ```python -async def handle(request: AsyncBoltRequest, response: Optional[BoltResponse]) -> None +handle(request, response) ``` Do something extra after the listener execution. -**Arguments**: - -- `request` _AsyncBoltRequest_ - The request. -- `response` _Optional[BoltResponse]_ - The response. - -## AsyncCustomListenerCompletionHandler Objects - -```python -class AsyncCustomListenerCompletionHandler(AsyncListenerCompletionHandler) -``` - -#### \_\_init\_\_ +**Parameters:** -```python -def __init__(logger: Logger, func: Callable[..., Awaitable[None]]) -``` - -#### handle - -```python -async def handle(request: AsyncBoltRequest, response: Optional[BoltResponse]) -> None -``` - -## AsyncDefaultListenerCompletionHandler Objects - -```python -class AsyncDefaultListenerCompletionHandler(AsyncListenerCompletionHandler) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger) -``` - -#### handle - -```python -async def handle(request: AsyncBoltRequest, response: Optional[BoltResponse]) -``` +- **request** (AsyncBoltRequest) – The request. +- **response** (Optional[BoltResponse]) – The response. diff --git a/docs/english/reference/listener/async_listener_error_handler.md b/docs/english/reference/listener/async_listener_error_handler.md index f42137530..fdf83e21f 100644 --- a/docs/english/reference/listener/async_listener_error_handler.md +++ b/docs/english/reference/listener/async_listener_error_handler.md @@ -3,67 +3,18 @@ sidebar_label: async_listener_error_handler title: slack_bolt.listener.async_listener_error_handler --- -## AsyncListenerErrorHandler Objects +## `AsyncListenerErrorHandler` -```python -class AsyncListenerErrorHandler() -``` - -#### handle +### `handle` ```python -async def handle( - error: Exception, - request: AsyncBoltRequest, - response: Optional[BoltResponse]) -> None +handle(error, request, response) ``` Handles an unhandled exception. -**Arguments**: - -- `error` _Exception_ - The raised exception. -- `request` _AsyncBoltRequest_ - The request. -- `response` _Optional[BoltResponse]_ - The response. - -## AsyncCustomListenerErrorHandler Objects - -```python -class AsyncCustomListenerErrorHandler(AsyncListenerErrorHandler) -``` - -#### \_\_init\_\_ +**Parameters:** -```python -def __init__(logger: Logger, func: Callable[..., Awaitable[Optional[BoltResponse]]]) -``` - -#### handle - -```python -async def handle( - error: Exception, - request: AsyncBoltRequest, - response: Optional[BoltResponse]) -> None -``` - -## AsyncDefaultListenerErrorHandler Objects - -```python -class AsyncDefaultListenerErrorHandler(AsyncListenerErrorHandler) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger) -``` - -#### handle - -```python -async def handle( - error: Exception, - request: AsyncBoltRequest, - response: Optional[BoltResponse]) -``` +- **error** (Exception) – The raised exception. +- **request** (AsyncBoltRequest) – The request. +- **response** (Optional[BoltResponse]) – The response. diff --git a/docs/english/reference/listener/async_listener_start_handler.md b/docs/english/reference/listener/async_listener_start_handler.md index ffb24f647..10db84904 100644 --- a/docs/english/reference/listener/async_listener_start_handler.md +++ b/docs/english/reference/listener/async_listener_start_handler.md @@ -3,57 +3,17 @@ sidebar_label: async_listener_start_handler title: slack_bolt.listener.async_listener_start_handler --- -## AsyncListenerStartHandler Objects +## `AsyncListenerStartHandler` -```python -class AsyncListenerStartHandler() -``` - -#### handle +### `handle` ```python -async def handle(request: AsyncBoltRequest, response: Optional[BoltResponse]) -> None +handle(request, response) ``` Do something extra before the listener execution. -**Arguments**: - -- `request` _AsyncBoltRequest_ - The request. -- `response` _Optional[BoltResponse]_ - The response. - -## AsyncCustomListenerStartHandler Objects - -```python -class AsyncCustomListenerStartHandler(AsyncListenerStartHandler) -``` - -#### \_\_init\_\_ +**Parameters:** -```python -def __init__(logger: Logger, func: Callable[..., Awaitable[None]]) -``` - -#### handle - -```python -async def handle(request: AsyncBoltRequest, response: Optional[BoltResponse]) -> None -``` - -## AsyncDefaultListenerStartHandler Objects - -```python -class AsyncDefaultListenerStartHandler(AsyncListenerStartHandler) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger) -``` - -#### handle - -```python -async def handle(request: AsyncBoltRequest, response: Optional[BoltResponse]) -``` +- **request** (AsyncBoltRequest) – The request. +- **response** (Optional[BoltResponse]) – The response. diff --git a/docs/english/reference/listener/asyncio_runner.md b/docs/english/reference/listener/asyncio_runner.md index 4abcd0711..a9eef3846 100644 --- a/docs/english/reference/listener/asyncio_runner.md +++ b/docs/english/reference/listener/asyncio_runner.md @@ -3,43 +3,4 @@ sidebar_label: asyncio_runner title: slack_bolt.listener.asyncio_runner --- -## AsyncioListenerRunner Objects -```python -class AsyncioListenerRunner() -``` - -#### logger: `Logger` - -#### process\_before\_response: `bool` - -#### listener\_error\_handler: `AsyncListenerErrorHandler` - -#### listener\_start\_handler: `AsyncListenerStartHandler` - -#### listener\_completion\_handler: `AsyncListenerCompletionHandler` - -#### lazy\_listener\_runner: `AsyncLazyListenerRunner` - -#### \_\_init\_\_ - -```python -def __init__( - logger: Logger, - process_before_response: bool, - listener_error_handler: AsyncListenerErrorHandler, - listener_start_handler: AsyncListenerStartHandler, - listener_completion_handler: AsyncListenerCompletionHandler, - lazy_listener_runner: AsyncLazyListenerRunner) -``` - -#### run - -```python -async def run( - request: AsyncBoltRequest, - response: BoltResponse, - listener_name: str, - listener: AsyncListener, - starting_time: Optional[float] = None) -> Optional[BoltResponse] -``` diff --git a/docs/english/reference/listener/builtins.md b/docs/english/reference/listener/builtins.md index c7cc38fbf..24ecda593 100644 --- a/docs/english/reference/listener/builtins.md +++ b/docs/english/reference/listener/builtins.md @@ -3,30 +3,10 @@ sidebar_label: builtins title: slack_bolt.listener.builtins --- -## TokenRevocationListeners Objects +## `TokenRevocationListeners` ```python -class TokenRevocationListeners() +TokenRevocationListeners(installation_store) ``` Listener functions to handle token revocation / uninstallation events. - -#### installation\_store: `InstallationStore` - -#### \_\_init\_\_ - -```python -def __init__(installation_store: InstallationStore) -``` - -#### handle\_tokens\_revoked\_events - -```python -def handle_tokens_revoked_events(event: dict, context: BoltContext) -> None -``` - -#### handle\_app\_uninstalled\_events - -```python -def handle_app_uninstalled_events(context: BoltContext) -> None -``` diff --git a/docs/english/reference/listener/custom_listener.md b/docs/english/reference/listener/custom_listener.md index 30504b959..fcce46baf 100644 --- a/docs/english/reference/listener/custom_listener.md +++ b/docs/english/reference/listener/custom_listener.md @@ -3,50 +3,4 @@ sidebar_label: custom_listener title: slack_bolt.listener.custom_listener --- -## CustomListener Objects -```python -class CustomListener(Listener) -``` - -#### app\_name: `str` - -#### ack\_function: `Callable[..., Optional[BoltResponse]]` - -#### lazy\_functions: `Sequence[Callable[..., None]]` - -#### matchers: `Sequence[ListenerMatcher]` - -#### middleware: `Sequence[Middleware]` - -#### auto\_acknowledgement: `bool` - -#### ack\_timeout: `int` - -#### arg\_names: `MutableSequence[str]` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__( - *, - app_name: str, - ack_function: Callable[..., Optional[BoltResponse]], - lazy_functions: Sequence[Callable[..., None]], - matchers: Sequence[ListenerMatcher], - middleware: Sequence[Middleware], - auto_acknowledgement: bool = False, - ack_timeout: int = 3, - base_logger: Optional[Logger] = None) -``` - -#### run\_ack\_function - -```python -def run_ack_function( - *, - request: BoltRequest, - response: BoltResponse) -> Optional[BoltResponse] -``` diff --git a/docs/english/reference/listener/index.md b/docs/english/reference/listener/index.md index 25d77026f..f86522f4b 100644 --- a/docs/english/reference/listener/index.md +++ b/docs/english/reference/listener/index.md @@ -8,132 +8,54 @@ Listeners process incoming requests from Slack. A listener runs when the request's type or data structure matches its predefined conditions. Typically, a listener acknowledges the request, processes its data, and may send a response back to Slack. -## Submodules +## `Listener` -- [slack_bolt.listener.async_builtins](/tools/bolt-python/reference/listener/async_builtins) -- [slack_bolt.listener.async_listener](/tools/bolt-python/reference/listener/async_listener) -- [slack_bolt.listener.async_listener_completion_handler](/tools/bolt-python/reference/listener/async_listener_completion_handler) -- [slack_bolt.listener.async_listener_error_handler](/tools/bolt-python/reference/listener/async_listener_error_handler) -- [slack_bolt.listener.async_listener_start_handler](/tools/bolt-python/reference/listener/async_listener_start_handler) -- [slack_bolt.listener.asyncio_runner](/tools/bolt-python/reference/listener/asyncio_runner) -- [slack_bolt.listener.builtins](/tools/bolt-python/reference/listener/builtins) -- [slack_bolt.listener.custom_listener](/tools/bolt-python/reference/listener/custom_listener) -- [slack_bolt.listener.listener](/tools/bolt-python/reference/listener/listener) -- [slack_bolt.listener.listener_completion_handler](/tools/bolt-python/reference/listener/listener_completion_handler) -- [slack_bolt.listener.listener_error_handler](/tools/bolt-python/reference/listener/listener_error_handler) -- [slack_bolt.listener.listener_start_handler](/tools/bolt-python/reference/listener/listener_start_handler) -- [slack_bolt.listener.thread_runner](/tools/bolt-python/reference/listener/thread_runner) - -## CustomListener Objects +### `run_ack_function` ```python -class CustomListener(Listener) +run_ack_function(*, request, response) ``` -#### app\_name: `str` - -#### ack\_function: `Callable[..., Optional[BoltResponse]]` - -#### lazy\_functions: `Sequence[Callable[..., None]]` - -#### matchers: `Sequence[ListenerMatcher]` - -#### middleware: `Sequence[Middleware]` - -#### auto\_acknowledgement: `bool` - -#### ack\_timeout: `int` - -#### arg\_names: `MutableSequence[str]` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__( - *, - app_name: str, - ack_function: Callable[..., Optional[BoltResponse]], - lazy_functions: Sequence[Callable[..., None]], - matchers: Sequence[ListenerMatcher], - middleware: Sequence[Middleware], - auto_acknowledgement: bool = False, - ack_timeout: int = 3, - base_logger: Optional[Logger] = None) -``` - -#### run\_ack\_function - -```python -def run_ack_function( - *, - request: BoltRequest, - response: BoltResponse) -> Optional[BoltResponse] -``` - -## Listener Objects - -```python -class Listener() -``` - -#### matchers: `Sequence[ListenerMatcher]` - -#### middleware: `Sequence[Middleware]` - -#### ack\_function: `Callable[..., BoltResponse]` - -#### lazy\_functions: `Sequence[Callable[..., None]]` +Runs all the registered middleware and then run the listener function. -#### auto\_acknowledgement: `bool` +**Parameters:** -#### ack\_timeout: `int` +- **request** (BoltRequest) – The incoming request +- **response** (BoltResponse) – The current response -#### matches +**Returns:** -```python -def matches(*, req: BoltRequest, resp: BoltResponse) -> bool -``` +- Optional[BoltResponse] – The processed response -#### run\_middleware +### `run_middleware` ```python -def run_middleware( - *, - req: BoltRequest, - resp: BoltResponse) -> Tuple[Optional[BoltResponse], bool] +run_middleware(*, req, resp) ``` Runs a middleware. -**Arguments**: - -- `req` _BoltRequest_ - The incoming request -- `resp` _BoltResponse_ - The current response - -**Returns**: - -- `Tuple[Optional[BoltResponse], bool]` - A tuple of the processed response and a flag indicating termination - -#### run\_ack\_function - -```python -def run_ack_function( - *, - request: BoltRequest, - response: BoltResponse) -> Optional[BoltResponse] -``` - -Runs all the registered middleware and then run the listener function. +**Parameters:** -**Arguments**: +- **req** (BoltRequest) – The incoming request +- **resp** (BoltResponse) – The current response -- `request` _BoltRequest_ - The incoming request -- `response` _BoltResponse_ - The current response +**Returns:** -**Returns**: +- Tuple[Optional[BoltResponse], bool] – A tuple of the processed response and a flag indicating termination -- `Optional[BoltResponse]` - The processed response +## Submodules -#### builtin\_listener\_classes +- [slack_bolt.listener.async_builtins](/tools/bolt-python/reference/listener/async_builtins) +- [slack_bolt.listener.async_listener](/tools/bolt-python/reference/listener/async_listener) +- [slack_bolt.listener.async_listener_completion_handler](/tools/bolt-python/reference/listener/async_listener_completion_handler) +- [slack_bolt.listener.async_listener_error_handler](/tools/bolt-python/reference/listener/async_listener_error_handler) +- [slack_bolt.listener.async_listener_start_handler](/tools/bolt-python/reference/listener/async_listener_start_handler) +- [slack_bolt.listener.asyncio_runner](/tools/bolt-python/reference/listener/asyncio_runner) +- [slack_bolt.listener.builtins](/tools/bolt-python/reference/listener/builtins) +- [slack_bolt.listener.custom_listener](/tools/bolt-python/reference/listener/custom_listener) +- [slack_bolt.listener.listener](/tools/bolt-python/reference/listener/listener) +- [slack_bolt.listener.listener_completion_handler](/tools/bolt-python/reference/listener/listener_completion_handler) +- [slack_bolt.listener.listener_error_handler](/tools/bolt-python/reference/listener/listener_error_handler) +- [slack_bolt.listener.listener_start_handler](/tools/bolt-python/reference/listener/listener_start_handler) +- [slack_bolt.listener.thread_runner](/tools/bolt-python/reference/listener/thread_runner) diff --git a/docs/english/reference/listener/listener.md b/docs/english/reference/listener/listener.md index f868d7bf6..1a5a0098f 100644 --- a/docs/english/reference/listener/listener.md +++ b/docs/english/reference/listener/listener.md @@ -4,66 +4,38 @@ title: slack_bolt.listener.listener slug: listener --- -## Listener Objects +## `Listener` -```python -class Listener() -``` - -#### matchers: `Sequence[ListenerMatcher]` - -#### middleware: `Sequence[Middleware]` - -#### ack\_function: `Callable[..., BoltResponse]` - -#### lazy\_functions: `Sequence[Callable[..., None]]` - -#### auto\_acknowledgement: `bool` - -#### ack\_timeout: `int` - -#### matches +### `run_ack_function` ```python -def matches(*, req: BoltRequest, resp: BoltResponse) -> bool +run_ack_function(*, request, response) ``` -#### run\_middleware - -```python -def run_middleware( - *, - req: BoltRequest, - resp: BoltResponse) -> Tuple[Optional[BoltResponse], bool] -``` - -Runs a middleware. +Runs all the registered middleware and then run the listener function. -**Arguments**: +**Parameters:** -- `req` _BoltRequest_ - The incoming request -- `resp` _BoltResponse_ - The current response +- **request** (BoltRequest) – The incoming request +- **response** (BoltResponse) – The current response -**Returns**: +**Returns:** -- `Tuple[Optional[BoltResponse], bool]` - A tuple of the processed response and a flag indicating termination +- Optional[BoltResponse] – The processed response -#### run\_ack\_function +### `run_middleware` ```python -def run_ack_function( - *, - request: BoltRequest, - response: BoltResponse) -> Optional[BoltResponse] +run_middleware(*, req, resp) ``` -Runs all the registered middleware and then run the listener function. +Runs a middleware. -**Arguments**: +**Parameters:** -- `request` _BoltRequest_ - The incoming request -- `response` _BoltResponse_ - The current response +- **req** (BoltRequest) – The incoming request +- **resp** (BoltResponse) – The current response -**Returns**: +**Returns:** -- `Optional[BoltResponse]` - The processed response +- Tuple[Optional[BoltResponse], bool] – A tuple of the processed response and a flag indicating termination diff --git a/docs/english/reference/listener/listener_completion_handler.md b/docs/english/reference/listener/listener_completion_handler.md index 3730de7e7..adb3af8ce 100644 --- a/docs/english/reference/listener/listener_completion_handler.md +++ b/docs/english/reference/listener/listener_completion_handler.md @@ -3,57 +3,17 @@ sidebar_label: listener_completion_handler title: slack_bolt.listener.listener_completion_handler --- -## ListenerCompletionHandler Objects +## `ListenerCompletionHandler` -```python -class ListenerCompletionHandler() -``` - -#### handle +### `handle` ```python -def handle(request: BoltRequest, response: Optional[BoltResponse]) -> None +handle(request, response) ``` Do something extra after the listener execution. -**Arguments**: - -- `request` _BoltRequest_ - The request. -- `response` _Optional[BoltResponse]_ - The response. - -## CustomListenerCompletionHandler Objects - -```python -class CustomListenerCompletionHandler(ListenerCompletionHandler) -``` - -#### \_\_init\_\_ +**Parameters:** -```python -def __init__(logger: Logger, func: Callable[..., None]) -``` - -#### handle - -```python -def handle(request: BoltRequest, response: Optional[BoltResponse]) -``` - -## DefaultListenerCompletionHandler Objects - -```python -class DefaultListenerCompletionHandler(ListenerCompletionHandler) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger) -``` - -#### handle - -```python -def handle(request: BoltRequest, response: Optional[BoltResponse]) -``` +- **request** (BoltRequest) – The request. +- **response** (Optional[BoltResponse]) – The response. diff --git a/docs/english/reference/listener/listener_error_handler.md b/docs/english/reference/listener/listener_error_handler.md index 1f846b1f0..a2e9228aa 100644 --- a/docs/english/reference/listener/listener_error_handler.md +++ b/docs/english/reference/listener/listener_error_handler.md @@ -3,61 +3,18 @@ sidebar_label: listener_error_handler title: slack_bolt.listener.listener_error_handler --- -## ListenerErrorHandler Objects +## `ListenerErrorHandler` -```python -class ListenerErrorHandler() -``` - -#### handle +### `handle` ```python -def handle( - error: Exception, - request: BoltRequest, - response: Optional[BoltResponse]) -> None +handle(error, request, response) ``` Handles an unhandled exception. -**Arguments**: - -- `error` _Exception_ - The raised exception. -- `request` _BoltRequest_ - The request. -- `response` _Optional[BoltResponse]_ - The response. - -## CustomListenerErrorHandler Objects - -```python -class CustomListenerErrorHandler(ListenerErrorHandler) -``` - -#### \_\_init\_\_ +**Parameters:** -```python -def __init__(logger: Logger, func: Callable[..., Optional[BoltResponse]]) -``` - -#### handle - -```python -def handle(error: Exception, request: BoltRequest, response: Optional[BoltResponse]) -``` - -## DefaultListenerErrorHandler Objects - -```python -class DefaultListenerErrorHandler(ListenerErrorHandler) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger) -``` - -#### handle - -```python -def handle(error: Exception, request: BoltRequest, response: Optional[BoltResponse]) -``` +- **error** (Exception) – The raised exception. +- **request** (BoltRequest) – The request. +- **response** (Optional[BoltResponse]) – The response. diff --git a/docs/english/reference/listener/listener_start_handler.md b/docs/english/reference/listener/listener_start_handler.md index fc4844fca..9ee7af9b3 100644 --- a/docs/english/reference/listener/listener_start_handler.md +++ b/docs/english/reference/listener/listener_start_handler.md @@ -3,16 +3,12 @@ sidebar_label: listener_start_handler title: slack_bolt.listener.listener_start_handler --- -## ListenerStartHandler Objects +## `ListenerStartHandler` -```python -class ListenerStartHandler() -``` - -#### handle +### `handle` ```python -def handle(request: BoltRequest, response: Optional[BoltResponse]) -> None +handle(request, response) ``` Do something extra before the listener execution. @@ -21,43 +17,7 @@ This handler is useful if a developer needs to maintain/clean up thread-local resources such as Django ORM database connections before a listener execution starts. -**Arguments**: - -- `request` _BoltRequest_ - The request. -- `response` _Optional[BoltResponse]_ - The response. - -## CustomListenerStartHandler Objects - -```python -class CustomListenerStartHandler(ListenerStartHandler) -``` - -#### \_\_init\_\_ +**Parameters:** -```python -def __init__(logger: Logger, func: Callable[..., None]) -``` - -#### handle - -```python -def handle(request: BoltRequest, response: Optional[BoltResponse]) -``` - -## DefaultListenerStartHandler Objects - -```python -class DefaultListenerStartHandler(ListenerStartHandler) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger) -``` - -#### handle - -```python -def handle(request: BoltRequest, response: Optional[BoltResponse]) -``` +- **request** (BoltRequest) – The request. +- **response** (Optional[BoltResponse]) – The response. diff --git a/docs/english/reference/listener/thread_runner.md b/docs/english/reference/listener/thread_runner.md index 105f81260..6d708591f 100644 --- a/docs/english/reference/listener/thread_runner.md +++ b/docs/english/reference/listener/thread_runner.md @@ -3,46 +3,4 @@ sidebar_label: thread_runner title: slack_bolt.listener.thread_runner --- -## ThreadListenerRunner Objects -```python -class ThreadListenerRunner() -``` - -#### logger: `Logger` - -#### process\_before\_response: `bool` - -#### listener\_error\_handler: `ListenerErrorHandler` - -#### listener\_start\_handler: `ListenerStartHandler` - -#### listener\_completion\_handler: `ListenerCompletionHandler` - -#### listener\_executor: `Executor` - -#### lazy\_listener\_runner: `LazyListenerRunner` - -#### \_\_init\_\_ - -```python -def __init__( - logger: Logger, - process_before_response: bool, - listener_error_handler: ListenerErrorHandler, - listener_start_handler: ListenerStartHandler, - listener_completion_handler: ListenerCompletionHandler, - listener_executor: Executor, - lazy_listener_runner: LazyListenerRunner) -``` - -#### run - -```python -def run( - request: BoltRequest, - response: BoltResponse, - listener_name: str, - listener: Listener, - starting_time: Optional[float] = None) -> Optional[BoltResponse] -``` diff --git a/docs/english/reference/listener_matcher/async_builtins.md b/docs/english/reference/listener_matcher/async_builtins.md index 0f1c9d444..9cd4d4180 100644 --- a/docs/english/reference/listener_matcher/async_builtins.md +++ b/docs/english/reference/listener_matcher/async_builtins.md @@ -3,14 +3,4 @@ sidebar_label: async_builtins title: slack_bolt.listener_matcher.async_builtins --- -## AsyncBuiltinListenerMatcher Objects -```python -class AsyncBuiltinListenerMatcher(BuiltinListenerMatcher, AsyncListenerMatcher) -``` - -#### async\_matches - -```python -async def async_matches(req: AsyncBoltRequest, resp: BoltResponse) -> bool -``` diff --git a/docs/english/reference/listener_matcher/async_listener_matcher.md b/docs/english/reference/listener_matcher/async_listener_matcher.md index 9dab3172a..48135cefc 100644 --- a/docs/english/reference/listener_matcher/async_listener_matcher.md +++ b/docs/english/reference/listener_matcher/async_listener_matcher.md @@ -3,57 +3,21 @@ sidebar_label: async_listener_matcher title: slack_bolt.listener_matcher.async_listener_matcher --- -## AsyncListenerMatcher Objects +## `AsyncListenerMatcher` -```python -class AsyncListenerMatcher() -``` - -#### async\_matches +### `async_matches` ```python -async def async_matches(req: AsyncBoltRequest, resp: BoltResponse) -> bool +async_matches(req, resp) ``` Matches against the request and returns True if matched. -**Arguments**: - -- `req` _AsyncBoltRequest_ - The request -- `resp` _BoltResponse_ - The response - -**Returns**: - -- `bool` - True if matched - -## AsyncCustomListenerMatcher Objects - -```python -class AsyncCustomListenerMatcher(AsyncListenerMatcher) -``` - -#### app\_name: `str` - -#### func: `Callable[..., Awaitable[bool]]` - -#### arg\_names: `Sequence[str]` - -#### logger: `Logger` - -#### \_\_init\_\_ +**Parameters:** -```python -def __init__( - *, - app_name: str, - func: Callable[..., Awaitable[bool]], - base_logger: Optional[Logger] = None) -``` - -#### async\_matches +- **req** (AsyncBoltRequest) – The request +- **resp** (BoltResponse) – The response -```python -async def async_matches(req: AsyncBoltRequest, resp: BoltResponse) -> bool -``` +**Returns:** -#### builtin\_async\_listener\_matcher\_classes +- bool – True if matched diff --git a/docs/english/reference/listener_matcher/builtins.md b/docs/english/reference/listener_matcher/builtins.md index 571b4476f..c4006c432 100644 --- a/docs/english/reference/listener_matcher/builtins.md +++ b/docs/english/reference/listener_matcher/builtins.md @@ -3,222 +3,4 @@ sidebar_label: builtins title: slack_bolt.listener_matcher.builtins --- -## BuiltinListenerMatcher Objects -```python -class BuiltinListenerMatcher(ListenerMatcher) -``` - -#### \_\_init\_\_ - -```python -def __init__( - *, - func: Callable[..., Union[bool, Awaitable[bool]]], - base_logger: Optional[Logger] = None) -``` - -#### matches - -```python -def matches(req: BoltRequest, resp: BoltResponse) -> bool -``` - -#### build\_listener\_matcher - -```python -def build_listener_matcher( - func: Callable[..., bool], - asyncio: bool, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### event - -```python -def event( - constraints: Union[str, Pattern, Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]]], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### message\_event - -```python -def message_event( - constraints: Dict[str, Optional[Union[str, Sequence[Optional[Union[str, Pattern]]]]]], - keyword: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### function\_executed - -```python -def function_executed( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### workflow\_step\_execute - -```python -def workflow_step_execute( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### command - -```python -def command( - command: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### shortcut - -```python -def shortcut( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### global\_shortcut - -```python -def global_shortcut( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### message\_shortcut - -```python -def message_shortcut( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### action - -```python -def action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### block\_action - -```python -def block_action( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### attachment\_action - -```python -def attachment_action( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### dialog\_submission - -```python -def dialog_submission( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### dialog\_cancellation - -```python -def dialog_cancellation( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### workflow\_step\_edit - -```python -def workflow_step_edit( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### view - -```python -def view( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### view\_submission - -```python -def view_submission( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### view\_closed - -```python -def view_closed( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### workflow\_step\_save - -```python -def workflow_step_save( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### options - -```python -def options( - constraints: Union[str, Pattern, Dict[str, Union[str, Pattern]]], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### block\_suggestion - -```python -def block_suggestion( - action_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` - -#### dialog\_suggestion - -```python -def dialog_suggestion( - callback_id: Union[str, Pattern], - asyncio: bool = False, - base_logger: Optional[Logger] = None) -> Union[ListenerMatcher, AsyncListenerMatcher] -``` diff --git a/docs/english/reference/listener_matcher/custom_listener_matcher.md b/docs/english/reference/listener_matcher/custom_listener_matcher.md index 1b38b6460..7a984d0fa 100644 --- a/docs/english/reference/listener_matcher/custom_listener_matcher.md +++ b/docs/english/reference/listener_matcher/custom_listener_matcher.md @@ -3,32 +3,4 @@ sidebar_label: custom_listener_matcher title: slack_bolt.listener_matcher.custom_listener_matcher --- -## CustomListenerMatcher Objects -```python -class CustomListenerMatcher(ListenerMatcher) -``` - -#### app\_name: `str` - -#### func: `Callable[..., bool]` - -#### arg\_names: `MutableSequence[str]` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__( - *, - app_name: str, - func: Callable[..., bool], - base_logger: Optional[Logger] = None) -``` - -#### matches - -```python -def matches(req: BoltRequest, resp: BoltResponse) -> bool -``` diff --git a/docs/english/reference/listener_matcher/index.md b/docs/english/reference/listener_matcher/index.md index f24f19b70..0ce5056d2 100644 --- a/docs/english/reference/listener_matcher/index.md +++ b/docs/english/reference/listener_matcher/index.md @@ -8,65 +8,29 @@ A listener matcher is a simplified version of listener middleware. A listener matcher function returns bool value instead of `next()` method invocation inside. This interface enables developers to utilize simple predicate functions for additional listener conditions. -## Submodules - -- [slack_bolt.listener_matcher.async_builtins](/tools/bolt-python/reference/listener_matcher/async_builtins) -- [slack_bolt.listener_matcher.async_listener_matcher](/tools/bolt-python/reference/listener_matcher/async_listener_matcher) -- [slack_bolt.listener_matcher.builtins](/tools/bolt-python/reference/listener_matcher/builtins) -- [slack_bolt.listener_matcher.custom_listener_matcher](/tools/bolt-python/reference/listener_matcher/custom_listener_matcher) -- [slack_bolt.listener_matcher.listener_matcher](/tools/bolt-python/reference/listener_matcher/listener_matcher) - -## CustomListenerMatcher Objects - -```python -class CustomListenerMatcher(ListenerMatcher) -``` - -#### app\_name: `str` - -#### func: `Callable[..., bool]` - -#### arg\_names: `MutableSequence[str]` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__( - *, - app_name: str, - func: Callable[..., bool], - base_logger: Optional[Logger] = None) -``` +## `ListenerMatcher` -#### matches +### `matches` ```python -def matches(req: BoltRequest, resp: BoltResponse) -> bool -``` - -## ListenerMatcher Objects - -```python -class ListenerMatcher() -``` - -#### matches - -```python -def matches(req: BoltRequest, resp: BoltResponse) -> bool +matches(req, resp) ``` Matches against the request and returns True if matched. -**Arguments**: +**Parameters:** + +- **req** (BoltRequest) – The request +- **resp** (BoltResponse) – The response -- `req` _BoltRequest_ - The request -- `resp` _BoltResponse_ - The response +**Returns:** -**Returns**: +- bool – True if matched. -- `bool` - True if matched. +## Submodules -#### builtin\_listener\_matcher\_classes +- [slack_bolt.listener_matcher.async_builtins](/tools/bolt-python/reference/listener_matcher/async_builtins) +- [slack_bolt.listener_matcher.async_listener_matcher](/tools/bolt-python/reference/listener_matcher/async_listener_matcher) +- [slack_bolt.listener_matcher.builtins](/tools/bolt-python/reference/listener_matcher/builtins) +- [slack_bolt.listener_matcher.custom_listener_matcher](/tools/bolt-python/reference/listener_matcher/custom_listener_matcher) +- [slack_bolt.listener_matcher.listener_matcher](/tools/bolt-python/reference/listener_matcher/listener_matcher) diff --git a/docs/english/reference/listener_matcher/listener_matcher.md b/docs/english/reference/listener_matcher/listener_matcher.md index 5827a6b03..6e7c48358 100644 --- a/docs/english/reference/listener_matcher/listener_matcher.md +++ b/docs/english/reference/listener_matcher/listener_matcher.md @@ -4,25 +4,21 @@ title: slack_bolt.listener_matcher.listener_matcher slug: listener_matcher --- -## ListenerMatcher Objects +## `ListenerMatcher` -```python -class ListenerMatcher() -``` - -#### matches +### `matches` ```python -def matches(req: BoltRequest, resp: BoltResponse) -> bool +matches(req, resp) ``` Matches against the request and returns True if matched. -**Arguments**: +**Parameters:** -- `req` _BoltRequest_ - The request -- `resp` _BoltResponse_ - The response +- **req** (BoltRequest) – The request +- **resp** (BoltResponse) – The response -**Returns**: +**Returns:** -- `bool` - True if matched. +- bool – True if matched. diff --git a/docs/english/reference/logger/index.md b/docs/english/reference/logger/index.md index c1d106177..cd19a2a81 100644 --- a/docs/english/reference/logger/index.md +++ b/docs/english/reference/logger/index.md @@ -8,18 +8,3 @@ Bolt for Python relies on the standard `logging` module. ## Submodules - [slack_bolt.logger.messages](/tools/bolt-python/reference/logger/messages) - -#### get\_bolt\_logger - -```python -def get_bolt_logger(cls: Any, base_logger: Optional[Logger] = None) -> Logger -``` - -#### get\_bolt\_app\_logger - -```python -def get_bolt_app_logger( - app_name: str, - cls: object = None, - base_logger: Optional[Logger] = None) -> Logger -``` diff --git a/docs/english/reference/logger/messages.md b/docs/english/reference/logger/messages.md index 367dc6c3a..2b8b4e613 100644 --- a/docs/english/reference/logger/messages.md +++ b/docs/english/reference/logger/messages.md @@ -3,178 +3,4 @@ sidebar_label: messages title: slack_bolt.logger.messages --- -#### error\_client\_invalid\_type -```python -def error_client_invalid_type() -> str -``` - -#### error\_client\_invalid\_type\_async - -```python -def error_client_invalid_type_async() -> str -``` - -#### error\_oauth\_flow\_invalid\_type\_async - -```python -def error_oauth_flow_invalid_type_async() -> str -``` - -#### error\_oauth\_settings\_invalid\_type\_async - -```python -def error_oauth_settings_invalid_type_async() -> str -``` - -#### error\_auth\_test\_failure - -```python -def error_auth_test_failure(error_response: SlackResponse) -> str -``` - -#### error\_token\_required - -```python -def error_token_required() -> str -``` - -#### error\_unexpected\_listener\_middleware - -```python -def error_unexpected_listener_middleware(middleware_type) -> str -``` - -#### error\_listener\_function\_must\_be\_coro\_func - -```python -def error_listener_function_must_be_coro_func(func_name: str) -> str -``` - -#### error\_authorize\_conflicts - -```python -def error_authorize_conflicts() -> str -``` - -#### error\_message\_event\_type - -```python -def error_message_event_type(event_type: Union[str, Pattern]) -> str -``` - -#### error\_installation\_store\_required\_for\_builtin\_listeners - -```python -def error_installation_store_required_for_builtin_listeners() -> str -``` - -#### error\_oauth\_flow\_or\_authorize\_required - -```python -def error_oauth_flow_or_authorize_required() -> str -``` - -#### warning\_client\_prioritized\_and\_token\_skipped - -```python -def warning_client_prioritized_and_token_skipped() -> str -``` - -#### warning\_token\_skipped - -```python -def warning_token_skipped() -> str -``` - -#### warning\_installation\_store\_conflicts - -```python -def warning_installation_store_conflicts() -> str -``` - -#### warning\_unhandled\_by\_global\_middleware - -```python -def warning_unhandled_by_global_middleware( - name: str, - req: Union[BoltRequest, AsyncBoltRequest]) -> str -``` - -#### warning\_unhandled\_request - -```python -def warning_unhandled_request(req: Union[BoltRequest, AsyncBoltRequest]) -> str -``` - -#### warning\_did\_not\_call\_ack - -```python -def warning_did_not_call_ack(listener_name: str) -> str -``` - -#### warning\_bot\_only\_conflicts - -```python -def warning_bot_only_conflicts() -> str -``` - -#### warning\_skip\_uncommon\_arg\_name - -```python -def warning_skip_uncommon_arg_name(arg_name: str) -> str -``` - -#### warning\_ack\_timeout\_has\_no\_effect - -```python -def warning_ack_timeout_has_no_effect( - identifier: Union[str, Pattern], - ack_timeout: int) -> str -``` - -#### info\_default\_oauth\_settings\_loaded - -```python -def info_default_oauth_settings_loaded() -> str -``` - -#### debug\_applying\_middleware - -```python -def debug_applying_middleware(middleware_name: str) -> str -``` - -#### debug\_checking\_listener - -```python -def debug_checking_listener(listener_name: str) -> str -``` - -#### debug\_running\_listener - -```python -def debug_running_listener(listener_name: str) -> str -``` - -#### debug\_running\_lazy\_listener - -```python -def debug_running_lazy_listener(func_name: str) -> str -``` - -#### debug\_responding - -```python -def debug_responding(status: int, body: str, millis: int) -> str -``` - -#### debug\_return\_listener\_middleware\_response - -```python -def debug_return_listener_middleware_response( - listener_name: str, - status: int, - body: str, - starting_time: float) -> str -``` diff --git a/docs/english/reference/middleware/assistant/assistant.md b/docs/english/reference/middleware/assistant/assistant.md index 0d67911e2..a07b2130f 100644 --- a/docs/english/reference/middleware/assistant/assistant.md +++ b/docs/english/reference/middleware/assistant/assistant.md @@ -4,90 +4,4 @@ title: slack_bolt.middleware.assistant.assistant slug: assistant --- -## Assistant Objects -```python -class Assistant(Middleware) -``` - -#### thread\_context\_store: `Optional[AssistantThreadContextStore]` - -#### base\_logger: `Optional[logging.Logger]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - app_name: str = 'assistant', - thread_context_store: Optional[AssistantThreadContextStore] = None, - logger: Optional[logging.Logger] = None) -``` - -#### thread\_started - -```python -def thread_started( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### user\_message - -```python -def user_message( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### bot\_message - -```python -def bot_message( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### thread\_context\_changed - -```python -def thread_context_changed( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### default\_thread\_context\_changed - -```python -def default_thread_context_changed( - save_thread_context: SaveThreadContext, - payload: dict) -``` - -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> Optional[BoltResponse] -``` - -#### build\_listener - -```python -def build_listener( - listener_or_functions: Union[Listener, Callable, List[Callable]], - matchers: Optional[List[Union[ListenerMatcher, Callable[..., bool]]]] = None, - middleware: Optional[List[Middleware]] = None, - base_logger: Optional[Logger] = None) -> Listener -``` diff --git a/docs/english/reference/middleware/assistant/async_assistant.md b/docs/english/reference/middleware/assistant/async_assistant.md index 1b4fa1f8e..bce338e64 100644 --- a/docs/english/reference/middleware/assistant/async_assistant.md +++ b/docs/english/reference/middleware/assistant/async_assistant.md @@ -3,90 +3,4 @@ sidebar_label: async_assistant title: slack_bolt.middleware.assistant.async_assistant --- -## AsyncAssistant Objects -```python -class AsyncAssistant(AsyncMiddleware) -``` - -#### thread\_context\_store: `Optional[AsyncAssistantThreadContextStore]` - -#### base\_logger: `Optional[logging.Logger]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - app_name: str = 'assistant', - thread_context_store: Optional[AsyncAssistantThreadContextStore] = None, - logger: Optional[logging.Logger] = None) -``` - -#### thread\_started - -```python -def thread_started( - *args, - matchers: Optional[Union[Callable[..., bool], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### user\_message - -```python -def user_message( - *args, - matchers: Optional[Union[Callable[..., bool], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### bot\_message - -```python -def bot_message( - *args, - matchers: Optional[Union[Callable[..., bool], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### thread\_context\_changed - -```python -def thread_context_changed( - *args, - matchers: Optional[Union[Callable[..., bool], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### default\_thread\_context\_changed - -```python -async def default_thread_context_changed( - save_thread_context: AsyncSaveThreadContext, - payload: dict) -``` - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> Optional[BoltResponse] -``` - -#### build\_listener - -```python -def build_listener( - listener_or_functions: Union[AsyncListener, Callable, List[Callable]], - matchers: Optional[List[Union[AsyncListenerMatcher, Callable[..., Awaitable[bool]]]]] = None, - middleware: Optional[List[AsyncMiddleware]] = None, - base_logger: Optional[Logger] = None) -> AsyncListener -``` diff --git a/docs/english/reference/middleware/assistant/index.md b/docs/english/reference/middleware/assistant/index.md index 5d94bc94f..eebd4f0ca 100644 --- a/docs/english/reference/middleware/assistant/index.md +++ b/docs/english/reference/middleware/assistant/index.md @@ -7,91 +7,3 @@ title: slack_bolt.middleware.assistant - [slack_bolt.middleware.assistant.assistant](/tools/bolt-python/reference/middleware/assistant/assistant) - [slack_bolt.middleware.assistant.async_assistant](/tools/bolt-python/reference/middleware/assistant/async_assistant) - -## Assistant Objects - -```python -class Assistant(Middleware) -``` - -#### thread\_context\_store: `Optional[AssistantThreadContextStore]` - -#### base\_logger: `Optional[logging.Logger]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - app_name: str = 'assistant', - thread_context_store: Optional[AssistantThreadContextStore] = None, - logger: Optional[logging.Logger] = None) -``` - -#### thread\_started - -```python -def thread_started( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### user\_message - -```python -def user_message( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### bot\_message - -```python -def bot_message( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### thread\_context\_changed - -```python -def thread_context_changed( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) -``` - -#### default\_thread\_context\_changed - -```python -def default_thread_context_changed( - save_thread_context: SaveThreadContext, - payload: dict) -``` - -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> Optional[BoltResponse] -``` - -#### build\_listener - -```python -def build_listener( - listener_or_functions: Union[Listener, Callable, List[Callable]], - matchers: Optional[List[Union[ListenerMatcher, Callable[..., bool]]]] = None, - middleware: Optional[List[Middleware]] = None, - base_logger: Optional[Logger] = None) -> Listener -``` diff --git a/docs/english/reference/middleware/async_builtins.md b/docs/english/reference/middleware/async_builtins.md index 3b512ce7d..43881536a 100644 --- a/docs/english/reference/middleware/async_builtins.md +++ b/docs/english/reference/middleware/async_builtins.md @@ -3,142 +3,38 @@ sidebar_label: async_builtins title: slack_bolt.middleware.async_builtins --- -## AsyncIgnoringSelfEvents Objects +## `AsyncMessageListenerMatches` ```python -class AsyncIgnoringSelfEvents(IgnoringSelfEvents, AsyncMiddleware) +AsyncMessageListenerMatches(keyword) ``` -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` - -## AsyncRequestVerification Objects - -```python -class AsyncRequestVerification(RequestVerification, AsyncMiddleware) -``` - -Verifies an incoming request from Slack. - -Checks the validity of `x-slack-signature`, `x-slack-request-timestamp`, and the request body data. - -Refer to https://docs.slack.dev/authentication/verifying-requests-from-slack/ for details. - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` - -## AsyncSslCheck Objects - -```python -class AsyncSslCheck(SslCheck, AsyncMiddleware) -``` - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` - -## AsyncUrlVerification Objects - -```python -class AsyncUrlVerification(UrlVerification, AsyncMiddleware) -``` - -#### \_\_init\_\_ - -```python -def __init__(base_logger: Optional[Logger] = None) -``` - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` - -## AsyncMessageListenerMatches Objects - -```python -class AsyncMessageListenerMatches(AsyncMiddleware) -``` - -#### \_\_init\_\_ - -```python -def __init__(keyword: Union[str, Pattern]) -``` +Bases: AsyncMiddleware Captures matched keywords and saves the values in context. -#### async\_process +### `name` ```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse +name: str ``` -## AsyncAttachingFunctionToken Objects +The name of this middleware. -```python -class AsyncAttachingFunctionToken(AsyncMiddleware) -``` +## `AsyncRequestVerification` -#### async\_process +Bases: RequestVerification, AsyncMiddleware -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` - -## AsyncAttachingConversationKwargs Objects +Verifies an incoming request from Slack. -```python -class AsyncAttachingConversationKwargs(AsyncMiddleware) -``` +Checks the validity of `x-slack-signature`, `x-slack-request-timestamp`, and the request body data. -#### thread\_context\_store: `Optional[AsyncAssistantThreadContextStore]` +Refer to https://docs.slack.dev/authentication/verifying-requests-from-slack/ for details. -#### \_\_init\_\_ +### `name` ```python -def __init__(thread_context_store: Optional[AsyncAssistantThreadContextStore] = None) +name: str ``` -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> Optional[BoltResponse] -``` +The name of this middleware. diff --git a/docs/english/reference/middleware/async_custom_middleware.md b/docs/english/reference/middleware/async_custom_middleware.md index 825532aef..4599f78e3 100644 --- a/docs/english/reference/middleware/async_custom_middleware.md +++ b/docs/english/reference/middleware/async_custom_middleware.md @@ -3,43 +3,4 @@ sidebar_label: async_custom_middleware title: slack_bolt.middleware.async_custom_middleware --- -## AsyncCustomMiddleware Objects -```python -class AsyncCustomMiddleware(AsyncMiddleware) -``` - -#### app\_name: `str` - -#### func: `Callable[..., Awaitable[Any]]` - -#### arg\_names: `MutableSequence[str]` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__( - *, - app_name: str, - func: Callable[..., Awaitable[Any]], - base_logger: Optional[Logger] = None) -``` - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` - -#### name - -```python -@property -def name() -> str -``` diff --git a/docs/english/reference/middleware/async_middleware.md b/docs/english/reference/middleware/async_middleware.md index d4f13b25e..5c199d68e 100644 --- a/docs/english/reference/middleware/async_middleware.md +++ b/docs/english/reference/middleware/async_middleware.md @@ -3,22 +3,14 @@ sidebar_label: async_middleware title: slack_bolt.middleware.async_middleware --- -## AsyncMiddleware Objects - -```python -class AsyncMiddleware() -``` +## `AsyncMiddleware` A middleware can process request data before other middleware and listener functions. -#### async\_process +### `async_process` ```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> Optional[BoltResponse] +async_process(*, req, resp, next) ``` Processes a request data before other middleware and listeners. @@ -42,22 +34,20 @@ async def simple_middleware(req, resp, next_): await next_() ``` +**Parameters:** -**Arguments**: - -- `req` _AsyncBoltRequest_ - The incoming request -- `resp` _BoltResponse_ - The response -- `next` _Callable[[], Awaitable[BoltResponse]]_ - The function to tell the chain that it can continue +- **req** (AsyncBoltRequest) – The incoming request +- **resp** (BoltResponse) – The response +- **next** (Callable[[], Awaitable[BoltResponse]]) – The function to tell the chain that it can continue -**Returns**: +**Returns:** -- `Optional[BoltResponse]` - Processed response (optional) +- Optional[BoltResponse] – Processed response (optional) -#### name +### `name` ```python -@property -def name() -> str +name: str ``` The name of this middleware. diff --git a/docs/english/reference/middleware/async_middleware_error_handler.md b/docs/english/reference/middleware/async_middleware_error_handler.md index acbe7b4e4..4aa03952b 100644 --- a/docs/english/reference/middleware/async_middleware_error_handler.md +++ b/docs/english/reference/middleware/async_middleware_error_handler.md @@ -3,67 +3,18 @@ sidebar_label: async_middleware_error_handler title: slack_bolt.middleware.async_middleware_error_handler --- -## AsyncMiddlewareErrorHandler Objects +## `AsyncMiddlewareErrorHandler` -```python -class AsyncMiddlewareErrorHandler() -``` - -#### handle +### `handle` ```python -async def handle( - error: Exception, - request: AsyncBoltRequest, - response: Optional[BoltResponse]) -> None +handle(error, request, response) ``` Handles an unhandled exception. -**Arguments**: - -- `error` _Exception_ - The raised exception. -- `request` _AsyncBoltRequest_ - The request. -- `response` _Optional[BoltResponse]_ - The response. - -## AsyncCustomMiddlewareErrorHandler Objects - -```python -class AsyncCustomMiddlewareErrorHandler(AsyncMiddlewareErrorHandler) -``` - -#### \_\_init\_\_ +**Parameters:** -```python -def __init__(logger: Logger, func: Callable[..., Awaitable[Optional[BoltResponse]]]) -``` - -#### handle - -```python -async def handle( - error: Exception, - request: AsyncBoltRequest, - response: Optional[BoltResponse]) -> None -``` - -## AsyncDefaultMiddlewareErrorHandler Objects - -```python -class AsyncDefaultMiddlewareErrorHandler(AsyncMiddlewareErrorHandler) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger) -``` - -#### handle - -```python -async def handle( - error: Exception, - request: AsyncBoltRequest, - response: Optional[BoltResponse]) -``` +- **error** (Exception) – The raised exception. +- **request** (AsyncBoltRequest) – The request. +- **response** (Optional[BoltResponse]) – The response. diff --git a/docs/english/reference/middleware/attaching_conversation_kwargs/async_attaching_conversation_kwargs.md b/docs/english/reference/middleware/attaching_conversation_kwargs/async_attaching_conversation_kwargs.md index e209ed415..080f9978e 100644 --- a/docs/english/reference/middleware/attaching_conversation_kwargs/async_attaching_conversation_kwargs.md +++ b/docs/english/reference/middleware/attaching_conversation_kwargs/async_attaching_conversation_kwargs.md @@ -3,26 +3,4 @@ sidebar_label: async_attaching_conversation_kwargs title: slack_bolt.middleware.attaching_conversation_kwargs.async_attaching_conversation_kwargs --- -## AsyncAttachingConversationKwargs Objects -```python -class AsyncAttachingConversationKwargs(AsyncMiddleware) -``` - -#### thread\_context\_store: `Optional[AsyncAssistantThreadContextStore]` - -#### \_\_init\_\_ - -```python -def __init__(thread_context_store: Optional[AsyncAssistantThreadContextStore] = None) -``` - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> Optional[BoltResponse] -``` diff --git a/docs/english/reference/middleware/attaching_conversation_kwargs/attaching_conversation_kwargs.md b/docs/english/reference/middleware/attaching_conversation_kwargs/attaching_conversation_kwargs.md index c3e38e7eb..763150e05 100644 --- a/docs/english/reference/middleware/attaching_conversation_kwargs/attaching_conversation_kwargs.md +++ b/docs/english/reference/middleware/attaching_conversation_kwargs/attaching_conversation_kwargs.md @@ -4,26 +4,4 @@ title: slack_bolt.middleware.attaching_conversation_kwargs.attaching_conversatio slug: attaching_conversation_kwargs --- -## AttachingConversationKwargs Objects -```python -class AttachingConversationKwargs(Middleware) -``` - -#### thread\_context\_store: `Optional[AssistantThreadContextStore]` - -#### \_\_init\_\_ - -```python -def __init__(thread_context_store: Optional[AssistantThreadContextStore] = None) -``` - -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> Optional[BoltResponse] -``` diff --git a/docs/english/reference/middleware/attaching_conversation_kwargs/index.md b/docs/english/reference/middleware/attaching_conversation_kwargs/index.md index 3fa0850c1..50c1994fe 100644 --- a/docs/english/reference/middleware/attaching_conversation_kwargs/index.md +++ b/docs/english/reference/middleware/attaching_conversation_kwargs/index.md @@ -7,27 +7,3 @@ title: slack_bolt.middleware.attaching_conversation_kwargs - [slack_bolt.middleware.attaching_conversation_kwargs.async_attaching_conversation_kwargs](/tools/bolt-python/reference/middleware/attaching_conversation_kwargs/async_attaching_conversation_kwargs) - [slack_bolt.middleware.attaching_conversation_kwargs.attaching_conversation_kwargs](/tools/bolt-python/reference/middleware/attaching_conversation_kwargs/attaching_conversation_kwargs) - -## AttachingConversationKwargs Objects - -```python -class AttachingConversationKwargs(Middleware) -``` - -#### thread\_context\_store: `Optional[AssistantThreadContextStore]` - -#### \_\_init\_\_ - -```python -def __init__(thread_context_store: Optional[AssistantThreadContextStore] = None) -``` - -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> Optional[BoltResponse] -``` diff --git a/docs/english/reference/middleware/attaching_function_token/async_attaching_function_token.md b/docs/english/reference/middleware/attaching_function_token/async_attaching_function_token.md index 98f90a3f3..28ddc7f81 100644 --- a/docs/english/reference/middleware/attaching_function_token/async_attaching_function_token.md +++ b/docs/english/reference/middleware/attaching_function_token/async_attaching_function_token.md @@ -3,18 +3,4 @@ sidebar_label: async_attaching_function_token title: slack_bolt.middleware.attaching_function_token.async_attaching_function_token --- -## AsyncAttachingFunctionToken Objects -```python -class AsyncAttachingFunctionToken(AsyncMiddleware) -``` - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` diff --git a/docs/english/reference/middleware/attaching_function_token/attaching_function_token.md b/docs/english/reference/middleware/attaching_function_token/attaching_function_token.md index 1670e92ae..d65004a85 100644 --- a/docs/english/reference/middleware/attaching_function_token/attaching_function_token.md +++ b/docs/english/reference/middleware/attaching_function_token/attaching_function_token.md @@ -4,18 +4,4 @@ title: slack_bolt.middleware.attaching_function_token.attaching_function_token slug: attaching_function_token --- -## AttachingFunctionToken Objects -```python -class AttachingFunctionToken(Middleware) -``` - -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse -``` diff --git a/docs/english/reference/middleware/attaching_function_token/index.md b/docs/english/reference/middleware/attaching_function_token/index.md index 48b531ef2..96e2a5a75 100644 --- a/docs/english/reference/middleware/attaching_function_token/index.md +++ b/docs/english/reference/middleware/attaching_function_token/index.md @@ -7,19 +7,3 @@ title: slack_bolt.middleware.attaching_function_token - [slack_bolt.middleware.attaching_function_token.async_attaching_function_token](/tools/bolt-python/reference/middleware/attaching_function_token/async_attaching_function_token) - [slack_bolt.middleware.attaching_function_token.attaching_function_token](/tools/bolt-python/reference/middleware/attaching_function_token/attaching_function_token) - -## AttachingFunctionToken Objects - -```python -class AttachingFunctionToken(Middleware) -``` - -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse -``` diff --git a/docs/english/reference/middleware/authorization/async_authorization.md b/docs/english/reference/middleware/authorization/async_authorization.md index c583ddedc..f12e00d55 100644 --- a/docs/english/reference/middleware/authorization/async_authorization.md +++ b/docs/english/reference/middleware/authorization/async_authorization.md @@ -3,8 +3,4 @@ sidebar_label: async_authorization title: slack_bolt.middleware.authorization.async_authorization --- -## AsyncAuthorization Objects -```python -class AsyncAuthorization(AsyncMiddleware, ABC) -``` diff --git a/docs/english/reference/middleware/authorization/async_multi_teams_authorization.md b/docs/english/reference/middleware/authorization/async_multi_teams_authorization.md index 4a9bf9c86..40093211f 100644 --- a/docs/english/reference/middleware/authorization/async_multi_teams_authorization.md +++ b/docs/english/reference/middleware/authorization/async_multi_teams_authorization.md @@ -3,41 +3,27 @@ sidebar_label: async_multi_teams_authorization title: slack_bolt.middleware.authorization.async_multi_teams_authorization --- -## AsyncMultiTeamsAuthorization Objects +## `AsyncMultiTeamsAuthorization` ```python -class AsyncMultiTeamsAuthorization(AsyncAuthorization) +AsyncMultiTeamsAuthorization(authorize, base_logger=None, user_token_resolution='authed_user', user_facing_authorize_error_message=None) ``` -#### authorize: `AsyncAuthorize` - -#### user\_token\_resolution: `str` - -#### \_\_init\_\_ - -```python -def __init__( - authorize: AsyncAuthorize, - base_logger: Optional[Logger] = None, - user_token_resolution: str = 'authed_user', - user_facing_authorize_error_message: Optional[str] = None) -``` +Bases: AsyncAuthorization Multi-workspace authorization. -**Arguments**: +**Parameters:** -- `authorize` _AsyncAuthorize_ - The function to authorize incoming requests from Slack. -- `base_logger` _Optional[Logger]_ - The base logger -- `user_token_resolution` _str_ - "authed_user" or "actor" -- `user_facing_authorize_error_message` _Optional[str]_ - The user-facing error message when installation is not found +- **authorize** (AsyncAuthorize) – The function to authorize incoming requests from Slack. +- **base_logger** (Optional[Logger]) – The base logger +- **user_token_resolution** (str) – "authed_user" or "actor" +- **user_facing_authorize_error_message** (Optional[str]) – The user-facing error message when installation is not found -#### async\_process +### `name` ```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse +name: str ``` + +The name of this middleware. diff --git a/docs/english/reference/middleware/authorization/async_single_team_authorization.md b/docs/english/reference/middleware/authorization/async_single_team_authorization.md index 0ab9b05f5..d9fbbab05 100644 --- a/docs/english/reference/middleware/authorization/async_single_team_authorization.md +++ b/docs/english/reference/middleware/authorization/async_single_team_authorization.md @@ -3,30 +3,20 @@ sidebar_label: async_single_team_authorization title: slack_bolt.middleware.authorization.async_single_team_authorization --- -## AsyncSingleTeamAuthorization Objects +## `AsyncSingleTeamAuthorization` ```python -class AsyncSingleTeamAuthorization(AsyncAuthorization) +AsyncSingleTeamAuthorization(base_logger=None, user_facing_authorize_error_message=None) ``` -#### \_\_init\_\_ - -```python -def __init__( - base_logger: Optional[Logger] = None, - user_facing_authorize_error_message: Optional[str] = None) -``` +Bases: AsyncAuthorization Single-workspace authorization. -#### auth\_test\_result: `Optional[AsyncSlackResponse]` - -#### async\_process +### `name` ```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse +name: str ``` + +The name of this middleware. diff --git a/docs/english/reference/middleware/authorization/authorization.md b/docs/english/reference/middleware/authorization/authorization.md index 421f49eb5..dc26576a9 100644 --- a/docs/english/reference/middleware/authorization/authorization.md +++ b/docs/english/reference/middleware/authorization/authorization.md @@ -4,8 +4,4 @@ title: slack_bolt.middleware.authorization.authorization slug: authorization --- -## Authorization Objects -```python -class Authorization(Middleware) -``` diff --git a/docs/english/reference/middleware/authorization/index.md b/docs/english/reference/middleware/authorization/index.md index 08e6e43b4..71f4d204b 100644 --- a/docs/english/reference/middleware/authorization/index.md +++ b/docs/english/reference/middleware/authorization/index.md @@ -3,93 +3,62 @@ sidebar_label: authorization title: slack_bolt.middleware.authorization --- -## Submodules - -- [slack_bolt.middleware.authorization.async_authorization](/tools/bolt-python/reference/middleware/authorization/async_authorization) -- [slack_bolt.middleware.authorization.async_internals](/tools/bolt-python/reference/middleware/authorization/async_internals) -- [slack_bolt.middleware.authorization.async_multi_teams_authorization](/tools/bolt-python/reference/middleware/authorization/async_multi_teams_authorization) -- [slack_bolt.middleware.authorization.async_single_team_authorization](/tools/bolt-python/reference/middleware/authorization/async_single_team_authorization) -- [slack_bolt.middleware.authorization.authorization](/tools/bolt-python/reference/middleware/authorization/authorization) -- [slack_bolt.middleware.authorization.internals](/tools/bolt-python/reference/middleware/authorization/internals) -- [slack_bolt.middleware.authorization.multi_teams_authorization](/tools/bolt-python/reference/middleware/authorization/multi_teams_authorization) -- [slack_bolt.middleware.authorization.single_team_authorization](/tools/bolt-python/reference/middleware/authorization/single_team_authorization) - -## Authorization Objects +## `MultiTeamsAuthorization` ```python -class Authorization(Middleware) +MultiTeamsAuthorization(*, authorize, base_logger=None, user_token_resolution='authed_user', user_facing_authorize_error_message=None) ``` -## MultiTeamsAuthorization Objects - -```python -class MultiTeamsAuthorization(Authorization) -``` - -#### authorize: `Authorize` - -#### user\_token\_resolution: `str` - -#### \_\_init\_\_ - -```python -def __init__( - *, - authorize: Authorize, - base_logger: Optional[Logger] = None, - user_token_resolution: str = 'authed_user', - user_facing_authorize_error_message: Optional[str] = None) -``` +Bases: Authorization Multi-workspace authorization. -**Arguments**: +**Parameters:** -- `authorize` _Authorize_ - The function to authorize incoming requests from Slack. -- `base_logger` _Optional[Logger]_ - The base logger -- `user_token_resolution` _str_ - "authed_user" or "actor" -- `user_facing_authorize_error_message` _Optional[str]_ - The user-facing error message when installation is not found +- **authorize** (Authorize) – The function to authorize incoming requests from Slack. +- **base_logger** (Optional[Logger]) – The base logger +- **user_token_resolution** (str) – "authed_user" or "actor" +- **user_facing_authorize_error_message** (Optional[str]) – The user-facing error message when installation is not found -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` -## SingleTeamAuthorization Objects - -```python -class SingleTeamAuthorization(Authorization) -``` +The name of this middleware. -#### \_\_init\_\_ +## `SingleTeamAuthorization` ```python -def __init__( - *, - auth_test_result: Optional[SlackResponse] = None, - base_logger: Optional[Logger] = None, - user_facing_authorize_error_message: Optional[str] = None) +SingleTeamAuthorization(*, auth_test_result=None, base_logger=None, user_facing_authorize_error_message=None) ``` +Bases: Authorization + Single-workspace authorization. -**Arguments**: +**Parameters:** -- `auth_test_result` _Optional[SlackResponse]_ - The initial `auth.test` API call result. -- `base_logger` _Optional[Logger]_ - The base logger -- `user_facing_authorize_error_message` _Optional[str]_ - The message shown to the end-user when authorization fails +- **auth_test_result** (Optional[SlackResponse]) – The initial `auth.test` API call result. +- **base_logger** (Optional[Logger]) – The base logger +- **user_facing_authorize_error_message** (Optional[str]) – The message shown to the end-user when authorization fails -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` + +The name of this middleware. + +## Submodules + +- [slack_bolt.middleware.authorization.async_authorization](/tools/bolt-python/reference/middleware/authorization/async_authorization) +- [slack_bolt.middleware.authorization.async_internals](/tools/bolt-python/reference/middleware/authorization/async_internals) +- [slack_bolt.middleware.authorization.async_multi_teams_authorization](/tools/bolt-python/reference/middleware/authorization/async_multi_teams_authorization) +- [slack_bolt.middleware.authorization.async_single_team_authorization](/tools/bolt-python/reference/middleware/authorization/async_single_team_authorization) +- [slack_bolt.middleware.authorization.authorization](/tools/bolt-python/reference/middleware/authorization/authorization) +- [slack_bolt.middleware.authorization.internals](/tools/bolt-python/reference/middleware/authorization/internals) +- [slack_bolt.middleware.authorization.multi_teams_authorization](/tools/bolt-python/reference/middleware/authorization/multi_teams_authorization) +- [slack_bolt.middleware.authorization.single_team_authorization](/tools/bolt-python/reference/middleware/authorization/single_team_authorization) diff --git a/docs/english/reference/middleware/authorization/internals.md b/docs/english/reference/middleware/authorization/internals.md index 7309240da..879a44291 100644 --- a/docs/english/reference/middleware/authorization/internals.md +++ b/docs/english/reference/middleware/authorization/internals.md @@ -3,4 +3,4 @@ sidebar_label: internals title: slack_bolt.middleware.authorization.internals --- -#### no\_auth\_test\_events + diff --git a/docs/english/reference/middleware/authorization/multi_teams_authorization.md b/docs/english/reference/middleware/authorization/multi_teams_authorization.md index ae8865577..4e33b4756 100644 --- a/docs/english/reference/middleware/authorization/multi_teams_authorization.md +++ b/docs/english/reference/middleware/authorization/multi_teams_authorization.md @@ -3,42 +3,27 @@ sidebar_label: multi_teams_authorization title: slack_bolt.middleware.authorization.multi_teams_authorization --- -## MultiTeamsAuthorization Objects +## `MultiTeamsAuthorization` ```python -class MultiTeamsAuthorization(Authorization) +MultiTeamsAuthorization(*, authorize, base_logger=None, user_token_resolution='authed_user', user_facing_authorize_error_message=None) ``` -#### authorize: `Authorize` - -#### user\_token\_resolution: `str` - -#### \_\_init\_\_ - -```python -def __init__( - *, - authorize: Authorize, - base_logger: Optional[Logger] = None, - user_token_resolution: str = 'authed_user', - user_facing_authorize_error_message: Optional[str] = None) -``` +Bases: Authorization Multi-workspace authorization. -**Arguments**: +**Parameters:** -- `authorize` _Authorize_ - The function to authorize incoming requests from Slack. -- `base_logger` _Optional[Logger]_ - The base logger -- `user_token_resolution` _str_ - "authed_user" or "actor" -- `user_facing_authorize_error_message` _Optional[str]_ - The user-facing error message when installation is not found +- **authorize** (Authorize) – The function to authorize incoming requests from Slack. +- **base_logger** (Optional[Logger]) – The base logger +- **user_token_resolution** (str) – "authed_user" or "actor" +- **user_facing_authorize_error_message** (Optional[str]) – The user-facing error message when installation is not found -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` + +The name of this middleware. diff --git a/docs/english/reference/middleware/authorization/single_team_authorization.md b/docs/english/reference/middleware/authorization/single_team_authorization.md index c240f856a..0c3789b9e 100644 --- a/docs/english/reference/middleware/authorization/single_team_authorization.md +++ b/docs/english/reference/middleware/authorization/single_team_authorization.md @@ -3,36 +3,26 @@ sidebar_label: single_team_authorization title: slack_bolt.middleware.authorization.single_team_authorization --- -## SingleTeamAuthorization Objects +## `SingleTeamAuthorization` ```python -class SingleTeamAuthorization(Authorization) +SingleTeamAuthorization(*, auth_test_result=None, base_logger=None, user_facing_authorize_error_message=None) ``` -#### \_\_init\_\_ - -```python -def __init__( - *, - auth_test_result: Optional[SlackResponse] = None, - base_logger: Optional[Logger] = None, - user_facing_authorize_error_message: Optional[str] = None) -``` +Bases: Authorization Single-workspace authorization. -**Arguments**: +**Parameters:** -- `auth_test_result` _Optional[SlackResponse]_ - The initial `auth.test` API call result. -- `base_logger` _Optional[Logger]_ - The base logger -- `user_facing_authorize_error_message` _Optional[str]_ - The message shown to the end-user when authorization fails +- **auth_test_result** (Optional[SlackResponse]) – The initial `auth.test` API call result. +- **base_logger** (Optional[Logger]) – The base logger +- **user_facing_authorize_error_message** (Optional[str]) – The message shown to the end-user when authorization fails -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` + +The name of this middleware. diff --git a/docs/english/reference/middleware/custom_middleware.md b/docs/english/reference/middleware/custom_middleware.md index b65b9ee44..4027402cd 100644 --- a/docs/english/reference/middleware/custom_middleware.md +++ b/docs/english/reference/middleware/custom_middleware.md @@ -3,39 +3,4 @@ sidebar_label: custom_middleware title: slack_bolt.middleware.custom_middleware --- -## CustomMiddleware Objects -```python -class CustomMiddleware(Middleware) -``` - -#### app\_name: `str` - -#### func: `Callable[..., Any]` - -#### arg\_names: `MutableSequence[str]` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__(*, app_name: str, func: Callable, base_logger: Optional[Logger] = None) -``` - -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse -``` - -#### name - -```python -@property -def name() -> str -``` diff --git a/docs/english/reference/middleware/ignoring_self_events/async_ignoring_self_events.md b/docs/english/reference/middleware/ignoring_self_events/async_ignoring_self_events.md index a3eb92dc3..d08fb86f1 100644 --- a/docs/english/reference/middleware/ignoring_self_events/async_ignoring_self_events.md +++ b/docs/english/reference/middleware/ignoring_self_events/async_ignoring_self_events.md @@ -3,18 +3,4 @@ sidebar_label: async_ignoring_self_events title: slack_bolt.middleware.ignoring_self_events.async_ignoring_self_events --- -## AsyncIgnoringSelfEvents Objects -```python -class AsyncIgnoringSelfEvents(IgnoringSelfEvents, AsyncMiddleware) -``` - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` diff --git a/docs/english/reference/middleware/ignoring_self_events/ignoring_self_events.md b/docs/english/reference/middleware/ignoring_self_events/ignoring_self_events.md index 816a153bb..a2367afdd 100644 --- a/docs/english/reference/middleware/ignoring_self_events/ignoring_self_events.md +++ b/docs/english/reference/middleware/ignoring_self_events/ignoring_self_events.md @@ -4,30 +4,20 @@ title: slack_bolt.middleware.ignoring_self_events.ignoring_self_events slug: ignoring_self_events --- -## IgnoringSelfEvents Objects +## `IgnoringSelfEvents` ```python -class IgnoringSelfEvents(Middleware) +IgnoringSelfEvents(base_logger=None, ignoring_self_assistant_message_events_enabled=True) ``` -#### \_\_init\_\_ - -```python -def __init__( - base_logger: Optional[logging.Logger] = None, - ignoring_self_assistant_message_events_enabled: bool = True) -``` +Bases: Middleware Ignores the events generated by this bot user itself. -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` -#### events\_that\_should\_be\_kept +The name of this middleware. diff --git a/docs/english/reference/middleware/ignoring_self_events/index.md b/docs/english/reference/middleware/ignoring_self_events/index.md index 3d9badbbc..d2977bf85 100644 --- a/docs/english/reference/middleware/ignoring_self_events/index.md +++ b/docs/english/reference/middleware/ignoring_self_events/index.md @@ -3,35 +3,25 @@ sidebar_label: ignoring_self_events title: slack_bolt.middleware.ignoring_self_events --- -## Submodules - -- [slack_bolt.middleware.ignoring_self_events.async_ignoring_self_events](/tools/bolt-python/reference/middleware/ignoring_self_events/async_ignoring_self_events) -- [slack_bolt.middleware.ignoring_self_events.ignoring_self_events](/tools/bolt-python/reference/middleware/ignoring_self_events/ignoring_self_events) - -## IgnoringSelfEvents Objects +## `IgnoringSelfEvents` ```python -class IgnoringSelfEvents(Middleware) +IgnoringSelfEvents(base_logger=None, ignoring_self_assistant_message_events_enabled=True) ``` -#### \_\_init\_\_ - -```python -def __init__( - base_logger: Optional[logging.Logger] = None, - ignoring_self_assistant_message_events_enabled: bool = True) -``` +Bases: Middleware Ignores the events generated by this bot user itself. -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` -#### events\_that\_should\_be\_kept +The name of this middleware. + +## Submodules + +- [slack_bolt.middleware.ignoring_self_events.async_ignoring_self_events](/tools/bolt-python/reference/middleware/ignoring_self_events/async_ignoring_self_events) +- [slack_bolt.middleware.ignoring_self_events.ignoring_self_events](/tools/bolt-python/reference/middleware/ignoring_self_events/ignoring_self_events) diff --git a/docs/english/reference/middleware/index.md b/docs/english/reference/middleware/index.md index 81c65872c..baf36f827 100644 --- a/docs/english/reference/middleware/index.md +++ b/docs/english/reference/middleware/index.md @@ -10,167 +10,214 @@ Call the `next()` method if the execution chain should continue running the foll Middleware can be used globally before all listener executions. It's also possible to run a middleware only for a particular listener. -## Submodules - -- [slack_bolt.middleware.assistant](/tools/bolt-python/reference/middleware/assistant) -- [slack_bolt.middleware.async_builtins](/tools/bolt-python/reference/middleware/async_builtins) -- [slack_bolt.middleware.async_custom_middleware](/tools/bolt-python/reference/middleware/async_custom_middleware) -- [slack_bolt.middleware.async_middleware](/tools/bolt-python/reference/middleware/async_middleware) -- [slack_bolt.middleware.async_middleware_error_handler](/tools/bolt-python/reference/middleware/async_middleware_error_handler) -- [slack_bolt.middleware.attaching_conversation_kwargs](/tools/bolt-python/reference/middleware/attaching_conversation_kwargs) -- [slack_bolt.middleware.attaching_function_token](/tools/bolt-python/reference/middleware/attaching_function_token) -- [slack_bolt.middleware.authorization](/tools/bolt-python/reference/middleware/authorization) -- [slack_bolt.middleware.custom_middleware](/tools/bolt-python/reference/middleware/custom_middleware) -- [slack_bolt.middleware.ignoring_self_events](/tools/bolt-python/reference/middleware/ignoring_self_events) -- [slack_bolt.middleware.message_listener_matches](/tools/bolt-python/reference/middleware/message_listener_matches) -- [slack_bolt.middleware.middleware](/tools/bolt-python/reference/middleware/middleware) -- [slack_bolt.middleware.middleware_error_handler](/tools/bolt-python/reference/middleware/middleware_error_handler) -- [slack_bolt.middleware.request_verification](/tools/bolt-python/reference/middleware/request_verification) -- [slack_bolt.middleware.ssl_check](/tools/bolt-python/reference/middleware/ssl_check) -- [slack_bolt.middleware.url_verification](/tools/bolt-python/reference/middleware/url_verification) - -## SingleTeamAuthorization Objects +## `IgnoringSelfEvents` ```python -class SingleTeamAuthorization(Authorization) +IgnoringSelfEvents(base_logger=None, ignoring_self_assistant_message_events_enabled=True) ``` -## MultiTeamsAuthorization Objects +Bases: Middleware -```python -class MultiTeamsAuthorization(Authorization) -``` +Ignores the events generated by this bot user itself. -## CustomMiddleware Objects +### `name` ```python -class CustomMiddleware(Middleware) +name: str ``` -#### app\_name: `str` - -#### func: `Callable[..., Any]` +The name of this middleware. -#### arg\_names: `MutableSequence[str]` +## `Middleware` -#### logger: `Logger` +A middleware can process request data before other middleware and listener functions. -#### \_\_init\_\_ +### `name` ```python -def __init__(*, app_name: str, func: Callable, base_logger: Optional[Logger] = None) +name: str ``` -#### process +The name of this middleware. + +### `process` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +process(*, req, resp, next) ``` -#### name +Processes a request data before other middleware and listeners. + +A middleware calls `next()` function if the chain should continue. ```python -@property -def name() -> str +@app.middleware +def simple_middleware(req, resp, next): + # do something here + next() ``` -## IgnoringSelfEvents Objects +This `process(req, resp, next)` method is supposed to be invoked only inside bolt-python. +If you want to avoid the name `next()` in your middleware functions, you can use `next_()` method instead. ```python -class IgnoringSelfEvents(Middleware) +@app.middleware +def simple_middleware(req, resp, next_): + # do something here + next_() ``` -## Middleware Objects +**Parameters:** -```python -class Middleware() -``` +- **req** (BoltRequest) – The incoming request +- **resp** (BoltResponse) – The response +- **next** (Callable[[], BoltResponse]) – The function to tell the chain that it can continue -A middleware can process request data before other middleware and listener functions. +**Returns:** + +- Optional[BoltResponse] – Processed response (optional) -#### process +## `MultiTeamsAuthorization` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> Optional[BoltResponse] +MultiTeamsAuthorization(*, authorize, base_logger=None, user_token_resolution='authed_user', user_facing_authorize_error_message=None) ``` -Processes a request data before other middleware and listeners. +Bases: Authorization -A middleware calls `next()` function if the chain should continue. +Multi-workspace authorization. + +**Parameters:** + +- **authorize** (Authorize) – The function to authorize incoming requests from Slack. +- **base_logger** (Optional[Logger]) – The base logger +- **user_token_resolution** (str) – "authed_user" or "actor" +- **user_facing_authorize_error_message** (Optional[str]) – The user-facing error message when installation is not found + +### `name` ```python -@app.middleware -def simple_middleware(req, resp, next): - # do something here - next() +name: str ``` -This `process(req, resp, next)` method is supposed to be invoked only inside bolt-python. -If you want to avoid the name `next()` in your middleware functions, you can use `next_()` method instead. +The name of this middleware. + +## `RequestVerification` ```python -@app.middleware -def simple_middleware(req, resp, next_): - # do something here - next_() +RequestVerification(signing_secret, base_logger=None) ``` +Bases: Middleware + +Verifies an incoming request from Slack. -**Arguments**: +Checks the validity of `x-slack-signature`, `x-slack-request-timestamp`, and the request body data. -- `req` _BoltRequest_ - The incoming request -- `resp` _BoltResponse_ - The response -- `next` _Callable[[], BoltResponse]_ - The function to tell the chain that it can continue +Refer to https://docs.slack.dev/authentication/verifying-requests-from-slack/ for details. -**Returns**: +**Parameters:** -- `Optional[BoltResponse]` - Processed response (optional) +- **signing_secret** (str) – The signing secret +- **base_logger** (Optional[Logger]) – The base logger -#### name +### `name` ```python -@property -def name() -> str +name: str ``` The name of this middleware. -## RequestVerification Objects +## `SingleTeamAuthorization` ```python -class RequestVerification(Middleware) +SingleTeamAuthorization(*, auth_test_result=None, base_logger=None, user_facing_authorize_error_message=None) ``` -## SslCheck Objects +Bases: Authorization + +Single-workspace authorization. + +**Parameters:** + +- **auth_test_result** (Optional[SlackResponse]) – The initial `auth.test` API call result. +- **base_logger** (Optional[Logger]) – The base logger +- **user_facing_authorize_error_message** (Optional[str]) – The message shown to the end-user when authorization fails + +### `name` ```python -class SslCheck(Middleware) +name: str ``` -## UrlVerification Objects +The name of this middleware. + +## `SslCheck` ```python -class UrlVerification(Middleware) +SslCheck(verification_token=None, base_logger=None) ``` -## AttachingFunctionToken Objects +Bases: Middleware + +Handles `ssl_check` requests. + +Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details. + +**Parameters:** + +- **verification_token** (Optional[str]) – The verification token to check +(optional as it's already deprecated - https://docs.slack.dev/authentication/verifying-requests-from-slack/#deprecation) +- **base_logger** (Optional[Logger]) – The base logger + +### `name` ```python -class AttachingFunctionToken(Middleware) +name: str ``` -## AttachingConversationKwargs Objects +The name of this middleware. + +## `UrlVerification` ```python -class AttachingConversationKwargs(Middleware) +UrlVerification(base_logger=None) ``` -#### builtin\_middleware\_classes +Bases: Middleware + +Handles url_verification requests. + +Refer to https://docs.slack.dev/reference/events/url_verification/ for details. + +**Parameters:** + +- **base_logger** (Optional[Logger]) – The base logger + +### `name` + +```python +name: str +``` + +The name of this middleware. + +## Submodules + +- [slack_bolt.middleware.assistant](/tools/bolt-python/reference/middleware/assistant) +- [slack_bolt.middleware.async_builtins](/tools/bolt-python/reference/middleware/async_builtins) +- [slack_bolt.middleware.async_custom_middleware](/tools/bolt-python/reference/middleware/async_custom_middleware) +- [slack_bolt.middleware.async_middleware](/tools/bolt-python/reference/middleware/async_middleware) +- [slack_bolt.middleware.async_middleware_error_handler](/tools/bolt-python/reference/middleware/async_middleware_error_handler) +- [slack_bolt.middleware.attaching_conversation_kwargs](/tools/bolt-python/reference/middleware/attaching_conversation_kwargs) +- [slack_bolt.middleware.attaching_function_token](/tools/bolt-python/reference/middleware/attaching_function_token) +- [slack_bolt.middleware.authorization](/tools/bolt-python/reference/middleware/authorization) +- [slack_bolt.middleware.custom_middleware](/tools/bolt-python/reference/middleware/custom_middleware) +- [slack_bolt.middleware.ignoring_self_events](/tools/bolt-python/reference/middleware/ignoring_self_events) +- [slack_bolt.middleware.message_listener_matches](/tools/bolt-python/reference/middleware/message_listener_matches) +- [slack_bolt.middleware.middleware](/tools/bolt-python/reference/middleware/middleware) +- [slack_bolt.middleware.middleware_error_handler](/tools/bolt-python/reference/middleware/middleware_error_handler) +- [slack_bolt.middleware.request_verification](/tools/bolt-python/reference/middleware/request_verification) +- [slack_bolt.middleware.ssl_check](/tools/bolt-python/reference/middleware/ssl_check) +- [slack_bolt.middleware.url_verification](/tools/bolt-python/reference/middleware/url_verification) diff --git a/docs/english/reference/middleware/message_listener_matches/async_message_listener_matches.md b/docs/english/reference/middleware/message_listener_matches/async_message_listener_matches.md index 48a06af5e..62ead6881 100644 --- a/docs/english/reference/middleware/message_listener_matches/async_message_listener_matches.md +++ b/docs/english/reference/middleware/message_listener_matches/async_message_listener_matches.md @@ -3,26 +3,20 @@ sidebar_label: async_message_listener_matches title: slack_bolt.middleware.message_listener_matches.async_message_listener_matches --- -## AsyncMessageListenerMatches Objects +## `AsyncMessageListenerMatches` ```python -class AsyncMessageListenerMatches(AsyncMiddleware) +AsyncMessageListenerMatches(keyword) ``` -#### \_\_init\_\_ - -```python -def __init__(keyword: Union[str, Pattern]) -``` +Bases: AsyncMiddleware Captures matched keywords and saves the values in context. -#### async\_process +### `name` ```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse +name: str ``` + +The name of this middleware. diff --git a/docs/english/reference/middleware/message_listener_matches/index.md b/docs/english/reference/middleware/message_listener_matches/index.md index 5e61fb235..ab10a521d 100644 --- a/docs/english/reference/middleware/message_listener_matches/index.md +++ b/docs/english/reference/middleware/message_listener_matches/index.md @@ -3,31 +3,25 @@ sidebar_label: message_listener_matches title: slack_bolt.middleware.message_listener_matches --- -## Submodules - -- [slack_bolt.middleware.message_listener_matches.async_message_listener_matches](/tools/bolt-python/reference/middleware/message_listener_matches/async_message_listener_matches) -- [slack_bolt.middleware.message_listener_matches.message_listener_matches](/tools/bolt-python/reference/middleware/message_listener_matches/message_listener_matches) - -## MessageListenerMatches Objects +## `MessageListenerMatches` ```python -class MessageListenerMatches(Middleware) +MessageListenerMatches(keyword) ``` -#### \_\_init\_\_ - -```python -def __init__(keyword: Union[str, Pattern]) -``` +Bases: Middleware Captures matched keywords and saves the values in context. -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` + +The name of this middleware. + +## Submodules + +- [slack_bolt.middleware.message_listener_matches.async_message_listener_matches](/tools/bolt-python/reference/middleware/message_listener_matches/async_message_listener_matches) +- [slack_bolt.middleware.message_listener_matches.message_listener_matches](/tools/bolt-python/reference/middleware/message_listener_matches/message_listener_matches) diff --git a/docs/english/reference/middleware/message_listener_matches/message_listener_matches.md b/docs/english/reference/middleware/message_listener_matches/message_listener_matches.md index 04536976d..0136441f7 100644 --- a/docs/english/reference/middleware/message_listener_matches/message_listener_matches.md +++ b/docs/english/reference/middleware/message_listener_matches/message_listener_matches.md @@ -4,26 +4,20 @@ title: slack_bolt.middleware.message_listener_matches.message_listener_matches slug: message_listener_matches --- -## MessageListenerMatches Objects +## `MessageListenerMatches` ```python -class MessageListenerMatches(Middleware) +MessageListenerMatches(keyword) ``` -#### \_\_init\_\_ - -```python -def __init__(keyword: Union[str, Pattern]) -``` +Bases: Middleware Captures matched keywords and saves the values in context. -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` + +The name of this middleware. diff --git a/docs/english/reference/middleware/middleware.md b/docs/english/reference/middleware/middleware.md index 39efeca02..e7d1492fb 100644 --- a/docs/english/reference/middleware/middleware.md +++ b/docs/english/reference/middleware/middleware.md @@ -4,22 +4,22 @@ title: slack_bolt.middleware.middleware slug: middleware --- -## Middleware Objects +## `Middleware` + +A middleware can process request data before other middleware and listener functions. + +### `name` ```python -class Middleware() +name: str ``` -A middleware can process request data before other middleware and listener functions. +The name of this middleware. -#### process +### `process` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> Optional[BoltResponse] +process(*, req, resp, next) ``` Processes a request data before other middleware and listeners. @@ -43,22 +43,12 @@ def simple_middleware(req, resp, next_): next_() ``` +**Parameters:** -**Arguments**: - -- `req` _BoltRequest_ - The incoming request -- `resp` _BoltResponse_ - The response -- `next` _Callable[[], BoltResponse]_ - The function to tell the chain that it can continue +- **req** (BoltRequest) – The incoming request +- **resp** (BoltResponse) – The response +- **next** (Callable[[], BoltResponse]) – The function to tell the chain that it can continue -**Returns**: +**Returns:** -- `Optional[BoltResponse]` - Processed response (optional) - -#### name - -```python -@property -def name() -> str -``` - -The name of this middleware. +- Optional[BoltResponse] – Processed response (optional) diff --git a/docs/english/reference/middleware/middleware_error_handler.md b/docs/english/reference/middleware/middleware_error_handler.md index 2cde0622b..06cff6d06 100644 --- a/docs/english/reference/middleware/middleware_error_handler.md +++ b/docs/english/reference/middleware/middleware_error_handler.md @@ -3,61 +3,18 @@ sidebar_label: middleware_error_handler title: slack_bolt.middleware.middleware_error_handler --- -## MiddlewareErrorHandler Objects +## `MiddlewareErrorHandler` -```python -class MiddlewareErrorHandler() -``` - -#### handle +### `handle` ```python -def handle( - error: Exception, - request: BoltRequest, - response: Optional[BoltResponse]) -> None +handle(error, request, response) ``` Handles an unhandled exception. -**Arguments**: - -- `error` _Exception_ - The raised exception. -- `request` _BoltRequest_ - The request. -- `response` _Optional[BoltResponse]_ - The response. - -## CustomMiddlewareErrorHandler Objects - -```python -class CustomMiddlewareErrorHandler(MiddlewareErrorHandler) -``` - -#### \_\_init\_\_ +**Parameters:** -```python -def __init__(logger: Logger, func: Callable[..., Optional[BoltResponse]]) -``` - -#### handle - -```python -def handle(error: Exception, request: BoltRequest, response: Optional[BoltResponse]) -``` - -## DefaultMiddlewareErrorHandler Objects - -```python -class DefaultMiddlewareErrorHandler(MiddlewareErrorHandler) -``` - -#### \_\_init\_\_ - -```python -def __init__(logger: Logger) -``` - -#### handle - -```python -def handle(error: Exception, request: BoltRequest, response: Optional[BoltResponse]) -``` +- **error** (Exception) – The raised exception. +- **request** (BoltRequest) – The request. +- **response** (Optional[BoltResponse]) – The response. diff --git a/docs/english/reference/middleware/request_verification/async_request_verification.md b/docs/english/reference/middleware/request_verification/async_request_verification.md index 0f3286483..8519927d8 100644 --- a/docs/english/reference/middleware/request_verification/async_request_verification.md +++ b/docs/english/reference/middleware/request_verification/async_request_verification.md @@ -3,11 +3,9 @@ sidebar_label: async_request_verification title: slack_bolt.middleware.request_verification.async_request_verification --- -## AsyncRequestVerification Objects +## `AsyncRequestVerification` -```python -class AsyncRequestVerification(RequestVerification, AsyncMiddleware) -``` +Bases: RequestVerification, AsyncMiddleware Verifies an incoming request from Slack. @@ -15,12 +13,10 @@ Checks the validity of `x-slack-signature`, `x-slack-request-timestamp`, and the Refer to https://docs.slack.dev/authentication/verifying-requests-from-slack/ for details. -#### async\_process +### `name` ```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse +name: str ``` + +The name of this middleware. diff --git a/docs/english/reference/middleware/request_verification/index.md b/docs/english/reference/middleware/request_verification/index.md index dc593da96..0403a6039 100644 --- a/docs/english/reference/middleware/request_verification/index.md +++ b/docs/english/reference/middleware/request_verification/index.md @@ -3,22 +3,13 @@ sidebar_label: request_verification title: slack_bolt.middleware.request_verification --- -## Submodules - -- [slack_bolt.middleware.request_verification.async_request_verification](/tools/bolt-python/reference/middleware/request_verification/async_request_verification) -- [slack_bolt.middleware.request_verification.request_verification](/tools/bolt-python/reference/middleware/request_verification/request_verification) - -## RequestVerification Objects +## `RequestVerification` ```python -class RequestVerification(Middleware) +RequestVerification(signing_secret, base_logger=None) ``` -#### \_\_init\_\_ - -```python -def __init__(signing_secret: str, base_logger: Optional[Logger] = None) -``` +Bases: Middleware Verifies an incoming request from Slack. @@ -26,24 +17,20 @@ Checks the validity of `x-slack-signature`, `x-slack-request-timestamp`, and the Refer to https://docs.slack.dev/authentication/verifying-requests-from-slack/ for details. -**Arguments**: +**Parameters:** -- `signing_secret` _str_ - The signing secret -- `base_logger` _Optional[Logger]_ - The base logger +- **signing_secret** (str) – The signing secret +- **base_logger** (Optional[Logger]) – The base logger -#### verifier +### `name` ```python -@property -def verifier() -> SignatureVerifier +name: str ``` -#### process +The name of this middleware. -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse -``` +## Submodules + +- [slack_bolt.middleware.request_verification.async_request_verification](/tools/bolt-python/reference/middleware/request_verification/async_request_verification) +- [slack_bolt.middleware.request_verification.request_verification](/tools/bolt-python/reference/middleware/request_verification/request_verification) diff --git a/docs/english/reference/middleware/request_verification/request_verification.md b/docs/english/reference/middleware/request_verification/request_verification.md index 14c67c06c..fd43a5bb7 100644 --- a/docs/english/reference/middleware/request_verification/request_verification.md +++ b/docs/english/reference/middleware/request_verification/request_verification.md @@ -4,17 +4,13 @@ title: slack_bolt.middleware.request_verification.request_verification slug: request_verification --- -## RequestVerification Objects +## `RequestVerification` ```python -class RequestVerification(Middleware) +RequestVerification(signing_secret, base_logger=None) ``` -#### \_\_init\_\_ - -```python -def __init__(signing_secret: str, base_logger: Optional[Logger] = None) -``` +Bases: Middleware Verifies an incoming request from Slack. @@ -22,24 +18,15 @@ Checks the validity of `x-slack-signature`, `x-slack-request-timestamp`, and the Refer to https://docs.slack.dev/authentication/verifying-requests-from-slack/ for details. -**Arguments**: +**Parameters:** -- `signing_secret` _str_ - The signing secret -- `base_logger` _Optional[Logger]_ - The base logger +- **signing_secret** (str) – The signing secret +- **base_logger** (Optional[Logger]) – The base logger -#### verifier +### `name` ```python -@property -def verifier() -> SignatureVerifier +name: str ``` -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse -``` +The name of this middleware. diff --git a/docs/english/reference/middleware/ssl_check/async_ssl_check.md b/docs/english/reference/middleware/ssl_check/async_ssl_check.md index c6b1ad56a..e5fffa11d 100644 --- a/docs/english/reference/middleware/ssl_check/async_ssl_check.md +++ b/docs/english/reference/middleware/ssl_check/async_ssl_check.md @@ -3,18 +3,4 @@ sidebar_label: async_ssl_check title: slack_bolt.middleware.ssl_check.async_ssl_check --- -## AsyncSslCheck Objects -```python -class AsyncSslCheck(SslCheck, AsyncMiddleware) -``` - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` diff --git a/docs/english/reference/middleware/ssl_check/index.md b/docs/english/reference/middleware/ssl_check/index.md index 99171ad4b..8fa86d585 100644 --- a/docs/english/reference/middleware/ssl_check/index.md +++ b/docs/english/reference/middleware/ssl_check/index.md @@ -3,45 +3,33 @@ sidebar_label: ssl_check title: slack_bolt.middleware.ssl_check --- -## Submodules - -- [slack_bolt.middleware.ssl_check.async_ssl_check](/tools/bolt-python/reference/middleware/ssl_check/async_ssl_check) -- [slack_bolt.middleware.ssl_check.ssl_check](/tools/bolt-python/reference/middleware/ssl_check/ssl_check) - -## SslCheck Objects +## `SslCheck` ```python -class SslCheck(Middleware) +SslCheck(verification_token=None, base_logger=None) ``` -#### verification\_token: `Optional[str]` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__( - verification_token: Optional[str] = None, - base_logger: Optional[Logger] = None) -``` +Bases: Middleware Handles `ssl_check` requests. Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details. -**Arguments**: +**Parameters:** -- `verification_token` _Optional[str]_ - The verification token to check - (optional as it's already deprecated - https://docs.slack.dev/authentication/verifying-requests-from-slack/#deprecation) -- `base_logger` _Optional[Logger]_ - The base logger +- **verification_token** (Optional[str]) – The verification token to check +(optional as it's already deprecated - https://docs.slack.dev/authentication/verifying-requests-from-slack/#deprecation) +- **base_logger** (Optional[Logger]) – The base logger -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` + +The name of this middleware. + +## Submodules + +- [slack_bolt.middleware.ssl_check.async_ssl_check](/tools/bolt-python/reference/middleware/ssl_check/async_ssl_check) +- [slack_bolt.middleware.ssl_check.ssl_check](/tools/bolt-python/reference/middleware/ssl_check/ssl_check) diff --git a/docs/english/reference/middleware/ssl_check/ssl_check.md b/docs/english/reference/middleware/ssl_check/ssl_check.md index b22b8aba1..f8e7f9aca 100644 --- a/docs/english/reference/middleware/ssl_check/ssl_check.md +++ b/docs/english/reference/middleware/ssl_check/ssl_check.md @@ -4,40 +4,28 @@ title: slack_bolt.middleware.ssl_check.ssl_check slug: ssl_check --- -## SslCheck Objects +## `SslCheck` ```python -class SslCheck(Middleware) +SslCheck(verification_token=None, base_logger=None) ``` -#### verification\_token: `Optional[str]` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__( - verification_token: Optional[str] = None, - base_logger: Optional[Logger] = None) -``` +Bases: Middleware Handles `ssl_check` requests. Refer to https://docs.slack.dev/interactivity/implementing-slash-commands/ for details. -**Arguments**: +**Parameters:** -- `verification_token` _Optional[str]_ - The verification token to check - (optional as it's already deprecated - https://docs.slack.dev/authentication/verifying-requests-from-slack/#deprecation) -- `base_logger` _Optional[Logger]_ - The base logger +- **verification_token** (Optional[str]) – The verification token to check +(optional as it's already deprecated - https://docs.slack.dev/authentication/verifying-requests-from-slack/#deprecation) +- **base_logger** (Optional[Logger]) – The base logger -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` + +The name of this middleware. diff --git a/docs/english/reference/middleware/url_verification/async_url_verification.md b/docs/english/reference/middleware/url_verification/async_url_verification.md index f74152f77..760ccf15b 100644 --- a/docs/english/reference/middleware/url_verification/async_url_verification.md +++ b/docs/english/reference/middleware/url_verification/async_url_verification.md @@ -3,24 +3,4 @@ sidebar_label: async_url_verification title: slack_bolt.middleware.url_verification.async_url_verification --- -## AsyncUrlVerification Objects -```python -class AsyncUrlVerification(UrlVerification, AsyncMiddleware) -``` - -#### \_\_init\_\_ - -```python -def __init__(base_logger: Optional[Logger] = None) -``` - -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` diff --git a/docs/english/reference/middleware/url_verification/index.md b/docs/english/reference/middleware/url_verification/index.md index ce2b8bd4f..3eb6ce388 100644 --- a/docs/english/reference/middleware/url_verification/index.md +++ b/docs/english/reference/middleware/url_verification/index.md @@ -3,37 +3,31 @@ sidebar_label: url_verification title: slack_bolt.middleware.url_verification --- -## Submodules - -- [slack_bolt.middleware.url_verification.async_url_verification](/tools/bolt-python/reference/middleware/url_verification/async_url_verification) -- [slack_bolt.middleware.url_verification.url_verification](/tools/bolt-python/reference/middleware/url_verification/url_verification) - -## UrlVerification Objects +## `UrlVerification` ```python -class UrlVerification(Middleware) +UrlVerification(base_logger=None) ``` -#### \_\_init\_\_ - -```python -def __init__(base_logger: Optional[Logger] = None) -``` +Bases: Middleware Handles url_verification requests. Refer to https://docs.slack.dev/reference/events/url_verification/ for details. -**Arguments**: +**Parameters:** -- `base_logger` _Optional[Logger]_ - The base logger +- **base_logger** (Optional[Logger]) – The base logger -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` + +The name of this middleware. + +## Submodules + +- [slack_bolt.middleware.url_verification.async_url_verification](/tools/bolt-python/reference/middleware/url_verification/async_url_verification) +- [slack_bolt.middleware.url_verification.url_verification](/tools/bolt-python/reference/middleware/url_verification/url_verification) diff --git a/docs/english/reference/middleware/url_verification/url_verification.md b/docs/english/reference/middleware/url_verification/url_verification.md index a54d70ba2..76c3a5d13 100644 --- a/docs/english/reference/middleware/url_verification/url_verification.md +++ b/docs/english/reference/middleware/url_verification/url_verification.md @@ -4,32 +4,26 @@ title: slack_bolt.middleware.url_verification.url_verification slug: url_verification --- -## UrlVerification Objects +## `UrlVerification` ```python -class UrlVerification(Middleware) +UrlVerification(base_logger=None) ``` -#### \_\_init\_\_ - -```python -def __init__(base_logger: Optional[Logger] = None) -``` +Bases: Middleware Handles url_verification requests. Refer to https://docs.slack.dev/reference/events/url_verification/ for details. -**Arguments**: +**Parameters:** -- `base_logger` _Optional[Logger]_ - The base logger +- **base_logger** (Optional[Logger]) – The base logger -#### process +### `name` ```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> BoltResponse +name: str ``` + +The name of this middleware. diff --git a/docs/english/reference/oauth/async_callback_options.md b/docs/english/reference/oauth/async_callback_options.md index 344fad325..c62ddf5b8 100644 --- a/docs/english/reference/oauth/async_callback_options.md +++ b/docs/english/reference/oauth/async_callback_options.md @@ -3,96 +3,34 @@ sidebar_label: async_callback_options title: slack_bolt.oauth.async_callback_options --- -## AsyncSuccessArgs Objects +## `AsyncFailureArgs` ```python -class AsyncSuccessArgs() -``` - -#### \_\_init\_\_ - -```python -def __init__( - *, - request: AsyncBoltRequest, - installation: Installation, - settings: AsyncOAuthSettings, - default: AsyncCallbackOptions) -``` - -The arguments for a success function. - -**Arguments**: - -- `request` _AsyncBoltRequest_ - The request. -- `installation` _Installation_ - The installation data. -- `settings` _AsyncOAuthSettings_ - The settings for Slack OAuth flow. -- `default` _AsyncCallbackOptions_ - The default `AsyncCallbackOptions`. - -## AsyncFailureArgs Objects - -```python -class AsyncFailureArgs() -``` - -#### \_\_init\_\_ - -```python -def __init__( - *, - request: AsyncBoltRequest, - reason: str, - error: Optional[Exception] = None, - suggested_status_code: int, - settings: AsyncOAuthSettings, - default: AsyncCallbackOptions) +AsyncFailureArgs(*, request, reason, error=None, suggested_status_code, settings, default) ``` The arguments for a failure function. -**Arguments**: - -- `request` _AsyncBoltRequest_ - The request. -- `reason` _str_ - The response. -- `error` _Optional[Exception]_ - An exception if exists. -- `suggested_status_code` _int_ - The recommended HTTP status code for the failure. -- `settings` _AsyncOAuthSettings_ - The settings for Slack OAuth flow. -- `default` _AsyncCallbackOptions_ - The default `AsyncCallbackOptions`. - -## AsyncCallbackOptions Objects - -```python -class AsyncCallbackOptions() -``` +**Parameters:** -#### success: `Callable[[AsyncSuccessArgs], Awaitable[BoltResponse]]` +- **request** (AsyncBoltRequest) – The request. +- **reason** (str) – The response. +- **error** (Optional[Exception]) – An exception if exists. +- **suggested_status_code** (int) – The recommended HTTP status code for the failure. +- **settings** (AsyncOAuthSettings) – The settings for Slack OAuth flow. +- **default** (AsyncCallbackOptions) – The default `AsyncCallbackOptions`. -#### failure: `Callable[[AsyncFailureArgs], Awaitable[BoltResponse]]` - -#### \_\_init\_\_ +## `AsyncSuccessArgs` ```python -def __init__( - success: Callable[[AsyncSuccessArgs], Awaitable[BoltResponse]], - failure: Callable[[AsyncFailureArgs], Awaitable[BoltResponse]]) +AsyncSuccessArgs(*, request, installation, settings, default) ``` -## DefaultAsyncCallbackOptions Objects - -```python -class DefaultAsyncCallbackOptions(AsyncCallbackOptions) -``` - -#### success: `Callable[[AsyncSuccessArgs], Awaitable[BoltResponse]]` - -#### failure: `Callable[[AsyncFailureArgs], Awaitable[BoltResponse]]` +The arguments for a success function. -#### \_\_init\_\_ +**Parameters:** -```python -def __init__( - *, - logger: Logger, - state_utils: OAuthStateUtils, - redirect_uri_page_renderer: RedirectUriPageRenderer) -``` +- **request** (AsyncBoltRequest) – The request. +- **installation** (Installation) – The installation data. +- **settings** (AsyncOAuthSettings) – The settings for Slack OAuth flow. +- **default** (AsyncCallbackOptions) – The default `AsyncCallbackOptions`. diff --git a/docs/english/reference/oauth/async_internals.md b/docs/english/reference/oauth/async_internals.md index e0e3d5098..0f5f9b135 100644 --- a/docs/english/reference/oauth/async_internals.md +++ b/docs/english/reference/oauth/async_internals.md @@ -3,20 +3,4 @@ sidebar_label: async_internals title: slack_bolt.oauth.async_internals --- -#### default\_installation\_stores: `Dict[str, AsyncInstallationStore]` -#### get\_or\_create\_default\_installation\_store - -```python -def get_or_create_default_installation_store(client_id: str) -> AsyncInstallationStore -``` - -#### select\_consistent\_installation\_store - -```python -def select_consistent_installation_store( - client_id: str, - app_store: Optional[AsyncInstallationStore], - oauth_flow_store: Optional[AsyncInstallationStore], - logger: Logger) -> Optional[AsyncInstallationStore] -``` diff --git a/docs/english/reference/oauth/async_oauth_flow.md b/docs/english/reference/oauth/async_oauth_flow.md index 49c49453d..f9738c2dc 100644 --- a/docs/english/reference/oauth/async_oauth_flow.md +++ b/docs/english/reference/oauth/async_oauth_flow.md @@ -3,125 +3,16 @@ sidebar_label: async_oauth_flow title: slack_bolt.oauth.async_oauth_flow --- -## AsyncOAuthFlow Objects +## `AsyncOAuthFlow` ```python -class AsyncOAuthFlow() -``` - -#### settings: `AsyncOAuthSettings` - -#### client\_id: `str` - -#### redirect\_uri: `Optional[str]` - -#### install\_path: `str` - -#### redirect\_uri\_path: `str` - -#### success\_handler: `Callable[[AsyncSuccessArgs], Awaitable[BoltResponse]]` - -#### failure\_handler: `Callable[[AsyncFailureArgs], Awaitable[BoltResponse]]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - client: Optional[AsyncWebClient] = None, - logger: Optional[Logger] = None, - settings: AsyncOAuthSettings) +AsyncOAuthFlow(*, client=None, logger=None, settings) ``` The module to run the Slack app installation flow (OAuth flow). -**Arguments**: - -- `client` _Optional[AsyncWebClient]_ - The `slack_sdk.web.async_client.AsyncWebClient` instance. -- `logger` _Optional[Logger]_ - The logger. -- `settings` _AsyncOAuthSettings_ - OAuth settings to configure this module. - -#### client - -```python -@property -def client() -> AsyncWebClient -``` - -#### logger - -```python -@property -def logger() -> Logger -``` - -#### sqlite3 - -```python -def sqlite3( - database: str, - authorization_url: Optional[str] = None, - client_id: Optional[str] = None, - client_secret: Optional[str] = None, - scopes: Optional[Sequence[str]] = None, - user_scopes: Optional[Sequence[str]] = None, - redirect_uri: Optional[str] = None, - install_path: Optional[str] = None, - redirect_uri_path: Optional[str] = None, - callback_options: Optional[AsyncCallbackOptions] = None, - success_url: Optional[str] = None, - failure_url: Optional[str] = None, - state_cookie_name: str = OAuthStateUtils.default_cookie_name, - state_expiration_seconds: int = OAuthStateUtils.default_expiration_seconds, - installation_store_bot_only: bool = False, - client: Optional[AsyncWebClient] = None, - logger: Optional[Logger] = None) -> AsyncOAuthFlow -``` - -#### handle\_installation - -```python -async def handle_installation(request: AsyncBoltRequest) -> BoltResponse -``` +**Parameters:** -#### issue\_new\_state - -```python -async def issue_new_state(request: AsyncBoltRequest) -> str -``` - -#### build\_authorize\_url - -```python -async def build_authorize_url(state: str, request: AsyncBoltRequest) -> str -``` - -#### build\_install\_page\_html - -```python -async def build_install_page_html(url: str, request: AsyncBoltRequest) -> str -``` - -#### append\_set\_cookie\_headers - -```python -async def append_set_cookie_headers(headers: dict, set_cookie_value: Optional[str]) -``` - -#### handle\_callback - -```python -async def handle_callback(request: AsyncBoltRequest) -> BoltResponse -``` - -#### run\_installation - -```python -async def run_installation(code: str) -> Optional[Installation] -``` - -#### store\_installation - -```python -async def store_installation(request: AsyncBoltRequest, installation: Installation) -``` +- **client** (Optional[AsyncWebClient]) – The `slack_sdk.web.async_client.AsyncWebClient` instance. +- **logger** (Optional[Logger]) – The logger. +- **settings** (AsyncOAuthSettings) – OAuth settings to configure this module. diff --git a/docs/english/reference/oauth/async_oauth_settings.md b/docs/english/reference/oauth/async_oauth_settings.md index fca5fd18f..79f6fad7d 100644 --- a/docs/english/reference/oauth/async_oauth_settings.md +++ b/docs/english/reference/oauth/async_oauth_settings.md @@ -3,116 +3,38 @@ sidebar_label: async_oauth_settings title: slack_bolt.oauth.async_oauth_settings --- -## AsyncOAuthSettings Objects +## `AsyncOAuthSettings` ```python -class AsyncOAuthSettings() -``` - -#### client\_id: `str` - -#### client\_secret: `str` - -#### scopes: `Optional[Sequence[str]]` - -#### user\_scopes: `Optional[Sequence[str]]` - -#### redirect\_uri: `Optional[str]` - -#### install\_path: `str` - -#### install\_page\_rendering\_enabled: `bool` - -#### redirect\_uri\_path: `str` - -#### callback\_options: `Optional[AsyncCallbackOptions]` - -#### success\_url: `Optional[str]` - -#### failure\_url: `Optional[str]` - -#### authorization\_url: `str` - -#### installation\_store: `AsyncInstallationStore` - -#### installation\_store\_bot\_only: `bool` - -#### token\_rotation\_expiration\_minutes: `int` - -#### user\_token\_resolution: `str` - -#### authorize: `AsyncAuthorize` - -#### state\_validation\_enabled: `bool` - -#### state\_store: `AsyncOAuthStateStore` - -#### state\_cookie\_name: `str` - -#### state\_expiration\_seconds: `int` - -#### state\_utils: `OAuthStateUtils` - -#### authorize\_url\_generator: `AuthorizeUrlGenerator` - -#### redirect\_uri\_page\_renderer: `RedirectUriPageRenderer` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__( - *, - client_id: Optional[str] = None, - client_secret: Optional[str] = None, - scopes: Optional[Union[Sequence[str], str]] = None, - user_scopes: Optional[Union[Sequence[str], str]] = None, - redirect_uri: Optional[str] = None, - install_path: str = '/slack/install', - install_page_rendering_enabled: bool = True, - redirect_uri_path: str = '/slack/oauth_redirect', - callback_options: Optional[AsyncCallbackOptions] = None, - success_url: Optional[str] = None, - failure_url: Optional[str] = None, - authorization_url: Optional[str] = None, - installation_store: Optional[AsyncInstallationStore] = None, - installation_store_bot_only: bool = False, - token_rotation_expiration_minutes: int = 120, - user_token_resolution: str = 'authed_user', - state_validation_enabled: bool = True, - state_store: Optional[AsyncOAuthStateStore] = None, - state_cookie_name: str = OAuthStateUtils.default_cookie_name, - state_expiration_seconds: int = OAuthStateUtils.default_expiration_seconds, - logger: Logger = logging.getLogger(__name__)) +AsyncOAuthSettings(*, client_id=None, client_secret=None, scopes=None, user_scopes=None, redirect_uri=None, install_path='/slack/install', install_page_rendering_enabled=True, redirect_uri_path='/slack/oauth_redirect', callback_options=None, success_url=None, failure_url=None, authorization_url=None, installation_store=None, installation_store_bot_only=False, token_rotation_expiration_minutes=120, user_token_resolution='authed_user', state_validation_enabled=True, state_store=None, state_cookie_name=OAuthStateUtils.default_cookie_name, state_expiration_seconds=OAuthStateUtils.default_expiration_seconds, logger=logging.getLogger(__name__)) ``` The settings for Slack App installation (OAuth flow). -**Arguments**: - -- `client_id` _Optional[str]_ - Check the value in Settings > Basic Information > App Credentials -- `client_secret` _Optional[str]_ - Check the value in Settings > Basic Information > App Credentials -- `scopes` _Optional[Union[Sequence[str], str]]_ - Check the value in Settings > Manage Distribution -- `user_scopes` _Optional[Union[Sequence[str], str]]_ - Check the value in Settings > Manage Distribution -- `redirect_uri` _Optional[str]_ - Check the value in Features > OAuth & Permissions > Redirect URLs -- `install_path` _str_ - The endpoint to start an OAuth flow (Default: `/slack/install`) -- `install_page_rendering_enabled` _bool_ - Renders a web page for install_path access if True -- `redirect_uri_path` _str_ - The path of Redirect URL (Default: `/slack/oauth_redirect`) -- `callback_options` _Optional[AsyncCallbackOptions]_ - Give success/failure functions f you want to customize callback functions. -- `success_url` _Optional[str]_ - Set a complete URL if you want to redirect end-users when an installation completes. -- `failure_url` _Optional[str]_ - Set a complete URL if you want to redirect end-users when an installation fails. -- `authorization_url` _Optional[str]_ - Set a URL if you want to customize the URL `https://slack.com/oauth/v2/authorize` -- `installation_store` _Optional[AsyncInstallationStore]_ - Specify the instance of `InstallationStore` (Default: `FileInstallationStore`) -- `installation_store_bot_only` _bool_ - Use `InstallationStore#find_bot()` if True (Default: False) -- `token_rotation_expiration_minutes` _int_ - Minutes before refreshing tokens (Default: 2 hours) -- `user_token_resolution` _str_ - The option to pick up a user token per request (Default: authed_user) - The available values are "authed_user" and "actor". When you want to resolve the user token per request - using the event's actor IDs, you can set "actor" instead. With this option, bolt-python tries to resolve - a user token for context.actor_enterprise/team/user_id. This can be useful for events in Slack Connect - channels. Note that actor IDs can be absent in some scenarios. -- `state_validation_enabled` _bool_ - Set False if your OAuth flow omits the state parameter validation (Default: True) -- `state_store` _Optional[AsyncOAuthStateStore]_ - Specify the instance of `InstallationStore` (Default: `FileOAuthStateStore`) -- `state_cookie_name` _str_ - The cookie name that is set for installers' browser. (Default: "slack-app-oauth-state") -- `state_expiration_seconds` _int_ - The seconds that the state value is alive (Default: 600 seconds) -- `logger` _Logger_ - The logger that will be used internally +**Parameters:** + +- **client_id** (Optional[str]) – Check the value in Settings > Basic Information > App Credentials +- **client_secret** (Optional[str]) – Check the value in Settings > Basic Information > App Credentials +- **scopes** (Optional[Union[Sequence[str], str]]) – Check the value in Settings > Manage Distribution +- **user_scopes** (Optional[Union[Sequence[str], str]]) – Check the value in Settings > Manage Distribution +- **redirect_uri** (Optional[str]) – Check the value in Features > OAuth & Permissions > Redirect URLs +- **install_path** (str) – The endpoint to start an OAuth flow (Default: `/slack/install`) +- **install_page_rendering_enabled** (bool) – Renders a web page for install_path access if True +- **redirect_uri_path** (str) – The path of Redirect URL (Default: `/slack/oauth_redirect`) +- **callback_options** (Optional[AsyncCallbackOptions]) – Give success/failure functions f you want to customize callback functions. +- **success_url** (Optional[str]) – Set a complete URL if you want to redirect end-users when an installation completes. +- **failure_url** (Optional[str]) – Set a complete URL if you want to redirect end-users when an installation fails. +- **authorization_url** (Optional[str]) – Set a URL if you want to customize the URL `https://slack.com/oauth/v2/authorize` +- **installation_store** (Optional[AsyncInstallationStore]) – Specify the instance of `InstallationStore` (Default: `FileInstallationStore`) +- **installation_store_bot_only** (bool) – Use `InstallationStore#find_bot()` if True (Default: False) +- **token_rotation_expiration_minutes** (int) – Minutes before refreshing tokens (Default: 2 hours) +- **user_token_resolution** (str) – The option to pick up a user token per request (Default: authed_user) +The available values are "authed_user" and "actor". When you want to resolve the user token per request +using the event's actor IDs, you can set "actor" instead. With this option, bolt-python tries to resolve +a user token for context.actor_enterprise/team/user_id. This can be useful for events in Slack Connect +channels. Note that actor IDs can be absent in some scenarios. +- **state_validation_enabled** (bool) – Set False if your OAuth flow omits the state parameter validation (Default: True) +- **state_store** (Optional[AsyncOAuthStateStore]) – Specify the instance of `InstallationStore` (Default: `FileOAuthStateStore`) +- **state_cookie_name** (str) – The cookie name that is set for installers' browser. (Default: "slack-app-oauth-state") +- **state_expiration_seconds** (int) – The seconds that the state value is alive (Default: 600 seconds) +- **logger** (Logger) – The logger that will be used internally diff --git a/docs/english/reference/oauth/callback_options.md b/docs/english/reference/oauth/callback_options.md index 44ff7fcbb..5072779af 100644 --- a/docs/english/reference/oauth/callback_options.md +++ b/docs/english/reference/oauth/callback_options.md @@ -3,103 +3,47 @@ sidebar_label: callback_options title: slack_bolt.oauth.callback_options --- -## SuccessArgs Objects +## `CallbackOptions` ```python -class SuccessArgs() +CallbackOptions(success, failure) ``` -#### \_\_init\_\_ - -```python -def __init__( - *, - request: BoltRequest, - installation: Installation, - settings: OAuthSettings, - default: CallbackOptions) -``` - -The arguments for a success function. - -**Arguments**: - -- `request` _BoltRequest_ - The request. -- `installation` _Installation_ - The installation data. -- `settings` _OAuthSettings_ - The settings for Slack OAuth flow. -- `default` _CallbackOptions_ - The default `CallbackOptions` +The configurations for OAuth flow. -## FailureArgs Objects +**Parameters:** -```python -class FailureArgs() -``` +- **success** (Callable[[SuccessArgs], BoltResponse]) – A handler for successful installation. +- **failure** (Callable[[FailureArgs], BoltResponse]) – A handler for any types of installation failures. -#### \_\_init\_\_ +## `FailureArgs` ```python -def __init__( - *, - request: BoltRequest, - reason: str, - error: Optional[Exception] = None, - suggested_status_code: int, - settings: OAuthSettings, - default: CallbackOptions) +FailureArgs(*, request, reason, error=None, suggested_status_code, settings, default) ``` The arguments for a failure function. -**Arguments**: - -- `request` _BoltRequest_ - The request. -- `reason` _str_ - The response. -- `error` _Optional[Exception]_ - An exception if exists. -- `suggested_status_code` _int_ - The recommended HTTP status code for the failure. -- `settings` _OAuthSettings_ - The settings for Slack OAuth flow. -- `default` _CallbackOptions_ - The default `CallbackOptions`. - -## CallbackOptions Objects - -```python -class CallbackOptions() -``` - -#### success: `Callable[[SuccessArgs], BoltResponse]` - -#### failure: `Callable[[FailureArgs], BoltResponse]` - -#### \_\_init\_\_ - -```python -def __init__( - success: Callable[[SuccessArgs], BoltResponse], - failure: Callable[[FailureArgs], BoltResponse]) -``` - -The configurations for OAuth flow. - -**Arguments**: +**Parameters:** -- `success` _Callable[[SuccessArgs], BoltResponse]_ - A handler for successful installation. -- `failure` _Callable[[FailureArgs], BoltResponse]_ - A handler for any types of installation failures. +- **request** (BoltRequest) – The request. +- **reason** (str) – The response. +- **error** (Optional[Exception]) – An exception if exists. +- **suggested_status_code** (int) – The recommended HTTP status code for the failure. +- **settings** (OAuthSettings) – The settings for Slack OAuth flow. +- **default** (CallbackOptions) – The default `CallbackOptions`. -## DefaultCallbackOptions Objects +## `SuccessArgs` ```python -class DefaultCallbackOptions(CallbackOptions) +SuccessArgs(*, request, installation, settings, default) ``` -#### success: `Callable[[SuccessArgs], BoltResponse]` - -#### failure: `Callable[[FailureArgs], BoltResponse]` +The arguments for a success function. -#### \_\_init\_\_ +**Parameters:** -```python -def __init__( - *, - logger: Logger, - state_utils: OAuthStateUtils, - redirect_uri_page_renderer: RedirectUriPageRenderer) -``` +- **request** (BoltRequest) – The request. +- **installation** (Installation) – The installation data. +- **settings** (OAuthSettings) – The settings for Slack OAuth flow. +- **default** (CallbackOptions) – The default `CallbackOptions` diff --git a/docs/english/reference/oauth/index.md b/docs/english/reference/oauth/index.md index 29fa841a6..816ac48b7 100644 --- a/docs/english/reference/oauth/index.md +++ b/docs/english/reference/oauth/index.md @@ -7,6 +7,20 @@ Slack OAuth flow support for building an app that is installable in any workspac Refer to https://docs.slack.dev/tools/bolt-python/concepts/authenticating-oauth for details. +## `OAuthFlow` + +```python +OAuthFlow(*, client=None, logger=None, settings) +``` + +The module to run the Slack app installation flow (OAuth flow). + +**Parameters:** + +- **client** (Optional[WebClient]) – The `slack_sdk.web.WebClient` instance. +- **logger** (Optional[Logger]) – The logger. +- **settings** (OAuthSettings) – OAuth settings to configure this module. + ## Submodules - [slack_bolt.oauth.async_callback_options](/tools/bolt-python/reference/oauth/async_callback_options) @@ -17,127 +31,3 @@ Refer to https://docs.slack.dev/tools/bolt-python/concepts/authenticating-oauth - [slack_bolt.oauth.internals](/tools/bolt-python/reference/oauth/internals) - [slack_bolt.oauth.oauth_flow](/tools/bolt-python/reference/oauth/oauth_flow) - [slack_bolt.oauth.oauth_settings](/tools/bolt-python/reference/oauth/oauth_settings) - -## OAuthFlow Objects - -```python -class OAuthFlow() -``` - -#### settings: `OAuthSettings` - -#### client\_id: `str` - -#### redirect\_uri: `Optional[str]` - -#### install\_path: `str` - -#### redirect\_uri\_path: `str` - -#### success\_handler: `Callable[[SuccessArgs], BoltResponse]` - -#### failure\_handler: `Callable[[FailureArgs], BoltResponse]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - client: Optional[WebClient] = None, - logger: Optional[Logger] = None, - settings: OAuthSettings) -``` - -The module to run the Slack app installation flow (OAuth flow). - -**Arguments**: - -- `client` _Optional[WebClient]_ - The `slack_sdk.web.WebClient` instance. -- `logger` _Optional[Logger]_ - The logger. -- `settings` _OAuthSettings_ - OAuth settings to configure this module. - -#### client - -```python -@property -def client() -> WebClient -``` - -#### logger - -```python -@property -def logger() -> Logger -``` - -#### sqlite3 - -```python -def sqlite3( - database: str, - client_id: Optional[str] = None, - client_secret: Optional[str] = None, - scopes: Optional[Sequence[str]] = None, - user_scopes: Optional[Sequence[str]] = None, - redirect_uri: Optional[str] = None, - install_path: Optional[str] = None, - redirect_uri_path: Optional[str] = None, - callback_options: Optional[CallbackOptions] = None, - success_url: Optional[str] = None, - failure_url: Optional[str] = None, - authorization_url: Optional[str] = None, - state_cookie_name: str = OAuthStateUtils.default_cookie_name, - state_expiration_seconds: int = OAuthStateUtils.default_expiration_seconds, - installation_store_bot_only: bool = False, - token_rotation_expiration_minutes: int = 120, - client: Optional[WebClient] = None, - logger: Optional[Logger] = None) -> OAuthFlow -``` - -#### handle\_installation - -```python -def handle_installation(request: BoltRequest) -> BoltResponse -``` - -#### issue\_new\_state - -```python -def issue_new_state(request: BoltRequest) -> str -``` - -#### build\_authorize\_url - -```python -def build_authorize_url(state: str, request: BoltRequest) -> str -``` - -#### build\_install\_page\_html - -```python -def build_install_page_html(url: str, request: BoltRequest) -> str -``` - -#### append\_set\_cookie\_headers - -```python -def append_set_cookie_headers(headers: dict, set_cookie_value: Optional[str]) -``` - -#### handle\_callback - -```python -def handle_callback(request: BoltRequest) -> BoltResponse -``` - -#### run\_installation - -```python -def run_installation(code: str) -> Optional[Installation] -``` - -#### store\_installation - -```python -def store_installation(request: BoltRequest, installation: Installation) -``` diff --git a/docs/english/reference/oauth/internals.md b/docs/english/reference/oauth/internals.md index 34c9fc7ce..88068945f 100644 --- a/docs/english/reference/oauth/internals.md +++ b/docs/english/reference/oauth/internals.md @@ -3,42 +3,4 @@ sidebar_label: internals title: slack_bolt.oauth.internals --- -## CallbackResponseBuilder Objects -```python -class CallbackResponseBuilder() -``` - -#### \_\_init\_\_ - -```python -def __init__( - *, - logger: Logger, - state_utils: OAuthStateUtils, - redirect_uri_page_renderer: RedirectUriPageRenderer) -``` - -#### default\_installation\_stores: `Dict[str, InstallationStore]` - -#### get\_or\_create\_default\_installation\_store - -```python -def get_or_create_default_installation_store(client_id: str) -> InstallationStore -``` - -#### select\_consistent\_installation\_store - -```python -def select_consistent_installation_store( - client_id: str, - app_store: Optional[InstallationStore], - oauth_flow_store: Optional[InstallationStore], - logger: Logger) -> Optional[InstallationStore] -``` - -#### build\_detailed\_error - -```python -def build_detailed_error(reason: str) -> str -``` diff --git a/docs/english/reference/oauth/oauth_flow.md b/docs/english/reference/oauth/oauth_flow.md index 76e74b02d..897dce1ca 100644 --- a/docs/english/reference/oauth/oauth_flow.md +++ b/docs/english/reference/oauth/oauth_flow.md @@ -3,126 +3,16 @@ sidebar_label: oauth_flow title: slack_bolt.oauth.oauth_flow --- -## OAuthFlow Objects +## `OAuthFlow` ```python -class OAuthFlow() -``` - -#### settings: `OAuthSettings` - -#### client\_id: `str` - -#### redirect\_uri: `Optional[str]` - -#### install\_path: `str` - -#### redirect\_uri\_path: `str` - -#### success\_handler: `Callable[[SuccessArgs], BoltResponse]` - -#### failure\_handler: `Callable[[FailureArgs], BoltResponse]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - client: Optional[WebClient] = None, - logger: Optional[Logger] = None, - settings: OAuthSettings) +OAuthFlow(*, client=None, logger=None, settings) ``` The module to run the Slack app installation flow (OAuth flow). -**Arguments**: - -- `client` _Optional[WebClient]_ - The `slack_sdk.web.WebClient` instance. -- `logger` _Optional[Logger]_ - The logger. -- `settings` _OAuthSettings_ - OAuth settings to configure this module. - -#### client - -```python -@property -def client() -> WebClient -``` - -#### logger - -```python -@property -def logger() -> Logger -``` - -#### sqlite3 - -```python -def sqlite3( - database: str, - client_id: Optional[str] = None, - client_secret: Optional[str] = None, - scopes: Optional[Sequence[str]] = None, - user_scopes: Optional[Sequence[str]] = None, - redirect_uri: Optional[str] = None, - install_path: Optional[str] = None, - redirect_uri_path: Optional[str] = None, - callback_options: Optional[CallbackOptions] = None, - success_url: Optional[str] = None, - failure_url: Optional[str] = None, - authorization_url: Optional[str] = None, - state_cookie_name: str = OAuthStateUtils.default_cookie_name, - state_expiration_seconds: int = OAuthStateUtils.default_expiration_seconds, - installation_store_bot_only: bool = False, - token_rotation_expiration_minutes: int = 120, - client: Optional[WebClient] = None, - logger: Optional[Logger] = None) -> OAuthFlow -``` - -#### handle\_installation - -```python -def handle_installation(request: BoltRequest) -> BoltResponse -``` +**Parameters:** -#### issue\_new\_state - -```python -def issue_new_state(request: BoltRequest) -> str -``` - -#### build\_authorize\_url - -```python -def build_authorize_url(state: str, request: BoltRequest) -> str -``` - -#### build\_install\_page\_html - -```python -def build_install_page_html(url: str, request: BoltRequest) -> str -``` - -#### append\_set\_cookie\_headers - -```python -def append_set_cookie_headers(headers: dict, set_cookie_value: Optional[str]) -``` - -#### handle\_callback - -```python -def handle_callback(request: BoltRequest) -> BoltResponse -``` - -#### run\_installation - -```python -def run_installation(code: str) -> Optional[Installation] -``` - -#### store\_installation - -```python -def store_installation(request: BoltRequest, installation: Installation) -``` +- **client** (Optional[WebClient]) – The `slack_sdk.web.WebClient` instance. +- **logger** (Optional[Logger]) – The logger. +- **settings** (OAuthSettings) – OAuth settings to configure this module. diff --git a/docs/english/reference/oauth/oauth_settings.md b/docs/english/reference/oauth/oauth_settings.md index 3f2793041..c6088e5ea 100644 --- a/docs/english/reference/oauth/oauth_settings.md +++ b/docs/english/reference/oauth/oauth_settings.md @@ -3,116 +3,38 @@ sidebar_label: oauth_settings title: slack_bolt.oauth.oauth_settings --- -## OAuthSettings Objects +## `OAuthSettings` ```python -class OAuthSettings() -``` - -#### client\_id: `str` - -#### client\_secret: `str` - -#### scopes: `Optional[Sequence[str]]` - -#### user\_scopes: `Optional[Sequence[str]]` - -#### redirect\_uri: `Optional[str]` - -#### install\_path: `str` - -#### install\_page\_rendering\_enabled: `bool` - -#### redirect\_uri\_path: `str` - -#### callback\_options: `Optional[CallbackOptions]` - -#### success\_url: `Optional[str]` - -#### failure\_url: `Optional[str]` - -#### authorization\_url: `str` - -#### installation\_store: `InstallationStore` - -#### installation\_store\_bot\_only: `bool` - -#### token\_rotation\_expiration\_minutes: `int` - -#### authorize: `Authorize` - -#### user\_token\_resolution: `str` - -#### state\_validation\_enabled: `bool` - -#### state\_store: `OAuthStateStore` - -#### state\_cookie\_name: `str` - -#### state\_expiration\_seconds: `int` - -#### state\_utils: `OAuthStateUtils` - -#### authorize\_url\_generator: `AuthorizeUrlGenerator` - -#### redirect\_uri\_page\_renderer: `RedirectUriPageRenderer` - -#### logger: `Logger` - -#### \_\_init\_\_ - -```python -def __init__( - *, - client_id: Optional[str] = None, - client_secret: Optional[str] = None, - scopes: Optional[Union[Sequence[str], str]] = None, - user_scopes: Optional[Union[Sequence[str], str]] = None, - redirect_uri: Optional[str] = None, - install_path: str = '/slack/install', - install_page_rendering_enabled: bool = True, - redirect_uri_path: str = '/slack/oauth_redirect', - callback_options: Optional[CallbackOptions] = None, - success_url: Optional[str] = None, - failure_url: Optional[str] = None, - authorization_url: Optional[str] = None, - installation_store: Optional[InstallationStore] = None, - installation_store_bot_only: bool = False, - token_rotation_expiration_minutes: int = 120, - user_token_resolution: str = 'authed_user', - state_validation_enabled: bool = True, - state_store: Optional[OAuthStateStore] = None, - state_cookie_name: str = OAuthStateUtils.default_cookie_name, - state_expiration_seconds: int = OAuthStateUtils.default_expiration_seconds, - logger: Logger = logging.getLogger(__name__)) +OAuthSettings(*, client_id=None, client_secret=None, scopes=None, user_scopes=None, redirect_uri=None, install_path='/slack/install', install_page_rendering_enabled=True, redirect_uri_path='/slack/oauth_redirect', callback_options=None, success_url=None, failure_url=None, authorization_url=None, installation_store=None, installation_store_bot_only=False, token_rotation_expiration_minutes=120, user_token_resolution='authed_user', state_validation_enabled=True, state_store=None, state_cookie_name=OAuthStateUtils.default_cookie_name, state_expiration_seconds=OAuthStateUtils.default_expiration_seconds, logger=logging.getLogger(__name__)) ``` The settings for Slack App installation (OAuth flow). -**Arguments**: - -- `client_id` _Optional[str]_ - Check the value in Settings > Basic Information > App Credentials -- `client_secret` _Optional[str]_ - Check the value in Settings > Basic Information > App Credentials -- `scopes` _Optional[Union[Sequence[str], str]]_ - Check the value in Settings > Manage Distribution -- `user_scopes` _Optional[Union[Sequence[str], str]]_ - Check the value in Settings > Manage Distribution -- `redirect_uri` _Optional[str]_ - Check the value in Features > OAuth & Permissions > Redirect URLs -- `install_path` _str_ - The endpoint to start an OAuth flow (Default: `/slack/install`) -- `install_page_rendering_enabled` _bool_ - Renders a web page for install_path access if True -- `redirect_uri_path` _str_ - The path of Redirect URL (Default: `/slack/oauth_redirect`) -- `callback_options` _Optional[CallbackOptions]_ - Give success/failure functions f you want to customize callback functions. -- `success_url` _Optional[str]_ - Set a complete URL if you want to redirect end-users when an installation completes. -- `failure_url` _Optional[str]_ - Set a complete URL if you want to redirect end-users when an installation fails. -- `authorization_url` _Optional[str]_ - Set a URL if you want to customize the URL `https://slack.com/oauth/v2/authorize` -- `installation_store` _Optional[InstallationStore]_ - Specify the instance of `InstallationStore` (Default: `FileInstallationStore`) -- `installation_store_bot_only` _bool_ - Use `InstallationStore#find_bot()` if True (Default: False) -- `token_rotation_expiration_minutes` _int_ - Minutes before refreshing tokens (Default: 2 hours) -- `user_token_resolution` _str_ - The option to pick up a user token per request (Default: authed_user) - The available values are "authed_user" and "actor". When you want to resolve the user token per request - using the event's actor IDs, you can set "actor" instead. With this option, bolt-python tries to resolve - a user token for context.actor_enterprise/team/user_id. This can be useful for events in Slack Connect - channels. Note that actor IDs can be absent in some scenarios. -- `state_validation_enabled` _bool_ - Set False if your OAuth flow omits the state parameter validation (Default: True) -- `state_store` _Optional[OAuthStateStore]_ - Specify the instance of `InstallationStore` (Default: `FileOAuthStateStore`) -- `state_cookie_name` _str_ - The cookie name that is set for installers' browser. (Default: "slack-app-oauth-state") -- `state_expiration_seconds` _int_ - The seconds that the state value is alive (Default: 600 seconds) -- `logger` _Logger_ - The logger that will be used internally +**Parameters:** + +- **client_id** (Optional[str]) – Check the value in Settings > Basic Information > App Credentials +- **client_secret** (Optional[str]) – Check the value in Settings > Basic Information > App Credentials +- **scopes** (Optional[Union[Sequence[str], str]]) – Check the value in Settings > Manage Distribution +- **user_scopes** (Optional[Union[Sequence[str], str]]) – Check the value in Settings > Manage Distribution +- **redirect_uri** (Optional[str]) – Check the value in Features > OAuth & Permissions > Redirect URLs +- **install_path** (str) – The endpoint to start an OAuth flow (Default: `/slack/install`) +- **install_page_rendering_enabled** (bool) – Renders a web page for install_path access if True +- **redirect_uri_path** (str) – The path of Redirect URL (Default: `/slack/oauth_redirect`) +- **callback_options** (Optional[CallbackOptions]) – Give success/failure functions f you want to customize callback functions. +- **success_url** (Optional[str]) – Set a complete URL if you want to redirect end-users when an installation completes. +- **failure_url** (Optional[str]) – Set a complete URL if you want to redirect end-users when an installation fails. +- **authorization_url** (Optional[str]) – Set a URL if you want to customize the URL `https://slack.com/oauth/v2/authorize` +- **installation_store** (Optional[InstallationStore]) – Specify the instance of `InstallationStore` (Default: `FileInstallationStore`) +- **installation_store_bot_only** (bool) – Use `InstallationStore#find_bot()` if True (Default: False) +- **token_rotation_expiration_minutes** (int) – Minutes before refreshing tokens (Default: 2 hours) +- **user_token_resolution** (str) – The option to pick up a user token per request (Default: authed_user) +The available values are "authed_user" and "actor". When you want to resolve the user token per request +using the event's actor IDs, you can set "actor" instead. With this option, bolt-python tries to resolve +a user token for context.actor_enterprise/team/user_id. This can be useful for events in Slack Connect +channels. Note that actor IDs can be absent in some scenarios. +- **state_validation_enabled** (bool) – Set False if your OAuth flow omits the state parameter validation (Default: True) +- **state_store** (Optional[OAuthStateStore]) – Specify the instance of `InstallationStore` (Default: `FileOAuthStateStore`) +- **state_cookie_name** (str) – The cookie name that is set for installers' browser. (Default: "slack-app-oauth-state") +- **state_expiration_seconds** (int) – The seconds that the state value is alive (Default: 600 seconds) +- **logger** (Logger) – The logger that will be used internally diff --git a/docs/english/reference/request/async_internals.md b/docs/english/reference/request/async_internals.md index 9bc9262d6..eb9a039c2 100644 --- a/docs/english/reference/request/async_internals.md +++ b/docs/english/reference/request/async_internals.md @@ -3,10 +3,4 @@ sidebar_label: async_internals title: slack_bolt.request.async_internals --- -#### build\_async\_context -```python -def build_async_context( - context: AsyncBoltContext, - body: Dict[str, Any]) -> AsyncBoltContext -``` diff --git a/docs/english/reference/request/async_request.md b/docs/english/reference/request/async_request.md index 5c5944970..55b2b2604 100644 --- a/docs/english/reference/request/async_request.md +++ b/docs/english/reference/request/async_request.md @@ -3,54 +3,18 @@ sidebar_label: async_request title: slack_bolt.request.async_request --- -## AsyncBoltRequest Objects +## `AsyncBoltRequest` ```python -class AsyncBoltRequest() -``` - -#### raw\_body: `str` - -#### body: `Dict[str, Any]` - -#### query: `Dict[str, Sequence[str]]` - -#### headers: `Dict[str, Sequence[str]]` - -#### content\_type: `Optional[str]` - -#### context: `AsyncBoltContext` - -#### lazy\_only: `bool` - -#### lazy\_function\_name: `Optional[str]` - -#### mode: `str` - -#### \_\_init\_\_ - -```python -def __init__( - *, - body: Union[str, dict], - query: Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]] = None, - headers: Optional[Dict[str, Union[str, Sequence[str]]]] = None, - context: Optional[Dict[str, Any]] = None, - mode: str = 'http') +AsyncBoltRequest(*, body, query=None, headers=None, context=None, mode='http') ``` Request to a Bolt app. -**Arguments**: +**Parameters:** -- `body` _Union[str, dict]_ - The raw request body (only plain text is supported for "http" mode) -- `query` _Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]_ - The query string data in any data format. -- `headers` _Optional[Dict[str, Union[str, Sequence[str]]]]_ - The request headers. -- `context` _Optional[Dict[str, Any]]_ - The context in this request. -- `mode` _str_ - The mode used for this request. (either "http" or "socket_mode") - -#### to\_copyable - -```python -def to_copyable() -> AsyncBoltRequest -``` +- **body** (Union[str, dict]) – The raw request body (only plain text is supported for "http" mode) +- **query** (Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]) – The query string data in any data format. +- **headers** (Optional[Dict[str, Union[str, Sequence[str]]]]) – The request headers. +- **context** (Optional[Dict[str, Any]]) – The context in this request. +- **mode** (str) – The mode used for this request. (either "http" or "socket_mode") diff --git a/docs/english/reference/request/index.md b/docs/english/reference/request/index.md index 2a3e6d251..bfeeab5dd 100644 --- a/docs/english/reference/request/index.md +++ b/docs/english/reference/request/index.md @@ -8,62 +8,26 @@ Incoming request from Slack through either HTTP request or Socket Mode connectio Refer to https://docs.slack.dev/apis/events-api/ for the two types of connections. This interface encapsulates the difference between the two. -## Submodules - -- [slack_bolt.request.async_internals](/tools/bolt-python/reference/request/async_internals) -- [slack_bolt.request.async_request](/tools/bolt-python/reference/request/async_request) -- [slack_bolt.request.internals](/tools/bolt-python/reference/request/internals) -- [slack_bolt.request.payload_utils](/tools/bolt-python/reference/request/payload_utils) -- [slack_bolt.request.request](/tools/bolt-python/reference/request/request) - -## BoltRequest Objects +## `BoltRequest` ```python -class BoltRequest() -``` - -#### raw\_body: `str` - -#### query: `Dict[str, Sequence[str]]` - -#### headers: `Dict[str, Sequence[str]]` - -#### content\_type: `Optional[str]` - -#### body: `Dict[str, Any]` - -#### context: `BoltContext` - -#### lazy\_only: `bool` - -#### lazy\_function\_name: `Optional[str]` - -#### mode: `str` - -#### \_\_init\_\_ - -```python -def __init__( - *, - body: Union[str, dict], - query: Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]] = None, - headers: Optional[Dict[str, Union[str, Sequence[str]]]] = None, - context: Optional[Dict[str, Any]] = None, - mode: str = 'http') +BoltRequest(*, body, query=None, headers=None, context=None, mode='http') ``` Request to a Bolt app. -**Arguments**: +**Parameters:** -- `body` _Union[str, dict]_ - The raw request body (only plain text is supported for "http" mode) -- `query` _Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]_ - The query string data in any data format. -- `headers` _Optional[Dict[str, Union[str, Sequence[str]]]]_ - The request headers. -- `context` _Optional[Dict[str, Any]]_ - The context in this request. -- `mode` _str_ - The mode used for this request. (either "http" or "socket_mode") +- **body** (Union[str, dict]) – The raw request body (only plain text is supported for "http" mode) +- **query** (Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]) – The query string data in any data format. +- **headers** (Optional[Dict[str, Union[str, Sequence[str]]]]) – The request headers. +- **context** (Optional[Dict[str, Any]]) – The context in this request. +- **mode** (str) – The mode used for this request. (either "http" or "socket_mode") -#### to\_copyable +## Submodules -```python -def to_copyable() -> BoltRequest -``` +- [slack_bolt.request.async_internals](/tools/bolt-python/reference/request/async_internals) +- [slack_bolt.request.async_request](/tools/bolt-python/reference/request/async_request) +- [slack_bolt.request.internals](/tools/bolt-python/reference/request/internals) +- [slack_bolt.request.payload_utils](/tools/bolt-python/reference/request/payload_utils) +- [slack_bolt.request.request](/tools/bolt-python/reference/request/request) diff --git a/docs/english/reference/request/internals.md b/docs/english/reference/request/internals.md index 321deec77..cae00ef03 100644 --- a/docs/english/reference/request/internals.md +++ b/docs/english/reference/request/internals.md @@ -3,118 +3,4 @@ sidebar_label: internals title: slack_bolt.request.internals --- -#### parse\_query -```python -def parse_query( - query: Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]) -> Dict[str, Sequence[str]] -``` - -#### parse\_body - -```python -def parse_body(body: str, content_type: Optional[str]) -> Dict[str, Any] -``` - -#### extract\_is\_enterprise\_install - -```python -def extract_is_enterprise_install(payload: Dict[str, Any]) -> Optional[bool] -``` - -#### extract\_enterprise\_id - -```python -def extract_enterprise_id(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_actor\_enterprise\_id - -```python -def extract_actor_enterprise_id(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_team\_id - -```python -def extract_team_id(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_actor\_team\_id - -```python -def extract_actor_team_id(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_user\_id - -```python -def extract_user_id(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_actor\_user\_id - -```python -def extract_actor_user_id(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_channel\_id - -```python -def extract_channel_id(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_thread\_ts - -```python -def extract_thread_ts(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_function\_execution\_id - -```python -def extract_function_execution_id(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_function\_bot\_access\_token - -```python -def extract_function_bot_access_token(payload: Dict[str, Any]) -> Optional[str] -``` - -#### extract\_function\_inputs - -```python -def extract_function_inputs(payload: Dict[str, Any]) -> Optional[Dict[str, Any]] -``` - -#### build\_context - -```python -def build_context(context: BoltContext, body: Dict[str, Any]) -> BoltContext -``` - -#### extract\_content\_type - -```python -def extract_content_type(headers: Dict[str, Sequence[str]]) -> Optional[str] -``` - -#### build\_normalized\_headers - -```python -def build_normalized_headers( - headers: Optional[Dict[str, Union[str, Sequence[str]]]]) -> Dict[str, Sequence[str]] -``` - -#### error\_message\_raw\_body\_required\_in\_http\_mode - -```python -def error_message_raw_body_required_in_http_mode() -> str -``` - -#### debug\_multiple\_response\_urls\_detected - -```python -def debug_multiple_response_urls_detected() -> str -``` diff --git a/docs/english/reference/request/payload_utils.md b/docs/english/reference/request/payload_utils.md index cb7a62513..f060fa860 100644 --- a/docs/english/reference/request/payload_utils.md +++ b/docs/english/reference/request/payload_utils.md @@ -3,230 +3,4 @@ sidebar_label: payload_utils title: slack_bolt.request.payload_utils --- -#### to\_event -```python -def to_event(body: Dict[str, Any]) -> Optional[Dict[str, Any]] -``` - -#### to\_message - -```python -def to_message(body: Dict[str, Any]) -> Optional[Dict[str, Any]] -``` - -#### is\_function - -```python -def is_function(body: Dict[str, Any]) -> bool -``` - -#### is\_event - -```python -def is_event(body: Dict[str, Any]) -> bool -``` - -#### is\_workflow\_step\_execute - -```python -def is_workflow_step_execute(body: Dict[str, Any]) -> bool -``` - -#### is\_message\_event - -```python -def is_message_event(body: Dict[str, Any]) -> bool -``` - -#### is\_any\_im\_message\_event - -```python -def is_any_im_message_event(body: Dict[str, Any]) -> bool -``` - -#### is\_im\_message\_event - -```python -def is_im_message_event(body: Dict[str, Any]) -> bool -``` - -#### is\_assistant\_event - -```python -def is_assistant_event(body: Dict[str, Any]) -> bool -``` - -#### is\_assistant\_thread\_started\_event - -```python -def is_assistant_thread_started_event(body: Dict[str, Any]) -> bool -``` - -#### is\_assistant\_thread\_context\_changed\_event - -```python -def is_assistant_thread_context_changed_event(body: Dict[str, Any]) -> bool -``` - -#### is\_app\_home\_opened\_event - -```python -def is_app_home_opened_event(body: Dict[str, Any], tab: Optional[str] = None) -> bool -``` - -#### is\_user\_message\_event\_in\_assistant\_thread - -```python -def is_user_message_event_in_assistant_thread(body: Dict[str, Any]) -> bool -``` - -#### is\_bot\_message\_event\_in\_assistant\_thread - -```python -def is_bot_message_event_in_assistant_thread(body: Dict[str, Any]) -> bool -``` - -#### is\_other\_message\_sub\_event\_in\_assistant\_thread - -```python -def is_other_message_sub_event_in_assistant_thread(body: Dict[str, Any]) -> bool -``` - -#### to\_command - -```python -def to_command(body: Dict[str, Any]) -> Optional[Dict[str, Any]] -``` - -#### is\_slash\_command - -```python -def is_slash_command(body: Dict[str, Any]) -> bool -``` - -#### to\_action - -```python -def to_action(body: Dict[str, Any]) -> Optional[Dict[str, Any]] -``` - -#### is\_action - -```python -def is_action(body: Dict[str, Any]) -> bool -``` - -#### is\_attachment\_action - -```python -def is_attachment_action(body: Dict[str, Any]) -> bool -``` - -#### is\_block\_actions - -```python -def is_block_actions(body: Dict[str, Any]) -> bool -``` - -#### is\_dialog\_submission - -```python -def is_dialog_submission(body: Dict[str, Any]) -> bool -``` - -#### is\_dialog\_cancellation - -```python -def is_dialog_cancellation(body: Dict[str, Any]) -> bool -``` - -#### is\_workflow\_step\_edit - -```python -def is_workflow_step_edit(body: Dict[str, Any]) -> bool -``` - -#### to\_options - -```python -def to_options(body: Dict[str, Any]) -> Optional[Dict[str, Any]] -``` - -#### is\_options - -```python -def is_options(body: Dict[str, Any]) -> bool -``` - -#### is\_block\_suggestion - -```python -def is_block_suggestion(body: Dict[str, Any]) -> bool -``` - -#### is\_dialog\_suggestion - -```python -def is_dialog_suggestion(body: Dict[str, Any]) -> bool -``` - -#### to\_shortcut - -```python -def to_shortcut(body: Dict[str, Any]) -> Optional[Dict[str, Any]] -``` - -#### is\_shortcut - -```python -def is_shortcut(body: Dict[str, Any]) -> bool -``` - -#### is\_global\_shortcut - -```python -def is_global_shortcut(body: Dict[str, Any]) -> bool -``` - -#### is\_message\_shortcut - -```python -def is_message_shortcut(body: Dict[str, Any]) -> bool -``` - -#### to\_view - -```python -def to_view(body: Dict[str, Any]) -> Optional[Dict[str, Any]] -``` - -#### is\_view - -```python -def is_view(body: Dict[str, Any]) -> bool -``` - -#### is\_view\_submission - -```python -def is_view_submission(body: Dict[str, Any]) -> bool -``` - -#### is\_view\_closed - -```python -def is_view_closed(body: Dict[str, Any]) -> bool -``` - -#### is\_workflow\_step\_save - -```python -def is_workflow_step_save(body: Dict[str, Any]) -> bool -``` - -#### to\_step - -```python -def to_step(body: Dict[str, Any]) -> Optional[Dict[str, Any]] -``` diff --git a/docs/english/reference/request/request.md b/docs/english/reference/request/request.md index e1434a781..016fa4d3d 100644 --- a/docs/english/reference/request/request.md +++ b/docs/english/reference/request/request.md @@ -4,54 +4,18 @@ title: slack_bolt.request.request slug: request --- -## BoltRequest Objects +## `BoltRequest` ```python -class BoltRequest() -``` - -#### raw\_body: `str` - -#### query: `Dict[str, Sequence[str]]` - -#### headers: `Dict[str, Sequence[str]]` - -#### content\_type: `Optional[str]` - -#### body: `Dict[str, Any]` - -#### context: `BoltContext` - -#### lazy\_only: `bool` - -#### lazy\_function\_name: `Optional[str]` - -#### mode: `str` - -#### \_\_init\_\_ - -```python -def __init__( - *, - body: Union[str, dict], - query: Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]] = None, - headers: Optional[Dict[str, Union[str, Sequence[str]]]] = None, - context: Optional[Dict[str, Any]] = None, - mode: str = 'http') +BoltRequest(*, body, query=None, headers=None, context=None, mode='http') ``` Request to a Bolt app. -**Arguments**: +**Parameters:** -- `body` _Union[str, dict]_ - The raw request body (only plain text is supported for "http" mode) -- `query` _Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]_ - The query string data in any data format. -- `headers` _Optional[Dict[str, Union[str, Sequence[str]]]]_ - The request headers. -- `context` _Optional[Dict[str, Any]]_ - The context in this request. -- `mode` _str_ - The mode used for this request. (either "http" or "socket_mode") - -#### to\_copyable - -```python -def to_copyable() -> BoltRequest -``` +- **body** (Union[str, dict]) – The raw request body (only plain text is supported for "http" mode) +- **query** (Optional[Union[str, Dict[str, str], Dict[str, Sequence[str]]]]) – The query string data in any data format. +- **headers** (Optional[Dict[str, Union[str, Sequence[str]]]]) – The request headers. +- **context** (Optional[Dict[str, Any]]) – The context in this request. +- **mode** (str) – The mode used for this request. (either "http" or "socket_mode") diff --git a/docs/english/reference/response/index.md b/docs/english/reference/response/index.md index 1e867986a..98ff63e7f 100644 --- a/docs/english/reference/response/index.md +++ b/docs/english/reference/response/index.md @@ -10,54 +10,20 @@ the response data becomes an HTTP response data. Refer to https://docs.slack.dev/apis/events-api/ for the two types of connections. -## Submodules - -- [slack_bolt.response.response](/tools/bolt-python/reference/response/response) - -## BoltResponse Objects - -```python -class BoltResponse() -``` - -#### status: `int` - -#### body: `str` - -#### headers: `Dict[str, Sequence[str]]` - -#### \_\_init\_\_ +## `BoltResponse` ```python -def __init__( - *, - status: int, - body: Union[str, dict] = '', - headers: Optional[Dict[str, Union[str, Sequence[str]]]] = None) +BoltResponse(*, status, body='', headers=None) ``` The response from a Bolt app. -**Arguments**: - -- `status` _int_ - HTTP status code -- `body` _Union[str, dict]_ - The response body (dict and str are supported) -- `headers` _Optional[Dict[str, Union[str, Sequence[str]]]]_ - The response headers. +**Parameters:** -#### first\_headers +- **status** (int) – HTTP status code +- **body** (Union[str, dict]) – The response body (dict and str are supported) +- **headers** (Optional[Dict[str, Union[str, Sequence[str]]]]) – The response headers. -```python -def first_headers() -> Dict[str, str] -``` - -#### first\_headers\_without\_set\_cookie - -```python -def first_headers_without_set_cookie() -> Dict[str, str] -``` - -#### cookies +## Submodules -```python -def cookies() -> Sequence[SimpleCookie] -``` +- [slack_bolt.response.response](/tools/bolt-python/reference/response/response) diff --git a/docs/english/reference/response/response.md b/docs/english/reference/response/response.md index 260e4dbc0..04c7b2e8e 100644 --- a/docs/english/reference/response/response.md +++ b/docs/english/reference/response/response.md @@ -4,50 +4,16 @@ title: slack_bolt.response.response slug: response --- -## BoltResponse Objects +## `BoltResponse` ```python -class BoltResponse() -``` - -#### status: `int` - -#### body: `str` - -#### headers: `Dict[str, Sequence[str]]` - -#### \_\_init\_\_ - -```python -def __init__( - *, - status: int, - body: Union[str, dict] = '', - headers: Optional[Dict[str, Union[str, Sequence[str]]]] = None) +BoltResponse(*, status, body='', headers=None) ``` The response from a Bolt app. -**Arguments**: - -- `status` _int_ - HTTP status code -- `body` _Union[str, dict]_ - The response body (dict and str are supported) -- `headers` _Optional[Dict[str, Union[str, Sequence[str]]]]_ - The response headers. +**Parameters:** -#### first\_headers - -```python -def first_headers() -> Dict[str, str] -``` - -#### first\_headers\_without\_set\_cookie - -```python -def first_headers_without_set_cookie() -> Dict[str, str] -``` - -#### cookies - -```python -def cookies() -> Sequence[SimpleCookie] -``` +- **status** (int) – HTTP status code +- **body** (Union[str, dict]) – The response body (dict and str are supported) +- **headers** (Optional[Dict[str, Union[str, Sequence[str]]]]) – The response headers. diff --git a/docs/english/reference/util/async_utils.md b/docs/english/reference/util/async_utils.md index 9c2f7ffb7..975065685 100644 --- a/docs/english/reference/util/async_utils.md +++ b/docs/english/reference/util/async_utils.md @@ -3,10 +3,4 @@ sidebar_label: async_utils title: slack_bolt.util.async_utils --- -#### create\_async\_web\_client -```python -def create_async_web_client( - token: Optional[str] = None, - logger: Optional[Logger] = None) -> AsyncWebClient -``` diff --git a/docs/english/reference/util/utils.md b/docs/english/reference/util/utils.md index 58b64ad08..b5847231e 100644 --- a/docs/english/reference/util/utils.md +++ b/docs/english/reference/util/utils.md @@ -3,78 +3,34 @@ sidebar_label: utils title: slack_bolt.util.utils --- -#### create\_web\_client +## `get_name_for_callable` ```python -def create_web_client( - token: Optional[str] = None, - logger: Optional[Logger] = None) -> WebClient -``` - -#### convert\_to\_dict\_list - -```python -def convert_to_dict_list(objects: Sequence[Union[Dict, JsonObject]]) -> Sequence[Dict] -``` - -#### convert\_to\_dict - -```python -def convert_to_dict(obj: Union[Dict, JsonObject]) -> Dict -``` - -#### create\_copy - -```python -def create_copy(original: Any) -> Any -``` - -#### get\_boot\_message - -```python -def get_boot_message(development_server: bool = False) -> str -``` - -#### get\_name\_for\_callable - -```python -def get_name_for_callable(func: Callable) -> str +get_name_for_callable(func) ``` Returns the name for the given Callable function object. -**Arguments**: - -- `func` _Callable_ - Either a `Callable` instance or a function, which as `__name__` +**Parameters:** -**Returns**: +- **func** (Callable) – Either a `Callable` instance or a function, which as `__name__` -- `str` - The name of the given Callable object +**Returns:** -#### get\_arg\_names\_of\_callable - -```python -def get_arg_names_of_callable(func: Callable) -> List[str] -``` - -#### is\_callable\_coroutine - -```python -def is_callable_coroutine(func: Optional[Any]) -> bool -``` +- str – The name of the given Callable object -#### is\_used\_without\_argument +## `is_used_without_argument` ```python -def is_used_without_argument(args) -> bool +is_used_without_argument(args) ``` Tests if a decorator invocation is without () or (args). -**Arguments**: +**Parameters:** -- `args` - arguments +- **args** – arguments -**Returns**: +**Returns:** -- `bool` - True if it's an invocation without args +- bool – True if it's an invocation without args diff --git a/docs/english/reference/workflows/step/async_step.md b/docs/english/reference/workflows/step/async_step.md index 7334db580..fb4d3ddfe 100644 --- a/docs/english/reference/workflows/step/async_step.md +++ b/docs/english/reference/workflows/step/async_step.md @@ -3,31 +3,84 @@ sidebar_label: async_step title: slack_bolt.workflows.step.async_step --- -## AsyncWorkflowStepBuilder Objects +## `AsyncWorkflowStep` ```python -class AsyncWorkflowStepBuilder() +AsyncWorkflowStep(*, callback_id, edit, save, execute, app_name=None, base_logger=None) ``` -Steps from apps. +Deprecated: Steps from apps for legacy workflows are now deprecated. -Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details. +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -#### callback\_id: `Union[str, Pattern]` +**Parameters:** -#### \_\_init\_\_ +- **callback_id** (Union[str, Pattern]) – The callback_id for this step from app +- **edit** (Union[Callable..., [Awaitable[BoltResponse]], AsyncListener, Sequence[Callable]]) – Either a single function or a list of functions for opening a modal in the builder UI +When it's a list, the first one is responsible for ack() while the rest are lazy listeners. +- **save** (Union[Callable..., [Awaitable[BoltResponse]], AsyncListener, Sequence[Callable]]) – Either a single function or a list of functions for handling modal interactions in the builder UI +When it's a list, the first one is responsible for ack() while the rest are lazy listeners. +- **execute** (Union[Callable..., [Awaitable[BoltResponse]], AsyncListener, Sequence[Callable]]) – Either a single function or a list of functions for handling steps from apps executions +When it's a list, the first one is responsible for ack() while the rest are lazy listeners. +- **app_name** (Optional[str]) – The app name that can be mainly used for logging +- **base_logger** (Optional[Logger]) – The logger instance that can be used as a template when creating this step's logger + +### `builder` ```python -def __init__( - callback_id: Union[str, Pattern], - app_name: Optional[str] = None, - base_logger: Optional[Logger] = None) +builder(callback_id, base_logger=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ +### `callback_id` + +```python +callback_id: Union[str, Pattern] = callback_id +``` + +The Callback ID of the step from app + +### `edit` + +```python +edit: AsyncListener = self.build_listener(callback_id=callback_id, app_name=app_name, listener_or_functions=edit, name='edit', base_logger=base_logger) +``` + +`edit` listener, which displays a modal in Workflow Builder + +### `execute` + +```python +execute: AsyncListener = self.build_listener(callback_id=callback_id, app_name=app_name, listener_or_functions=execute, name='execute', base_logger=base_logger) +``` + +`execute` listener, which processes the step from app execution + +### `save` + +```python +save: AsyncListener = self.build_listener(callback_id=callback_id, app_name=app_name, listener_or_functions=save, name='save', base_logger=base_logger) +``` + +`save` listener, which accepts workflow creator's data submission in Workflow Builder + +## `AsyncWorkflowStepBuilder` + +```python +AsyncWorkflowStepBuilder(callback_id, app_name=None, base_logger=None) +``` + +Steps from apps. + +Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details. + +Deprecated: Steps from apps for legacy workflows are now deprecated. + +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ + This builder is supposed to be used as decorator. ```python @@ -48,84 +101,54 @@ For further information about AsyncWorkflowStep specific function arguments such as `configure`, `update`, `complete`, and `fail`, refer to the `async` prefixed ones in `slack_bolt.workflows.step.utilities` API documents. -**Arguments**: +**Parameters:** -- `callback_id` _Union[str, Pattern]_ - The callback_id for the workflow -- `app_name` _Optional[str]_ - The application name mainly for logging -- `base_logger` _Optional[Logger]_ - The base logger +- **callback_id** (Union[str, Pattern]) – The callback_id for the workflow +- **app_name** (Optional[str]) – The application name mainly for logging +- **base_logger** (Optional[Logger]) – The base logger -#### edit +### `build` ```python -def edit( - *args, - matchers: Optional[Union[Callable[..., Awaitable[bool]], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., Awaitable[None]]]] = None) +build(base_logger=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -Registers a new edit listener with details. - -You can use this method as decorator as well. - -```python -@my_step.edit -def edit_my_step(ack, configure): - pass -``` - -It's also possible to add additional listener matchers and/or middleware - -```python -@my_step.edit(matchers=[is_valid], middleware=[update_context]) -def edit_my_step(ack, configure): - pass -``` - -For further information about AsyncWorkflowStep specific function arguments -such as `configure`, `update`, `complete`, and `fail`, -refer to the `async` prefixed ones in `slack_bolt.workflows.step.utilities` API documents. +Constructs a WorkflowStep object. This method may raise an exception +if the builder doesn't have enough configurations to build the object. -**Arguments**: +**Returns:** -- `*args` - This method can behave as either decorator or a method -- `matchers` _Optional[Union[Callable[..., Awaitable[bool]], AsyncListenerMatcher]]_ - Listener matchers -- `middleware` _Optional[Union[Callable, AsyncMiddleware]]_ - Listener middleware -- `lazy` _Optional[List[Callable[..., Awaitable[None]]]]_ - Lazy listeners +- AsyncWorkflowStep – An `AsyncWorkflowStep` object -#### save +### `edit` ```python -def save( - *args, - matchers: Optional[Union[Callable[..., Awaitable[bool]], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., Awaitable[None]]]] = None) +edit(*args, matchers=None, middleware=None, lazy=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -Registers a new save listener with details. +Registers a new edit listener with details. You can use this method as decorator as well. ```python -@my_step.save -def save_my_step(ack, step, update): +@my_step.edit +def edit_my_step(ack, configure): pass ``` It's also possible to add additional listener matchers and/or middleware ```python -@my_step.save(matchers=[is_valid], middleware=[update_context]) -def save_my_step(ack, step, update): +@my_step.edit(matchers=[is_valid], middleware=[update_context]) +def edit_my_step(ack, configure): pass ``` @@ -133,21 +156,17 @@ For further information about AsyncWorkflowStep specific function arguments such as `configure`, `update`, `complete`, and `fail`, refer to the `async` prefixed ones in `slack_bolt.workflows.step.utilities` API documents. -**Arguments**: +**Parameters:** -- `*args` - This method can behave as either decorator or a method -- `matchers` _Optional[Union[Callable[..., Awaitable[bool]], AsyncListenerMatcher]]_ - Listener matchers -- `middleware` _Optional[Union[Callable, AsyncMiddleware]]_ - Listener middleware -- `lazy` _Optional[List[Callable[..., Awaitable[None]]]]_ - Lazy listeners +- ***args** – This method can behave as either decorator or a method +- **matchers** (Optional[Union[Callable..., [Awaitable[bool]], AsyncListenerMatcher]]) – Listener matchers +- **middleware** (Optional[Union[Callable, AsyncMiddleware]]) – Listener middleware +- **lazy** (Optional[List[Callable..., [Awaitable[None]]]]) – Lazy listeners -#### execute +### `execute` ```python -def execute( - *args, - matchers: Optional[Union[Callable[..., Awaitable[bool]], AsyncListenerMatcher]] = None, - middleware: Optional[Union[Callable, AsyncMiddleware]] = None, - lazy: Optional[List[Callable[..., Awaitable[None]]]] = None) +execute(*args, matchers=None, middleware=None, lazy=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. @@ -176,118 +195,48 @@ For further information about AsyncWorkflowStep specific function arguments such as `configure`, `update`, `complete`, and `fail`, refer to the `async` prefixed ones in `slack_bolt.workflows.step.utilities` API documents. -**Arguments**: +**Parameters:** -- `*args` - This method can behave as either decorator or a method -- `matchers` _Optional[Union[Callable[..., Awaitable[bool]], AsyncListenerMatcher]]_ - Listener matchers -- `middleware` _Optional[Union[Callable, AsyncMiddleware]]_ - Listener middleware -- `lazy` _Optional[List[Callable[..., Awaitable[None]]]]_ - Lazy listeners +- ***args** – This method can behave as either decorator or a method +- **matchers** (Optional[Union[Callable..., [Awaitable[bool]], AsyncListenerMatcher]]) – Listener matchers +- **middleware** (Optional[Union[Callable, AsyncMiddleware]]) – Listener middleware +- **lazy** (Optional[List[Callable..., [Awaitable[None]]]]) – Lazy listeners -#### build +### `save` ```python -def build(base_logger: Optional[Logger] = None) -> AsyncWorkflowStep +save(*args, matchers=None, middleware=None, lazy=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -Constructs a WorkflowStep object. This method may raise an exception -if the builder doesn't have enough configurations to build the object. - -**Returns**: - -- `AsyncWorkflowStep` - An `AsyncWorkflowStep` object - -#### to\_listener\_matchers - -```python -def to_listener_matchers( - app_name: str, - matchers: Optional[List[Union[Callable[..., Awaitable[bool]], AsyncListenerMatcher]]]) -> List[AsyncListenerMatcher] -``` - -#### to\_listener\_middleware - -```python -def to_listener_middleware( - app_name: str, - middleware: Optional[List[Union[Callable, AsyncMiddleware]]]) -> List[AsyncMiddleware] -``` - -## AsyncWorkflowStep Objects - -```python -class AsyncWorkflowStep() -``` - -#### callback\_id: `Union[str, Pattern]` - -The Callback ID of the step from app - -#### edit: `AsyncListener` - -`edit` listener, which displays a modal in Workflow Builder - -#### save: `AsyncListener` - -`save` listener, which accepts workflow creator's data submission in Workflow Builder - -#### execute: `AsyncListener` - -`execute` listener, which processes the step from app execution +Registers a new save listener with details. -#### \_\_init\_\_ +You can use this method as decorator as well. ```python -def __init__( - *, - callback_id: Union[str, Pattern], - edit: Union[Callable[..., Awaitable[BoltResponse]], AsyncListener, Sequence[Callable]], - save: Union[Callable[..., Awaitable[BoltResponse]], AsyncListener, Sequence[Callable]], - execute: Union[Callable[..., Awaitable[BoltResponse]], AsyncListener, Sequence[Callable]], - app_name: Optional[str] = None, - base_logger: Optional[Logger] = None) +@my_step.save +def save_my_step(ack, step, update): + pass ``` -Deprecated: Steps from apps for legacy workflows are now deprecated. - -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ - -**Arguments**: - -- `callback_id` _Union[str, Pattern]_ - The callback_id for this step from app -- `edit` _Union[Callable[..., Awaitable[BoltResponse]], AsyncListener, Sequence[Callable]]_ - Either a single function or a list of functions for opening a modal in the builder UI - When it's a list, the first one is responsible for ack() while the rest are lazy listeners. -- `save` _Union[Callable[..., Awaitable[BoltResponse]], AsyncListener, Sequence[Callable]]_ - Either a single function or a list of functions for handling modal interactions in the builder UI - When it's a list, the first one is responsible for ack() while the rest are lazy listeners. -- `execute` _Union[Callable[..., Awaitable[BoltResponse]], AsyncListener, Sequence[Callable]]_ - Either a single function or a list of functions for handling steps from apps executions - When it's a list, the first one is responsible for ack() while the rest are lazy listeners. -- `app_name` _Optional[str]_ - The app name that can be mainly used for logging -- `base_logger` _Optional[Logger]_ - The logger instance that can be used as a template when creating this step's logger - -#### builder +It's also possible to add additional listener matchers and/or middleware ```python -def builder( - callback_id: Union[str, Pattern], - base_logger: Optional[Logger] = None) -> AsyncWorkflowStepBuilder +@my_step.save(matchers=[is_valid], middleware=[update_context]) +def save_my_step(ack, step, update): + pass ``` -Deprecated: Steps from apps for legacy workflows are now deprecated. - -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ +For further information about AsyncWorkflowStep specific function arguments +such as `configure`, `update`, `complete`, and `fail`, +refer to the `async` prefixed ones in `slack_bolt.workflows.step.utilities` API documents. -#### build\_listener +**Parameters:** -```python -def build_listener( - callback_id: Union[str, Pattern], - app_name: str, - listener_or_functions: Union[AsyncListener, Callable, List[Callable]], - name: str, - matchers: Optional[List[AsyncListenerMatcher]] = None, - middleware: Optional[List[AsyncMiddleware]] = None, - base_logger: Optional[Logger] = None) -``` +- ***args** – This method can behave as either decorator or a method +- **matchers** (Optional[Union[Callable..., [Awaitable[bool]], AsyncListenerMatcher]]) – Listener matchers +- **middleware** (Optional[Union[Callable, AsyncMiddleware]]) – Listener middleware +- **lazy** (Optional[List[Callable..., [Awaitable[None]]]]) – Lazy listeners diff --git a/docs/english/reference/workflows/step/async_step_middleware.md b/docs/english/reference/workflows/step/async_step_middleware.md index 532f131ce..8aa1ec901 100644 --- a/docs/english/reference/workflows/step/async_step_middleware.md +++ b/docs/english/reference/workflows/step/async_step_middleware.md @@ -3,26 +3,20 @@ sidebar_label: async_step_middleware title: slack_bolt.workflows.step.async_step_middleware --- -## AsyncWorkflowStepMiddleware Objects +## `AsyncWorkflowStepMiddleware` ```python -class AsyncWorkflowStepMiddleware(AsyncMiddleware) +AsyncWorkflowStepMiddleware(step) ``` +Bases: AsyncMiddleware + Base middleware for step from app specific ones. -#### \_\_init\_\_ +### `name` ```python -def __init__(step: AsyncWorkflowStep) +name: str ``` -#### async\_process - -```python -async def async_process( - *, - req: AsyncBoltRequest, - resp: BoltResponse, - next: Callable[[], Awaitable[BoltResponse]]) -> BoltResponse -``` +The name of this middleware. diff --git a/docs/english/reference/workflows/step/index.md b/docs/english/reference/workflows/step/index.md index cb13b7551..429ec3f29 100644 --- a/docs/english/reference/workflows/step/index.md +++ b/docs/english/reference/workflows/step/index.md @@ -3,119 +3,10 @@ sidebar_label: step title: slack_bolt.workflows.step --- -## Submodules - -- [slack_bolt.workflows.step.async_step](/tools/bolt-python/reference/workflows/step/async_step) -- [slack_bolt.workflows.step.async_step_middleware](/tools/bolt-python/reference/workflows/step/async_step_middleware) -- [slack_bolt.workflows.step.internals](/tools/bolt-python/reference/workflows/step/internals) -- [slack_bolt.workflows.step.step](/tools/bolt-python/reference/workflows/step/step) -- [slack_bolt.workflows.step.step_middleware](/tools/bolt-python/reference/workflows/step/step_middleware) -- [slack_bolt.workflows.step.utilities](/tools/bolt-python/reference/workflows/step/utilities) - -## WorkflowStep Objects +## `Complete` ```python -class WorkflowStep() -``` - -#### callback\_id: `Union[str, Pattern]` - -The Callback ID of the step from app - -#### edit: `Listener` - -`edit` listener, which displays a modal in Workflow Builder - -#### save: `Listener` - -`save` listener, which accepts workflow creator's data submission in Workflow Builder - -#### execute: `Listener` - -`execute` listener, which processes step from app execution - -#### \_\_init\_\_ - -```python -def __init__( - *, - callback_id: Union[str, Pattern], - edit: Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]], - save: Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]], - execute: Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]], - app_name: Optional[str] = None, - base_logger: Optional[Logger] = None) -``` - -Deprecated: Steps from apps for legacy workflows are now deprecated. - -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ - -**Arguments**: - -- `callback_id` _Union[str, Pattern]_ - The callback_id for this step from app -- `edit` _Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]_ - Either a single function or a list of functions for opening a modal in the builder UI - When it's a list, the first one is responsible for ack() while the rest are lazy listeners. -- `save` _Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]_ - Either a single function or a list of functions for handling modal interactions in the builder UI - When it's a list, the first one is responsible for ack() while the rest are lazy listeners. -- `execute` _Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]_ - Either a single function or a list of functions for handling step from app executions - When it's a list, the first one is responsible for ack() while the rest are lazy listeners. -- `app_name` _Optional[str]_ - The app name that can be mainly used for logging -- `base_logger` _Optional[Logger]_ - The logger instance that can be used as a template when creating this step's logger - -#### builder - -```python -def builder( - callback_id: Union[str, Pattern], - base_logger: Optional[Logger] = None) -> WorkflowStepBuilder -``` - -Deprecated: Steps from apps for legacy workflows are now deprecated. - -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ - -#### build\_listener - -```python -def build_listener( - callback_id: Union[str, Pattern], - app_name: str, - listener_or_functions: Union[Listener, Callable, List[Callable]], - name: str, - matchers: Optional[List[ListenerMatcher]] = None, - middleware: Optional[List[Middleware]] = None, - base_logger: Optional[Logger] = None) -> Listener -``` - -## WorkflowStepMiddleware Objects - -```python -class WorkflowStepMiddleware(Middleware) -``` - -Base middleware for step from app specific ones. - -#### \_\_init\_\_ - -```python -def __init__(step: WorkflowStep) -``` - -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> Optional[BoltResponse] -``` - -## Complete Objects - -```python -class Complete() +Complete(*, client, body) ``` `complete()` utility to tell Slack the completion of a step from app execution. @@ -142,16 +33,10 @@ app.step(ws) This utility is a thin wrapper of workflows.stepCompleted API method. Refer to https://api.slack.com/methods/workflows.stepCompleted for details. -#### \_\_init\_\_ - -```python -def __init__(*, client: WebClient, body: dict) -``` - -## Configure Objects +## `Configure` ```python -class Configure() +Configure(*, callback_id, client, body) ``` `configure()` utility to send the modal view in Workflow Builder. @@ -185,16 +70,37 @@ app.step(ws) Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details. -#### \_\_init\_\_ +## `Fail` ```python -def __init__(*, callback_id: str, client: WebClient, body: dict) +Fail(*, client, body) +``` + +`fail()` utility to tell Slack the execution failure of a step from app. + +```python +def execute(step, complete, fail): + inputs = step["inputs"] + # if something went wrong + error = {"message": "Just testing step failure!"} + fail(error=error) + +ws = WorkflowStep( + callback_id="add_task", + edit=edit, + save=save, + execute=execute, +) +app.step(ws) ``` -## Update Objects +This utility is a thin wrapper of workflows.stepFailed API method. +Refer to https://api.slack.com/methods/workflows.stepFailed for details. + +## `Update` ```python -class Update() +Update(*, client, body) ``` `update()` utility to tell Slack the processing results of a `save` listener. @@ -237,41 +143,93 @@ app.step(ws) This utility is a thin wrapper of workflows.stepFailed API method. Refer to https://api.slack.com/methods/workflows.updateStep for details. -#### \_\_init\_\_ +## `WorkflowStep` ```python -def __init__(*, client: WebClient, body: dict) +WorkflowStep(*, callback_id, edit, save, execute, app_name=None, base_logger=None) ``` -## Fail Objects +Deprecated: Steps from apps for legacy workflows are now deprecated. + +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ + +**Parameters:** + +- **callback_id** (Union[str, Pattern]) – The callback_id for this step from app +- **edit** (Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]) – Either a single function or a list of functions for opening a modal in the builder UI +When it's a list, the first one is responsible for ack() while the rest are lazy listeners. +- **save** (Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]) – Either a single function or a list of functions for handling modal interactions in the builder UI +When it's a list, the first one is responsible for ack() while the rest are lazy listeners. +- **execute** (Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]) – Either a single function or a list of functions for handling step from app executions +When it's a list, the first one is responsible for ack() while the rest are lazy listeners. +- **app_name** (Optional[str]) – The app name that can be mainly used for logging +- **base_logger** (Optional[Logger]) – The logger instance that can be used as a template when creating this step's logger + +### `builder` ```python -class Fail() +builder(callback_id, base_logger=None) ``` -`fail()` utility to tell Slack the execution failure of a step from app. +Deprecated: Steps from apps for legacy workflows are now deprecated. + +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ + +### `callback_id` ```python -def execute(step, complete, fail): - inputs = step["inputs"] - # if something went wrong - error = {"message": "Just testing step failure!"} - fail(error=error) +callback_id: Union[str, Pattern] = callback_id +``` -ws = WorkflowStep( - callback_id="add_task", - edit=edit, - save=save, - execute=execute, -) -app.step(ws) +The Callback ID of the step from app + +### `edit` + +```python +edit: Listener = self.build_listener(callback_id=callback_id, app_name=app_name, listener_or_functions=edit, name='edit', base_logger=base_logger) ``` -This utility is a thin wrapper of workflows.stepFailed API method. -Refer to https://api.slack.com/methods/workflows.stepFailed for details. +`edit` listener, which displays a modal in Workflow Builder + +### `execute` + +```python +execute: Listener = self.build_listener(callback_id=callback_id, app_name=app_name, listener_or_functions=execute, name='execute', base_logger=base_logger) +``` + +`execute` listener, which processes step from app execution + +### `save` + +```python +save: Listener = self.build_listener(callback_id=callback_id, app_name=app_name, listener_or_functions=save, name='save', base_logger=base_logger) +``` + +`save` listener, which accepts workflow creator's data submission in Workflow Builder -#### \_\_init\_\_ +## `WorkflowStepMiddleware` ```python -def __init__(*, client: WebClient, body: dict) +WorkflowStepMiddleware(step) ``` + +Bases: Middleware + +Base middleware for step from app specific ones. + +### `name` + +```python +name: str +``` + +The name of this middleware. + +## Submodules + +- [slack_bolt.workflows.step.async_step](/tools/bolt-python/reference/workflows/step/async_step) +- [slack_bolt.workflows.step.async_step_middleware](/tools/bolt-python/reference/workflows/step/async_step_middleware) +- [slack_bolt.workflows.step.internals](/tools/bolt-python/reference/workflows/step/internals) +- [slack_bolt.workflows.step.step](/tools/bolt-python/reference/workflows/step/step) +- [slack_bolt.workflows.step.step_middleware](/tools/bolt-python/reference/workflows/step/step_middleware) +- [slack_bolt.workflows.step.utilities](/tools/bolt-python/reference/workflows/step/utilities) diff --git a/docs/english/reference/workflows/step/step.md b/docs/english/reference/workflows/step/step.md index 1cea19175..44865b670 100644 --- a/docs/english/reference/workflows/step/step.md +++ b/docs/english/reference/workflows/step/step.md @@ -4,31 +4,84 @@ title: slack_bolt.workflows.step.step slug: step --- -## WorkflowStepBuilder Objects +## `WorkflowStep` ```python -class WorkflowStepBuilder() +WorkflowStep(*, callback_id, edit, save, execute, app_name=None, base_logger=None) ``` -Steps from apps. +Deprecated: Steps from apps for legacy workflows are now deprecated. -Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details. +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -#### callback\_id: `Union[str, Pattern]` +**Parameters:** -#### \_\_init\_\_ +- **callback_id** (Union[str, Pattern]) – The callback_id for this step from app +- **edit** (Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]) – Either a single function or a list of functions for opening a modal in the builder UI +When it's a list, the first one is responsible for ack() while the rest are lazy listeners. +- **save** (Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]) – Either a single function or a list of functions for handling modal interactions in the builder UI +When it's a list, the first one is responsible for ack() while the rest are lazy listeners. +- **execute** (Union[Callable..., [Optional[BoltResponse]], Listener, Sequence[Callable]]) – Either a single function or a list of functions for handling step from app executions +When it's a list, the first one is responsible for ack() while the rest are lazy listeners. +- **app_name** (Optional[str]) – The app name that can be mainly used for logging +- **base_logger** (Optional[Logger]) – The logger instance that can be used as a template when creating this step's logger + +### `builder` ```python -def __init__( - callback_id: Union[str, Pattern], - app_name: Optional[str] = None, - base_logger: Optional[Logger] = None) +builder(callback_id, base_logger=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ +### `callback_id` + +```python +callback_id: Union[str, Pattern] = callback_id +``` + +The Callback ID of the step from app + +### `edit` + +```python +edit: Listener = self.build_listener(callback_id=callback_id, app_name=app_name, listener_or_functions=edit, name='edit', base_logger=base_logger) +``` + +`edit` listener, which displays a modal in Workflow Builder + +### `execute` + +```python +execute: Listener = self.build_listener(callback_id=callback_id, app_name=app_name, listener_or_functions=execute, name='execute', base_logger=base_logger) +``` + +`execute` listener, which processes step from app execution + +### `save` + +```python +save: Listener = self.build_listener(callback_id=callback_id, app_name=app_name, listener_or_functions=save, name='save', base_logger=base_logger) +``` + +`save` listener, which accepts workflow creator's data submission in Workflow Builder + +## `WorkflowStepBuilder` + +```python +WorkflowStepBuilder(callback_id, app_name=None, base_logger=None) +``` + +Steps from apps. + +Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details. + +Deprecated: Steps from apps for legacy workflows are now deprecated. + +Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ + This builder is supposed to be used as decorator. ```python @@ -49,84 +102,54 @@ For further information about WorkflowStep specific function arguments such as `configure`, `update`, `complete`, and `fail`, refer to `slack_bolt.workflows.step.utilities` API documents. -**Arguments**: +**Parameters:** -- `callback_id` _Union[str, Pattern]_ - The callback_id for the workflow -- `app_name` _Optional[str]_ - The application name mainly for logging -- `base_logger` _Optional[Logger]_ - The base logger +- **callback_id** (Union[str, Pattern]) – The callback_id for the workflow +- **app_name** (Optional[str]) – The application name mainly for logging +- **base_logger** (Optional[Logger]) – The base logger -#### edit +### `build` ```python -def edit( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) +build(base_logger=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -Registers a new edit listener with details. - -You can use this method as decorator as well. - -```python -@my_step.edit -def edit_my_step(ack, configure): - pass -``` - -It's also possible to add additional listener matchers and/or middleware - -```python -@my_step.edit(matchers=[is_valid], middleware=[update_context]) -def edit_my_step(ack, configure): - pass -``` - -For further information about WorkflowStep specific function arguments -such as `configure`, `update`, `complete`, and `fail`, -refer to `slack_bolt.workflows.step.utilities` API documents. +Constructs a WorkflowStep object. This method may raise an exception +if the builder doesn't have enough configurations to build the object. -**Arguments**: +**Returns:** -- `*args` - This method can behave as either decorator or a method -- `matchers` _Optional[Union[Callable[..., bool], ListenerMatcher]]_ - Listener matchers -- `middleware` _Optional[Union[Callable, Middleware]]_ - Listener middleware -- `lazy` _Optional[List[Callable[..., None]]]_ - Lazy listeners +- WorkflowStep – WorkflowStep object -#### save +### `edit` ```python -def save( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) +edit(*args, matchers=None, middleware=None, lazy=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -Registers a new save listener with details. +Registers a new edit listener with details. You can use this method as decorator as well. ```python -@my_step.save -def save_my_step(ack, step, update): +@my_step.edit +def edit_my_step(ack, configure): pass ``` It's also possible to add additional listener matchers and/or middleware ```python -@my_step.save(matchers=[is_valid], middleware=[update_context]) -def save_my_step(ack, step, update): +@my_step.edit(matchers=[is_valid], middleware=[update_context]) +def edit_my_step(ack, configure): pass ``` @@ -134,21 +157,17 @@ For further information about WorkflowStep specific function arguments such as `configure`, `update`, `complete`, and `fail`, refer to `slack_bolt.workflows.step.utilities` API documents. -**Arguments**: +**Parameters:** -- `*args` - This method can behave as either decorator or a method -- `matchers` _Optional[Union[Callable[..., bool], ListenerMatcher]]_ - Listener matchers -- `middleware` _Optional[Union[Callable, Middleware]]_ - Listener middleware -- `lazy` _Optional[List[Callable[..., None]]]_ - Lazy listeners +- ***args** – This method can behave as either decorator or a method +- **matchers** (Optional[Union[Callable..., [bool], ListenerMatcher]]) – Listener matchers +- **middleware** (Optional[Union[Callable, Middleware]]) – Listener middleware +- **lazy** (Optional[List[Callable[..., None]]]) – Lazy listeners -#### execute +### `execute` ```python -def execute( - *args, - matchers: Optional[Union[Callable[..., bool], ListenerMatcher]] = None, - middleware: Optional[Union[Callable, Middleware]] = None, - lazy: Optional[List[Callable[..., None]]] = None) +execute(*args, matchers=None, middleware=None, lazy=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. @@ -177,120 +196,48 @@ For further information about WorkflowStep specific function arguments such as `configure`, `update`, `complete`, and `fail`, refer to `slack_bolt.workflows.step.utilities` API documents. -**Arguments**: +**Parameters:** -- `*args` - This method can behave as either decorator or a method -- `matchers` _Optional[Union[Callable[..., bool], ListenerMatcher]]_ - Listener matchers -- `middleware` _Optional[Union[Callable, Middleware]]_ - Listener middleware -- `lazy` _Optional[List[Callable[..., None]]]_ - Lazy listeners +- ***args** – This method can behave as either decorator or a method +- **matchers** (Optional[Union[Callable..., [bool], ListenerMatcher]]) – Listener matchers +- **middleware** (Optional[Union[Callable, Middleware]]) – Listener middleware +- **lazy** (Optional[List[Callable[..., None]]]) – Lazy listeners -#### build +### `save` ```python -def build(base_logger: Optional[Logger] = None) -> WorkflowStep +save(*args, matchers=None, middleware=None, lazy=None) ``` Deprecated: Steps from apps for legacy workflows are now deprecated. Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ -Constructs a WorkflowStep object. This method may raise an exception -if the builder doesn't have enough configurations to build the object. - -**Returns**: - -- `WorkflowStep` - WorkflowStep object - -#### to\_listener\_matchers - -```python -def to_listener_matchers( - app_name: str, - matchers: Optional[List[Union[Callable[..., bool], ListenerMatcher]]], - base_logger: Optional[Logger] = None) -> List[ListenerMatcher] -``` - -#### to\_listener\_middleware - -```python -def to_listener_middleware( - app_name: str, - middleware: Optional[List[Union[Callable, Middleware]]], - base_logger: Optional[Logger] = None) -> List[Middleware] -``` - -## WorkflowStep Objects - -```python -class WorkflowStep() -``` - -#### callback\_id: `Union[str, Pattern]` - -The Callback ID of the step from app - -#### edit: `Listener` - -`edit` listener, which displays a modal in Workflow Builder - -#### save: `Listener` - -`save` listener, which accepts workflow creator's data submission in Workflow Builder - -#### execute: `Listener` - -`execute` listener, which processes step from app execution +Registers a new save listener with details. -#### \_\_init\_\_ +You can use this method as decorator as well. ```python -def __init__( - *, - callback_id: Union[str, Pattern], - edit: Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]], - save: Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]], - execute: Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]], - app_name: Optional[str] = None, - base_logger: Optional[Logger] = None) +@my_step.save +def save_my_step(ack, step, update): + pass ``` -Deprecated: Steps from apps for legacy workflows are now deprecated. - -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ - -**Arguments**: - -- `callback_id` _Union[str, Pattern]_ - The callback_id for this step from app -- `edit` _Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]_ - Either a single function or a list of functions for opening a modal in the builder UI - When it's a list, the first one is responsible for ack() while the rest are lazy listeners. -- `save` _Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]_ - Either a single function or a list of functions for handling modal interactions in the builder UI - When it's a list, the first one is responsible for ack() while the rest are lazy listeners. -- `execute` _Union[Callable[..., Optional[BoltResponse]], Listener, Sequence[Callable]]_ - Either a single function or a list of functions for handling step from app executions - When it's a list, the first one is responsible for ack() while the rest are lazy listeners. -- `app_name` _Optional[str]_ - The app name that can be mainly used for logging -- `base_logger` _Optional[Logger]_ - The logger instance that can be used as a template when creating this step's logger - -#### builder +It's also possible to add additional listener matchers and/or middleware ```python -def builder( - callback_id: Union[str, Pattern], - base_logger: Optional[Logger] = None) -> WorkflowStepBuilder +@my_step.save(matchers=[is_valid], middleware=[update_context]) +def save_my_step(ack, step, update): + pass ``` -Deprecated: Steps from apps for legacy workflows are now deprecated. - -Use new custom steps: https://docs.slack.dev/workflows/workflow-steps/ +For further information about WorkflowStep specific function arguments +such as `configure`, `update`, `complete`, and `fail`, +refer to `slack_bolt.workflows.step.utilities` API documents. -#### build\_listener +**Parameters:** -```python -def build_listener( - callback_id: Union[str, Pattern], - app_name: str, - listener_or_functions: Union[Listener, Callable, List[Callable]], - name: str, - matchers: Optional[List[ListenerMatcher]] = None, - middleware: Optional[List[Middleware]] = None, - base_logger: Optional[Logger] = None) -> Listener -``` +- ***args** – This method can behave as either decorator or a method +- **matchers** (Optional[Union[Callable..., [bool], ListenerMatcher]]) – Listener matchers +- **middleware** (Optional[Union[Callable, Middleware]]) – Listener middleware +- **lazy** (Optional[List[Callable[..., None]]]) – Lazy listeners diff --git a/docs/english/reference/workflows/step/step_middleware.md b/docs/english/reference/workflows/step/step_middleware.md index 72f1894c7..f8f198f99 100644 --- a/docs/english/reference/workflows/step/step_middleware.md +++ b/docs/english/reference/workflows/step/step_middleware.md @@ -3,26 +3,20 @@ sidebar_label: step_middleware title: slack_bolt.workflows.step.step_middleware --- -## WorkflowStepMiddleware Objects +## `WorkflowStepMiddleware` ```python -class WorkflowStepMiddleware(Middleware) +WorkflowStepMiddleware(step) ``` +Bases: Middleware + Base middleware for step from app specific ones. -#### \_\_init\_\_ +### `name` ```python -def __init__(step: WorkflowStep) +name: str ``` -#### process - -```python -def process( - *, - req: BoltRequest, - resp: BoltResponse, - next: Callable[[], BoltResponse]) -> Optional[BoltResponse] -``` +The name of this middleware. diff --git a/docs/english/reference/workflows/step/utilities/async_complete.md b/docs/english/reference/workflows/step/utilities/async_complete.md index ff80ef42e..20302ba39 100644 --- a/docs/english/reference/workflows/step/utilities/async_complete.md +++ b/docs/english/reference/workflows/step/utilities/async_complete.md @@ -3,10 +3,10 @@ sidebar_label: async_complete title: slack_bolt.workflows.step.utilities.async_complete --- -## AsyncComplete Objects +## `AsyncComplete` ```python -class AsyncComplete() +AsyncComplete(*, client, body) ``` `complete()` utility to tell Slack the completion of a step from app execution. @@ -32,9 +32,3 @@ app.step(ws) This utility is a thin wrapper of workflows.stepCompleted API method. Refer to https://api.slack.com/methods/workflows.stepCompleted for details. - -#### \_\_init\_\_ - -```python -def __init__(*, client: AsyncWebClient, body: dict) -``` diff --git a/docs/english/reference/workflows/step/utilities/async_configure.md b/docs/english/reference/workflows/step/utilities/async_configure.md index c9a17f0db..0726eec43 100644 --- a/docs/english/reference/workflows/step/utilities/async_configure.md +++ b/docs/english/reference/workflows/step/utilities/async_configure.md @@ -3,10 +3,10 @@ sidebar_label: async_configure title: slack_bolt.workflows.step.utilities.async_configure --- -## AsyncConfigure Objects +## `AsyncConfigure` ```python -class AsyncConfigure() +AsyncConfigure(*, callback_id, client, body) ``` `configure()` utility to send the modal view in Workflow Builder. @@ -39,9 +39,3 @@ app.step(ws) ``` Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details. - -#### \_\_init\_\_ - -```python -def __init__(*, callback_id: str, client: AsyncWebClient, body: dict) -``` diff --git a/docs/english/reference/workflows/step/utilities/async_fail.md b/docs/english/reference/workflows/step/utilities/async_fail.md index cfadf7b0d..3f4d2f12e 100644 --- a/docs/english/reference/workflows/step/utilities/async_fail.md +++ b/docs/english/reference/workflows/step/utilities/async_fail.md @@ -3,10 +3,10 @@ sidebar_label: async_fail title: slack_bolt.workflows.step.utilities.async_fail --- -## AsyncFail Objects +## `AsyncFail` ```python -class AsyncFail() +AsyncFail(*, client, body) ``` `fail()` utility to tell Slack the execution failure of a step from app. @@ -29,9 +29,3 @@ app.step(ws) This utility is a thin wrapper of workflows.stepFailed API method. Refer to https://api.slack.com/methods/workflows.stepFailed for details. - -#### \_\_init\_\_ - -```python -def __init__(*, client: AsyncWebClient, body: dict) -``` diff --git a/docs/english/reference/workflows/step/utilities/async_update.md b/docs/english/reference/workflows/step/utilities/async_update.md index 7a761e4e9..0c7f916ae 100644 --- a/docs/english/reference/workflows/step/utilities/async_update.md +++ b/docs/english/reference/workflows/step/utilities/async_update.md @@ -3,10 +3,10 @@ sidebar_label: async_update title: slack_bolt.workflows.step.utilities.async_update --- -## AsyncUpdate Objects +## `AsyncUpdate` ```python -class AsyncUpdate() +AsyncUpdate(*, client, body) ``` `update()` utility to tell Slack the processing results of a `save` listener. @@ -48,9 +48,3 @@ app.step(ws) This utility is a thin wrapper of workflows.stepFailed API method. Refer to https://api.slack.com/methods/workflows.updateStep for details. - -#### \_\_init\_\_ - -```python -def __init__(*, client: AsyncWebClient, body: dict) -``` diff --git a/docs/english/reference/workflows/step/utilities/complete.md b/docs/english/reference/workflows/step/utilities/complete.md index 624901495..a6d27577f 100644 --- a/docs/english/reference/workflows/step/utilities/complete.md +++ b/docs/english/reference/workflows/step/utilities/complete.md @@ -3,10 +3,10 @@ sidebar_label: complete title: slack_bolt.workflows.step.utilities.complete --- -## Complete Objects +## `Complete` ```python -class Complete() +Complete(*, client, body) ``` `complete()` utility to tell Slack the completion of a step from app execution. @@ -32,9 +32,3 @@ app.step(ws) This utility is a thin wrapper of workflows.stepCompleted API method. Refer to https://api.slack.com/methods/workflows.stepCompleted for details. - -#### \_\_init\_\_ - -```python -def __init__(*, client: WebClient, body: dict) -``` diff --git a/docs/english/reference/workflows/step/utilities/configure.md b/docs/english/reference/workflows/step/utilities/configure.md index bc33f857a..055d8ad2e 100644 --- a/docs/english/reference/workflows/step/utilities/configure.md +++ b/docs/english/reference/workflows/step/utilities/configure.md @@ -3,10 +3,10 @@ sidebar_label: configure title: slack_bolt.workflows.step.utilities.configure --- -## Configure Objects +## `Configure` ```python -class Configure() +Configure(*, callback_id, client, body) ``` `configure()` utility to send the modal view in Workflow Builder. @@ -39,9 +39,3 @@ app.step(ws) ``` Refer to https://docs.slack.dev/legacy/legacy-steps-from-apps/ for details. - -#### \_\_init\_\_ - -```python -def __init__(*, callback_id: str, client: WebClient, body: dict) -``` diff --git a/docs/english/reference/workflows/step/utilities/fail.md b/docs/english/reference/workflows/step/utilities/fail.md index ccf3c6fec..156f31d7d 100644 --- a/docs/english/reference/workflows/step/utilities/fail.md +++ b/docs/english/reference/workflows/step/utilities/fail.md @@ -3,10 +3,10 @@ sidebar_label: fail title: slack_bolt.workflows.step.utilities.fail --- -## Fail Objects +## `Fail` ```python -class Fail() +Fail(*, client, body) ``` `fail()` utility to tell Slack the execution failure of a step from app. @@ -29,9 +29,3 @@ app.step(ws) This utility is a thin wrapper of workflows.stepFailed API method. Refer to https://api.slack.com/methods/workflows.stepFailed for details. - -#### \_\_init\_\_ - -```python -def __init__(*, client: WebClient, body: dict) -``` diff --git a/docs/english/reference/workflows/step/utilities/update.md b/docs/english/reference/workflows/step/utilities/update.md index 066f89be3..f65b8d65f 100644 --- a/docs/english/reference/workflows/step/utilities/update.md +++ b/docs/english/reference/workflows/step/utilities/update.md @@ -3,10 +3,10 @@ sidebar_label: update title: slack_bolt.workflows.step.utilities.update --- -## Update Objects +## `Update` ```python -class Update() +Update(*, client, body) ``` `update()` utility to tell Slack the processing results of a `save` listener. @@ -48,9 +48,3 @@ app.step(ws) This utility is a thin wrapper of workflows.stepFailed API method. Refer to https://api.slack.com/methods/workflows.updateStep for details. - -#### \_\_init\_\_ - -```python -def __init__(*, client: WebClient, body: dict) -``` diff --git a/docs/english/reference_redirects.json b/docs/english/reference_redirects.json deleted file mode 100644 index f14a9c800..000000000 --- a/docs/english/reference_redirects.json +++ /dev/null @@ -1,236 +0,0 @@ -{ - "/tools/bolt-python/reference/adapter/aiohttp/index.html": "/tools/bolt-python/reference/adapter/aiohttp", - "/tools/bolt-python/reference/adapter/asgi/aiohttp/index.html": "/tools/bolt-python/reference/adapter/asgi/aiohttp", - "/tools/bolt-python/reference/adapter/asgi/async_handler.html": "/tools/bolt-python/reference/adapter/asgi/async_handler", - "/tools/bolt-python/reference/adapter/asgi/base_handler.html": "/tools/bolt-python/reference/adapter/asgi/base_handler", - "/tools/bolt-python/reference/adapter/asgi/builtin/index.html": "/tools/bolt-python/reference/adapter/asgi/builtin", - "/tools/bolt-python/reference/adapter/asgi/http_request.html": "/tools/bolt-python/reference/adapter/asgi/http_request", - "/tools/bolt-python/reference/adapter/asgi/http_response.html": "/tools/bolt-python/reference/adapter/asgi/http_response", - "/tools/bolt-python/reference/adapter/asgi/index.html": "/tools/bolt-python/reference/adapter/asgi", - "/tools/bolt-python/reference/adapter/asgi/utils.html": "/tools/bolt-python/reference/adapter/asgi/utils", - "/tools/bolt-python/reference/adapter/aws_lambda/chalice_handler.html": "/tools/bolt-python/reference/adapter/aws_lambda/chalice_handler", - "/tools/bolt-python/reference/adapter/aws_lambda/chalice_lazy_listener_runner.html": "/tools/bolt-python/reference/adapter/aws_lambda/chalice_lazy_listener_runner", - "/tools/bolt-python/reference/adapter/aws_lambda/handler.html": "/tools/bolt-python/reference/adapter/aws_lambda/handler", - "/tools/bolt-python/reference/adapter/aws_lambda/index.html": "/tools/bolt-python/reference/adapter/aws_lambda", - "/tools/bolt-python/reference/adapter/aws_lambda/internals.html": "/tools/bolt-python/reference/adapter/aws_lambda/internals", - "/tools/bolt-python/reference/adapter/aws_lambda/lambda_s3_oauth_flow.html": "/tools/bolt-python/reference/adapter/aws_lambda/lambda_s3_oauth_flow", - "/tools/bolt-python/reference/adapter/aws_lambda/lazy_listener_runner.html": "/tools/bolt-python/reference/adapter/aws_lambda/lazy_listener_runner", - "/tools/bolt-python/reference/adapter/aws_lambda/local_lambda_client.html": "/tools/bolt-python/reference/adapter/aws_lambda/local_lambda_client", - "/tools/bolt-python/reference/adapter/bottle/handler.html": "/tools/bolt-python/reference/adapter/bottle/handler", - "/tools/bolt-python/reference/adapter/bottle/index.html": "/tools/bolt-python/reference/adapter/bottle", - "/tools/bolt-python/reference/adapter/cherrypy/handler.html": "/tools/bolt-python/reference/adapter/cherrypy/handler", - "/tools/bolt-python/reference/adapter/cherrypy/index.html": "/tools/bolt-python/reference/adapter/cherrypy", - "/tools/bolt-python/reference/adapter/django/handler.html": "/tools/bolt-python/reference/adapter/django/handler", - "/tools/bolt-python/reference/adapter/django/index.html": "/tools/bolt-python/reference/adapter/django", - "/tools/bolt-python/reference/adapter/falcon/async_resource.html": "/tools/bolt-python/reference/adapter/falcon/async_resource", - "/tools/bolt-python/reference/adapter/falcon/index.html": "/tools/bolt-python/reference/adapter/falcon", - "/tools/bolt-python/reference/adapter/falcon/resource.html": "/tools/bolt-python/reference/adapter/falcon/resource", - "/tools/bolt-python/reference/adapter/fastapi/async_handler.html": "/tools/bolt-python/reference/adapter/fastapi/async_handler", - "/tools/bolt-python/reference/adapter/fastapi/index.html": "/tools/bolt-python/reference/adapter/fastapi", - "/tools/bolt-python/reference/adapter/flask/handler.html": "/tools/bolt-python/reference/adapter/flask/handler", - "/tools/bolt-python/reference/adapter/flask/index.html": "/tools/bolt-python/reference/adapter/flask", - "/tools/bolt-python/reference/adapter/google_cloud_functions/handler.html": "/tools/bolt-python/reference/adapter/google_cloud_functions/handler", - "/tools/bolt-python/reference/adapter/google_cloud_functions/index.html": "/tools/bolt-python/reference/adapter/google_cloud_functions", - "/tools/bolt-python/reference/adapter/index.html": "/tools/bolt-python/reference/adapter", - "/tools/bolt-python/reference/adapter/pyramid/handler.html": "/tools/bolt-python/reference/adapter/pyramid/handler", - "/tools/bolt-python/reference/adapter/pyramid/index.html": "/tools/bolt-python/reference/adapter/pyramid", - "/tools/bolt-python/reference/adapter/sanic/async_handler.html": "/tools/bolt-python/reference/adapter/sanic/async_handler", - "/tools/bolt-python/reference/adapter/sanic/index.html": "/tools/bolt-python/reference/adapter/sanic", - "/tools/bolt-python/reference/adapter/socket_mode/aiohttp/index.html": "/tools/bolt-python/reference/adapter/socket_mode/aiohttp", - "/tools/bolt-python/reference/adapter/socket_mode/async_base_handler.html": "/tools/bolt-python/reference/adapter/socket_mode/async_base_handler", - "/tools/bolt-python/reference/adapter/socket_mode/async_handler.html": "/tools/bolt-python/reference/adapter/socket_mode/async_handler", - "/tools/bolt-python/reference/adapter/socket_mode/async_internals.html": "/tools/bolt-python/reference/adapter/socket_mode/async_internals", - "/tools/bolt-python/reference/adapter/socket_mode/base_handler.html": "/tools/bolt-python/reference/adapter/socket_mode/base_handler", - "/tools/bolt-python/reference/adapter/socket_mode/builtin/index.html": "/tools/bolt-python/reference/adapter/socket_mode/builtin", - "/tools/bolt-python/reference/adapter/socket_mode/index.html": "/tools/bolt-python/reference/adapter/socket_mode", - "/tools/bolt-python/reference/adapter/socket_mode/internals.html": "/tools/bolt-python/reference/adapter/socket_mode/internals", - "/tools/bolt-python/reference/adapter/socket_mode/websocket_client/index.html": "/tools/bolt-python/reference/adapter/socket_mode/websocket_client", - "/tools/bolt-python/reference/adapter/socket_mode/websockets/index.html": "/tools/bolt-python/reference/adapter/socket_mode/websockets", - "/tools/bolt-python/reference/adapter/starlette/async_handler.html": "/tools/bolt-python/reference/adapter/starlette/async_handler", - "/tools/bolt-python/reference/adapter/starlette/handler.html": "/tools/bolt-python/reference/adapter/starlette/handler", - "/tools/bolt-python/reference/adapter/starlette/index.html": "/tools/bolt-python/reference/adapter/starlette", - "/tools/bolt-python/reference/adapter/tornado/async_handler.html": "/tools/bolt-python/reference/adapter/tornado/async_handler", - "/tools/bolt-python/reference/adapter/tornado/handler.html": "/tools/bolt-python/reference/adapter/tornado/handler", - "/tools/bolt-python/reference/adapter/tornado/index.html": "/tools/bolt-python/reference/adapter/tornado", - "/tools/bolt-python/reference/adapter/wsgi/handler.html": "/tools/bolt-python/reference/adapter/wsgi/handler", - "/tools/bolt-python/reference/adapter/wsgi/http_request.html": "/tools/bolt-python/reference/adapter/wsgi/http_request", - "/tools/bolt-python/reference/adapter/wsgi/http_response.html": "/tools/bolt-python/reference/adapter/wsgi/http_response", - "/tools/bolt-python/reference/adapter/wsgi/index.html": "/tools/bolt-python/reference/adapter/wsgi", - "/tools/bolt-python/reference/adapter/wsgi/internals.html": "/tools/bolt-python/reference/adapter/wsgi/internals", - "/tools/bolt-python/reference/app/app.html": "/tools/bolt-python/reference/app/app", - "/tools/bolt-python/reference/app/async_app.html": "/tools/bolt-python/reference/app/async_app", - "/tools/bolt-python/reference/app/async_server.html": "/tools/bolt-python/reference/app/async_server", - "/tools/bolt-python/reference/app/index.html": "/tools/bolt-python/reference/app", - "/tools/bolt-python/reference/async_app.html": "/tools/bolt-python/reference/async_app", - "/tools/bolt-python/reference/authorization/async_authorize.html": "/tools/bolt-python/reference/authorization/async_authorize", - "/tools/bolt-python/reference/authorization/async_authorize_args.html": "/tools/bolt-python/reference/authorization/async_authorize_args", - "/tools/bolt-python/reference/authorization/authorize.html": "/tools/bolt-python/reference/authorization/authorize", - "/tools/bolt-python/reference/authorization/authorize_args.html": "/tools/bolt-python/reference/authorization/authorize_args", - "/tools/bolt-python/reference/authorization/authorize_result.html": "/tools/bolt-python/reference/authorization/authorize_result", - "/tools/bolt-python/reference/authorization/index.html": "/tools/bolt-python/reference/authorization", - "/tools/bolt-python/reference/context/ack/ack.html": "/tools/bolt-python/reference/context/ack/ack", - "/tools/bolt-python/reference/context/ack/async_ack.html": "/tools/bolt-python/reference/context/ack/async_ack", - "/tools/bolt-python/reference/context/ack/index.html": "/tools/bolt-python/reference/context/ack", - "/tools/bolt-python/reference/context/ack/internals.html": "/tools/bolt-python/reference/context/ack/internals", - "/tools/bolt-python/reference/context/assistant/assistant_utilities.html": "/tools/bolt-python/reference/context/assistant/assistant_utilities", - "/tools/bolt-python/reference/context/assistant/async_assistant_utilities.html": "/tools/bolt-python/reference/context/assistant/async_assistant_utilities", - "/tools/bolt-python/reference/context/assistant/index.html": "/tools/bolt-python/reference/context/assistant", - "/tools/bolt-python/reference/context/assistant/internals.html": "/tools/bolt-python/reference/context/assistant/internals", - "/tools/bolt-python/reference/context/assistant/thread_context/index.html": "/tools/bolt-python/reference/context/assistant/thread_context", - "/tools/bolt-python/reference/context/assistant/thread_context_store/async_store.html": "/tools/bolt-python/reference/context/assistant/thread_context_store/async_store", - "/tools/bolt-python/reference/context/assistant/thread_context_store/default_async_store.html": "/tools/bolt-python/reference/context/assistant/thread_context_store/default_async_store", - "/tools/bolt-python/reference/context/assistant/thread_context_store/default_store.html": "/tools/bolt-python/reference/context/assistant/thread_context_store/default_store", - "/tools/bolt-python/reference/context/assistant/thread_context_store/file/index.html": "/tools/bolt-python/reference/context/assistant/thread_context_store/file", - "/tools/bolt-python/reference/context/assistant/thread_context_store/index.html": "/tools/bolt-python/reference/context/assistant/thread_context_store", - "/tools/bolt-python/reference/context/assistant/thread_context_store/store.html": "/tools/bolt-python/reference/context/assistant/thread_context_store/store", - "/tools/bolt-python/reference/context/async_context.html": "/tools/bolt-python/reference/context/async_context", - "/tools/bolt-python/reference/context/base_context.html": "/tools/bolt-python/reference/context/base_context", - "/tools/bolt-python/reference/context/complete/async_complete.html": "/tools/bolt-python/reference/context/complete/async_complete", - "/tools/bolt-python/reference/context/complete/complete.html": "/tools/bolt-python/reference/context/complete/complete", - "/tools/bolt-python/reference/context/complete/index.html": "/tools/bolt-python/reference/context/complete", - "/tools/bolt-python/reference/context/context.html": "/tools/bolt-python/reference/context/context", - "/tools/bolt-python/reference/context/fail/async_fail.html": "/tools/bolt-python/reference/context/fail/async_fail", - "/tools/bolt-python/reference/context/fail/fail.html": "/tools/bolt-python/reference/context/fail/fail", - "/tools/bolt-python/reference/context/fail/index.html": "/tools/bolt-python/reference/context/fail", - "/tools/bolt-python/reference/context/get_thread_context/async_get_thread_context.html": "/tools/bolt-python/reference/context/get_thread_context/async_get_thread_context", - "/tools/bolt-python/reference/context/get_thread_context/get_thread_context.html": "/tools/bolt-python/reference/context/get_thread_context/get_thread_context", - "/tools/bolt-python/reference/context/get_thread_context/index.html": "/tools/bolt-python/reference/context/get_thread_context", - "/tools/bolt-python/reference/context/index.html": "/tools/bolt-python/reference/context", - "/tools/bolt-python/reference/context/respond/async_respond.html": "/tools/bolt-python/reference/context/respond/async_respond", - "/tools/bolt-python/reference/context/respond/index.html": "/tools/bolt-python/reference/context/respond", - "/tools/bolt-python/reference/context/respond/internals.html": "/tools/bolt-python/reference/context/respond/internals", - "/tools/bolt-python/reference/context/respond/respond.html": "/tools/bolt-python/reference/context/respond/respond", - "/tools/bolt-python/reference/context/save_thread_context/async_save_thread_context.html": "/tools/bolt-python/reference/context/save_thread_context/async_save_thread_context", - "/tools/bolt-python/reference/context/save_thread_context/index.html": "/tools/bolt-python/reference/context/save_thread_context", - "/tools/bolt-python/reference/context/save_thread_context/save_thread_context.html": "/tools/bolt-python/reference/context/save_thread_context/save_thread_context", - "/tools/bolt-python/reference/context/say/async_say.html": "/tools/bolt-python/reference/context/say/async_say", - "/tools/bolt-python/reference/context/say/index.html": "/tools/bolt-python/reference/context/say", - "/tools/bolt-python/reference/context/say/internals.html": "/tools/bolt-python/reference/context/say/internals", - "/tools/bolt-python/reference/context/say/say.html": "/tools/bolt-python/reference/context/say/say", - "/tools/bolt-python/reference/context/say_stream/async_say_stream.html": "/tools/bolt-python/reference/context/say_stream/async_say_stream", - "/tools/bolt-python/reference/context/say_stream/index.html": "/tools/bolt-python/reference/context/say_stream", - "/tools/bolt-python/reference/context/say_stream/say_stream.html": "/tools/bolt-python/reference/context/say_stream/say_stream", - "/tools/bolt-python/reference/context/set_status/async_set_status.html": "/tools/bolt-python/reference/context/set_status/async_set_status", - "/tools/bolt-python/reference/context/set_status/index.html": "/tools/bolt-python/reference/context/set_status", - "/tools/bolt-python/reference/context/set_status/set_status.html": "/tools/bolt-python/reference/context/set_status/set_status", - "/tools/bolt-python/reference/context/set_suggested_prompts/async_set_suggested_prompts.html": "/tools/bolt-python/reference/context/set_suggested_prompts/async_set_suggested_prompts", - "/tools/bolt-python/reference/context/set_suggested_prompts/index.html": "/tools/bolt-python/reference/context/set_suggested_prompts", - "/tools/bolt-python/reference/context/set_suggested_prompts/set_suggested_prompts.html": "/tools/bolt-python/reference/context/set_suggested_prompts/set_suggested_prompts", - "/tools/bolt-python/reference/context/set_title/async_set_title.html": "/tools/bolt-python/reference/context/set_title/async_set_title", - "/tools/bolt-python/reference/context/set_title/index.html": "/tools/bolt-python/reference/context/set_title", - "/tools/bolt-python/reference/context/set_title/set_title.html": "/tools/bolt-python/reference/context/set_title/set_title", - "/tools/bolt-python/reference/error/index.html": "/tools/bolt-python/reference/error", - "/tools/bolt-python/reference/index.html": "/tools/bolt-python/reference", - "/tools/bolt-python/reference/kwargs_injection/args.html": "/tools/bolt-python/reference/kwargs_injection/args", - "/tools/bolt-python/reference/kwargs_injection/async_args.html": "/tools/bolt-python/reference/kwargs_injection/async_args", - "/tools/bolt-python/reference/kwargs_injection/async_utils.html": "/tools/bolt-python/reference/kwargs_injection/async_utils", - "/tools/bolt-python/reference/kwargs_injection/index.html": "/tools/bolt-python/reference/kwargs_injection", - "/tools/bolt-python/reference/kwargs_injection/utils.html": "/tools/bolt-python/reference/kwargs_injection/utils", - "/tools/bolt-python/reference/lazy_listener/async_internals.html": "/tools/bolt-python/reference/lazy_listener/async_internals", - "/tools/bolt-python/reference/lazy_listener/async_runner.html": "/tools/bolt-python/reference/lazy_listener/async_runner", - "/tools/bolt-python/reference/lazy_listener/asyncio_runner.html": "/tools/bolt-python/reference/lazy_listener/asyncio_runner", - "/tools/bolt-python/reference/lazy_listener/index.html": "/tools/bolt-python/reference/lazy_listener", - "/tools/bolt-python/reference/lazy_listener/internals.html": "/tools/bolt-python/reference/lazy_listener/internals", - "/tools/bolt-python/reference/lazy_listener/runner.html": "/tools/bolt-python/reference/lazy_listener/runner", - "/tools/bolt-python/reference/lazy_listener/thread_runner.html": "/tools/bolt-python/reference/lazy_listener/thread_runner", - "/tools/bolt-python/reference/listener/async_builtins.html": "/tools/bolt-python/reference/listener/async_builtins", - "/tools/bolt-python/reference/listener/async_listener.html": "/tools/bolt-python/reference/listener/async_listener", - "/tools/bolt-python/reference/listener/async_listener_completion_handler.html": "/tools/bolt-python/reference/listener/async_listener_completion_handler", - "/tools/bolt-python/reference/listener/async_listener_error_handler.html": "/tools/bolt-python/reference/listener/async_listener_error_handler", - "/tools/bolt-python/reference/listener/async_listener_start_handler.html": "/tools/bolt-python/reference/listener/async_listener_start_handler", - "/tools/bolt-python/reference/listener/asyncio_runner.html": "/tools/bolt-python/reference/listener/asyncio_runner", - "/tools/bolt-python/reference/listener/builtins.html": "/tools/bolt-python/reference/listener/builtins", - "/tools/bolt-python/reference/listener/custom_listener.html": "/tools/bolt-python/reference/listener/custom_listener", - "/tools/bolt-python/reference/listener/index.html": "/tools/bolt-python/reference/listener", - "/tools/bolt-python/reference/listener/listener.html": "/tools/bolt-python/reference/listener/listener", - "/tools/bolt-python/reference/listener/listener_completion_handler.html": "/tools/bolt-python/reference/listener/listener_completion_handler", - "/tools/bolt-python/reference/listener/listener_error_handler.html": "/tools/bolt-python/reference/listener/listener_error_handler", - "/tools/bolt-python/reference/listener/listener_start_handler.html": "/tools/bolt-python/reference/listener/listener_start_handler", - "/tools/bolt-python/reference/listener/thread_runner.html": "/tools/bolt-python/reference/listener/thread_runner", - "/tools/bolt-python/reference/listener_matcher/async_builtins.html": "/tools/bolt-python/reference/listener_matcher/async_builtins", - "/tools/bolt-python/reference/listener_matcher/async_listener_matcher.html": "/tools/bolt-python/reference/listener_matcher/async_listener_matcher", - "/tools/bolt-python/reference/listener_matcher/builtins.html": "/tools/bolt-python/reference/listener_matcher/builtins", - "/tools/bolt-python/reference/listener_matcher/custom_listener_matcher.html": "/tools/bolt-python/reference/listener_matcher/custom_listener_matcher", - "/tools/bolt-python/reference/listener_matcher/index.html": "/tools/bolt-python/reference/listener_matcher", - "/tools/bolt-python/reference/listener_matcher/listener_matcher.html": "/tools/bolt-python/reference/listener_matcher/listener_matcher", - "/tools/bolt-python/reference/logger/index.html": "/tools/bolt-python/reference/logger", - "/tools/bolt-python/reference/logger/messages.html": "/tools/bolt-python/reference/logger/messages", - "/tools/bolt-python/reference/middleware/assistant/assistant.html": "/tools/bolt-python/reference/middleware/assistant/assistant", - "/tools/bolt-python/reference/middleware/assistant/async_assistant.html": "/tools/bolt-python/reference/middleware/assistant/async_assistant", - "/tools/bolt-python/reference/middleware/assistant/index.html": "/tools/bolt-python/reference/middleware/assistant", - "/tools/bolt-python/reference/middleware/async_builtins.html": "/tools/bolt-python/reference/middleware/async_builtins", - "/tools/bolt-python/reference/middleware/async_custom_middleware.html": "/tools/bolt-python/reference/middleware/async_custom_middleware", - "/tools/bolt-python/reference/middleware/async_middleware.html": "/tools/bolt-python/reference/middleware/async_middleware", - "/tools/bolt-python/reference/middleware/async_middleware_error_handler.html": "/tools/bolt-python/reference/middleware/async_middleware_error_handler", - "/tools/bolt-python/reference/middleware/attaching_conversation_kwargs/async_attaching_conversation_kwargs.html": "/tools/bolt-python/reference/middleware/attaching_conversation_kwargs/async_attaching_conversation_kwargs", - "/tools/bolt-python/reference/middleware/attaching_conversation_kwargs/attaching_conversation_kwargs.html": "/tools/bolt-python/reference/middleware/attaching_conversation_kwargs/attaching_conversation_kwargs", - "/tools/bolt-python/reference/middleware/attaching_conversation_kwargs/index.html": "/tools/bolt-python/reference/middleware/attaching_conversation_kwargs", - "/tools/bolt-python/reference/middleware/attaching_function_token/async_attaching_function_token.html": "/tools/bolt-python/reference/middleware/attaching_function_token/async_attaching_function_token", - "/tools/bolt-python/reference/middleware/attaching_function_token/attaching_function_token.html": "/tools/bolt-python/reference/middleware/attaching_function_token/attaching_function_token", - "/tools/bolt-python/reference/middleware/attaching_function_token/index.html": "/tools/bolt-python/reference/middleware/attaching_function_token", - "/tools/bolt-python/reference/middleware/authorization/async_authorization.html": "/tools/bolt-python/reference/middleware/authorization/async_authorization", - "/tools/bolt-python/reference/middleware/authorization/async_internals.html": "/tools/bolt-python/reference/middleware/authorization/async_internals", - "/tools/bolt-python/reference/middleware/authorization/async_multi_teams_authorization.html": "/tools/bolt-python/reference/middleware/authorization/async_multi_teams_authorization", - "/tools/bolt-python/reference/middleware/authorization/async_single_team_authorization.html": "/tools/bolt-python/reference/middleware/authorization/async_single_team_authorization", - "/tools/bolt-python/reference/middleware/authorization/authorization.html": "/tools/bolt-python/reference/middleware/authorization/authorization", - "/tools/bolt-python/reference/middleware/authorization/index.html": "/tools/bolt-python/reference/middleware/authorization", - "/tools/bolt-python/reference/middleware/authorization/internals.html": "/tools/bolt-python/reference/middleware/authorization/internals", - "/tools/bolt-python/reference/middleware/authorization/multi_teams_authorization.html": "/tools/bolt-python/reference/middleware/authorization/multi_teams_authorization", - "/tools/bolt-python/reference/middleware/authorization/single_team_authorization.html": "/tools/bolt-python/reference/middleware/authorization/single_team_authorization", - "/tools/bolt-python/reference/middleware/custom_middleware.html": "/tools/bolt-python/reference/middleware/custom_middleware", - "/tools/bolt-python/reference/middleware/ignoring_self_events/async_ignoring_self_events.html": "/tools/bolt-python/reference/middleware/ignoring_self_events/async_ignoring_self_events", - "/tools/bolt-python/reference/middleware/ignoring_self_events/ignoring_self_events.html": "/tools/bolt-python/reference/middleware/ignoring_self_events/ignoring_self_events", - "/tools/bolt-python/reference/middleware/ignoring_self_events/index.html": "/tools/bolt-python/reference/middleware/ignoring_self_events", - "/tools/bolt-python/reference/middleware/index.html": "/tools/bolt-python/reference/middleware", - "/tools/bolt-python/reference/middleware/message_listener_matches/async_message_listener_matches.html": "/tools/bolt-python/reference/middleware/message_listener_matches/async_message_listener_matches", - "/tools/bolt-python/reference/middleware/message_listener_matches/index.html": "/tools/bolt-python/reference/middleware/message_listener_matches", - "/tools/bolt-python/reference/middleware/message_listener_matches/message_listener_matches.html": "/tools/bolt-python/reference/middleware/message_listener_matches/message_listener_matches", - "/tools/bolt-python/reference/middleware/middleware.html": "/tools/bolt-python/reference/middleware/middleware", - "/tools/bolt-python/reference/middleware/middleware_error_handler.html": "/tools/bolt-python/reference/middleware/middleware_error_handler", - "/tools/bolt-python/reference/middleware/request_verification/async_request_verification.html": "/tools/bolt-python/reference/middleware/request_verification/async_request_verification", - "/tools/bolt-python/reference/middleware/request_verification/index.html": "/tools/bolt-python/reference/middleware/request_verification", - "/tools/bolt-python/reference/middleware/request_verification/request_verification.html": "/tools/bolt-python/reference/middleware/request_verification/request_verification", - "/tools/bolt-python/reference/middleware/ssl_check/async_ssl_check.html": "/tools/bolt-python/reference/middleware/ssl_check/async_ssl_check", - "/tools/bolt-python/reference/middleware/ssl_check/index.html": "/tools/bolt-python/reference/middleware/ssl_check", - "/tools/bolt-python/reference/middleware/ssl_check/ssl_check.html": "/tools/bolt-python/reference/middleware/ssl_check/ssl_check", - "/tools/bolt-python/reference/middleware/url_verification/async_url_verification.html": "/tools/bolt-python/reference/middleware/url_verification/async_url_verification", - "/tools/bolt-python/reference/middleware/url_verification/index.html": "/tools/bolt-python/reference/middleware/url_verification", - "/tools/bolt-python/reference/middleware/url_verification/url_verification.html": "/tools/bolt-python/reference/middleware/url_verification/url_verification", - "/tools/bolt-python/reference/oauth/async_callback_options.html": "/tools/bolt-python/reference/oauth/async_callback_options", - "/tools/bolt-python/reference/oauth/async_internals.html": "/tools/bolt-python/reference/oauth/async_internals", - "/tools/bolt-python/reference/oauth/async_oauth_flow.html": "/tools/bolt-python/reference/oauth/async_oauth_flow", - "/tools/bolt-python/reference/oauth/async_oauth_settings.html": "/tools/bolt-python/reference/oauth/async_oauth_settings", - "/tools/bolt-python/reference/oauth/callback_options.html": "/tools/bolt-python/reference/oauth/callback_options", - "/tools/bolt-python/reference/oauth/index.html": "/tools/bolt-python/reference/oauth", - "/tools/bolt-python/reference/oauth/internals.html": "/tools/bolt-python/reference/oauth/internals", - "/tools/bolt-python/reference/oauth/oauth_flow.html": "/tools/bolt-python/reference/oauth/oauth_flow", - "/tools/bolt-python/reference/oauth/oauth_settings.html": "/tools/bolt-python/reference/oauth/oauth_settings", - "/tools/bolt-python/reference/request/async_internals.html": "/tools/bolt-python/reference/request/async_internals", - "/tools/bolt-python/reference/request/async_request.html": "/tools/bolt-python/reference/request/async_request", - "/tools/bolt-python/reference/request/index.html": "/tools/bolt-python/reference/request", - "/tools/bolt-python/reference/request/internals.html": "/tools/bolt-python/reference/request/internals", - "/tools/bolt-python/reference/request/payload_utils.html": "/tools/bolt-python/reference/request/payload_utils", - "/tools/bolt-python/reference/request/request.html": "/tools/bolt-python/reference/request/request", - "/tools/bolt-python/reference/response/index.html": "/tools/bolt-python/reference/response", - "/tools/bolt-python/reference/response/response.html": "/tools/bolt-python/reference/response/response", - "/tools/bolt-python/reference/util/async_utils.html": "/tools/bolt-python/reference/util/async_utils", - "/tools/bolt-python/reference/util/index.html": "/tools/bolt-python/reference/util", - "/tools/bolt-python/reference/util/utils.html": "/tools/bolt-python/reference/util/utils", - "/tools/bolt-python/reference/version.html": "/tools/bolt-python/reference/version", - "/tools/bolt-python/reference/workflows/index.html": "/tools/bolt-python/reference/workflows", - "/tools/bolt-python/reference/workflows/step/async_step.html": "/tools/bolt-python/reference/workflows/step/async_step", - "/tools/bolt-python/reference/workflows/step/async_step_middleware.html": "/tools/bolt-python/reference/workflows/step/async_step_middleware", - "/tools/bolt-python/reference/workflows/step/index.html": "/tools/bolt-python/reference/workflows/step", - "/tools/bolt-python/reference/workflows/step/internals.html": "/tools/bolt-python/reference/workflows/step/internals", - "/tools/bolt-python/reference/workflows/step/step.html": "/tools/bolt-python/reference/workflows/step/step", - "/tools/bolt-python/reference/workflows/step/step_middleware.html": "/tools/bolt-python/reference/workflows/step/step_middleware", - "/tools/bolt-python/reference/workflows/step/utilities/async_complete.html": "/tools/bolt-python/reference/workflows/step/utilities/async_complete", - "/tools/bolt-python/reference/workflows/step/utilities/async_configure.html": "/tools/bolt-python/reference/workflows/step/utilities/async_configure", - "/tools/bolt-python/reference/workflows/step/utilities/async_fail.html": "/tools/bolt-python/reference/workflows/step/utilities/async_fail", - "/tools/bolt-python/reference/workflows/step/utilities/async_update.html": "/tools/bolt-python/reference/workflows/step/utilities/async_update", - "/tools/bolt-python/reference/workflows/step/utilities/complete.html": "/tools/bolt-python/reference/workflows/step/utilities/complete", - "/tools/bolt-python/reference/workflows/step/utilities/configure.html": "/tools/bolt-python/reference/workflows/step/utilities/configure", - "/tools/bolt-python/reference/workflows/step/utilities/fail.html": "/tools/bolt-python/reference/workflows/step/utilities/fail", - "/tools/bolt-python/reference/workflows/step/utilities/index.html": "/tools/bolt-python/reference/workflows/step/utilities", - "/tools/bolt-python/reference/workflows/step/utilities/update.html": "/tools/bolt-python/reference/workflows/step/utilities/update" -} \ No newline at end of file diff --git a/requirements/docs.txt b/requirements/docs.txt new file mode 100644 index 000000000..b57cc690d --- /dev/null +++ b/requirements/docs.txt @@ -0,0 +1,10 @@ +# pip install -r requirements/docs.txt +# Note: doc-gen only; runs on the latest supported Python (see scripts/generate_api_docs.sh). +# Note: pinned so the committed reference tree under docs/english/reference stays reproducible; +# an unpinned griffe/griffe2md can silently shift the generated Markdown (and fail the drift CI job). + +# griffe2md -- renders griffe objects to Markdown (pulls in griffelib + jinja2 + mdformat) +griffe2md==1.5.0 + +# griffelib -- griffe's PyPI distribution (import name `griffe`); pinned to match griffe2md's rendering +griffelib==2.2.0 diff --git a/requirements/documentation.txt b/requirements/documentation.txt deleted file mode 100644 index 75e2bcb0a..000000000 --- a/requirements/documentation.txt +++ /dev/null @@ -1,8 +0,0 @@ -# pip install -r requirements/documentation.txt - -# griffe -# Note: doc-gen only; the generator runs on the latest supported Python (see -# scripts/generate_api_docs.sh), so no python_version markers are needed. -# Note: pinned so the committed reference tree under docs/english/reference stays -# reproducible -- an unpinned griffe can silently shift the generated Markdown. -griffe==2.2.0 diff --git a/scripts/generate_api_docs.py b/scripts/generate_api_docs.py index dde672fc0..ac2393a17 100644 --- a/scripts/generate_api_docs.py +++ b/scripts/generate_api_docs.py @@ -1,16 +1,18 @@ #!/usr/bin/env python -"""Generate the Markdown API reference for slack_bolt using griffe. +"""Generate the Markdown API reference for slack_bolt using griffe + griffe2md. -Invoked by scripts/generate_api_docs.sh. griffe (the parser behind -mkdocstrings) is used purely as the extraction engine: it loads the package, -resolves re-export aliases to their concrete definition, and parses Google-style -docstrings into structured sections. This module renders that structured data -into the Docusaurus-flavored Markdown tree the docs site imports. +Invoked by scripts/generate_api_docs.sh. griffe loads the package, resolves +re-export aliases to their concrete definition, and parses Google-style +docstrings into structured data; griffe2md renders that data to Markdown. This +module is the thin Docusaurus adapter around griffe2md: it walks the package, +writes one Markdown page per module under ``reference/`` (packages become +``index.md``), and post-processes griffe2md's output so the docs site can +compile it as MDX. The output layout (flattened under ``reference/``, package overviews as -``index.md``) is produced directly rather than rendered and then rewritten. The -reference nav is contributed by a single ``autogenerated`` entry in -``docs/english/_sidebar.json``; this script writes only Markdown. +``index.md``) is produced directly. The reference nav is contributed by a +single ``autogenerated`` entry in ``docs/english/_sidebar.json``; this script +writes only Markdown. """ import os @@ -18,6 +20,7 @@ import shutil import griffe +from griffe2md import default_config, render_object_docs REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) @@ -32,142 +35,67 @@ # hence the prefix. SIDEBAR_DOC_ID_PREFIX = "tools/bolt-python/" -# Signatures longer than this render one parameter per line. -MAX_SIGNATURE_WIDTH = 88 - PACKAGE = "slack_bolt" # --------------------------------------------------------------------------- # -# MDX escaping +# griffe2md rendering # --------------------------------------------------------------------------- # -# Docusaurus v3 parses every .md file as MDX: a bare ``<`` reads as JSX and a -# bare ``{`` as a JS expression, either of which aborts the docs build. Escape -# those two characters in prose while leaving fenced blocks and inline code -# spans untouched. -_CODE_SPLIT_RE = re.compile(r"(```[\s\S]*?```|`[^`]*`)") - - -def _escape_mdx(text): - """Escape MDX-hazardous characters outside code spans and fenced blocks.""" - out = [] - for i, chunk in enumerate(_CODE_SPLIT_RE.split(text)): - # Odd indices are the captured code spans/blocks -- leave them verbatim. - if i % 2 == 1: - out.append(chunk) - else: - out.append(chunk.replace("<", "<").replace("{", "{")) - return "".join(out) - - -def _escape_header(name): - """Escape a name for use in a Markdown header (underscores/asterisks).""" - return name.replace("_", "\\_").replace("*", "\\*") +# griffe2md renders a griffe object to Markdown. We accept its default output +# style (``## `Name```, ``**Parameters:**``, ``- **app** (App) - ...``) and only +# adjust structural knobs so each module renders as a flat, root-less section +# that slots beneath our own front-matter and submodule links. +CONFIG = dict(default_config) +CONFIG.update( + docstring_style="google", + summary=False, + show_if_no_docstring=False, + show_submodules=False, + show_root_heading=False, + show_root_full_path=False, + show_root_members_full_path=False, + show_object_full_path=False, + heading_level=2, + # big to keep signatures single-line, so output never depends on Black. + line_length=10**9, +) + + +def _render_module(module): + """Render a module to MDX-safe Markdown via griffe2md + post-processing.""" + return _post_process(render_object_docs(module, CONFIG)) # --------------------------------------------------------------------------- # -# Signatures +# MDX-safety post-processing # --------------------------------------------------------------------------- # -_VAR_POSITIONAL = "variadic positional" -_VAR_KEYWORD = "variadic keyword" -_POSITIONAL_ONLY = "positional-only" -_KEYWORD_ONLY = "keyword-only" - - -def _parameter_source(param): - """Render a single parameter as Python source (``name: type = default``).""" - if param.kind.value == _VAR_POSITIONAL: - text = "*" + param.name - elif param.kind.value == _VAR_KEYWORD: - text = "**" + param.name - else: - text = param.name - - annotation = str(param.annotation) if param.annotation is not None else None - default = str(param.default) if param.default is not None else None - if annotation: - text += ": " + annotation - if default is not None and param.kind.value not in (_VAR_POSITIONAL, _VAR_KEYWORD): - text += " = " + default if annotation else "=" + default - return text - - -def _parameter_list(func, drop_first_self): - """Build the ordered parameter fragments for a function, inserting the - ``/`` (positional-only) and bare ``*`` (keyword-only) separators the way - ``inspect.Signature`` does.""" - params = list(func.parameters) - if drop_first_self and params and params[0].name in ("self", "cls"): - params = params[1:] - - fragments = [] - render_pos_only_sep = False - render_kw_only_sep = True - for param in params: - kind = param.kind.value - if kind == _POSITIONAL_ONLY: - render_pos_only_sep = True - elif render_pos_only_sep: - fragments.append("/") - render_pos_only_sep = False - - if kind == _VAR_POSITIONAL: - render_kw_only_sep = False - elif kind == _KEYWORD_ONLY and render_kw_only_sep: - fragments.append("*") - render_kw_only_sep = False - - fragments.append(_parameter_source(param)) - - if render_pos_only_sep: - fragments.append("/") - return fragments - - -def _format_function_signature(func, name, is_method): - """Render a ``def``/``async def`` signature, wrapping long ones one - parameter per line.""" - prefix = "async def " if "async" in (func.labels or set()) else "def " - fragments = _parameter_list(func, drop_first_self=is_method) - returns = " -> {}".format(func.returns) if func.returns is not None else "" - - one_line = "{}{}({}){}".format(prefix, name, ", ".join(fragments), returns) - if len(one_line) <= MAX_SIGNATURE_WIDTH: - return one_line - - inner = ",\n".join(" " + fragment for fragment in fragments) - return "{}{}(\n{}){}".format(prefix, name, inner, returns) - - -def _format_classdef_signature(cls): - """Render a ``class Name(bases)`` signature.""" - bases = ", ".join(str(base) for base in cls.bases) - return "class {}({})".format(cls.name, bases) - - -def _property_signature(attr): - """Render a property as a ``@property``-decorated getter.""" - returns = " -> {}".format(attr.annotation) if attr.annotation is not None else "" - return "@property\ndef {}(){}".format(attr.name, returns) +# Docusaurus v3 parses every .md file as MDX: a bare ``<`` reads as JSX and a +# bare ``{`` as a JS expression, either of which aborts the docs build. Escape +# those two characters in prose while leaving fenced blocks and inline code +# spans untouched. +_CODE_SPLIT_RE = re.compile(r"(```[\s\S]*?```|`[^`]*`)") - -# --------------------------------------------------------------------------- # -# Docstrings -# --------------------------------------------------------------------------- # +# griffe2md wraps type annotations and base classes in ```` and links +# symbols to intra-page anchors (``#slack_bolt.App``). We render one page per +# module and emit no cross-references, so those anchors don't resolve -- strip +# the wrapper and the anchor links back to plain text +# (``[App](#slack_bolt.App)`` -> ``App``). Links to real URLs +# (``(https://...)``) are left intact. +_CODE_TAG_RE = re.compile(r"") +_ANCHOR_LINK_RE = re.compile(r"\[([^\]]+)\]\(#[^)]*\)") def _reflow_indented_code(text): - """Convert Markdown indented code blocks (4-space, RST literal-block style - used in many docstrings) into fenced ``python`` blocks. + """Convert 4-space indented docstring code blocks into fenced python blocks. A bare indented block renders without syntax highlighting and, worse, its - ``#`` comment lines can be misread as headers by some Markdown/MDX - processors. Re-emitting the block fenced removes both problems and lets - _escape_mdx leave the code verbatim. Only blocks preceded by a blank line - are treated as code, matching CommonMark (an indented run cannot interrupt - a paragraph).""" + ``<``/``{`` characters would be escaped as prose by _escape_prose. Re-emitting + the block fenced fixes highlighting and lets the code survive verbatim. Only + blocks preceded by a blank line are treated as code, matching CommonMark (an + indented run cannot interrupt a paragraph). + """ lines = text.split("\n") out = [] i = 0 @@ -208,165 +136,29 @@ def _reflow_indented_code(text): return "\n".join(out) -def _indent_continuation(text): - """Indent wrapped continuation lines of a list item by two spaces.""" - return _escape_mdx(text).replace("\n", "\n ") - - -def _render_docstring(obj, out): - """Append an object's docstring, section by section, to ``out``.""" - if not obj.docstring: - return - for section in obj.docstring.parsed: - kind = section.kind.value - if kind == "text": - out.append(_escape_mdx(_reflow_indented_code(section.value))) - out.append("") - elif kind == "parameters": - out.append("**Arguments**:") - out.append("") - for param in section.value: - typ = " _{}_".format(param.annotation) if param.annotation else "" - if param.description: - out.append("- `{}`{} - {}".format(param.name, typ, _indent_continuation(param.description))) - else: - out.append("- `{}`{}".format(param.name, typ)) - out.append("") - elif kind == "returns": - out.append("**Returns**:") - out.append("") - for ret in section.value: - bits = [] - if ret.annotation: - bits.append("`{}`".format(ret.annotation)) - if ret.description: - bits.append(_indent_continuation(ret.description)) - out.append("- " + " - ".join(bits)) - out.append("") - elif kind == "raises": - out.append("**Raises**:") - out.append("") - for exc in section.value: - typ = "`{}`".format(exc.annotation) if exc.annotation else "" - if exc.description: - out.append("- {} - {}".format(typ, _indent_continuation(exc.description))) - else: - out.append("- {}".format(typ)) - out.append("") - elif kind == "admonition": - label = (section.value.kind or "note").replace("-", " ").title() - out.append("**{}**:".format(label)) - out.append("") - out.append(_escape_mdx(_reflow_indented_code(section.value.contents))) - out.append("") - else: - # Unknown/rare section (examples, yields, ...): render its text form. - contents = str(getattr(section.value, "contents", section.value)) - out.append(_escape_mdx(_reflow_indented_code(contents))) - out.append("") - - -# --------------------------------------------------------------------------- # -# Member selection (with re-export inlining) -# --------------------------------------------------------------------------- # - - -def _is_public(name): - """Keep public names plus ``__init__`` (constructors carry the class's - ``Args:``); drop every other dunder/private name.""" - return name == "__init__" or not name.startswith("_") - - -def _inlined_export_target(alias): - """If *alias* re-exports a concrete slack_bolt class/function, return it.""" - try: - target = alias.target - except Exception: - return None - if target.canonical_path.startswith(PACKAGE + ".") and target.kind.value in ("class", "function"): - return target - return None - - -def _documented_members(parent): - """Yield ``(display_name, object)`` pairs to document under *parent*. - - Submodules are skipped (they become their own files). Aliases are inlined - only when they are declared in the module's ``__all__`` and resolve to a - concrete slack_bolt class/function, so genuine public re-exports render - inline while incidental imports do not.""" - exports = set(parent.exports or []) if parent.is_module else set() - members = [] - for name, member in parent.members.items(): - if member.is_alias: - if name in exports: - target = _inlined_export_target(member) - if target is not None: - members.append((name, target)) - continue - if member.is_module: - continue - if not _is_public(name): - continue - # Drop undocumented instance attributes (bare ``self.x = x`` assignments - # with neither a type annotation nor a docstring) -- they are - # implementation detail. Class- and module-level constants are kept. - labels = member.labels or set() - if member.kind.value == "attribute" and labels == {"instance-attribute"}: - if member.annotation is None and not member.docstring: - continue - members.append((name, member)) - return members +def _escape_prose(chunk): + """Strip griffe2md markup, then escape MDX-hazardous characters in prose. + Removes ```` wrappers and intra-page anchor links, then escapes ``<`` + and ``{``. Applied only to prose chunks, never to code. + """ + chunk = _CODE_TAG_RE.sub("", chunk) + chunk = _ANCHOR_LINK_RE.sub(r"\1", chunk) + return chunk.replace("<", "<").replace("{", "{") -# --------------------------------------------------------------------------- # -# Object rendering -# --------------------------------------------------------------------------- # +def _post_process(text): + """Make griffe2md's Markdown safe to compile as MDX. -def _render_object(display_name, obj, out): - """Append the Markdown for a single class/function/attribute to ``out``.""" - kind = obj.kind.value - - if kind == "class": - out.append("## {} Objects".format(_escape_header(obj.name))) - out.append("") - out.append("```python") - out.append(_format_classdef_signature(obj)) - out.append("```") - out.append("") - _render_docstring(obj, out) - for child_name, child in _documented_members(obj): - _render_object(child_name, child, out) - return - - if kind == "function": - is_method = obj.parent is not None and obj.parent.kind.value == "class" - out.append("#### {}".format(_escape_header(display_name))) - out.append("") - out.append("```python") - out.append(_format_function_signature(obj, display_name, is_method)) - out.append("```") - out.append("") - _render_docstring(obj, out) - return - - # Attribute -- a property renders as a getter, a plain variable as a header - # carrying its type hint (no value block). - if "property" in (obj.labels or set()): - out.append("#### {}".format(_escape_header(display_name))) - out.append("") - out.append("```python") - out.append(_property_signature(obj)) - out.append("```") - out.append("") - elif obj.annotation is not None: - out.append("#### {}: `{}`".format(_escape_header(display_name), obj.annotation)) - out.append("") - else: - out.append("#### {}".format(_escape_header(display_name))) - out.append("") - _render_docstring(obj, out) + Fence indented code so it survives verbatim, then rewrite only the prose + (fenced/inline code spans are left untouched). + """ + text = _reflow_indented_code(text) + out = [] + for i, chunk in enumerate(_CODE_SPLIT_RE.split(text)): + # Odd indices are the captured code spans/blocks -- leave them verbatim. + out.append(chunk if i % 2 else _escape_prose(chunk)) + return "".join(out).rstrip("\n") # --------------------------------------------------------------------------- # @@ -389,30 +181,17 @@ def _iter_modules(module): yield from _iter_modules(member) -def _module_docstring(module): - """Render a module's own docstring (the package/module overview), if any.""" - out = [] - _render_docstring(module, out) - return "\n".join(out).rstrip("\n") - - -def _render_body(module): - """Render a module's members (the module docstring is rendered separately - at the top of the page).""" - out = [] - for name, obj in _documented_members(module): - _render_object(name, obj, out) - return "\n".join(out).rstrip("\n") + "\n" if out else "" - - # --------------------------------------------------------------------------- # # Routes # --------------------------------------------------------------------------- # def _doc_id(rel_path, is_package): - """Docs-root doc ID for a module, e.g. ``reference/app/app`` or the package - overview ``reference/app/index``.""" + """Docs-root doc ID for a module. + + For example ``reference/app/app`` or the package overview + ``reference/app/index``. + """ if not rel_path: base = REFERENCE_SUBDIR + "/index" elif is_package: @@ -440,6 +219,7 @@ def _load_package(): PACKAGE, search_paths=[REPO_ROOT], docstring_parser=griffe.Parser.google, + resolve_aliases=True, ) @@ -459,8 +239,7 @@ def _build_pages(root): "title": dotted, "sidebar_label": sidebar_label, "doc_id": _doc_id(rel_path, is_package), - "docstring": _module_docstring(module), - "body": _render_body(module), + "content": _render_module(module), } return pages @@ -490,6 +269,10 @@ def _write_pages(pages): os.makedirs(os.path.dirname(path), exist_ok=True) frontmatter = ["---", "sidebar_label: {}".format(page["sidebar_label"]), "title: {}".format(page["title"])] + # Pin the top-level reference index to the top of its sidebar category; + # siblings have no explicit position, so any number floats it first. + if not rel_path: + frontmatter.append("sidebar_position: 1") # A module whose file is /.md collides with the folder's # index.md route; pin it with a relative slug. basename = os.path.basename(path)[: -len(".md")] @@ -499,8 +282,8 @@ def _write_pages(pages): frontmatter.append("---") body_parts = [] - if page["docstring"]: - body_parts.append(page["docstring"]) + if page["content"]: + body_parts.append(page["content"]) body_parts.append("") if page["is_package"] or not rel_path: links = _submodule_links(rel_path, pages) @@ -509,8 +292,6 @@ def _write_pages(pages): body_parts.append("") body_parts += ["- [{}]({})".format(title, route) for title, route in links] body_parts.append("") - if page["body"]: - body_parts.append(page["body"]) with open(path, "w", encoding="utf-8") as handle: handle.write("\n".join(frontmatter) + "\n\n" + "\n".join(body_parts).rstrip("\n") + "\n") @@ -524,10 +305,12 @@ def _write_pages(pages): def _check_mdx_hazards(): - """Fail generation if any rendered Markdown has an MDX/acorn hazard: a line - outside a code fence beginning with ``export``/``import`` (ESM) or ``<`` - (JSX). These come from unfenced code examples in docstrings; the fix is to - fence the example in its source docstring.""" + """Fail generation if any rendered Markdown has an MDX/acorn hazard. + + A hazard is a line outside a code fence beginning with ``export``/``import`` + (ESM) or ``<`` (JSX). These come from unfenced code examples in docstrings; + the fix is to fence the example in its source docstring. + """ reference_dir = os.path.join(DOCS_BASE_PATH, REFERENCE_SUBDIR) hazards = [] for dirpath, _dirnames, filenames in os.walk(reference_dir): diff --git a/scripts/generate_api_docs.sh b/scripts/generate_api_docs.sh index 6f5305c12..884cdac40 100755 --- a/scripts/generate_api_docs.sh +++ b/scripts/generate_api_docs.sh @@ -1,17 +1,20 @@ #!/bin/bash # Generate the Markdown API reference from the latest source code. -# The heavy lifting (including inlining re-exported classes) lives in -# scripts/generate_api_docs.py. +# The heavy lifting (griffe extraction + griffe2md rendering + MDX-safety +# post-processing) lives in scripts/generate_api_docs.py. set -e script_dir=$(dirname "$0") cd "${script_dir}/.." -pip install -U pip -pip install -U -r requirements/adapter_dev.txt -pip install -U -r requirements/async_dev.txt -pip install -U -r requirements/documentation.txt -pip install . +if [[ "$1" != "--no-install" ]]; then + pip install -U pip + pip install -U -r requirements/adapter_dev.txt + pip install -U -r requirements/async_dev.txt + pip install -U -r requirements/docs.txt + pip install . +fi + rm -rf docs/english/reference python scripts/generate_api_docs.py diff --git a/slack_bolt/adapter/asgi/aiohttp/__init__.py b/slack_bolt/adapter/asgi/aiohttp/__init__.py index 796098537..26332d45b 100644 --- a/slack_bolt/adapter/asgi/aiohttp/__init__.py +++ b/slack_bolt/adapter/asgi/aiohttp/__init__.py @@ -18,14 +18,16 @@ def __init__(self, app: AsyncApp, path: str = "/slack/events"): With the default settings, `http://localhost:3000/slack/events` Run Bolt with [uvicron](https://www.uvicorn.org/) - # Python - app = AsyncApp() - api = SlackRequestHandler(app) - - # bash - export SLACK_SIGNING_SECRET=*** - export SLACK_BOT_TOKEN=xoxb-*** - uvicorn app:api --port 3000 --log-level debug + ```python + app = AsyncApp() + api = SlackRequestHandler(app) + ``` + + ```bash + export SLACK_SIGNING_SECRET=*** + export SLACK_BOT_TOKEN=xoxb-*** + uvicorn app:api --port 3000 --log-level debug + ``` Args: app: Your bolt application diff --git a/slack_bolt/adapter/asgi/builtin/__init__.py b/slack_bolt/adapter/asgi/builtin/__init__.py index b05451f34..a52395ef2 100644 --- a/slack_bolt/adapter/asgi/builtin/__init__.py +++ b/slack_bolt/adapter/asgi/builtin/__init__.py @@ -17,14 +17,16 @@ def __init__(self, app: App, path: str = "/slack/events"): With the default settings, `http://localhost:3000/slack/events` Run Bolt with [uvicron](https://www.uvicorn.org/) - # Python - app = App() - api = SlackRequestHandler(app) - - # bash - export SLACK_SIGNING_SECRET=*** - export SLACK_BOT_TOKEN=xoxb-*** - uvicorn app:api --port 3000 --log-level debug + ```python + app = App() + api = SlackRequestHandler(app) + ``` + + ```bash + export SLACK_SIGNING_SECRET=*** + export SLACK_BOT_TOKEN=xoxb-*** + uvicorn app:api --port 3000 --log-level debug + ``` Args: app: Your bolt application diff --git a/slack_bolt/adapter/wsgi/handler.py b/slack_bolt/adapter/wsgi/handler.py index b13e64530..ab7971096 100644 --- a/slack_bolt/adapter/wsgi/handler.py +++ b/slack_bolt/adapter/wsgi/handler.py @@ -20,17 +20,19 @@ def __init__(self, app: App, path: str = "/slack/events"): With the default settings, `http://localhost:3000/slack/events` Run Bolt with [gunicorn](https://gunicorn.org/) - # Python - app = App() + ```python + app = App() - api = SlackRequestHandler(app) + api = SlackRequestHandler(app) + ``` - # bash - export SLACK_SIGNING_SECRET=*** + ```bash + export SLACK_SIGNING_SECRET=*** - export SLACK_BOT_TOKEN=xoxb-*** + export SLACK_BOT_TOKEN=xoxb-*** - gunicorn app:api -b 0.0.0.0:3000 --log-level debug + gunicorn app:api -b 0.0.0.0:3000 --log-level debug + ``` Args: app: Your bolt application