Skip to content

Commit c678018

Browse files
seratchseratch
authored
Update the documents for v3.9.0 release (#1087)
1 parent daff025 commit c678018

File tree

22 files changed

+539
-19
lines changed

22 files changed

+539
-19
lines changed

‎docs-src/audit-logs/index.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,4 +50,55 @@ If you are keen to use asyncio for SCIM API calls, we offer AsyncSCIMClient for
5050
api_response.typed_body # slack_sdk.audit_logs.v1.LogsResponse
5151
5252
53+
--------
54+
55+
RetryHandler
56+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
57+
58+
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).
59+
60+
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:
61+
62+
.. code-block:: python
63+
64+
import os
65+
from slack_sdk.audit_logs import AuditLogsClient
66+
client = AuditLogsClient(token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"])
67+
68+
# This handler does retries when HTTP status 429 is returned
69+
from slack_sdk.http_retry.builtin_handlers import RateLimitErrorRetryHandler
70+
rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1)
71+
72+
# Enable rate limited error retries as well
73+
client.retry_handlers.append(rate_limit_handler)
74+
75+
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.
76+
77+
.. code-block:: python
78+
79+
import socket
80+
from typing import Optional
81+
from slack_sdk.http_retry import (RetryHandler, RetryState, HttpRequest, HttpResponse)
82+
from slack_sdk.http_retry.builtin_interval_calculators import BackoffRetryIntervalCalculator
83+
from slack_sdk.http_retry.jitter import RandomJitter
84+
85+
class MyRetryHandler(RetryHandler):
86+
def _can_retry(
87+
self,
88+
*,
89+
state: RetryState,
90+
request: HttpRequest,
91+
response: Optional[HttpResponse] = None,
92+
error: Optional[Exception] = None
93+
) -> bool:
94+
# [Errno 104] Connection reset by peer
95+
return error is not None and isinstance(error, socket.error) and error.errno == 104
96+
97+
client = AuditLogsClient(
98+
token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"],
99+
retry_handlers=[MyRetryHandler()],
100+
)
101+
102+
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.
103+
53104
.. include:: ../metadata.rst

‎docs-src/index.rst‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ The Slack platform offers several APIs to build apps. Each Slack API delivers pa
3131
+--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
3232
| Socket Mode | Receive and send messages over Socket Mode connections. | ``slack_sdk.socket_mode`` |
3333
+--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
34-
| OAuth | Setup the authentication flow using V2 OAuth for Slack apps. | ``slack_sdk.oauth`` |
34+
| OAuth | Setup the authentication flow using V2 OAuth, OpenID Connect for Slack apps. | ``slack_sdk.oauth`` |
3535
+--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
3636
| Audit Logs API | Receive audit logs API data. | ``slack_sdk.audit_logs`` |
3737
+--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
@@ -60,22 +60,25 @@ Of course, you can always pull the source code directly into your project:
6060
.. code-block:: bash
6161
6262
git clone https://github.com/slackapi/python-slack-sdk.git
63+
cd python-slack-sdk
64+
python3 -m venv .venv
65+
source .venv/bin/activate
66+
pip install -U pip
67+
pip install -e . # install the SDK project into the virtual env
6368
6469
And then, save a few lines of code as ``./test.py``.
6570

6671
.. code-block:: python
6772
68-
# test.py
69-
import sys
70-
# Load the local source directly
71-
sys.path.insert(1, "./python-slack-sdk")
72-
# Enable debug logging
73-
import logging
74-
logging.basicConfig(level=logging.DEBUG)
75-
# Verify it works
76-
from slack_sdk import WebClient
77-
client = WebClient()
78-
api_response = client.api_test()
73+
# test.py
74+
import sys
75+
# Enable debug logging
76+
import logging
77+
logging.basicConfig(level=logging.DEBUG)
78+
# Verify it works
79+
from slack_sdk import WebClient
80+
client = WebClient()
81+
api_response = client.api_test()
7982
8083
You can run the code this way.
8184

‎docs-src/oauth/index.rst‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -236,5 +236,35 @@ You can use the same ``InstallationStore`` in the Slack event handler.
236236
237237
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.
238238

239+
Sign in with Slack
240+
*************************************************
241+
242+
`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.
243+
244+
When you create a new Slack app, set the following user scopes:
245+
246+
.. code-block:: yaml
247+
248+
oauth_config:
249+
redirect_urls:
250+
- https://{your-domain}/slack/oauth_redirect
251+
scopes:
252+
user:
253+
- openid # required
254+
- email # optional
255+
- profile # optional
256+
257+
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:
258+
259+
**Build the OpenID Connect authorize URL**
260+
261+
- ``slack_sdk.oauth.OpenIDConnectAuthorizeUrlGenerator`` helps you easily do this
262+
- ``slack_sdk.oauth.OAuthStateStore`` is still available for generating ``state`` parameter value. It's available for ``nonce`` management too.
263+
264+
**openid.connect.* API calls**
265+
266+
``WebClient`` can perform ``openid.connect.token`` API calls with given ``code`` parameter
267+
268+
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.
239269

240-
.. include:: ../metadata.rst
270+
.. include:: ../metadata.rst

‎docs-src/scim/index.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,4 +98,55 @@ Lastly, if you are keen to use asyncio for SCIM API calls, we offer ``AsyncSCIMC
9898
9999
asyncio.run(main())
100100
101+
--------
102+
103+
RetryHandler
104+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
105+
106+
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).
107+
108+
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:
109+
110+
.. code-block:: python
111+
112+
import os
113+
from slack_sdk.scim import SCIMClient
114+
client = SCIMClient(token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"])
115+
116+
# This handler does retries when HTTP status 429 is returned
117+
from slack_sdk.http_retry.builtin_handlers import RateLimitErrorRetryHandler
118+
rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1)
119+
120+
# Enable rate limited error retries as well
121+
client.retry_handlers.append(rate_limit_handler)
122+
123+
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.
124+
125+
.. code-block:: python
126+
127+
import socket
128+
from typing import Optional
129+
from slack_sdk.http_retry import (RetryHandler, RetryState, HttpRequest, HttpResponse)
130+
from slack_sdk.http_retry.builtin_interval_calculators import BackoffRetryIntervalCalculator
131+
from slack_sdk.http_retry.jitter import RandomJitter
132+
133+
class MyRetryHandler(RetryHandler):
134+
def _can_retry(
135+
self,
136+
*,
137+
state: RetryState,
138+
request: HttpRequest,
139+
response: Optional[HttpResponse] = None,
140+
error: Optional[Exception] = None
141+
) -> bool:
142+
# [Errno 104] Connection reset by peer
143+
return error is not None and isinstance(error, socket.error) and error.errno == 104
144+
145+
client = SCIMClient(
146+
token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"],
147+
retry_handlers=[MyRetryHandler()],
148+
)
149+
150+
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.
151+
101152
.. include:: ../metadata.rst

‎docs-src/web/index.rst‎

Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -590,7 +590,9 @@ Here's a very basic example of how one might deal with rate limited requests.
590590
# other errors
591591
raise e
592592
593-
See the documentation on `Rate Limiting <https://api.slack.com/docs/rate-limits>`_ for more info.
593+
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.
594+
595+
To learn the Slack rate limits in general, see the documentation on `Rate Limiting <https://api.slack.com/docs/rate-limits>`_.
594596

595597
--------
596598

@@ -649,4 +651,57 @@ All the API methods are available in asynchronous programming using the standard
649651
# but you can go with any ways to run it
650652
asyncio.run(post_message())
651653
654+
655+
--------
656+
657+
RetryHandler
658+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
659+
660+
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).
661+
662+
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:
663+
664+
.. code-block:: python
665+
666+
import os
667+
from slack_sdk.web import WebClient
668+
client = WebClient(token=os.environ["SLACK_BOT_TOKEN"])
669+
670+
# This handler does retries when HTTP status 429 is returned
671+
from slack_sdk.http_retry.builtin_handlers import RateLimitErrorRetryHandler
672+
rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1)
673+
674+
# Enable rate limited error retries as well
675+
client.retry_handlers.append(rate_limit_handler)
676+
677+
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.
678+
679+
.. code-block:: python
680+
681+
import socket
682+
from typing import Optional
683+
from slack_sdk.http_retry import (RetryHandler, RetryState, HttpRequest, HttpResponse)
684+
from slack_sdk.http_retry.builtin_interval_calculators import BackoffRetryIntervalCalculator
685+
from slack_sdk.http_retry.jitter import RandomJitter
686+
687+
class MyRetryHandler(RetryHandler):
688+
def _can_retry(
689+
self,
690+
*,
691+
state: RetryState,
692+
request: HttpRequest,
693+
response: Optional[HttpResponse] = None,
694+
error: Optional[Exception] = None
695+
) -> bool:
696+
# [Errno 104] Connection reset by peer
697+
return error is not None and isinstance(error, socket.error) and error.errno == 104
698+
699+
client = WebClient(
700+
token=os.environ["SLACK_BOT_TOKEN"],
701+
retry_handlers=[MyRetryHandler()],
702+
)
703+
704+
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.
705+
706+
652707
.. include:: ../metadata.rst

‎docs-src/webhook/index.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,4 +107,55 @@ The webhook client is available in asynchronous programming using the standard `
107107
# but you can go with any ways to run it
108108
asyncio.run(send_message_via_webhook(url))
109109
110+
--------
111+
112+
RetryHandler
113+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
114+
115+
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).
116+
117+
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:
118+
119+
.. code-block:: python
120+
121+
from slack_sdk.webhook import WebhookClient
122+
url = "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
123+
webhook = WebhookClient(url=url)
124+
125+
# This handler does retries when HTTP status 429 is returned
126+
from slack_sdk.http_retry.builtin_handlers import RateLimitErrorRetryHandler
127+
rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1)
128+
129+
# Enable rate limited error retries as well
130+
client.retry_handlers.append(rate_limit_handler)
131+
132+
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.
133+
134+
.. code-block:: python
135+
136+
import socket
137+
from typing import Optional
138+
from slack_sdk.http_retry import (RetryHandler, RetryState, HttpRequest, HttpResponse)
139+
from slack_sdk.http_retry.builtin_interval_calculators import BackoffRetryIntervalCalculator
140+
from slack_sdk.http_retry.jitter import RandomJitter
141+
142+
class MyRetryHandler(RetryHandler):
143+
def _can_retry(
144+
self,
145+
*,
146+
state: RetryState,
147+
request: HttpRequest,
148+
response: Optional[HttpResponse] = None,
149+
error: Optional[Exception] = None
150+
) -> bool:
151+
# [Errno 104] Connection reset by peer
152+
return error is not None and isinstance(error, socket.error) and error.errno == 104
153+
154+
webhook = WebhookClient(
155+
url=url,
156+
retry_handlers=[MyRetryHandler()],
157+
)
158+
159+
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.
160+
110161
.. include:: ../metadata.rst

‎docs/about.html‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,12 +135,14 @@
135135
</ul>
136136
</li>
137137
<li class="toctree-l2"><a class="reference internal" href="web/index.html#asyncwebclient">AsyncWebClient</a></li>
138+
<li class="toctree-l2"><a class="reference internal" href="web/index.html#retryhandler">RetryHandler</a></li>
138139
</ul>
139140
</li>
140141
<li class="toctree-l1"><a class="reference internal" href="webhook/index.html">Webhook Client</a><ul>
141142
<li class="toctree-l2"><a class="reference internal" href="webhook/index.html#id1">Incoming Webhooks</a></li>
142143
<li class="toctree-l2"><a class="reference internal" href="webhook/index.html#response-url">response_url</a></li>
143144
<li class="toctree-l2"><a class="reference internal" href="webhook/index.html#asyncwebhookclient">AsyncWebhookClient</a></li>
145+
<li class="toctree-l2"><a class="reference internal" href="webhook/index.html#retryhandler">RetryHandler</a></li>
144146
</ul>
145147
</li>
146148
<li class="toctree-l1"><a class="reference internal" href="socket-mode/index.html">Socket Mode Client</a><ul>
@@ -152,16 +154,19 @@
152154
<li class="toctree-l1"><a class="reference internal" href="oauth/index.html">OAuth Modules</a><ul>
153155
<li class="toctree-l2"><a class="reference internal" href="oauth/index.html#app-installation-flow">App Installation Flow</a></li>
154156
<li class="toctree-l2"><a class="reference internal" href="oauth/index.html#token-lookup">Token Lookup</a></li>
157+
<li class="toctree-l2"><a class="reference internal" href="oauth/index.html#sign-in-with-slack">Sign in with Slack</a></li>
155158
</ul>
156159
</li>
157160
<li class="toctree-l1"><a class="reference internal" href="audit-logs/index.html">Audit Logs API Client</a><ul>
158161
<li class="toctree-l2"><a class="reference internal" href="audit-logs/index.html#auditlogsclient">AuditLogsClient</a></li>
159162
<li class="toctree-l2"><a class="reference internal" href="audit-logs/index.html#asyncauditlogsclient">AsyncAuditLogsClient</a></li>
163+
<li class="toctree-l2"><a class="reference internal" href="audit-logs/index.html#retryhandler">RetryHandler</a></li>
160164
</ul>
161165
</li>
162166
<li class="toctree-l1"><a class="reference internal" href="scim/index.html">SCIM API Client</a><ul>
163167
<li class="toctree-l2"><a class="reference internal" href="scim/index.html#scimclient">SCIMClient</a></li>
164168
<li class="toctree-l2"><a class="reference internal" href="scim/index.html#asyncscimclient">AsyncSCIMClient</a></li>
169+
<li class="toctree-l2"><a class="reference internal" href="scim/index.html#retryhandler">RetryHandler</a></li>
165170
</ul>
166171
</li>
167172
<li class="toctree-l1"><a class="reference internal" href="real_time_messaging.html">RTM Client</a><ul>

0 commit comments

Comments
 (0)