Skip to content

Docs: Update old links, apply style guide, and generally copyedit/clean up the Python SDK docs. #1699

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
technically-tracy merged 1 commit into from
Jun 10, 2025
Merged

Docs: Update old links, apply style guide, and generally copyedit/clean up the Python SDK docs. #1699

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 15 additions & 41 deletions docs/content/audit-logs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,20 @@
# Audit Logs API Client
# Audit Logs API client

[Audit Logs API](https://api.slack.com/admins/audit-logs) is a set of APIs for monitoring what's happening in your [Enterprise Grid](https://api.slack.com/enterprise/grid) organization.
The [Audit Logs API](https://docs.slack.dev/admins/audit-logs-api) is a set of APIs that you can use to monitor what's happening in your [Enterprise Grid](https://docs.slack.dev/enterprise-grid) organization.

The Audit Logs API can be used by security information and event management (SIEM) tools to provide an analysis of how your Slack organization is being accessed. You can also use this API to write your own applications to see how members of your organization are using Slack.
The Audit Logs API can be used by Security Information and Event Management (SIEM) tools to provide an analysis of how your Slack organization is being accessed. You can also use this API to write your own apps to see how members of your organization are using Slack.

Follow the instructions in [the API document](https://api.slack.com/admins/audit-logs) to get a valid token for using Audit Logs API. The Slack app using the Audit Logs API needs to be installed in the Enterprise Grid Organization, not an individual workspace within the organization.
You'll need a valid token in order to use the Audit Logs API. In addition, the Slack app using the Audit Logs API needs to be installed in the Enterprise Grid organization, not an individual workspace within the organization.

---

## AuditLogsClient
## AuditLogsClient {#auditlogsclient}

An OAuth token with [the admin
scope](https://api.slack.com/scopes/admin) is required to access this
API.
An OAuth token with [the admin scope](https://docs.slack.dev/reference/scopes/admin) is required to access this API.

You will likely use the `/logs` endpoint as it's the essential part of
this API.
You'll likely use the `/logs` endpoint as it's the essential part of this API.

To learn about the available parameters for this endpoint, check out
[this
guide](https://api.slack.com/admins/audit-logs#how_to_call_the_audit_logs_api).
You can also learn more about the data structure of
`api_response.typed_body` from [the class source
code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py).
To learn about the available parameters for this endpoint, check out [using the Audit Logs API](https://docs.slack.dev/admins/audit-logs-api). You can also learn more about the data structure of `api_response.typed_body` from [the class source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py).

``` python
import os
Expand All @@ -42,10 +34,9 @@ api_response = client.schemas()
api_response = client.actions()
```

## AsyncAuditLogsClient
## AsyncAuditLogsClient {#asyncauditlogsclient}

If you are keen to use asyncio for SCIM API calls, we offer
AsyncSCIMClient for it. This client relies on aiohttp library.
If you are keen to use asyncio for SCIM API calls, we offer AsyncSCIMClient for it. This client relies on aiohttp library.

``` python
from slack_sdk.audit_logs.async_client import AsyncAuditLogsClient
Expand All @@ -57,18 +48,11 @@ api_response.typed_body # slack_sdk.audit_logs.v1.LogsResponse

---

## RetryHandler
## RetryHandler {#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).
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:
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:

``` python
import os
Expand All @@ -83,11 +67,7 @@ rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1)
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.
You can also create one on your own by 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 out the source code for the ones that are built in to learn how to properly implement them.

``` python
import socket
Expand Down Expand Up @@ -120,10 +100,4 @@ client = AuditLogsClient(
)
```

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.
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) for more details.
14 changes: 7 additions & 7 deletions docs/content/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Python Slack SDK

The Slack Python SDK has corresponding package for Slack APIs. They are small and powerful when used independently, and work seamlessly when used together, too.
The Slack Python SDK has corresponding packages for Slack APIs. They are small and powerful when used independently, and work seamlessly when used together, too.

The Slack platform offers several APIs to build apps. Each Slack API delivers part of the capabilities from the platform, so that you can pick just those that fit for your needs.
The Slack platform offers several APIs to build apps. Each Slack API delivers part of the capabilities from the platform, so that you can pick just those that fit your needs.

## Features
## Features {#features}

| Feature | Use | Package |
|--------------------------------|----------|-------|
Expand All @@ -20,17 +20,17 @@ The Slack platform offers several APIs to build apps. Each Slack API delivers pa

You can also view the [Python module documents](https://tools.slack.dev/python-slack-sdk/api-docs/slack_sdk/)!

## Getting help
## Getting help {#getting-help}

These docs have lots of information on the Python Slack SDK. There's also an in-depth Reference section. Please explore!

If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue:
If you get stuck, we're here to help. The following are the best ways to get assistance working through your issue:

* [Issue Tracker](http://github.com/slackapi/python-slack-sdk/issues) for questions, bug reports, feature requests, and general discussion related to the Python Slack SDK. Try searching for an existing issue before creating a new one.
* [Email](mailto:support@slack.com) our developer support team: `support@slack.com`.

## Contributing
## Contributing {#contributing}

These docs live within the [Python Slack SDK](https://github.com/slackapi/python-slack-sdk) repository and are open source.

We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/python-slack-sdk/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way.
We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/python-slack-sdk/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way.
106 changes: 29 additions & 77 deletions docs/content/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
# Installation

This package supports Python 3.6 and higher. We recommend using [PyPI](https://pypi.python.org/pypi) to install. Run the following command:
This package supports Python 3.6 and higher. We recommend using [PyPI](https://pypi.python.org/pypi) for installation. Run the following command:

```bash
pip install slack_sdk
```

Alternatively, you can always pull the source code directly into your
project:
Alternatively, you can always pull the source code directly into your project:

```bash
git clone https://github.com/slackapi/python-slack-sdk.git
Expand Down Expand Up @@ -40,24 +39,13 @@ python test.py

It's also good to try on the Python REPL.

## Access Tokens {#handling-tokens}
## Access tokens {#handling-tokens}

Making calls to the Slack API often requires a [token](https://docs.slack.dev/authentication/tokens) with associated scopes that grant access to resources.

Collecting a token can be done from app settings or with an OAuth installation depending on your app's requirements:

- [Single Workspace Install](#single-workspace-install)
- [Multiple Workspace Install](#multiple-workspace-install)
Making calls to the Slack API often requires a [token](https://docs.slack.dev/authentication/tokens) with associated scopes that grant access to resources. Collecting a token can be done from app settings or with an OAuth installation depending on your app's requirements.

**Always keep your access tokens safe.**

The OAuth token you use to call the Slack API has access to the data on
the workspace where it is installed.

Depending on the scopes granted to the token, it potentially has the
ability to read and write data. Treat these tokens just as you would a
password — don't publish them, don't check them into source code, and
don't share them with others.
The OAuth token you use to call the Slack Web API has access to the data on the workspace where it is installed. Depending on the scopes granted to the token, it potentially has the ability to read and write data. Treat these tokens just as you would a password — don't publish them, don't check them into source code, and don't share them with others.

:::danger

Expand All @@ -69,51 +57,34 @@ token = 'xoxb-111-222-xxxxx'

:::

We recommend you pass tokens in as environment variables, or persist
them in a database that is accessed at runtime. You can add a token to
the environment by starting your app as:
We recommend you pass tokens in as environment variables, or store them in a database that is accessed at runtime. You can add a token to the environment by starting your app as follows:

```python
SLACK_BOT_TOKEN="xoxb-111-222-xxxxx" python myapp.py
```

Then retrieve the key with:
Then, retrieve the key as follows:

```python
import os
SLACK_BOT_TOKEN = os.environ["SLACK_BOT_TOKEN"]
```

For additional information, please see the [Safely Storing
Credentials](https://api.slack.com/authentication/best-practices) page within the Slack API docs.
Refer to our [best practices for security](https://docs.slack.dev/authentication/best-practices-for-security) page for more information.

## Workspace Installations
## Installing on a single workspace {#single-workspace}

### Single Workspace Install
If you're building an application for a single Slack workspace, there's no need to build out the entire OAuth flow. Once you've set up your features, click the **Install App to Team** button on the **Install App** page. If you add new permission scopes or Slack app features after an app has been installed, you must reinstall the app to your workspace for the changes to take effect.

If you're building an application for a single Slack workspace, there's no need to build out the entire OAuth flow.
Refer to the [quickstart](https://docs.slack.dev/quickstart) guide for more details.

After [creating an app](https://api.slack.com/apps?new_app=1) and adding [scopes](http://docs.slack.dev/reference/scopes) on the **OAuth & Permissions** page, go to the **Install App** page and click the **Install to Team** button to authorize the app and generate a token.
## Installing on multiple workspaces {#multi-workspace}

If you add new permission scopes or Slack app features after an app has been installed, you must reinstall the app to your workspace for changes to take effect.
If you intend for an app to be installed on multiple Slack workspaces, you will need to handle this installation via the industry-standard OAuth protocol. Read more about [installing with OAuth](https://docs.slack.dev/authentication/installing-with-oauth).

## Multiple Workspace Install
The OAuth exchange is facilitated via HTTP and requires a webserver; in this example, we'll use [Flask](https://flask.palletsprojects.com/).

If you intend for an app to be installed on multiple Slack workspaces,
you will need to handle this installation via the industry-standard
OAuth protocol. You can read more about [how Slack handles
Oauth](https://api.slack.com/authentication/oauth-v2).

(The OAuth exchange is facilitated via HTTP and requires a webserver; in
this example, we'll use [Flask](https://flask.palletsprojects.com/).)

To configure your app for OAuth, you'll need a client ID, a client
secret, and a set of one or more scopes that will be applied to the
token once it is granted. The client ID and client secret are available
from your [app's configuration page](https://api.slack.com/apps). The
scopes are determined by the functionality of the app — every method
you wish to access has a corresponding scope and your app will need to
request that scope in order to be able to access the method. Review the [full list of Slack OAuth scopes](http://docs.slack.dev/reference/scopes).
To configure your app for OAuth, you'll need a client ID, a client secret, and a set of one or more scopes that will be applied to the token once it is granted. The client ID and client secret are available from the [app page](https://api.slack.com/apps). The scopes are determined by the functionality of the app — every method you wish to access has a corresponding scope, and your app will need to request that scope in order to be able to access the method. Review the full list of [OAuth scopes](https://docs.slack.dev/reference/scopes).

```python
import os
Expand All @@ -127,18 +98,12 @@ oauth_scope = os.environ["SLACK_SCOPES"]
app = Flask(__name__)
```

### The OAuth initiation link
### The OAuth initiation link {#oauth-link}

To begin the OAuth flow that will install your app on a workspace,
you'll need to provide the user with a link to the Slack OAuth page.
This can be a simple link to `https://slack.com/oauth/v2/authorize` with
`scope` and `client_id` query parameters, or you can use our pre-built
[Add to Slack button](https://api.slack.com/docs/slack-button) to do all
the work for you.
To begin the OAuth flow that will install your app on a workspace, you'll need to provide the user with a link to the Slack OAuth page. This can be a simple link to `https://slack.com/oauth/v2/authorize` with the
`scope` and `client_id` query parameters.

This link directs the user to the Slack OAuth acceptance page, where the
user will review and accept or refuse the permissions your app is
requesting as defined by the scope(s).
This link directs the user to the OAuth acceptance page, where the user will review and accept or decline the permissions your app is requesting as defined by the scope(s).

```python
@app.route("/slack/install", methods=["GET"])
Expand All @@ -149,14 +114,9 @@ def pre_install():
'Add to Slack</a>'
```

### The OAuth completion page
### The OAuth completion page {#oauth-completion}

Once the user has agreed to the permissions you've requested, Slack
will redirect the user to your auth completion page, which includes a
`code` query string param. You'll use the `code` param to call the
`oauth.v2.access`
[endpoint](https://api.slack.com/methods/oauth.v2.access) that will
finally grant you the token.
Once the user has agreed to the permissions you've requested, Slack will redirect the user to your auth completion page, which includes a `code` query string parameter. You'll use the `code` parameter to call the [`oauth.v2.access`](https://docs.slack.dev/reference/methods/oauth.v2.access) API method that will grant you the token.

```python
@app.route("/slack/oauth_redirect", methods=["GET"])
Expand All @@ -177,8 +137,7 @@ def post_install():
)
```

A successful request to `oauth.v2.access` will yield a JSON payload with
at least one token, a bot token that begins with `xoxb`.
A successful request to the `oauth.v2.access` API method will yield a JSON payload with at least one token: a bot token that begins with `xoxb`.

```python
@app.route("/slack/oauth_redirect", methods=["GET"])
Expand Down Expand Up @@ -210,14 +169,13 @@ if __name__ == "__main__":
app.run("localhost", 3000)
```

Once your user has completed the OAuth flow, you'll be able to use the
provided tokens to call any of the Slack API methods that require an
access token.
Once your user has completed the OAuth flow, you'll be able to use the provided tokens to call any of the Slack Web API methods that require an access token.

Refer to the [basic usage](https://tools.slack.dev/python-slack-sdk/legacy/basic_usage) page for more examples.

## Installation Troubleshooting
## Installation troubleshooting {#troubleshooting}

We recommend using [virtualenv
(venv)](https://docs.python.org/3/tutorial/venv.html) to set up your
We recommend using [virtualenv (venv)](https://docs.python.org/3/tutorial/venv.html) to set up your
Python runtime.

```bash
Expand All @@ -234,8 +192,7 @@ pip install "slack_sdk>=3.0"
export SLACK_BOT_TOKEN=xoxb-***
```

Then, verify the following code works on the Python REPL (you can start
it by just `python`).
Then, verify the following code works on the Python REPL:

```python
import os
Expand All @@ -246,9 +203,4 @@ client = WebClient(token=os.environ["SLACK_BOT_TOKEN"])
res = client.api_test()
```

As the `slack` package is deprecated, we recommend switching to `slack_sdk`
package. That being said, the code you're working on may be still using
the old package. If you encounter an error saying
`AttributeError: module 'slack' has no attribute 'WebClient'`, run
`pip list`. If you find both `slack_sdk` and `slack` in the output, try
removing `slack` by `pip uninstall slack` and reinstalling `slack_sdk`.
As the `slack` package is deprecated, we recommend switching to `slack_sdk` package. That being said, the code you're working on may be still using the old package. If you encounter an error saying `AttributeError: module 'slack' has no attribute 'WebClient'`, run `pip list`. If you find both `slack_sdk` and `slack` in the output, try removing `slack` by `pip uninstall slack` and reinstalling `slack_sdk`.
Loading