Update API documents

Author: seratch

docs/api-docs/slack_bolt/authorization/async_authorize.html

@@ -44,6 +44,9 @@ <h1 class="title">Module <code>slack_bolt.authorization.async_authorize</code></
 
 
 class AsyncAuthorize:
+    &#34;&#34;&#34;This provides authorize function that returns AuthorizeResult
+    for an incoming request from Slack.&#34;&#34;&#34;
+
     def __init__(self):
         pass
 
@@ -59,6 +62,10 @@ <h1 class="title">Module <code>slack_bolt.authorization.async_authorize</code></
 
 
 class AsyncCallableAuthorize(AsyncAuthorize):
+    &#34;&#34;&#34;When you pass the authorize argument in AsyncApp constructor,
+    This authorize implementation will be used.
+    &#34;&#34;&#34;
+
     def __init__(
         self, *, logger: Logger, func: Callable[..., Awaitable[AuthorizeResult]]
     ):
@@ -121,6 +128,11 @@ <h1 class="title">Module <code>slack_bolt.authorization.async_authorize</code></
 
 
 class AsyncInstallationStoreAuthorize(AsyncAuthorize):
+    &#34;&#34;&#34;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.
+    &#34;&#34;&#34;
+
     authorize_result_cache: Dict[str, AuthorizeResult]
     find_installation_available: Optional[bool]
     find_bot_available: Optional[bool]
@@ -325,12 +337,16 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <span>class <span class="ident">AsyncAuthorize</span></span>
 </code></dt>
 <dd>
-<div class="desc"></div>
+<div class="desc"><p>This provides authorize function that returns AuthorizeResult
+for an incoming request from Slack.</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class AsyncAuthorize:
+    &#34;&#34;&#34;This provides authorize function that returns AuthorizeResult
+    for an incoming request from Slack.&#34;&#34;&#34;
+
     def __init__(self):
         pass
 
@@ -355,12 +371,17 @@ <h3>Subclasses</h3>
 <span>(</span><span>*, logger: logging.Logger, func: Callable[..., Awaitable[<a title="slack_bolt.authorization.authorize_result.AuthorizeResult" href="authorize_result.html#slack_bolt.authorization.authorize_result.AuthorizeResult">AuthorizeResult</a>]])</span>
 </code></dt>
 <dd>
-<div class="desc"></div>
+<div class="desc"><p>When you pass the authorize argument in AsyncApp constructor,
+This authorize implementation will be used.</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class AsyncCallableAuthorize(AsyncAuthorize):
+    &#34;&#34;&#34;When you pass the authorize argument in AsyncApp constructor,
+    This authorize implementation will be used.
+    &#34;&#34;&#34;
+
     def __init__(
         self, *, logger: Logger, func: Callable[..., Awaitable[AuthorizeResult]]
     ):
@@ -431,12 +452,19 @@ <h3>Ancestors</h3>
 <span>(</span><span>*, logger: logging.Logger, installation_store: slack_sdk.oauth.installation_store.async_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)</span>
 </code></dt>
 <dd>
-<div class="desc"></div>
+<div class="desc"><p>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.</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class AsyncInstallationStoreAuthorize(AsyncAuthorize):
+    &#34;&#34;&#34;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.
+    &#34;&#34;&#34;
+
     authorize_result_cache: Dict[str, AuthorizeResult]
     find_installation_available: Optional[bool]
     find_bot_available: Optional[bool]

docs/api-docs/slack_bolt/authorization/authorize.html

@@ -27,7 +27,6 @@ <h1 class="title">Module <code>slack_bolt.authorization.authorize</code></h1>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">import inspect
-import os
 from logging import Logger
 from typing import Optional, Callable, Dict, Any
 
@@ -44,6 +43,9 @@ <h1 class="title">Module <code>slack_bolt.authorization.authorize</code></h1>
 
 
 class Authorize:
+    &#34;&#34;&#34;This provides authorize function that returns AuthorizeResult
+    for an incoming request from Slack.&#34;&#34;&#34;
+
     def __init__(self):
         pass
 
@@ -59,6 +61,10 @@ <h1 class="title">Module <code>slack_bolt.authorization.authorize</code></h1>
 
 
 class CallableAuthorize(Authorize):
+    &#34;&#34;&#34;When you pass the authorize argument in AsyncApp constructor,
+    This authorize implementation will be used.
+    &#34;&#34;&#34;
+
     def __init__(
         self,
         *,
@@ -124,6 +130,11 @@ <h1 class="title">Module <code>slack_bolt.authorization.authorize</code></h1>
 
 
 class InstallationStoreAuthorize(Authorize):
+    &#34;&#34;&#34;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.
+    &#34;&#34;&#34;
+
     authorize_result_cache: Dict[str, AuthorizeResult]
     bot_only: bool
     find_installation_available: bool
@@ -322,12 +333,16 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <span>class <span class="ident">Authorize</span></span>
 </code></dt>
 <dd>
-<div class="desc"></div>
+<div class="desc"><p>This provides authorize function that returns AuthorizeResult
+for an incoming request from Slack.</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class Authorize:
+    &#34;&#34;&#34;This provides authorize function that returns AuthorizeResult
+    for an incoming request from Slack.&#34;&#34;&#34;
+
     def __init__(self):
         pass
 
@@ -352,12 +367,17 @@ <h3>Subclasses</h3>
 <span>(</span><span>*, logger: logging.Logger, func: Callable[..., <a title="slack_bolt.authorization.authorize_result.AuthorizeResult" href="authorize_result.html#slack_bolt.authorization.authorize_result.AuthorizeResult">AuthorizeResult</a>])</span>
 </code></dt>
 <dd>
-<div class="desc"></div>
+<div class="desc"><p>When you pass the authorize argument in AsyncApp constructor,
+This authorize implementation will be used.</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class CallableAuthorize(Authorize):
+    &#34;&#34;&#34;When you pass the authorize argument in AsyncApp constructor,
+    This authorize implementation will be used.
+    &#34;&#34;&#34;
+
     def __init__(
         self,
         *,
@@ -431,12 +451,19 @@ <h3>Ancestors</h3>
 <span>(</span><span>*, logger: logging.Logger, installation_store: slack_sdk.oauth.installation_store.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)</span>
 </code></dt>
 <dd>
-<div class="desc"></div>
+<div class="desc"><p>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.</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class InstallationStoreAuthorize(Authorize):
+    &#34;&#34;&#34;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.
+    &#34;&#34;&#34;
+
     authorize_result_cache: Dict[str, AuthorizeResult]
     bot_only: bool
     find_installation_available: bool

docs/api-docs/slack_bolt/middleware/authorization/async_multi_teams_authorization.html

@@ -90,8 +90,13 @@ <h1 class="title">Module <code>slack_bolt.middleware.authorization.async_multi_t
                 req.context.client.token = token
                 return await next()
             else:
-                # Just in case
-                self.logger.error(&#34;auth.test API call result is unexpectedly None&#34;)
+                # This situation can arise if:
+                # * A developer installed the app from the &#34;Install to Workspace&#34; button in Slack app config page
+                # * The InstallationStore failed to save or deleted the installation for this workspace
+                self.logger.error(
+                    &#34;Although the app should be installed into this workspace, &#34;
+                    &#34;the AuthorizeResult (returned value from authorize) for it was not found.&#34;
+                )
                 return _build_error_response()
 
         except SlackApiError as e:
@@ -175,8 +180,13 @@ <h2 id="args">Args</h2>
                 req.context.client.token = token
                 return await next()
             else:
-                # Just in case
-                self.logger.error(&#34;auth.test API call result is unexpectedly None&#34;)
+                # This situation can arise if:
+                # * A developer installed the app from the &#34;Install to Workspace&#34; button in Slack app config page
+                # * The InstallationStore failed to save or deleted the installation for this workspace
+                self.logger.error(
+                    &#34;Although the app should be installed into this workspace, &#34;
+                    &#34;the AuthorizeResult (returned value from authorize) for it was not found.&#34;
+                )
                 return _build_error_response()
 
         except SlackApiError as e:

docs/api-docs/slack_bolt/middleware/authorization/multi_teams_authorization.html

@@ -95,8 +95,13 @@ <h1 class="title">Module <code>slack_bolt.middleware.authorization.multi_teams_a
                 req.context.client.token = token
                 return next()
             else:
-                # Just in case
-                self.logger.error(&#34;auth.test API call result is unexpectedly None&#34;)
+                # This situation can arise if:
+                # * A developer installed the app from the &#34;Install to Workspace&#34; button in Slack app config page
+                # * The InstallationStore failed to save or deleted the installation for this workspace
+                self.logger.error(
+                    &#34;Although the app should be installed into this workspace, &#34;
+                    &#34;the AuthorizeResult (returned value from authorize) for it was not found.&#34;
+                )
                 return _build_error_response()
 
         except SlackApiError as e:
@@ -181,8 +186,13 @@ <h2 id="args">Args</h2>
                 req.context.client.token = token
                 return next()
             else:
-                # Just in case
-                self.logger.error(&#34;auth.test API call result is unexpectedly None&#34;)
+                # This situation can arise if:
+                # * A developer installed the app from the &#34;Install to Workspace&#34; button in Slack app config page
+                # * The InstallationStore failed to save or deleted the installation for this workspace
+                self.logger.error(
+                    &#34;Although the app should be installed into this workspace, &#34;
+                    &#34;the AuthorizeResult (returned value from authorize) for it was not found.&#34;
+                )
                 return _build_error_response()
 
         except SlackApiError as e:

docs/api-docs/slack_bolt/oauth/async_oauth_settings.html

@@ -146,14 +146,24 @@ <h1 class="title">Module <code>slack_bolt.oauth.async_oauth_settings</code></h1>
         self.client_id = client_id
         self.client_secret = client_secret
 
-        self.scopes = scopes or os.environ.get(&#34;SLACK_SCOPES&#34;, &#34;&#34;).split(&#34;,&#34;)
+        # NOTE: pytype says that self.scopes can be str, not Sequence[str].
+        # That&#39;s true but we will check the pattern in the following if statement.
+        # Thus, we ignore the warnings here. This is the same for user_scopes too.
+        self.scopes = (  # type: ignore
+            scopes  # type: ignore
+            if scopes is not None
+            else os.environ.get(&#34;SLACK_SCOPES&#34;, &#34;&#34;).split(&#34;,&#34;)  # type: ignore
+        )  # type: ignore
         if isinstance(self.scopes, str):
             self.scopes = self.scopes.split(&#34;,&#34;)
-        self.user_scopes = user_scopes or os.environ.get(&#34;SLACK_USER_SCOPES&#34;, &#34;&#34;).split(
-            &#34;,&#34;
-        )
+        self.user_scopes = (  # type: ignore
+            user_scopes
+            if user_scopes is not None
+            else os.environ.get(&#34;SLACK_USER_SCOPES&#34;, &#34;&#34;).split(&#34;,&#34;)  # type: ignore
+        )  # type: ignore
         if isinstance(self.user_scopes, str):
             self.user_scopes = self.user_scopes.split(&#34;,&#34;)
+
         self.redirect_uri = redirect_uri or os.environ.get(&#34;SLACK_REDIRECT_URI&#34;)
         # Handler configuration
         self.install_path = install_path or os.environ.get(
@@ -368,14 +378,24 @@ <h2 id="args">Args</h2>
         self.client_id = client_id
         self.client_secret = client_secret
 
-        self.scopes = scopes or os.environ.get(&#34;SLACK_SCOPES&#34;, &#34;&#34;).split(&#34;,&#34;)
+        # NOTE: pytype says that self.scopes can be str, not Sequence[str].
+        # That&#39;s true but we will check the pattern in the following if statement.
+        # Thus, we ignore the warnings here. This is the same for user_scopes too.
+        self.scopes = (  # type: ignore
+            scopes  # type: ignore
+            if scopes is not None
+            else os.environ.get(&#34;SLACK_SCOPES&#34;, &#34;&#34;).split(&#34;,&#34;)  # type: ignore
+        )  # type: ignore
         if isinstance(self.scopes, str):
             self.scopes = self.scopes.split(&#34;,&#34;)
-        self.user_scopes = user_scopes or os.environ.get(&#34;SLACK_USER_SCOPES&#34;, &#34;&#34;).split(
-            &#34;,&#34;
-        )
+        self.user_scopes = (  # type: ignore
+            user_scopes
+            if user_scopes is not None
+            else os.environ.get(&#34;SLACK_USER_SCOPES&#34;, &#34;&#34;).split(&#34;,&#34;)  # type: ignore
+        )  # type: ignore
         if isinstance(self.user_scopes, str):
             self.user_scopes = self.user_scopes.split(&#34;,&#34;)
+
         self.redirect_uri = redirect_uri or os.environ.get(&#34;SLACK_REDIRECT_URI&#34;)
         # Handler configuration
         self.install_path = install_path or os.environ.get(