Slack-sdk

New Features

All argument supports in `WebClient` / `AsyncWebClient`

Since this version, all the methods in `WebClient` / `AsyncWebClient` have not only required arguments but also all possible ones in the method signature for better developer experience. Refer to the pull request enabling this 1099 for details.

Easier way to test if a key exists in a Web API response

Now that `SlackResponse` / `AsyncSlackResponse` now have `__contains__` method, you can test if a key exists in WebClient responses. Refer to the pull request enabling this 1104 for details.

python
token = "xoxb-"
response = WebClient(token).auth_test()
"error" in response True / False


Changes

* 1099 Fix 1018 Add optional arguments in WebClient methods - Thanks seratch
* 1104 Fix 1102 Add `__contains__` method in slack_sdk.web.SlackResponse / AsyncSlackResponse - Thanks seratch
* 1097 Fix 1056 by changing the default type for Option values - Thanks weallwegot seratch
* 1096 Fix 1095 by correcting `ContextBlock` element type hint - Thanks uroboro seratch
* 1103 Fix 1100 by improving the `get`/`__getitem__` method behavior when response body is empty - Thanks janeliang0522 seratch
* 1105 Update the entity name in metadata / documents - Thanks seratch

---
* All issues/pull requests: https://github.com/slackapi/python-slack-sdk/milestone/41?closed=1
* All changes: https://github.com/slackapi/python-slack-sdk/compare/v3.9.1...v3.10.0

Changes

* 1094 Improve 1084 to run rate limited error retry handler correctly - Thanks seratch
* 1083 Fix 1082 by ignoring proxy parameter if env parameter is set but empty - Thanks y-adachi-00one

---
* All issues/pull requests: https://github.com/slackapi/python-slack-sdk/milestone/42?closed=1
* All changes: https://github.com/slackapi/python-slack-sdk/compare/v3.9.0...v3.9.1

New Features

Sign in with Slack (OpenID Connect)

[Sign in with Slack](https://api.slack.com/authentication/sign-in-with-slack) helps users log into your service using their Slack profile. The platform feature was recently upgraded to be compatible with the standard [OpenID Connect](https://openid.net/connect/) specification. With this version of `slack-sdk`, implementing the auth flow is much easier.

When you create a new Slack app, set the following user scopes:

yaml
oauth_config:
redirect_urls:
- https://{your-domain}/slack/oauth_redirect
scopes:
user:
- openid required
- email optional
- profile optional


Check [the Flask example in the repository](https://github.com/slackapi/python-slack-sdk/blob/main/integration_tests/samples/openid_connect/flask_example.py). It does the following:

* Build the OpenID Connect comaptible authorize URL
* `slack_sdk.oauth.OpenIDConnectAuthorizeUrlGenerator` helps you easily do this
* `OAuthStateStore` is still available for generating `state` parameter value (it's available for `nonce` management too)
* `WebClient` can perform `openid.connect.token` API calls with given `code` parameter

If you want to know the way with asyncio, check the [Sanic app example](https://github.com/slackapi/python-slack-sdk/blob/main/integration_tests/samples/openid_connect/sanic_example.py) in the same directory.

Built-in Retry Handlers

This version introduces a built-in retry functionalities to the following API clients:

* `slack_sdk.web.WebClient`
* `slack_sdk.webhook.WebhookClient`
* `slack_sdk.audit_logs.AuditLogsClient`
* `slack_sdk.scim.SCIMClient`
* `slack_sdk.web.async_client.AsyncWebClient` (aiohttp/asyncio compatible)
* `slack_sdk.webhook.async_client.AsyncWebhookClient` (aiohttp/asyncio compatible)
* `slack_sdk.audit_logs.async_client.AsyncAuditLogsClient` (aiohttp/asyncio compatible)
* `slack_sdk.scim.async_client.AsyncSCIMClient` (aiohttp/asyncio compatible)

With the default settings, only `slack_sdk.http_retry.builtin_handlers.ConnectionErrorRetryHandler` (`AsyncConnectionErrorRetryHandler` for asyncio clients) with its default configuratio (=only one retry in the manner of [exponential backoff and jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)) is enabled in the above clients. The retry handler retries if an API client encounters a connectivity-related failure (e.g., Connection reset by peer).

python
import os
from slack_sdk.web import WebClient

Only ConnectionErrorRetryHandler is enabled
client = WebClient(token=os.environ["SLACK_BOT_TOKEN"])


Another built-in retry handler is the one that handles rate limited errors.

python
--------------------------------
Use the built-in handlers
--------------------------------

client = WebClient(token=os.environ["SLACK_BOT_TOKEN"])

This handler does retries when HTTP status 429 is returned
from slack_sdk.http_retry.builtin_handlers import RateLimitErrorRetryHandler
rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1)
Enable rate limited error retries as well
cient.retry_handlers.append(rate_limit_handler)


Creating your own ones is also quite simple. Defining a new class that inherits `slack_sdk.http_retry.RetryHandler` and implements required methods (internals of can_retry / prepare_for_next_retry). Check the built-in ones' source code for learning how to properly implement.

python
--------------------------------
Create your own one
--------------------------------

import socket
from typing import Optional
from slack_sdk.http_retry import (RetryHandler, RetryState, HttpRequest, HttpResponse)
from slack_sdk.http_retry.builtin_interval_calculators import (
BackoffRetryIntervalCalculator,
)
from slack_sdk.http_retry.jitter import RandomJitter

class MyRetryHandler(RetryHandler):
def _can_retry(
self,
*,
state: RetryState,
request: HttpRequest,
response: Optional[HttpResponse] = None,
error: Optional[Exception] = None
) -> bool:
[Errno 104] Connection reset by peer
return (
error is not None and isinstance(error, socket.error) and error.errno == 104
)

Customize the settings
my_handler = MyRetryHandler(
max_retry_count=2, retry twice at maximum; the default is 1
interval_calculator=BackoffRetryIntervalCalculator( exponential backoff and jitter is the default
backoff_factor=1.0, 1, 2, 4, 8, 16 seconds later ...
jitter=RandomJitter(), will add 0.0 -- 1.0 second to the backoff duration
),
)

client = WebClient(
token=os.environ["SLACK_BOT_TOKEN"],
retry_handlers=[rate_limit_handler, my_handler],
)


For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those methods are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) and [tests](https://github.com/slackapi/python-slack-sdk/blob/main/tests/slack_sdk_async/web/test_async_web_client_http_retry.py) for more details.

Changes

* 1079 Fix 1078 Add Sign in with Slack (OpenID Connect) support - Thanks seratch
* 1084 Fix 887 Enable automatic retry by a handy way - Thanks seratch
* 1089 1058 Add Slack Connect API support - Thanks srajiang
* 1067 Fix 1065 by having lock for async Socket Mode client reconnection - Thanks seratch matthieucan
* 1091 1055 Socket Mode: ENOTSOCK every 300 minutes on Windows - Thanks dubois seratch
* 1077 Fix the wrong column data size for bot_token in the built-in SQLAlchemy data model - Thanks geeorgey
* 1081 Fix a data deletion bug in AmazonS3InstallationStore - Thanks seratch
* 1085 Add explicit arguments for files_\* methods - Thanks jaebradley
* 1076 Update example code for rate limiting in documents - Thanks tjstum
* 1071 1070 Link to Contributor's Guide from README + expand Maintainer's Guide - Thanks filmaj
* 1072 Fix WebSocket related unit test failures - Thanks seratch

---
* All issues/pull requests: https://github.com/slackapi/python-slack-sdk/milestone/40?closed=1
* All changes: https://github.com/slackapi/python-slack-sdk/compare/v3.8.0...v3.9.0

Refer to [the v3.9.0 release note](https://github.com/slackapi/python-slack-sdk/releases/tag/v3.9.0)

Refer to [the v3.9.0 release note](https://github.com/slackapi/python-slack-sdk/releases/tag/v3.9.0)

New Features

Token Rotation Support

This version includes the token rotation feature support for better security. Refer to [the API document](https://api.slack.com/authentication/rotation) for the general information about the feature.

How to enable token rotation with this SDK

Apart from the column additions for the feature (specifically, refresh token + expiration date time) and the corresponding changes in your app code, no significant code is needed. Checking the example apps using Flask, Sanic in [this directory](https://github.com/slackapi/python-slack-sdk/tree/main/integration_tests/samples/token_rotation) can be helpful to learn what to do.

In a nutshell, you can call the following `rotate_tokens` method before handling every single incoming request from Slack. As long as your `InstallationStore` support the token rotation patterns, the code below should work as-is.

python
from slack_sdk.oauth.token_rotation import TokenRotator
from slack_sdk.oauth.installation_store import FileInstallationStore

This instance can be singleton; thread-safe
token_rotator = TokenRotator(
These are required for refreshing tokens
client_id=client_id,
client_secret=client_secret,
)
Your own InstallationStore here
installation_store = FileInstallationStore()

def rotate_tokens(
enterprise_id: Optional[str] = None,
team_id: Optional[str] = None,
user_id: Optional[str] = None,
is_enterprise_install: Optional[bool] = None,
):
installation = installation_store.find_installation(
enterprise_id=enterprise_id,
team_id=team_id,
user_id=user_id,
is_enterprise_install=is_enterprise_install,
)
if installation is not None:
If rotation does not occur, refreshed_installation is None
refreshed_installation = token_rotator.perform_token_rotation(installation=installation)
if refreshed_installation is not None:
Save the new access token for the following processes
installation_store.save(refreshed_installation)


Migration guide for `SQLAlchemyInstallationStore` users

If your app uses the built-in `SQLAlchemyInstallationStore` for managing Slack app installations, adding the following database columns is required for this version upgrade. Refer to [the code](https://github.com/slackapi/python-slack-sdk/tree/main/slack_sdk/oauth/installation_store/sqlalchemy) to check the complete ones.

Also, since this version, all the table columns for string data have their max length for better compatibility with MySQL. We recommend setting the same ones for your models.

slack_installations

* `Column("bot_refresh_token", String(200)),`
* `Column("bot_token_expires_at", DateTime),`
* `Column("user_refresh_token", String(200)),`
* `Column("user_token_expires_at", DateTime),`

slack_bots

* `Column("bot_refresh_token", String(200)),`
* `Column("bot_token_expires_at", DateTime),`

Changes

* 1060 Add token rotation feature support - Thanks seratch
* 1040 Set max length for string columns in SQLAlchemy models for MySQL compatibility - Thanks tattee
* 1047 Make WebhookClient (sync/async) send method accept link unfurl params - Thanks srajiang
* 1061 WebClient's paginated response iterator does not work for admin.conversations.search API - Thanks seratch
* 1054 1053 conversations_invite() fails with "error: no_user" - Thanks seratch noperator
* 1044 Updates PythOnBoardingBot tutorial sample to use bolt-python - Thanks srajiang
* 1048 Update command in maintainers guide - Thanks srajiang

---
* All issues/pull requests: https://github.com/slackapi/python-slack-sdk/milestone/38?closed=1
* All changes: https://github.com/slackapi/python-slack-sdk/compare/v3.7.0...v3.8.0