Update the documents for v3.9.0 release (#1087)

docs-src/audit-logs/index.rst

@@ -50,4 +50,55 @@ If you are keen to use asyncio for SCIM API calls, we offer AsyncSCIMClient for
     api_response.typed_body  # slack_sdk.audit_logs.v1.LogsResponse
 
 
+--------
+
+RetryHandler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With the default settings, only ``ConnectionErrorRetryHandler`` with its default configuration (=only one retry in the manner of `exponential backoff and jitter <https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/>`_ is enabled. The retry handler retries if an API client encounters a connectivity-related failure (e.g., Connection reset by peer).
+
+To use other retry handlers, you can pass a list of ``RetryHandler`` to the client constructor. For instance, you can add the built-in ``RateLimitErrorRetryHandler`` this way:
+
+.. code-block:: python
+
+    import os
+    from slack_sdk.audit_logs import AuditLogsClient
+    client = AuditLogsClient(token=os.environ["SLACK_ORG_ADMIN_USER_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
+    client.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`` (``AsyncRetryHandler`` for asyncio apps) 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.
+
+.. code-block:: python
+
+    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
+
+    client = AuditLogsClient(
+        token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"],
+        retry_handlers=[MyRetryHandler()],
+    )
+
+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.
+
 .. include:: ../metadata.rst

docs-src/index.rst

@@ -31,7 +31,7 @@ The Slack platform offers several APIs to build apps. Each Slack API delivers pa
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
 | Socket Mode                    | Receive and send messages over Socket Mode connections.                                       | ``slack_sdk.socket_mode``          |
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
-| OAuth                          | Setup the authentication flow using V2 OAuth for Slack apps.                                  | ``slack_sdk.oauth``                |
+| OAuth                          | Setup the authentication flow using V2 OAuth, OpenID Connect for Slack apps.                  | ``slack_sdk.oauth``                |
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
 | Audit Logs API                 | Receive audit logs API data.                                                                  | ``slack_sdk.audit_logs``           |
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
@@ -60,22 +60,25 @@ Of course, you can always pull the source code directly into your project:
 .. code-block:: bash
 
 	git clone https://github.com/slackapi/python-slack-sdk.git
+	cd python-slack-sdk
+	python3 -m venv .venv
+	source .venv/bin/activate
+	pip install -U pip
+	pip install -e .  # install the SDK project into the virtual env
 
 And then, save a few lines of code as ``./test.py``.
 
 .. code-block:: python
 
-        # test.py
-        import sys
-        # Load the local source directly
-        sys.path.insert(1, "./python-slack-sdk")
-        # Enable debug logging
-        import logging
-        logging.basicConfig(level=logging.DEBUG)
-        # Verify it works
-        from slack_sdk import WebClient
-        client = WebClient()
-        api_response = client.api_test()
+    # test.py
+    import sys
+    # Enable debug logging
+    import logging
+    logging.basicConfig(level=logging.DEBUG)
+    # Verify it works
+    from slack_sdk import WebClient
+    client = WebClient()
+    api_response = client.api_test()
 
 You can run the code this way.
 

docs-src/oauth/index.rst

@@ -236,5 +236,35 @@ You can use the same ``InstallationStore`` in the Slack event handler.
 
 Again, if you're looking for an easier solution, take a look at `Bolt for Python <https://github.com/slackapi/bolt-python>`_. With Bolt, you don't need to implement most of the above code on your own.
 
+Sign in with Slack
+*************************************************
+
+`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 slack-sdk v3.9+, implementing the auth flow is much easier.
+
+When you create a new Slack app, set the following user scopes:
+
+.. code-block:: yaml
+
+  oauth_config:
+    redirect_urls:
+      - https://{your-domain}/slack/oauth_redirect
+    scopes:
+      user:
+        - openid   # required
+        - email    # optional
+        - profile  # optional
+
+Check `the Flask app example <https://github.com/slackapi/python-slack-sdk/blob/main/integration_tests/samples/openid_connect/flask_example.py>`_ to learn how to implement your Web app that handles the OpenID Connect flow with end-users. It does the following:
+
+**Build the OpenID Connect authorize URL**
+
+- ``slack_sdk.oauth.OpenIDConnectAuthorizeUrlGenerator`` helps you easily do this
+- ``slack_sdk.oauth.OAuthStateStore`` is still available for generating ``state`` parameter value. It's available for ``nonce`` management too.
+
+**openid.connect.* API calls**
+
+``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.
 
-.. include:: ../metadata.rst
+.. include:: ../metadata.rst

docs-src/scim/index.rst

@@ -98,4 +98,55 @@ Lastly, if you are keen to use asyncio for SCIM API calls, we offer ``AsyncSCIMC
 
     asyncio.run(main())
 
+--------
+
+RetryHandler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With the default settings, only ``ConnectionErrorRetryHandler`` with its default configuration (=only one retry in the manner of `exponential backoff and jitter <https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/>`_ is enabled. The retry handler retries if an API client encounters a connectivity-related failure (e.g., Connection reset by peer).
+
+To use other retry handlers, you can pass a list of ``RetryHandler`` to the client constructor. For instance, you can add the built-in ``RateLimitErrorRetryHandler`` this way:
+
+.. code-block:: python
+
+    import os
+    from slack_sdk.scim import SCIMClient
+    client = SCIMClient(token=os.environ["SLACK_ORG_ADMIN_USER_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
+    client.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`` (``AsyncRetryHandler`` for asyncio apps) 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.
+
+.. code-block:: python
+
+    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
+
+    client = SCIMClient(
+        token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"],
+        retry_handlers=[MyRetryHandler()],
+    )
+
+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.
+
 .. include:: ../metadata.rst

docs-src/web/index.rst

@@ -590,7 +590,9 @@ Here's a very basic example of how one might deal with rate limited requests.
                 # other errors
                 raise e
 
-See the documentation on `Rate Limiting <https://api.slack.com/docs/rate-limits>`_ for more info.
+Since v3.9.0, the built-in ``RateLimitErrorRetryHandler`` is available as an easier way to do the retries for rate limited errors. Refer to the RetryHandler section in this page for more details.
+
+To learn the Slack rate limits in general, see the documentation on `Rate Limiting <https://api.slack.com/docs/rate-limits>`_.
 
 --------
 
@@ -649,4 +651,57 @@ All the API methods are available in asynchronous programming using the standard
     # but you can go with any ways to run it
     asyncio.run(post_message())
 
+
+--------
+
+RetryHandler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With the default settings, only ``ConnectionErrorRetryHandler`` with its default configuration (=only one retry in the manner of `exponential backoff and jitter <https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/>`_ is enabled. The retry handler retries if an API client encounters a connectivity-related failure (e.g., Connection reset by peer).
+
+To use other retry handlers, you can pass a list of ``RetryHandler`` to the client constructor. For instance, you can add the built-in ``RateLimitErrorRetryHandler`` this way:
+
+.. code-block:: python
+
+    import os
+    from slack_sdk.web import WebClient
+    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
+    client.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`` (``AsyncRetryHandler`` for asyncio apps) 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.
+
+.. code-block:: python
+
+    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
+
+    client = WebClient(
+        token=os.environ["SLACK_BOT_TOKEN"],
+        retry_handlers=[MyRetryHandler()],
+    )
+
+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.
+
+
 .. include:: ../metadata.rst

docs-src/webhook/index.rst

@@ -107,4 +107,55 @@ The webhook client is available in asynchronous programming using the standard `
     # but you can go with any ways to run it
     asyncio.run(send_message_via_webhook(url))
 
+--------
+
+RetryHandler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With the default settings, only ``ConnectionErrorRetryHandler`` with its default configuration (=only one retry in the manner of `exponential backoff and jitter <https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/>`_ is enabled. The retry handler retries if an API client encounters a connectivity-related failure (e.g., Connection reset by peer).
+
+To use other retry handlers, you can pass a list of ``RetryHandler`` to the client constructor. For instance, you can add the built-in ``RateLimitErrorRetryHandler`` this way:
+
+.. code-block:: python
+
+    from slack_sdk.webhook import WebhookClient
+    url = "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
+    webhook = WebhookClient(url=url)
+
+    # 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
+    client.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`` (``AsyncRetryHandler`` for asyncio apps) 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.
+
+.. code-block:: python
+
+    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
+
+    webhook = WebhookClient(
+        url=url,
+        retry_handlers=[MyRetryHandler()],
+    )
+
+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.
+
 .. include:: ../metadata.rst

docs/about.html

@@ -135,12 +135,14 @@
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="web/index.html#asyncwebclient">AsyncWebClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="web/index.html#retryhandler">RetryHandler</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="webhook/index.html">Webhook Client</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="webhook/index.html#id1">Incoming Webhooks</a></li>
 <li class="toctree-l2"><a class="reference internal" href="webhook/index.html#response-url">response_url</a></li>
 <li class="toctree-l2"><a class="reference internal" href="webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="webhook/index.html#retryhandler">RetryHandler</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="socket-mode/index.html">Socket Mode Client</a><ul>
@@ -152,16 +154,19 @@
 <li class="toctree-l1"><a class="reference internal" href="oauth/index.html">OAuth Modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#app-installation-flow">App Installation Flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#token-lookup">Token Lookup</a></li>
+<li class="toctree-l2"><a class="reference internal" href="oauth/index.html#sign-in-with-slack">Sign in with Slack</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="audit-logs/index.html">Audit Logs API Client</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="audit-logs/index.html#auditlogsclient">AuditLogsClient</a></li>
 <li class="toctree-l2"><a class="reference internal" href="audit-logs/index.html#asyncauditlogsclient">AsyncAuditLogsClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="audit-logs/index.html#retryhandler">RetryHandler</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="scim/index.html">SCIM API Client</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="scim/index.html#scimclient">SCIMClient</a></li>
 <li class="toctree-l2"><a class="reference internal" href="scim/index.html#asyncscimclient">AsyncSCIMClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="scim/index.html#retryhandler">RetryHandler</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="real_time_messaging.html">RTM Client</a><ul>