Skip to content

Commit a85d12e

Browse files
misscodedmisscoded
authored
feat: update README (#9)
1 parent efed2b0 commit a85d12e

File tree

1 file changed

+29
-129
lines changed

1 file changed

+29
-129
lines changed

‎README.md‎

Lines changed: 29 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,154 +1,54 @@
1-
<h1 align="center">Python Slack Hooks</h1>
1+
# Python Slack Hooks
22

3-
A helper library implementing the contract between the
4-
[Slack CLI][slack-cli-docs] and
5-
[Bolt for Python](https://slack.dev/bolt-python/)
3+
This library defines the contract between the
4+
[Slack CLI](https://api.slack.com/automation/cli/install) and
5+
[Bolt for Python](https://slack.dev/bolt-python/).
66

7-
## Environment requirements
7+
## Overview
8+
This library enables inter-process communication between the [Slack CLI](https://api.slack.com/automation/cli/install) and applications built with Bolt for Python.
89

9-
Before getting started, make sure you have a development workspace where you
10-
have permissions to install apps. **Please note that leveraging all features in
11-
this project require that the workspace be part of
12-
[a Slack paid plan](https://slack.com/pricing).**
10+
When used together, the CLI delegates various tasks to the Bolt application by invoking processes ("hooks") and then making use of the responses provided by each hook's `stdout`.
1311

14-
### Install the Slack CLI
12+
For a complete list of available hooks, read the [Supported Hooks](#supported-hooks) section.
1513

16-
Install the Slack CLI. Step-by-step instructions can be found in this
17-
[Quickstart Guide][slack-cli-docs].
14+
## Requirements
15+
The latest minor version of [Bolt v1](https://pypi.org/project/slack-bolt/) is recommended.
1816

19-
### Environment Setup
17+
## Usage
18+
A Slack CLI-compatible Slack application includes a `./slack.json` file that contains hooks specific to that project. Each hook is associated with commands that are available in the Slack CLI. By default, `get-hooks` retrieves all of the [supported hooks](#supported-hooks) and their corresponding scripts as defined in this library.
2019

21-
Create a project folder and a
22-
[virtual environment](https://docs.python.org/3/library/venv.html#module-venv)
23-
within it
20+
The CLI will always use the version of the `python-slack-hooks` that is specified in the project's `requirements.txt`.
2421

25-
```zsh
26-
# Python 3.6+ required
27-
mkdir myproject
28-
cd myproject
29-
python3 -m venv .venv
30-
```
22+
### Supported Hooks
3123

32-
Activate the environment
24+
The hooks currently supported for use within the Slack CLI include `check-update`, `get-hooks`, `get-manifest`, and `start`:
3325

34-
```zsh
35-
source .venv/bin/activate
36-
```
26+
| Hook Name | CLI Command | File | Description |
27+
| --- | --- | --- | --- |
28+
| `check-update` | `slack update` | [check_update.py](./slack_cli_hooks/hooks/check_update.py) | Checks the project's Slack dependencies to determine whether or not any libraries need to be updated. |
29+
| `get-hooks` | All | [get_hooks.py](./slack_cli_hooks/hooks/get_hooks.py) | Fetches the list of available hooks for the CLI from this repository. |
30+
| `get-manifest` | `slack manifest` | [get_manifest.py](./slack_cli_hooks/hooks/get_manifest.py) | Converts a `manifest.json` file into a valid manifest JSON payload. |
31+
| `start` | `slack run` | [start.py](./slack_cli_hooks/hooks/start.py) | While developing locally, the CLI manages a socket connection with Slack's backend and utilizes this hook for events received via this connection. |
3732

38-
### Pypi
3933

40-
Install this package using pip.
34+
### Overriding Hooks
35+
To customize the behavior of a hook, add the hook to your application's `/slack.json` file, and provide a corresponding script to be executed.
4136

42-
```zsh
43-
pip install -U slack-cli-hooks
44-
```
37+
When commands are run, the Slack CLI will look to the project's hook definitions and use those instead of what's defined in this library, if provided.
4538

46-
### Clone
39+
Below is an example `/slack.json` file that overrides the default `start`:
4740

48-
Clone this project using git.
49-
50-
```zsh
51-
git clone https://github.com/slackapi/python-slack-hooks.git
5241
```
53-
54-
Follow the
55-
[Develop Locally](https://github.com/slackapi/python-slack-hooks/blob/main/.github/maintainers_guide.md#develop-locally)
56-
steps in the maintainers guide to build and use this package.
57-
58-
## Simple project
59-
60-
In the same directory where we installed `slack-cli-hooks`
61-
62-
1. Define basic information and metadata about our app via an
63-
[App Manifest](https://api.slack.com/reference/manifests) (`manifest.json`).
64-
2. Create a `slack.json` file that defines the interface between the
65-
[Slack CLI][slack-cli-docs] and [Bolt for Python][bolt-python-docs].
66-
3. Use an `app.py` file to define the entrypoint for a
67-
[Bolt for Python][bolt-python-docs] project.
68-
69-
### Application Configuration
70-
71-
Define your [Application Manifest](https://api.slack.com/reference/manifests) in
72-
a `manifest.json` file.
73-
74-
```json
75-
{
76-
"display_information": {
77-
"name": "simple-app"
78-
},
79-
"outgoing_domains": [],
80-
"settings": {
81-
"org_deploy_enabled": true,
82-
"socket_mode_enabled": true,
83-
},
84-
"features": {
85-
"bot_user": {
86-
"display_name": "simple-app"
87-
}
88-
},
89-
"oauth_config": {
90-
"scopes": {
91-
"bot": ["chat:write"]
92-
}
93-
}
94-
}
95-
```
96-
97-
### CLI/Bolt Interface Configuration
98-
99-
Define the Slack CLI configuration in a file named `slack.json`.
100-
101-
```json
10242
{
10343
"hooks": {
104-
"get-hooks": "python3 -m slack_cli_hooks.hooks.get_hooks"
44+
"get-hooks": "python3 -m slack_cli_hooks.hooks.get_hooks",
45+
"start": "python3 app.py"
10546
}
10647
}
10748
```
10849

109-
### Source code
110-
111-
Create a [Bolt for Python][bolt-python-docs] app in a file named `app.py`.
112-
Alternatively you can use an existing app instead.
113-
114-
```python
115-
from slack_bolt import App
116-
from slack_bolt.adapter.socket_mode import SocketModeHandler
117-
118-
app = App()
119-
120-
# Add functionality here
121-
122-
if __name__ == "__main__":
123-
SocketModeHandler(app).start()
124-
```
125-
126-
## Running the app
127-
128-
You should now be able to harness the power of the Slack CLI and Bolt.
129-
130-
Run the app this way:
131-
132-
```zsh
133-
slack run
134-
```
135-
136-
## Getting Help
137-
138-
If you get stuck we're here to help. Ensure your issue is related to this
139-
project and not to [Bolt for Python][bolt-python-docs]. The following are the
140-
best ways to get assistance working through your issue:
141-
142-
- [Issue Tracker](https://github.com/slackapi/python-slack-hooks/issues) for
143-
questions, bug reports, feature requests, and general discussion. **Try
144-
searching for an existing issue before creating a new one.**
145-
- Email our developer support team: `support@slack.com`
146-
14750
## Contributing
14851

149-
Contributions are more then welcome. Please look at the
52+
Contributions are always welcome! Please review the
15053
[contributing guidelines](https://github.com/slackapi/python-slack-hooks/blob/main/.github/CONTRIBUTING.md)
151-
for more info!
152-
153-
[slack-cli-docs]: https://api.slack.com/automation/cli
154-
[bolt-python-docs]: https://slack.dev/bolt-python/concepts
54+
for more information.

0 commit comments

Comments
 (0)