chirppy 0.1.0

Send simple notifications to Slack, Discord, Telegram, and webhooks.

chirppy

A lightweight Python library for sending notifications to multiple platforms with a unified API. Send messages to Slack, Discord, Telegram, and generic webhooks with minimal configuration.

Features

• Unified API - Send notifications to multiple platforms with a single function call.
• Multiple Providers - Supports Slack, Discord, Telegram, and arbitrary webhook endpoints.
• Async Support - Fully async-compatible API via async_send.
• Easy Configuration - Use environment variables or pass webhook URLs directly.
• Lightweight - Minimal dependencies.
• Built-in Retries - Automatic retry logic for failed requests.

Installation

pip install chirppy

Quick Start

Basic Usage

Send a simple notification:

from chirppy import send

# Send with explicit webhook URL
send("Hello world", slack="https://hooks.slack.com/services/...")

Provider-Specific Usage

Send a notification to a specific provider.

from chirppy.slack import send

# Send with an explicit webhook URL
send("Hello world", url="https://hooks.slack.com/services/...")

Using Environment Variables

For convenience, configure your webhooks as environment variables:

export CHIRPPY_SLACK_WEBHOOK=https://hooks.slack.com/services/...
export CHIRPPY_DISCORD_WEBHOOK=https://discord.com/api/webhooks/...
export CHIRPPY_TELEGRAM_TOKEN=your-telegram-bot-token
export CHIRPPY_TELEGRAM_CHAT_ID=your-telegram-chat-id
export CHIRPPY_CUSTOM_WEBHOOK=https://example.com/webhook

Then send notifications without specifying URLs:

from chirppy import send

# Automatically uses environment variables
send("Build completed", slack=True, discord=True)

Supported Providers

Provider	Parameter	Environment Variable
Slack	slack	CHIRPPY_SLACK_WEBHOOK
Discord	discord	CHIRPPY_DISCORD_WEBHOOK
Telegram	telegram	CHIRPPY_TELEGRAM_TOKEN, CHIRPPY_TELEGRAM_CHAT_ID
Custom	webhook	CHIRPPY_CUSTOM_WEBHOOK

Async Usage

Chirppy is fully async-compatible. Use async_send instead of send.

Basic Async Example

Send an asynchronous message.

import asyncio
from chirppy import async_send

async def main():
    await async_send(
        "Hello async world",
        slack="https://hooks.slack.com/services/..."
    )

asyncio.run(main())

Provider-Specific Usage

Send an asynchronous notification to a specific provider.

import asyncio
from chirppy.slack import async_send

async def main():
    await async_send("Async processing complete")

asyncio.run(main())

Configuration

Environment Variables

Chirppy supports the following environment variables for configuration:

# Slack and Discord webhooks
CHIRPPY_SLACK_WEBHOOK=https://...
CHIRPPY_DISCORD_WEBHOOK=https://...

# Telegram token and chat ID
CHIRPPY_TELEGRAM_TOKEN=your-bot-token
CHIRPPY_TELEGRAM_CHAT_ID=your-chat-id

# Custom webhook endpoint
CHIRPPY_CUSTOM_WEBHOOK=https://...

Examples

Send to Multiple Platforms

from chirppy import send

send(
    "Deployment complete",
    slack=True,
    telegram=True
    discord="https://...",
)

Send to Multiple Platforms with overrides

from chirppy import send

send(
    "Hello",
    slack=True,
    discord={"message": "Alternative message", "username": "different-user"},
    telegram={"token": "your-telegram-token", "chat_id": "your-chat-id"},
)

Send with Custom Webhook

from chirppy import send

send(
    "Custom alert",
    webhook="https://your-webhook-endpoint.com/notify"
)

License

This project is licensed under the MIT License - see the LICENSE file for details.