Skip to content
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

feat: update README #9

Merged
merged 3 commits into from
Jan 11, 2024
Merged

feat: update README #9

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aa94f3e
Update README
misscoded Jan 10, 2024
147ec20
Incorporate PR feedback
misscoded Jan 11, 2024
5c34b38
Another CLI repo ref
misscoded Jan 11, 2024
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
159 changes: 30 additions & 129 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,154 +1,55 @@
<h1 align="center">Python Slack Hooks</h1>
# Python Slack Hooks

A helper library implementing the contract between the
[Slack CLI][slack-cli-docs] and
[Bolt for Python](https://slack.dev/bolt-python/)
This library defines the contract between the
[Slack CLI](https://github.com/slackapi/slack-cli) and
misscoded marked this conversation as resolved.
Show resolved Hide resolved
[Bolt for Python](https://slack.dev/bolt-python/).

## Environment requirements
## Overview
This library enables inter-process communication between the [Slack CLI](https://github.com/slackapi/slack-cli) and applications built with Bolt for Python.

Before getting started, make sure you have a development workspace where you
have permissions to install apps. **Please note that leveraging all features in
this project require that the workspace be part of
[a Slack paid plan](https://slack.com/pricing).**
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`.

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

Install the Slack CLI. Step-by-step instructions can be found in this
[Quickstart Guide][slack-cli-docs].
## Requirements
This library requires Bolt `v1.18.0` or above.
misscoded marked this conversation as resolved.
Show resolved Hide resolved

### Environment Setup
## Usage
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 [supported hooks](#supported-hooks) and their corresponding scripts as defined in this library.
misscoded marked this conversation as resolved.
Show resolved Hide resolved

Create a project folder and a
[virtual environment](https://docs.python.org/3/library/venv.html#module-venv)
within it
The CLI will always use the version of the `python-slack-hooks` that is specified in the project's `requirements.txt`.
zimeg marked this conversation as resolved.
Show resolved Hide resolved

```zsh
# Python 3.6+ required
mkdir myproject
cd myproject
python3 -m venv .venv
```
### Supported Hooks

Activate the environment
The hooks currently supported for use within the Slack CLI include `check-update`,
`get-manifest`, `install-update`, and `start`:
misscoded marked this conversation as resolved.
Show resolved Hide resolved

```zsh
source .venv/bin/activate
```
| Hook Name | CLI Command | File | Description |
| --- | --- | --- | --- |
| `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. |
| `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. |
| `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. |
misscoded marked this conversation as resolved.
Show resolved Hide resolved
| `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. |

### Pypi

Install this package using pip.
### Overriding Hooks
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.

```zsh
pip install -U slack-cli-hooks
```
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. Only [supported hooks](#supported-hooks) will be recognized and executed by the Slack CLI.
misscoded marked this conversation as resolved.
Show resolved Hide resolved

### Clone
Below is an example `/slack.json` file that overrides the default `start` hook to **[???]**:
misscoded marked this conversation as resolved.
Show resolved Hide resolved

Clone this project using git.

```zsh
git clone https://github.com/slackapi/python-slack-hooks.git
```

Follow the
[Develop Locally](https://github.com/slackapi/python-slack-hooks/blob/main/.github/maintainers_guide.md#develop-locally)
steps in the maintainers guide to build and use this package.

## Simple project

In the same directory where we installed `slack-cli-hooks`

1. Define basic information and metadata about our app via an
[App Manifest](https://api.slack.com/reference/manifests) (`manifest.json`).
2. Create a `slack.json` file that defines the interface between the
[Slack CLI][slack-cli-docs] and [Bolt for Python][bolt-python-docs].
3. Use an `app.py` file to define the entrypoint for a
[Bolt for Python][bolt-python-docs] project.

### Application Configuration

Define your [Application Manifest](https://api.slack.com/reference/manifests) in
a `manifest.json` file.

```json
{
"display_information": {
"name": "simple-app"
},
"outgoing_domains": [],
"settings": {
"org_deploy_enabled": true,
"socket_mode_enabled": true,
},
"features": {
"bot_user": {
"display_name": "simple-app"
}
},
"oauth_config": {
"scopes": {
"bot": ["chat:write"]
}
}
}
```

### CLI/Bolt Interface Configuration

Define the Slack CLI configuration in a file named `slack.json`.

```json
{
"hooks": {
"get-hooks": "python3 -m slack_cli_hooks.hooks.get_hooks"
"get-hooks": "python3 -m slack_cli_hooks.hooks.get_hooks",
"start": "???"
misscoded marked this conversation as resolved.
Show resolved Hide resolved
}
}
```

### Source code

Create a [Bolt for Python][bolt-python-docs] app in a file named `app.py`.
Alternatively you can use an existing app instead.

```python
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler

app = App()

# Add functionality here

if __name__ == "__main__":
SocketModeHandler(app).start()
```

## Running the app

You should now be able to harness the power of the Slack CLI and Bolt.

Run the app this way:

```zsh
slack run
```

## Getting Help

If you get stuck we're here to help. Ensure your issue is related to this
project and not to [Bolt for Python][bolt-python-docs]. The following are the
best ways to get assistance working through your issue:

- [Issue Tracker](https://github.com/slackapi/python-slack-hooks/issues) for
questions, bug reports, feature requests, and general discussion. **Try
searching for an existing issue before creating a new one.**
- Email our developer support team: `[email protected]`

## Contributing

Contributions are more then welcome. Please look at the
Contributions are always welcome! Please review the
[contributing guidelines](https://github.com/slackapi/python-slack-hooks/blob/main/.github/CONTRIBUTING.md)
for more info!

[slack-cli-docs]: https://api.slack.com/automation/cli
[bolt-python-docs]: https://slack.dev/bolt-python/concepts
for more information.