Add Advanced Sections to documentation (#104)

Add advanced sections documentation

Author: Shay DeWael

docs/_advanced/adapters.md

@@ -1,44 +1,26 @@
 ---
-title: Using in Web frameworks
+title: Adapters
 lang: en
 slug: adapters
 order: 0
 ---
 
 <div class="section-content">
-`App#start()` starts a Web server process using the [`http.server` standard library](https://docs.python.org/3/library/http.server.html). As mentioned in its document, it is not recommended to use the module for production.
+Adapters are responsible for handling and parsing incoming events from Slack to conform to <a href="https://github.com/slackapi/bolt-python/blob/main/slack_bolt/request/request.py">`BoltRequest`</a>, then dispatching those events to your Bolt app.
 
-Once you're done with local development, it's about time to choose the right Web framework and production-ready server.
+By default, Bolt will use the built-in <a href="https://docs.python.org/3/library/http.server.html">`HTTPSever`</a> adapter. While this is okay for local development, <b>it is not recommended for production</b>. Bolt for Python includes a collection of built-in adapters that can be imported and used with your app. The built-in adapters support a variety of popular Python frameworks including Flask, Django, and Starlette among others. Adapters support the use of any production-ready web server of your choice.
 
-Let's try using [Flask](https://flask.palletsprojects.com/) framework along with the [Gunicorn](https://gunicorn.org/) WSGI HTTP server here.
-
-```bash
-pip install slack_bolt flask gunicorn
-export SLACK_SIGNING_SECRET=***
-export SLACK_BOT_TOKEN=xoxb-***
-# Save the source code as main.py
-gunicorn --bind :3000 --workers 1 --threads 2 --timeout 0 main:flask_app
-```
-
-We currently support the following frameworks. As long as a Web framework works, you can run Bolt app in any web servers.
-
-* [Django](https://www.djangoproject.com/)
-* [Flask](https://flask.palletsprojects.com/)
-* [Starlette](https://www.starlette.io/) & [FastAPI](https://fastapi.tiangolo.com/)
-* [Sanic](https://sanicframework.org/)
-* [Tornado](https://www.tornadoweb.org/)
-* [Falcon](https://falcon.readthedocs.io/)
-* [Bottle](https://bottlepy.org/)
-* [CherryPy](https://cherrypy.org/)
-* [Pyramid](https://trypyramid.com/)
-
-Check [samples](https://github.com/slackapi/bolt-python/tree/main/samples) in the GitHub repository to learn how to configure your app with frameworks.
+To use an adapter, you'll create an app with the framework of your choosing and import its corresponding adapter. Then you'll initalize the adapter instance and call its function that handles and parses incoming events.
 
+The full list adapters, as well as configuration and sample usage, can be found within the repository's <a href="https://github.com/slackapi/bolt-python/tree/main/samples">`samples` folder</a>.
 </div>
 
 ```python
 from slack_bolt import App
-app = App()
+app = App(
+    signing_secret=os.environ.get("SIGNING_SECRET"),
+    token=os.environ.get("SLACK_BOT_TOKEN")
+)
 
 # There is nothing specific to Flask here!
 # App is completely framework/runtime agnostic

docs/_advanced/async.md

@@ -1,23 +1,18 @@
 ---
-title: Async Bolt
+title: Using async
 lang: en
-slug: advanced-async
-order: 1
+slug: async
+order: 2
 ---
 
 <div class="section-content">
-In the Basic concepts section, all the code snippets are not in the asynchronous programming style. You may be wondering if Bolt for Python is not available for asynchronous frameworks and their runtime such as the standard `asyncio` library.
-
-No worries! You can use Bolt with [Starlette](https://www.starlette.io/), [FastAPI](https://fastapi.tiangolo.com/), [Sanic](https://sanicframework.org/), [AIOHTTP](https://docs.aiohttp.org/), and whatever you want to use.
-
-`AsyncApp` internally relies on AIOHTTP for making HTTP requests to Slack API servers. So, to use the async version of Bolt, add `aiohttp` to `requirements.txt` or run `pip install aiohttp`.
-
-You can find sample projects in [samples](https://github.com/slackapi/bolt-python/tree/main/samples) directory in the GitHub repository.
+To use the async version of Bolt, you can import and initialize an `AsyncApp` instance (rather than `App`). `AsyncApp` relies on <a href="https://docs.aiohttp.org/">AIOHTTP</a> to make API requests, which means you'll need to install `aiohttp` (by adding to `requirements.txt` or running `pip install aiohttp`).
 
+Sample async projects can be found within the repository's <a href="https://github.com/slackapi/bolt-python/tree/main/samples">`samples` folder</a>.
 </div>
 
 ```python
-# required: pip install aiohttp
+# Requirement: install aiohttp
 from slack_bolt.async_app import AsyncApp
 app = AsyncApp()
 
@@ -36,25 +31,23 @@ if __name__ == "__main__":
 
 <details class="secondary-wrapper">
 <summary class="section-head" markdown="0">
-<h4 class="section-head">Using other async frameworks</h4>
+<h4 class="section-head">Using other frameworks</h4>
 </summary>
 
 <div class="secondary-content" markdown="0">
 
-`AsyncApp#start()` internally uses [AIOHTTP](https://docs.aiohttp.org/)'s web server feature. However, this doesn't mean you have to use AIOHTTP. `AsyncApp` can handle incoming requests from Slack using any other frameworks.
+Internally `AsyncApp#start()` implements a [`AIOHTTP`](https://docs.aiohttp.org/) web server. If you prefer, you can use a framework other than `AIOHTTP` to handle incoming requests.
+
+This example uses [Sanic](https://sanicframework.org/), but the full list of adapters are in the [`adapter` folder](https://github.com/slackapi/bolt-python/tree/main/slack_bolt/adapter).
 
-The code snippet in this section is an example using [Sanic](https://sanicframework.org/). You can start your Slack app server-side built with Sanic only by running the following commands.
+The following commands install the necessary requirements and starts the Sanic server on port 3000.
 
 ```bash
+# Install requirements
 pip install slack_bolt sanic uvicorn
-export SLACK_SIGNING_SECRET=***
-export SLACK_BOT_TOKEN=xoxb-***
-# save the source as async_app.py
+# Save the source as async_app.py
 uvicorn async_app:api --reload --port 3000 --log-level debug
 ```
-
-If you would like to use other frameworks, check the list of the built-in adapters [here](https://github.com/slackapi/bolt-python/tree/main/slack_bolt/adapter). If your favorite framework is available there, you can use Bolt with it in a similar way.
-
 </div>
 
 ```python
@@ -85,5 +78,4 @@ async def endpoint(req: Request):
 if __name__ == "__main__":
     api.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
 ```
-
 </details>

docs/_advanced/authorization.md

@@ -0,0 +1,72 @@
+---
+title: Authorization
+lang: en
+slug: authorization
+order: 5
+---
+
+<div class="section-content">
+Authorization is the process of determining which Slack credentials should be available while processing an incoming Slack event.
+
+Apps installed on a single workspace can simply pass their bot token into the `App` constructor using the `token` parameter. However, if your app will be installed on multiple workspaces, you have two options. The easier option is to use the built-in OAuth support. This will handle setting up OAuth routes and verifying state. Read the section on [authenticating with OAuth](#authenticating-oauth) for details.
+
+For a more custom solution, you can set the `authorize` parameter to a function upon `App` instantiation. The `authorize` function should return [an instance of `AuthorizeResult`](https://github.com/slackapi/bolt-python/blob/main/slack_bolt/authorization/authorize_result.py), which contains information about who and where the event is coming from.
+
+`AuthorizeResult` should have a few specific properties, all of type `str`:
+- Either **`bot_token`** (xoxb) *or* **`user_token`** (xoxp) are **required**. Most apps will use `bot_token` by default. Passing a token allows built-in functions (like `say()`) to work.
+- **`bot_user_id`** and **`bot_id`**, if using a `bot_token`.
+- **`enterprise_id`** and **`team_id`**, which can be found in events sent to your app.
+- **`user_id`** only when using `user_token`.
+</div>
+
+```python
+import os
+from slack_bolt import App
+# Import the AuthorizationResult class
+from slack_bolt.authorization import AuthorizationResult
+
+# This is just an example (assumes there are no user tokens)
+# You should store authorizations in a secure DB
+installations = [
+    {
+      "enterprise_id": "E1234A12AB",
+      "team_id": "T12345",
+      "bot_token": "xoxb-123abc",
+      "bot_id": "B1251",
+      "bot_user_id": "U12385"
+    },
+    {
+      "team_id": "T77712",
+      "bot_token": "xoxb-102anc",
+      "bot_id": "B5910",
+      "bot_user_id": "U1239",
+      "enterprise_id": "E1234A12AB"
+    }
+]
+
+def authorize(enterprise_id, team_id, logger):
+
+    # You can implement your own logic to fetch token here
+    
+    for (team in installations):
+        # enterprise_id doesn't exist for some teams
+        is_valid_enterprise = True if (("enterprise_id" not in team) or (enterprise_id == team["enterprise_id"])) else False
+
+        if ((is_valid_enterprise == True) and (team["team_id"] == team_id)):
+          # Return an instance of AuthorizeResult
+          # If you don't store bot_id and bot_user_id, could also call `from_auth_test_response` with your bot_token to automatically fetch them
+          return AuthorizeResult(
+              enterprise_id=enterprise_id,
+              team_id=team_id,
+              bot_token=team["bot_token"],
+              bot_id=team["bot_id"],
+              bot_user_id=team["bot_user_id"]
+          )
+
+    logger.error("No authorization information was found")
+
+app = App(
+    signing_secret=os.environ["SLACK_SIGNING_SECRET"],
+    authorize=authorize
+)
+```

docs/_advanced/context.md

@@ -0,0 +1,74 @@
+---
+title: Adding context
+lang: en
+slug: context
+order: 7
+---
+
+<div class="section-content">
+All listeners have access to a `context` dictionary, which can be used to enrich events with additional information. Bolt automatically attaches information that is included in the incoming event, like `user_id`, `team_id`, `channel_id`, and `enterprise_id`.
+
+`context` is just a dictionary, so you can directly modify it.
+</div>
+
+```python
+# Listener middleware to fetch tasks from external system using userId
+def fetch_tasks(context, event, next):
+    user = event["user"]
+
+    try:
+        # Assume get_tasks fetchs list of tasks from DB corresponding to user ID
+        user_tasks = db.get_tasks(user)
+        tasks = user_tasks
+    except Exception:
+        # get_tasks() raises exception because no tasks are found
+        tasks = []
+    finally:
+        # Put user's tasks in context
+        context["tasks"] = tasks
+        next()
+
+# Listener middleware to create a list of section blocks
+def create_sections(context, next):
+    task_blocks = []
+
+    # Loops through tasks added to context in previous middleware
+    for task in context["tasks"]:
+        task_blocks.append(
+            {
+              "type": "section",
+              "text": {
+                  "type": "mrkdwn",
+                  "text": f"*{task['title']}*\n{task['body']}"
+              },
+              "accessory": {
+                  "type": "button",
+                  "text": {
+                    "type": "plain_text",
+                    "text": "See task"
+                  },
+                  "url": task["url"],
+                }
+            }
+        )
+
+    # Put list of blocks in context
+    context["blocks"] = task_blocks
+    next()
+
+# Listen for user opening app home
+# Include fetch_tasks middleware
+@app.event(
+  event = "app_home_opened",
+  middleware = [fetch_tasks, create_sections]
+)
+def show_tasks(event, client, context):
+    # Publish view to user's home tab
+    client.views_publish(
+        user_id=event["user"],
+        view={
+            "type": "home",
+            "blocks": context["blocks"]
+        }
+    )
+```

docs/_advanced/custom_adapters.md

@@ -0,0 +1,72 @@
+---
+title: Custom adapters
+lang: en
+slug: custom-adapters
+order: 1
+---
+
+<div class="section-content">
+[Adapters](#adapters) are flexible and can be adjusted based on the framework you prefer. There are two necessary components of adapters:
+
+- `__init__(app: App)`: Constructor that accepts and stores an instance of the Bolt `App`.
+- `handle(req: Request)`: Function (typically named `handle()`) that receives incoming Slack requests, parses them to conform to an instance of [`BoltRequest`](https://github.com/slackapi/bolt-python/blob/main/slack_bolt/request/request.py), then dispatches them to the stored Bolt app.
+
+`BoltRequest` instantiation accepts four parameters:
+
+| Parameter | Description | Required? |
+|-----------|-------------|-----------|
+| `body: str` | The raw request body | **Yes** |
+| `query: any` | The query string data | No |
+| `headers: Dict[str, Union[str, List[str]]]` | Request headers | No |
+| `context: Dict[str, str]` | Any context for the request | No |
+
+`BoltRequest` will return [an instance of `BoltResponse`](https://github.com/slackapi/bolt-python/blob/main/slack_bolt/response/response.py) from the Bolt app.
+
+For more in-depth examples of custom adapters, look at the implementations of the [built-in adapters](https://github.com/slackapi/bolt-python/tree/main/slack_bolt/adapter).
+</div>
+
+```python
+# Necessary imports for Flask
+from flask import Request, Response, make_response
+
+from slack_bolt.app import App
+from slack_bolt.request import BoltRequest
+from slack_bolt.response import BoltResponse
+
+# This example is a simplified version of the Flask adapter
+# For a more detailed, complete example, look in the adapter folder
+# github.com/slackapi/bolt-python/blob/main/slack_bolt/adapter/flask/handler.py
+
+# Takes in an HTTP request and converts it to a standard BoltRequest
+def to_bolt_request(req: Request) -> BoltRequest:
+    return BoltRequest(
+        body=req.get_data(as_text=True),
+        query=req.query_string.decode("utf-8"),
+        headers=req.headers,
+    )
+
+# Takes in a BoltResponse and converts it to a standard Flask response
+def to_flask_response(bolt_resp: BoltResponse) -> Response:
+    resp: Response = make_response(bolt_resp.body, bolt_resp.status)
+    for k, values in bolt_resp.headers.items():
+        for v in values:
+            resp.headers.add_header(k, v)
+    return resp
+
+# Instantiated from your app
+# Accepts a Flask app
+class SlackRequestHandler:
+    def __init__(self, app: App):
+        self.app = app
+
+    # handle() will be called from your Flask app 
+    # when you receive a request from Slack
+    def handle(self, req: Request) -> Response:
+        # This example does not cover OAuth
+        if req.method == "POST":
+            # Dispatch the request for Bolt to handle and route
+            bolt_resp: BoltResponse = self.app.dispatch(to_bolt_request(req))
+            return to_flask_response(bolt_resp)
+
+        return make_response("Not Found", 404)
+```

docs/_advanced/errors.md

@@ -0,0 +1,19 @@
+---
+title: Handling errors
+lang: en
+slug: errors
+order: 3
+---
+
+<div class="section-content">
+If an error occurs in a listener, you can handle it directly using a `try`/`except` block. Errors associated with your app will be of type `BoltError`. Errors associated with calling Slack APIs will be of type `SlackApiError`.
+
+By default, the global error handler will log all non-handled exceptions to the console. To handle global errors yourself, you can attach a global error handler to your app using the `app.error(fn)` function.
+</div>
+
+```python
+@app.error
+def custom_error_handler(error, body, logger):
+    logger.exception(f"Error: {error}")
+    logger.info(f"Request body: {body}")
+```