# slash-slack
A python framework for building slack slash bots. Get input parsing and validation, command routing, async responses, auto-generated help dialog, response visibility, and response message formatting all for free.
`slash-slack` is a web server with a single endpoint (by default `/slash_slack`). In order to connect the Slack Slash command with the `slash-slack` server, the `slash-slack` server must be publicly accessible and the slash command must be configured with Slack. View [Slack slash command documentation](https://api.slack.com/interactivity/slash-commands) here.
```python
# EX: /slash-slack math 10 * 10
# Response: 100.0
import os
from slash_slack import Flag, Float, SlashSlack, String
slash = SlashSlack(signing_secret=os.environ['SLACK_SIGNING_SECRET'])
app = slash.get_fast_api()
@slash.command("math")
def math_fn(
x: float = Float(),
symbol: str = Enum(values={"*", "+", "-", "/"}),
y: float = Float(),
):
if symbol == "*":
return x * y
if symbol == "+":
return x + y
if symbol == "-":
return x - y
if symbol == "/":
return x / y
```
View a tutorial of creating a Slack slash command bot with `slash-slack` [here](https://github.com/henryivesjones/slash-slack/blob/main/how_to/how_to_create_slash_slack_bot_python.md).
# Why use `slash-slack`?
Building a slack slash bot can seem very straightforward at first, however there are some complexities that make it difficult. `slash-slack` handles all of the complexities for you letting you focus on the bot response handlers.
## Webhook signature verification
`slash-slack` will verify that incoming requests were made by slack by validating the request signature. To disable signature verification use the `dev=True` option when creating the `SlashSlack` object.
## Command Response Timeout/Async responses
Slack requires that the slash bot webhook be responded to within 3 seconds.
Often times the action being taken by the bot will depend on external services which might not respond within 3 seconds.
`slash-slack` sends an immediate `200` response to the webhook request, and runs the command function in the background. When the command function finishes, the response is sent back to slack using the `response_url` from the request.
You can optionally add content to the immediate response to let your user know that something is being
done in the background. A global/default response can be set with the `acknowledge_response` parameter on
the `SlashSlack` class, or at the command level with the `acknowledge_response` parameter on the `command` decorator.
The value passed to `acknowledge_response` will be passed to `blocks._make_block_message` and can be a `str`, `block`, `list[str]`, or `list[block]`
where a `block` is a [block kit block](https://api.slack.com/block-kit/building#getting_started).
See the [example](https://github.com/henryivesjones/slash-slack/blob/main/example.py) for example usage.
## Input Arg/Flag parsing
`slash-slack` takes care of parsing command input into pre-defined args and flags which let you focus on writing the command function, and not wrangling the content into the format that you need.
## Auto-generated help
`slash-slack` provides help dialog auto-generated from your commands, args, and flags. Additional details can be embedded directly into the command decorator and arg/flag initializers.
To request global help:
```
/slash-slack help
```
To request command specific help:
```
/slash-slack command --help
```
## Response visibility
Slack slash command responses can be made visible only to the requestor, or to the entire channel. `slash-slack` adds the ability for any command to be made visible with the `--visible` flag.
## Response formatting
Slack expects responses to be in the Slack Block Kit format. `slash-slack` will automatically convert your string responses into slack `mrkdown` blocks.
# Deployment
`slash-slack` is a WSGI app based on the FastAPI framework. Deploy using `uvicorn`.
You must expose the underlying app from the `SlashSlack` bot.
```python
# main.py
from slash_slack import SlashSlack
slash = SlashSlack()
app = slash.get_fast_api()
```
```
uvicorn main:app --port 9002 --reload
```
# Development/Webhook mocking.
A mock slack webhook client `mock-slack` is bundled with `slash-slack`. This client can be used to mock webhooks sent by slack.
To enter the mock slack client simply run `mock-slack`.
> `SlashSlack` must be `dev=True` to disable signature verification.
`mock-slack` will prompt you for input. Responses from the `slash-slack` server will be served in your browser in the Slack Block Kit Builder.
```
$ mock-slack
MSG: echo test
```
# Command Inputs
The inputs and parsing for each command is determined by the parameters to the function. `SlashSlack` parses the function parameters and generates an input schema.
When a request is made to a given command, `SlashSlack` attempts to parse the input text into the command input schema.
## Flags
Flags are boolean options that can be added to commands anywhere within the request. During the input parsing, flags are parsed and removed, and then args are parsed.
There is no difference in doing `/slash-slack command arg --flag` and `/slash-slack command --flag arg`.
### Global Flags
There are 2 global flags: `--visible` and `--help`.
The `--visible` flag will make the response visible in the channel that the request was made. By default, responses are only visible to the user which made the request.
The `--help` flag will indicate that the `SlashSlack` app should return the relevant help message. Whether that is app level `/slash-slack --help`, or command level `/slash-slack command --help`.
## Args
All non-flag arguments to the command function make up the input schema for the command function. This means that the # of words in the command request must match up with the # of non-flag arguments. (With two exceptions: String, UnknownLengthList).
### String
When the only non-flag parameter for the function is a `String()` then the entire argument body (with flags removed) will be passed into that parameter.
```python
# EX: /slash-slack echo hello --upper world
# Response: HELLO WORLD
@slash.command("echo")
def echo(s: str, upper: bool = Flag()):
return s
```
### Unknown Length List
To collect an arbitrary # of args from the user use the `UnknownLengthList` arg type. This arg type will be passed a list of all of the values passed to it parsed into the given type.
Because this consumes args till the end of the arg list, this must be the last non-flag param for the command function.
```python
# EX: /slash-slack avg 10, 20, 30
# Response: 20.0
@slash.command("avg")
def avg(numbers = UnknownLengthList(arg_type=Float())):
return sum(numbers) / len(numbers)
```
### SlashSlackRequest
If you want to have access to the complete request as sent from the slack servers. Add a param with the type annotation of `SlashSlackRequest` to the command function.
```python
# EX: /slash-slack echo hello world
# Response: hello world This request was made by John Doe
@slash.command("echo")
def echo(content: str, slash_slack_request: SlashSlackRequest):
return f"{content} This request was made by {slash_slack_request.user_name}"
```
# Example Application with Usage
```python
from typing import List
from slash_slack import Enum, Flag, Float, SlashSlack, String, UnknownLengthList
slash = SlashSlack(
signing_secret=os.environ["SLACK_SIGNING_SECRET"],
description="A python framework for slack slash bots.",
)
app = slash.get_fast_api()
@slash.command(
"echo",
summary="Echo",
help="Returns the provided text (made upper or lower case)",
)
def test_fn(
content: str = String(help="The content which will be echoed"),
upper: bool = Flag(help="Converts the input text to all UPPERCASE"),
lower: bool = Flag(help="Converts the input text to all lowercase"),
):
if upper:
return content.upper()
if lower:
return content.lower()
return content
@slash.command(
"math",
summary="Performs basic arithmetic between two numbers",
)
def math_fn(
x: float = Float(help="A number."),
symbol: str = Enum(
values={"*", "+", "-", "/"}, help="The arithmetic operation to use."
),
y: float = Float(help="A number."),
):
if symbol == "*":
return x * y
if symbol == "+":
return x + y
if symbol == "-":
return x - y
if symbol == "/":
return x / y
@slash.command(
"avg",
summary="Return the average of the given numbers",
help="EX: `avg 90 100 110.9`",
)
def unknown(
nums: List[float] = UnknownLengthList(
arg_type=Float(), help="The numbers to average."
),
):
return f"The avg of the given numbers is {sum(nums) / len(nums)}"
```
## Global Help
```
/slash-slack help
```
## Command Help
```
/slash-slack math --help
```
## Command invocation
```
/slash-slack math 10 * 20
```
## Command parsing error
```
/slash-slack math a * 100
```
Raw data
{
"_id": null,
"home_page": "https://github.com/henryivesjones/slash-slack",
"name": "slash-slack",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "slack,fastapi,bot,slash command",
"author": "",
"author_email": "Henry Jones <henryivesjones@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6c/c8/c32e10ef3dea1db74fccc52ededc874488319dd6df126c46106ab23530bd/slash-slack-0.2.2.tar.gz",
"platform": null,
"description": "# slash-slack\nA python framework for building slack slash bots. Get input parsing and validation, command routing, async responses, auto-generated help dialog, response visibility, and response message formatting all for free.\n\n`slash-slack` is a web server with a single endpoint (by default `/slash_slack`). In order to connect the Slack Slash command with the `slash-slack` server, the `slash-slack` server must be publicly accessible and the slash command must be configured with Slack. View [Slack slash command documentation](https://api.slack.com/interactivity/slash-commands) here.\n\n```python\n# EX: /slash-slack math 10 * 10\n# Response: 100.0\nimport os\n\nfrom slash_slack import Flag, Float, SlashSlack, String\n\nslash = SlashSlack(signing_secret=os.environ['SLACK_SIGNING_SECRET'])\napp = slash.get_fast_api()\n\n\n@slash.command(\"math\")\ndef math_fn(\n x: float = Float(),\n symbol: str = Enum(values={\"*\", \"+\", \"-\", \"/\"}),\n y: float = Float(),\n):\n if symbol == \"*\":\n return x * y\n if symbol == \"+\":\n return x + y\n if symbol == \"-\":\n return x - y\n if symbol == \"/\":\n return x / y\n```\n\nView a tutorial of creating a Slack slash command bot with `slash-slack` [here](https://github.com/henryivesjones/slash-slack/blob/main/how_to/how_to_create_slash_slack_bot_python.md).\n\n# Why use `slash-slack`?\nBuilding a slack slash bot can seem very straightforward at first, however there are some complexities that make it difficult. `slash-slack` handles all of the complexities for you letting you focus on the bot response handlers.\n\n## Webhook signature verification\n`slash-slack` will verify that incoming requests were made by slack by validating the request signature. To disable signature verification use the `dev=True` option when creating the `SlashSlack` object.\n\n## Command Response Timeout/Async responses\nSlack requires that the slash bot webhook be responded to within 3 seconds.\n\nOften times the action being taken by the bot will depend on external services which might not respond within 3 seconds.\n\n`slash-slack` sends an immediate `200` response to the webhook request, and runs the command function in the background. When the command function finishes, the response is sent back to slack using the `response_url` from the request.\n\nYou can optionally add content to the immediate response to let your user know that something is being\ndone in the background. A global/default response can be set with the `acknowledge_response` parameter on\nthe `SlashSlack` class, or at the command level with the `acknowledge_response` parameter on the `command` decorator.\nThe value passed to `acknowledge_response` will be passed to `blocks._make_block_message` and can be a `str`, `block`, `list[str]`, or `list[block]`\nwhere a `block` is a [block kit block](https://api.slack.com/block-kit/building#getting_started).\nSee the [example](https://github.com/henryivesjones/slash-slack/blob/main/example.py) for example usage.\n\n## Input Arg/Flag parsing\n`slash-slack` takes care of parsing command input into pre-defined args and flags which let you focus on writing the command function, and not wrangling the content into the format that you need.\n\n## Auto-generated help\n`slash-slack` provides help dialog auto-generated from your commands, args, and flags. Additional details can be embedded directly into the command decorator and arg/flag initializers.\n\nTo request global help:\n```\n/slash-slack help\n```\n\nTo request command specific help:\n```\n/slash-slack command --help\n```\n\n## Response visibility\nSlack slash command responses can be made visible only to the requestor, or to the entire channel. `slash-slack` adds the ability for any command to be made visible with the `--visible` flag.\n\n## Response formatting\nSlack expects responses to be in the Slack Block Kit format. `slash-slack` will automatically convert your string responses into slack `mrkdown` blocks.\n\n# Deployment\n`slash-slack` is a WSGI app based on the FastAPI framework. Deploy using `uvicorn`.\nYou must expose the underlying app from the `SlashSlack` bot.\n```python\n# main.py\nfrom slash_slack import SlashSlack\n\nslash = SlashSlack()\napp = slash.get_fast_api()\n\n```\n```\nuvicorn main:app --port 9002 --reload\n```\n\n# Development/Webhook mocking.\nA mock slack webhook client `mock-slack` is bundled with `slash-slack`. This client can be used to mock webhooks sent by slack.\n\nTo enter the mock slack client simply run `mock-slack`.\n\n> `SlashSlack` must be `dev=True` to disable signature verification.\n\n`mock-slack` will prompt you for input. Responses from the `slash-slack` server will be served in your browser in the Slack Block Kit Builder.\n```\n$ mock-slack\nMSG: echo test\n```\n\n\n# Command Inputs\nThe inputs and parsing for each command is determined by the parameters to the function. `SlashSlack` parses the function parameters and generates an input schema.\n\nWhen a request is made to a given command, `SlashSlack` attempts to parse the input text into the command input schema.\n## Flags\nFlags are boolean options that can be added to commands anywhere within the request. During the input parsing, flags are parsed and removed, and then args are parsed.\n\nThere is no difference in doing `/slash-slack command arg --flag` and `/slash-slack command --flag arg`.\n### Global Flags\nThere are 2 global flags: `--visible` and `--help`.\n\nThe `--visible` flag will make the response visible in the channel that the request was made. By default, responses are only visible to the user which made the request.\n\nThe `--help` flag will indicate that the `SlashSlack` app should return the relevant help message. Whether that is app level `/slash-slack --help`, or command level `/slash-slack command --help`.\n## Args\nAll non-flag arguments to the command function make up the input schema for the command function. This means that the # of words in the command request must match up with the # of non-flag arguments. (With two exceptions: String, UnknownLengthList).\n\n### String\nWhen the only non-flag parameter for the function is a `String()` then the entire argument body (with flags removed) will be passed into that parameter.\n```python\n# EX: /slash-slack echo hello --upper world\n# Response: HELLO WORLD\n@slash.command(\"echo\")\ndef echo(s: str, upper: bool = Flag()):\n return s\n```\n### Unknown Length List\nTo collect an arbitrary # of args from the user use the `UnknownLengthList` arg type. This arg type will be passed a list of all of the values passed to it parsed into the given type.\n\nBecause this consumes args till the end of the arg list, this must be the last non-flag param for the command function.\n```python\n# EX: /slash-slack avg 10, 20, 30\n# Response: 20.0\n@slash.command(\"avg\")\ndef avg(numbers = UnknownLengthList(arg_type=Float())):\n return sum(numbers) / len(numbers)\n```\n\n### SlashSlackRequest\nIf you want to have access to the complete request as sent from the slack servers. Add a param with the type annotation of `SlashSlackRequest` to the command function.\n\n```python\n# EX: /slash-slack echo hello world\n# Response: hello world This request was made by John Doe\n@slash.command(\"echo\")\ndef echo(content: str, slash_slack_request: SlashSlackRequest):\n return f\"{content} This request was made by {slash_slack_request.user_name}\"\n\n```\n\n# Example Application with Usage\n```python\nfrom typing import List\n\nfrom slash_slack import Enum, Flag, Float, SlashSlack, String, UnknownLengthList\n\nslash = SlashSlack(\n signing_secret=os.environ[\"SLACK_SIGNING_SECRET\"],\n description=\"A python framework for slack slash bots.\",\n)\napp = slash.get_fast_api()\n\n\n@slash.command(\n \"echo\",\n summary=\"Echo\",\n help=\"Returns the provided text (made upper or lower case)\",\n)\ndef test_fn(\n content: str = String(help=\"The content which will be echoed\"),\n upper: bool = Flag(help=\"Converts the input text to all UPPERCASE\"),\n lower: bool = Flag(help=\"Converts the input text to all lowercase\"),\n):\n if upper:\n return content.upper()\n if lower:\n return content.lower()\n\n return content\n\n\n@slash.command(\n \"math\",\n summary=\"Performs basic arithmetic between two numbers\",\n)\ndef math_fn(\n x: float = Float(help=\"A number.\"),\n symbol: str = Enum(\n values={\"*\", \"+\", \"-\", \"/\"}, help=\"The arithmetic operation to use.\"\n ),\n y: float = Float(help=\"A number.\"),\n):\n if symbol == \"*\":\n return x * y\n if symbol == \"+\":\n return x + y\n if symbol == \"-\":\n return x - y\n if symbol == \"/\":\n return x / y\n\n\n@slash.command(\n \"avg\",\n summary=\"Return the average of the given numbers\",\n help=\"EX: `avg 90 100 110.9`\",\n)\ndef unknown(\n nums: List[float] = UnknownLengthList(\n arg_type=Float(), help=\"The numbers to average.\"\n ),\n):\n return f\"The avg of the given numbers is {sum(nums) / len(nums)}\"\n\n```\n## Global Help\n```\n/slash-slack help\n```\n\n\n## Command Help\n```\n/slash-slack math --help\n```\n\n\n## Command invocation\n```\n/slash-slack math 10 * 20\n```\n\n\n## Command parsing error\n```\n/slash-slack math a * 100\n```\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A python framework for slack slash bots.",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/henryivesjones/slash-slack"
},
"split_keywords": [
"slack",
"fastapi",
"bot",
"slash command"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "792634db2c8dfde41e1ceaf5e5fb935a2ce2b464e861624725298eafd65b0108",
"md5": "00248bc0329302c22e5cf013bfb71bd9",
"sha256": "d23820f8923e02016d28f7ef5303714e9b52745ab536fcf6ac8039ef51b68318"
},
"downloads": -1,
"filename": "slash_slack-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00248bc0329302c22e5cf013bfb71bd9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 29144,
"upload_time": "2023-07-20T21:23:46",
"upload_time_iso_8601": "2023-07-20T21:23:46.364913Z",
"url": "https://files.pythonhosted.org/packages/79/26/34db2c8dfde41e1ceaf5e5fb935a2ce2b464e861624725298eafd65b0108/slash_slack-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6cc8c32e10ef3dea1db74fccc52ededc874488319dd6df126c46106ab23530bd",
"md5": "1cc1459957a67fbee1e2aaace45854f9",
"sha256": "937d4f7eae6efa9f02daa91904725d8476ac849726c64b7a1850ffedb92cd1de"
},
"downloads": -1,
"filename": "slash-slack-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "1cc1459957a67fbee1e2aaace45854f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 32001,
"upload_time": "2023-07-20T21:23:47",
"upload_time_iso_8601": "2023-07-20T21:23:47.895825Z",
"url": "https://files.pythonhosted.org/packages/6c/c8/c32e10ef3dea1db74fccc52ededc874488319dd6df126c46106ab23530bd/slash-slack-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-20 21:23:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "henryivesjones",
"github_project": "slash-slack",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "slash-slack"
}
JSON
