slack-helpers

An easy wrapper to send objects to Slack.

📦 Main Features:

• Send text
• Send images (pillow)
• Send plots (matplotlib)
• Send tracebacks (rich tracebacks with syntax highlighting, in svg, png, or html)
• Set up with environment variables, so no need for more configuration. Just import and use.
• Ensure preview mode (append """"dear-viewer"""" prefix to the text so it won't be considered as a binary)
• Instantly preview with dear-chrome-viewer (a Chrome extension to preview html, PDB, and other files)
  • Normally, the Slack preview just views the file in plain text so the extension just makes it easier to view the file in the browser.
• Does NOT error out if the Slack token is not set. It just logs a warning and does not send the message.
  • You don't need to add a conditional check for the token. Just import and use.

😢 Caveats:

• External dependencies have to be installed (The cairo library and fira code font)
  • The scripts/install_binaries.sh script installs the dependencies.

🛠️ Installation

We recommend using Conda because it's easier to install Cairo. If you don't want to use Conda, you can install Cairo using apt-get or brew.

conda create -n slack-helpers python=3.12
conda activate slack-helpers
pip install slack-helpers
bash scripts/install_binaries.sh  # install Fira Code font ~/.local/share/fonts, and Cairo using Conda

Set environment variables for the slack token and channel.

export SLACK_BOT_TOKEN=xoxb-xxxx
export SLACK_APP_TOKEN=xapp-xxxx
export SLACK_CHANNEL_ID=CXXXXXXXX

or use a .env file with python-dotenv.

# .env
SLACK_BOT_TOKEN=xoxb-xxxx
SLACK_APP_TOKEN=xapp-xxxx
SLACK_CHANNEL_ID=CXXXXXXXX

import dotenv
dotenv.load_dotenv()

Check health of the installation. The below output shows that the Slack tokens are not set, and the Fira Code font is installed.

$ slack-helpers health
09/07 21:37:12 ERROR    slack_helpers.health.slack - 😡 Please set the environment variable SLACK_BOT_TOKEN.                                                slack.py:14
               ERROR    slack_helpers.health.slack - 😡 Please set the environment variable SLACK_APP_TOKEN.                                                slack.py:14
               ERROR    slack_helpers.health.slack - 😡 Please set the environment variable SLACK_CHANNEL_ID.                                               slack.py:14
               INFO     slack_helpers.health.slack - 🚀 Sending a test message to the Slack channel...                                                      slack.py:45
               WARNING  slack_helpers.send_only - You tried to send messages on Slack, but the token is not set. All messages will be ignored.          send_only.py:21
               ERROR    slack_helpers.health.slack - 😡 The response is None.                                                                               slack.py:49
               INFO     slack_helpers.health.font - ✅ FiraCode font is installed.                                                                           font.py:35

🚀 Usage

See tools/examples/ for complete set of examples.

Send-only example

from dotenv import load_dotenv

load_dotenv()

from slack_helpers.send_only import (
    send_divider,
    send_file,
    send_matplotlib_fig,
    send_pil_image,
    send_text,
)

if __name__ == "__main__":
    send_text("Hello, World!")
    send_divider()
    send_file(
        filename="1A0G.pdb",
        file="/path/to/1A0G.pdb",
        title="My Test PDB File",
        initial_comment="Here's a PDB file for you!",
    )
    send_matplotlib_fig(
        filename="matplotlib_fig.pdf",
        fig=fig,
        title="My Test Matplotlib Figure",
        initial_comment="Here's a matplotlib figure for you!",
    )
    send_pil_image(
        filename="pil_image.png",
        image=pil_image,
        title="My Test PIL Image",
        initial_comment="Here's a PIL image for you!",
    )

Traceback example

from dotenv import load_dotenv

load_dotenv()

from rich.traceback import Traceback

from slack_helpers.send_only import send_svg_as_pdf
from slack_helpers.utils.rich import (
    CONSOLE_WIDTH,
    rich_traceback_to_svg,
)


if __name__ == "__main__":
    try:
        raise Exception("This is an exception")
    except Exception:
        slack_text = "Exception occurred"

        tb = Traceback(show_locals=True, width=CONSOLE_WIDTH)
        tb_svg = rich_traceback_to_svg(
            tb, title=f"Exception occurred from host {socket.gethostname()}"
        )
        send_svg_as_pdf(
            filename="traceback.pdf",
            svg_file=tb_svg,
            title="traceback.pdf",
        )

Interactive example

from dotenv import load_dotenv

load_dotenv()

from slack_helpers import app
from slack_helpers.interactive import handler

assert app is not None, "Set environment variables SLACK_* first."


@app.message("hello")
def hello_message(body: dict[str, Any], say):
    print("Received a hello command")
    print(f"body: {pformat(body)}")
    say(text=f"Hi <@{body['event']['user']}>!")


handler.start()