-
Notifications
You must be signed in to change notification settings - Fork 55
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: basic documentation for async mode
- Loading branch information
1 parent
6323f5c
commit 65605c8
Showing
13 changed files
with
300 additions
and
81 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # API Documentation (Async) | ||
|
|
||
| This is the API documentation of **async versions** of all the classes and functions relevant for Plugin development. | ||
| The rest of the code deals with the internal workings of Slack Machine and is very much an implementation detail and | ||
| subject to change. Therefore it is not documented. | ||
|
|
||
| ## Plugin classes | ||
|
|
||
| The following 2 classes form the basis for Plugin development. | ||
|
|
||
| ### ::: machine.asyncio.plugins.base.MachineBasePlugin | ||
|
|
||
| ------------------------------------------------------------------------ | ||
|
|
||
| ### ::: machine.asyncio.plugins.base.Message | ||
|
|
||
|
|
||
| ## Decorators | ||
|
|
||
| These are the decorators you can use to have Slack Machine respond to | ||
| specific things (events, messages, etc.) | ||
|
|
||
| ### ::: machine.asyncio.plugins.decorators | ||
|
|
||
| ## Models | ||
|
|
||
| These classes represent base objects from the Slack API | ||
|
|
||
| ### ::: machine.asyncio.models.user.User | ||
|
|
||
| ### ::: machine.asyncio.models.channel.Channel | ||
|
|
||
| ## Storage | ||
|
|
||
| Storage is exposed to plugins through the `self.storage` field. The | ||
| following class implements the interface plugins can use to interact | ||
| with the storage backend. | ||
|
|
||
| ### ::: machine.asyncio.storage.PluginStorage | ||
|
|
||
| ------------------------------------------------------------------------ | ||
|
|
||
| New *Storage Backends* can be implemented by extending the following | ||
| class: | ||
|
|
||
| ### ::: machine.asyncio.storage.backends.base.MachineBaseStorage |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| # Async mode | ||
|
|
||
| As of v0.26.0 Slack Machine supports AsyncIO using the | ||
| [Slack Events API](https://api.slack.com/apis/connections/events-api) and | ||
| [Socket Mode](https://api.slack.com/apis/connections/socket). This is still experimental and should be thoroughly | ||
| tested. The goal is to eventually stop supporting the old version that uses the Slack RTM API, as the Events API is | ||
| recommended by Slack for must use cases and asyncio has the potential to be much more performant. | ||
|
|
||
| All the asyncio code is in the `machine.asyncio` package. | ||
|
|
||
| ## How to start using it | ||
|
|
||
| With the advent of asyncio in Slack Machine, we're also moving towards using **Slack Apps** instead of legacy bot | ||
| tokens. This means that you'll need to create a new app in Slack and get an app token and a bot token for it: | ||
|
|
||
| 1. Create a new app in Slack: <https://api.slack.com/apps> | ||
| 2. Choose to create an app from an _App manifest_ | ||
| 3. Copy/paste the following manifest: | ||
|
|
||
| ``` title="manifest.yaml" | ||
| --8<-- "docs/extra/manifest.yaml" | ||
| ``` | ||
| 4. Add the Slack API token to your `local_settings.py` like this: | ||
| ``` title="local_settings.py" | ||
| SLACK_APP_TOKEN = "xapp-my-app-token" | ||
| SLACK_BOT_TOKEN = "xoxb-my-bot-token" | ||
| ``` | ||
| 5. Start the bot with `slack-machine-async` | ||
| 6. ... | ||
| 7. Profit! | ||
| ## Choosing storage | ||
| Async mode uses different storage backend then the old sync mode. The following 2 backends are available: | ||
| - `machine.asyncio.storage.backends.memory.MemoryStorage` | ||
| - `machine.asyncio.storage.backends.memory.RedisStorage` | ||
| ## Plugin API and usage | ||
| To support asyncio, the plugin API is slightly different. All user-defined plugin methods (the methods that are | ||
| marked with the plugin [decorators][decorators]) should now be defined as `async def`. And all | ||
| [builtin plugin][machine.asyncio.plugins.base.MachineBasePlugin] methods are async as well. | ||
| This also means that the builtin plugins have async versions: | ||
| - `machine.asyncio.plugins.builtin.general.HelloPlugin`, | ||
| - `machine.asyncio.plugins.builtin.general.PingPongPlugin`, | ||
| - `machine.asyncio.plugins.builtin.help.HelpPlugin`, | ||
| - `machine.asyncio.plugins.builtin.fun.images.ImageSearchPlugin`, | ||
| - `machine.asyncio.plugins.builtin.fun.memes.MemePlugin`, | ||
| - `machine.asyncio.plugins.builtin.admin.RBACPlugin` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| display_information: | ||
| name: Slack Machine | ||
| features: | ||
| bot_user: | ||
| display_name: Slack Machine | ||
| always_online: false | ||
| oauth_config: | ||
| scopes: | ||
| bot: | ||
| - app_mentions:read | ||
| - channels:history | ||
| - channels:join | ||
| - channels:read | ||
| - chat:write | ||
| - chat:write.public | ||
| - emoji:read | ||
| - groups:history | ||
| - groups:read | ||
| - groups:write | ||
| - im:history | ||
| - im:read | ||
| - im:write | ||
| - mpim:history | ||
| - mpim:read | ||
| - mpim:write | ||
| - pins:read | ||
| - pins:write | ||
| - reactions:read | ||
| - reactions:write | ||
| - users:read | ||
| - users:read.email | ||
| - channels:manage | ||
| - chat:write.customize | ||
| - dnd:read | ||
| - files:read | ||
| - files:write | ||
| - links:read | ||
| - links:write | ||
| - metadata.message:read | ||
| - usergroups:read | ||
| - usergroups:write | ||
| - users.profile:read | ||
| - users:write | ||
| settings: | ||
| event_subscriptions: | ||
| bot_events: | ||
| - app_mention | ||
| - channel_archive | ||
| - channel_created | ||
| - channel_deleted | ||
| - channel_id_changed | ||
| - channel_left | ||
| - channel_rename | ||
| - channel_unarchive | ||
| - group_archive | ||
| - group_deleted | ||
| - group_left | ||
| - group_rename | ||
| - group_unarchive | ||
| - member_joined_channel | ||
| - member_left_channel | ||
| - message.channels | ||
| - message.groups | ||
| - message.im | ||
| - message.mpim | ||
| - reaction_added | ||
| - reaction_removed | ||
| - team_join | ||
| - user_change | ||
| - user_profile_changed | ||
| - user_status_changed | ||
| interactivity: | ||
| is_enabled: true | ||
| org_deploy_enabled: false | ||
| socket_mode_enabled: true | ||
| token_rotation_enabled: false |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.