update docs > basics with kaz feedback

misscoded · seratch · commit 4958dabde57a · 2020-09-19T09:34:01.000+09:00
diff --git a/docs/_basic/acknowledging_events.md b/docs/_basic/acknowledging_events.md
@@ -16,6 +16,8 @@ We recommend calling `ack()` right away before sending a new message or fetching
 </div>
 
 ```python
+import re
+
 # Listen for dialog submissions with a callback_id of ticket_submit
 @app.action("ticket_submit")
 def process_submission(ack, action):
@@ -31,5 +33,5 @@ def process_submission(ack, action):
             "name": "email_address",
             "error": "Sorry, this isn’t a valid email"
         }]
-        ack({"errors": errors})
+        ack(errors=errors)
 ```
diff --git a/docs/_basic/authenticating_oauth.md b/docs/_basic/authenticating_oauth.md
@@ -18,6 +18,10 @@ To learn more about the OAuth installation flow with Slack, [read the API docume
 </div>
 
 ```python
+from slack_bolt.oauth.oauth_settings import OAuthSettings
+from slack_sdk.oauth.installation_store import FileInstallationStore
+from slack_sdk.oauth.state_store import FileOAuthStateStore
+
 oauth_settings = OAuthSettings(
     client_id=os.environ["SLACK_CLIENT_ID"],
     client_secret=os.environ["SLACK_CLIENT_SECRET"],
@@ -38,29 +42,31 @@ app = App(signing_secret=os.environ["SIGNING_SECRET"],
 <div class="secondary-content" markdown="0">
 You can override the default OAuth using `oauth_settings`, which can be passed in during the initialization of App. You can override the following:
 
-- `authorization_url`: Used to toggle between new Slack Apps and Classic Slack Apps
 - `install_path`: Override default path for "Add to Slack" button
 - `redirect_uri`: Override default redirect url path
 - `callback_options`: Provide custom success and failure pages at the end of the OAuth flow
-- `state_store`: Provide a custom state store instead of using the built in `OAuthStateStore`
+- `state_store`: Provide a custom state store instead of using the built in `FileOAuthStateStore`
+- `installation_store`: Provide a custom installation store instead of the built-in `FileInstallationStore`
 
 </div>
 
 ```python
-oauth_settings = OAuthSettings(
-    client_id=os.environ["SLACK_CLIENT_ID"],
-    client_secret=os.environ["SLACK_CLIENT_SECRET"],
-    scopes=["channels:read", "groups:read", "chat:write", "incoming-webhook"],
+app = App(
+    signing_secret=os.environ.get("SLACK_SIGNING_SECRET"),
     installation_store=FileInstallationStore(),
-    state_store=FileOAuthStateStore(expiration_seconds=120),
-    install_path="/slack/install_app",
-    redirect_uri_path="/slack/redirect",
-    callback_options=CallbackOptions(success=success_handler,
-                                     failure=failure_handler)
+    oauth_settings=OAuthSettings(
+        client_id=os.environ.get("SLACK_CLIENT_ID"),
+        client_secret=os.environ.get("SLACK_CLIENT_SECRET"),
+        scopes=["app_mentions:read", "channels:history", "im:history", "chat:write"],
+        user_scopes=[],
+        redirect_uri=None,
+        install_path="/slack/install",
+        redirect_uri_path="/slack/oauth_redirect",
+        state_store=FileOAuthStateStore(expiration_seconds=600),
+        callback_options=CallbackOptions(success=success,
+                                         failure=failure),
+    ),
 )
-
-app = App(signing_secret=os.environ["SIGNING_SECRET"],
-          oauth_settings=oauth_settings)
 ```
 
 </details>
diff --git a/docs/_basic/listening_actions.md b/docs/_basic/listening_actions.md
@@ -8,7 +8,7 @@ order: 5
 <div class="section-content">
 Your app can listen to user actions like button clicks, and menu selects, using the `action` method.
 
-Actions can be filtered on an `action_id` of type `str` or `RegExp` object. `action_id`s act as unique identifiers for interactive components on the Slack platform.
+Actions can be filtered on an `action_id` of type `str` or `re.Pattern`. `action_id`s act as unique identifiers for interactive components on the Slack platform.
 
 You’ll notice in all `action()` examples, `ack()` is used. It is required to call the `ack()` function within an action listener to acknowledge that the event was received from Slack. This is discussed in the [acknowledging events section](#acknowledge).
 
@@ -29,18 +29,18 @@ def update_message(ack):
 
 <div class="secondary-content" markdown="0">
 
-You can use a constraints object to listen to `callback_id`s, `block_id`s, and `action_id`s (or any combination of them). Constraints in the object can be of type `str` or `RegExp` object.
+You can use a constraints object to listen to `callback_id`s, `block_id`s, and `action_id`s (or any combination of them). Constraints in the object can be of type `str` or `re.Pattern`.
 
 </div>
 
 ```python
 # Your function will only be called when the action_id matches 'select_user' AND the block_id matches 'assign_ticket'
 @app.action({"action_id": "select_user", "block_id": "assign_ticket"})
-def update_message(ack, action, client):
+def update_message(ack, action, body, client):
     ack()
     client.reactions_add(name='white_check_mark',
-                         timestamp=action['ts'],
-                         channel=action['channel'])
+                         timestamp=action['action_ts'],
+                         channel=body['channel']['id'])
 ```
 
 </details>
diff --git a/docs/_basic/listening_events.md b/docs/_basic/listening_events.md
@@ -16,9 +16,9 @@ The `event()` method requires an `eventType` of type `str`.
 ```python
 # When a user joins the team, send a message in a predefined channel asking them to introduce themselves
 @app.event("team_join")
-def ask_for_introduction(payload, say):
+def ask_for_introduction(event, say):
     welcome_channel_id = "C12345";
-    user_id = payload["event"]["user"]
+    user_id = event["user"]["id"]
     text = f"Welcome to the team, <@{user_id}>! 🎉 You can introduce yourself in this channel."
     say(text=text, channel=welcome_channel_id)
 ```
@@ -39,8 +39,7 @@ You can filter on subtypes of events by passing in the additional key `subtype`.
 ```python
 # Matches all messages from bot users
 @app.message({"subtype": "message_changed"})
-def log_message_change(logger, payload):
-    message = payload["event"]
+def log_message_change(logger, message):
     logger.info(f"The user {message['user']} changed the message to {message['text']}")
 ```
 
diff --git a/docs/_basic/listening_messages.md b/docs/_basic/listening_messages.md
@@ -16,8 +16,8 @@ To listen to messages that [your app has access to receive](https://api.slack.co
 ```python
 # This will match any message that contains 👋
 @app.message(":wave:")
-def say_hello(payload, say):
-    user = payload['event']['user']
+def say_hello(message, say):
+    user = message['user']
     say(f"Hi there, <@{user}>!")
 ```
 
@@ -35,7 +35,7 @@ The `re.compile()` method can be used instead of a string for more granular matc
 ```python
 @app.message(re.compile("(hi|hello|hey)"))
 def say_hello_regex(say, context):
-    # RegExp matches are inside of context.matches
+    # RegEx matches are inside of context.matches
     greeting = context['matches'][0]
     say(f"{greeting}, how are you?")
 ```
diff --git a/docs/_basic/listening_modals.md b/docs/_basic/listening_modals.md
@@ -7,7 +7,7 @@ order: 12
 
 <div class="section-content">
 
-If a <a href="https://api.slack.com/reference/block-kit/views">view payload</a> contains any input blocks, you must listen to `view_submission` events to receive their values. To listen to `view_submission` events, you can use the built-in `view()` method. `view()` requires a `callback_id` of type `str` or `RegExp`.
+If a <a href="https://api.slack.com/reference/block-kit/views">view payload</a> contains any input blocks, you must listen to `view_submission` events to receive their values. To listen to `view_submission` events, you can use the built-in `view()` method. `view()` requires a `callback_id` of type `str` or `re.Pattern`.
 
 You can access the value of the `input` blocks by accessing the `state` object. `state` contains a `values` object that uses the `block_id` and unique `action_id` to store the input values.
 
diff --git a/docs/_basic/listening_responding_options.md b/docs/_basic/listening_responding_options.md
@@ -30,5 +30,5 @@ def show_options(ack):
         },
     ]
 
-    ack({"options": options})
+    ack(options=options)
 ```
diff --git a/docs/_basic/listening_responding_shortcuts.md b/docs/_basic/listening_responding_shortcuts.md
@@ -9,7 +9,7 @@ order: 8
 
 The `shortcut()` method supports both [global shortcuts](https://api.slack.com/interactivity/shortcuts/using#global_shortcuts) and [message shortcuts](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts).
 
-Shortcuts are invokable entry points to apps. Global shortcuts are available from within search in Slack. Message shortcuts are available in the context menus of messages. Your app can use the `shortcut()` method to listen to incoming shortcut events. The method requires a `callback_id` parameter of type `str` or `RegExp`.
+Shortcuts are invokable entry points to apps. Global shortcuts are available from within search in Slack. Message shortcuts are available in the context menus of messages. Your app can use the `shortcut()` method to listen to incoming shortcut events. The method requires a `callback_id` parameter of type `str` or `re.Pattern`.
 
 Shortcuts must be acknowledged with `ack()` to inform Slack that your app has received the event.
 
@@ -25,12 +25,12 @@ When configuring shortcuts within your app configuration, you'll continue to app
 
 # The open_modal shortcut opens a plain old modal
 @app.shortcut("open_modal")
-def open_modal(ack, client):
+def open_modal(ack, shortcut, client):
     # Acknowledge the shortcut request
     ack()
     # Call the views_open method using one of the built-in WebClients
     client.views_open(
-        trigger_id=payload["trigger_id"],
+        trigger_id=shortcut["trigger_id"],
         view={
             "type": "modal",
             "title": {
@@ -69,19 +69,19 @@ def open_modal(ack, client):
   </summary>
 
   <div class="secondary-content" markdown="0">
-  You can use a constraints object to listen to `callback_id`s, and `type`s. Constraints in the object can be of type `str` or `RegExp` object.
+  You can use a constraints object to listen to `callback_id`s, and `type`s. Constraints in the object can be of type `str` or `re.Pattern`.
   </div>
 
 ```python
 
 # Your middleware will only be called when the callback_id matches 'open_modal' AND the type matches 'message_action'
-@app.shortcut({"callback_id": "open_modal", "type": "message_action"})
-def open_modal(ack, client):
-    # acknowledge the shortcut request
+@app.message_shortcut("open_modal")
+def open_modal(ack, shortcut, client):
+    # Acknowledge the shortcut request
     ack()
-    # call the views_open method using one of the built-in WebClients
+    # Call the views_open method using one of the built-in WebClients
     client.views_open(
-        trigger_id=payload["trigger_id"],
+        trigger_id=shortcut["trigger_id"],
         view={
             "type": "modal",
             "title": {
diff --git a/docs/_basic/opening_modals.md b/docs/_basic/opening_modals.md
@@ -17,14 +17,14 @@ Read more about modal composition in the <a href="https://api.slack.com/surfaces
 ```python
 # Listen for a slash command invocation
 @app.command("/ticket")
-def open_modal(ack, payload, client):
+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=payload["trigger_id"],
+        trigger_id=body["trigger_id"],
         # View payload
         view={
             "type": "modal",
diff --git a/docs/_basic/sending_messages.md b/docs/_basic/sending_messages.md
@@ -16,7 +16,7 @@ In the case that you’d like to send a message outside of a listener or you wan
 ```python
 # Listens for messages containing "knock knock" and responds with an italicized "who's there?"
 @app.message("knock knock")
-def ask_who(logger, payload, say):
+def ask_who(message, say):
     say("_Who's there?_")
 ```
 
@@ -35,8 +35,8 @@ To explore adding rich message layouts to your app, read through [the guide on o
 ```python
 # Sends a section block with datepicker when someone reacts with a 📅 emoji
 @app.event("reaction_added")
-def show_datepicker(logger, payload, say):
-  reaction = payload["event"]["reaction"]
+def show_datepicker(event, say):
+  reaction = event["reaction"]
   if reaction == "calendar":
       blocks = [{
           "type": "section",
@@ -55,8 +55,7 @@ def show_datepicker(logger, payload, say):
           }
       }]
 
-      channel_id = payload["event"]["item"]["channel"]
-      say(blocks=blocks, channel=channel_id)
+      say(blocks=blocks)
 ```
 
 </details>
diff --git a/docs/_basic/web_api.md b/docs/_basic/web_api.md
@@ -6,18 +6,18 @@ order: 4
 ---
 
 <div class="section-content">
-You can call [any Web API method](https://api.slack.com/methods) using the [`WebClient`](https://slack.dev/node-slack-sdk/web-api) provided to your Bolt app as `app.client` (given that your app has the appropriate scopes). When you call one the client’s methods, it returns a `SlackResponse` which contains the response from Slack.
+You can call [any Web API method](https://api.slack.com/methods) using the [`WebClient`](https://slack.dev/python-slack-sdk/basic_usage.html) provided to your Bolt app as `app.client` (given that your app has the appropriate scopes). When you call one the client’s methods, it returns a `SlackResponse` which contains the response from Slack.
 
 The token used to initialize Bolt can be found in the `context` object, which is required for most Web API methods.
 
 </div>
 
 ```python
 @app.message("wake me up")
-def say_hello(client, payload):
+def say_hello(client, message):
     # Unix Epoch time for September 30, 2020 11:59:59 PM
     when_september_ends = 1601510399
-    channel_id = payload['event']['channel']
+    channel_id = message['channel']
     client.chat_scheduleMessage(channel=channel_id,
                                 post_at=when_september_ends,
                                 text="Summer has come and passed")

Original file line number	Diff line number	Diff line change
`@@ -30,5 +30,5 @@ def show_options(ack):`
`30`	`30`	`},`
`31`	`31`	`]`
`32`	`32`
`33`		`- ack({"options": options})`
	`33`	`+ ack(options=options)`
`34`	`34`	```