script-reporter 🚀

A lightweight, zero-dependency Python status reporter designed for automation scripts and cron jobs. Easily report execution progress, stages, and results to Console, Discord, and Telegram.

✨ Key Features

• Zero External Dependencies: Uses Python standard library only (urllib).
• Multi-Channel: Simultaneous reporting to Console, Discord (Webhooks), and Telegram (Bot API).
• Stage Tracking: Monitor exactly where your script is (e.g., SETUP -> PROCESSING -> COMPLETE).
• Error Transparency: Automatically attaches tracebacks on failure.
• Duration Tracking: Automatically calculates and reports execution time.
• CI/CD & Cron Friendly: Standardized JSON output for logs makes it easy for other tools to parse.

📦 Installation

pip install script-reporter

🚀 Quick Start

1. Simple Usage (Auto-reporitng)

Set simple environment variables to enable channels:

• REPORTER_DISCORD_WEBHOOK: Discord Webhook URL
• REPORTER_TELEGRAM_TOKEN & REPORTER_TELEGRAM_CHAT_ID: Telegram Bot Token and Chat ID

from script_reporter import ScriptReporter
import traceback

# Initialize with a title (auto-detects Discord/Telegram from Env)
sr = ScriptReporter("My Automation Task")

try:
    # 1. Start a stage
    sr.stage("DATA_FETCH")
    # ... your logic ...
    
    # 2. Update stage as you progress
    sr.stage("PROCESSING")
    # ... your logic ...
    
    # 3. Report success with optional detail dictionary
    sr.success({"items_processed": 100, "status": "all_good"})

except Exception:
    # 4. Report failure with traceback
    sr.fail(traceback.format_exc())

2. Manual Configuration

Explicitly control adapters without environment variables:

from script_reporter import ScriptReporter, ConsoleAdapter, DiscordAdapter, TelegramAdapter

adapters = [
    ConsoleAdapter(),
    DiscordAdapter(webhook_url="https://discord.com/api/webhooks/..."),
    TelegramAdapter(token="BOT_TOKEN", chat_id="CHAT_ID")
]

sr = ScriptReporter("Manual Config Task", adapters=adapters)
sr.success({"msg": "Hello from code!"})

📊 JSON Log Format

ConsoleAdapter prints a machine-readable JSON line starting with __RESULT__:

__RESULT__ {"title": "My Task", "host": "server-01", "stage": "COMPLETE", "status": "SUCCESS", "duration": "1m 30s", "detail": {"processed": 5}}

🛠 Advanced Concepts

• Stages: Use sr.stage("NAME") to track progress. If sr.fail() is called, it identifies the last successful stage.
• Duration: Tracks time from ScriptReporter() initialization to success()/fail() call.
• Discord Rich Embeds: DiscordAdapter automatically formats details and errors into beautiful rich embeds.

📄 License

MIT License. See LICENSE for more details.