Metadata-Version: 2.4
Name: script-reporter
Version: 0.1.0
Summary: A lightweight status reporter for Python scripts with Discord and Telegram support
Author-email: Yoonbae Cho <y@xcv.kr>
License: MIT
Project-URL: Homepage, https://github.com/yoonbae81/script-reporter
Project-URL: Bug Tracker, https://github.com/yoonbae81/script-reporter/issues
Keywords: reporter,notification,discord,telegram,script,monitoring
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
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

```python
from script_reporter import ScriptReporter
import traceback

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

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

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

### 2. Manual Configuration

Explicitly control adapters without environment variables:

```python
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")
]

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

## 📊 JSON Log Format

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

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

## 🛠 Advanced Concepts

- **Stages**: Use `reporter.stage("NAME")` to track progress. If `reporter.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](LICENSE) for more details.
