Alerts#

The Alerts module in DMF Utils provides tools for sending notifications and alerts via messaging services such as Slack and Telegram. These alerts can be used to notify when a function completes, send files, or schedule messages. The module is highly configurable and designed to integrate into your existing workflows.

To install this module, use the following command:

pip install dmf-utils[alerts]

Overview#

The Alerts module allows you to:

Send messages and files to Slack or Telegram.
Decorate functions to automatically send notifications when they finish executing.
Customize alerts with different levels such as success, info, warning, and error.
Use different backends (Slack, Telegram) with simple configuration.

This module is useful for integrating notifications into your data processing pipelines, experiments, or any long-running tasks where you need to be informed of the status or results.

Reference#

Main Functions:

The main functions provided by the Alerts module are:

`dmf.alerts.alert`([func, output, input, ...])	Decorator that sends an alert after the execution of the decorated function.
`dmf.alerts.send_alert`([text, attachment, ...])	Sends a message formatted as an alert with the specified text and alert level.
`dmf.alerts.send_message`([text, attachment, ...])	Sends a message using the appropriate backend, encapsulating the logic of retrieving the backend and handling attachments and scheduling.

Backends:

Internally, the Alerts module uses different backends to send messages to Slack or Telegram, transparently handling the communication with the messaging services. See configuration instructions below for setting up Slack or Telegram.

`dmf.alerts.get_backend`([alert_token, store])	Get or create an AlertBackend instance.
`dmf.alerts.slack_backend.SlackBackend`(token)	A backend for sending alerts through Slack.
`dmf.alerts.telegram_backend.TelegramBackend`(token)	A backend for sending alerts through Telegram.

Other:

Additional classes and exceptions used by the module:

`dmf.alerts.backend.AlertException`	Exception raised for errors in the alert backend.
`dmf.alerts.backend.AlertBackend`([fail_silently])	Base class for alert backends.

Configuration#

Setting Up Slack#

To use the Alerts module with Slack, follow these steps:

Go to the Slack Apps website and log in to your workspace.
Go to an existing app or create a new Slack app in your workspace. If you are part of the DMF, you can ask for our API keys.
Navigate to the “OAuth & Permissions” section in your app’s settings.
In the “Scopes” section, add the following scopes: - chat:write (to send messages) - files:write (to send files) - channels:read (to write in public channels without being invited)
Install the app in a channel. This can be a personal app or any channel where you want to send notifications.
If you want to send notifications to a private channel, invite the bot to the channel. You can do this with the command /invite @name_of_the_bot.

To use the functions without specifying credentials every time:

Save the token into the environment variable DMF_ALERTS_TOKEN:
```
export DMF_ALERTS_TOKEN="your-slack-api-token"
```
Save the channel name or the channel ID into the environment variable DMF_DEFAULT_CHANNEL:
```
export DMF_DEFAULT_CHANNEL="your-channel-name-or-id"
```

Once these steps are complete, your Slack app will be able to send alerts through the DMF Utils package without requiring you to specify the token or channel name in your code.

Setting Up Telegram#

To use the Alerts module with Telegram, follow these steps:

Open Telegram and start a chat with the BotFather, which is the official bot used to create and manage Telegram bots.
Create a new bot by sending the command /newbot to the BotFather. Follow the prompts to choose a name and username for your bot. Once the bot is created, the BotFather will provide you with an API token.
Save the API token provided by the BotFather. This token is required to authenticate your bot and send messages.
Obtain the chat ID where the bot will send messages. You can get the chat ID by adding your bot to a group and sending a message. Then, use the https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates with your bot token to retrieve the chat ID from the response.

Replace <YOUR_BOT_TOKEN> with your actual bot token in the API call.

Alternatively, you can use third-party tools or Telegram bot management tools to easily find the chat ID.

To use the functions without specifying credentials every time:

Save the bot token into the environment variable DMF_ALERTS_TOKEN:
```
export DMF_ALERTS_TOKEN="your-telegram-bot-token"
```
Save the chat ID into the environment variable DMF_DEFAULT_CHANNEL:
```
export DMF_DEFAULT_CHANNEL="your-chat-id"
```

Once these steps are complete, your Telegram bot will be able to send alerts through the DMF Utils package without requiring you to specify the token or chat ID in your code.

Command-Line Interface#

The Alerts module also provides a command-line tool called dmf-alert for sending messages directly from the terminal.

Example:

dmf-alert "Execution finished successfully" -a output.txt

This command will send a message saying “Execution finished successfully” and attach the file output.txt.

Alternatively, you can use it to return the output of a command:

./my_script | dmf-alert -l info

Examples#

Sending Alerts in Python#

You can send alerts directly from your Python code using the send_alert and send_message functions.

Example:

from dmf.alerts import send_alert

send_alert(text="This is a test alert", level="info")

This will send a simple alert with the specified text and level.

Function Decorator#

The alert decorator can be used to automatically send notifications when a function completes. This is particularly useful for long-running tasks.

Example:

from dmf.alerts import alert

@alert
def my_function(name):
    # Simulate a task
    sleep(5)
    return f"Hello, {name}!"

my_function("World")

In this example, a notification will be sent when my_function finishes, including the function’s output and duration.

Sending Messages with Attachments#

You can also send files as attachments in your alerts. This is useful for sending logs, reports, or any other file generated during your script’s execution.

Example:

from dmf.alerts import send_message
from pathlib import Path

send_message(text="Here is the report", attachment=Path("report.pdf"))

This will send the report.pdf file along with the message text.