Metadata-Version: 2.4
Name: tg-dropin
Version: 0.1.0
Summary: Zero-dependency Telegram sidecar for existing Python scripts
Author: jacerdev
License-Expression: MIT
Project-URL: Homepage, https://github.com/jacerdev/tg-dropin
Project-URL: Repository, https://github.com/jacerdev/tg-dropin
Project-URL: Issues, https://github.com/jacerdev/tg-dropin/issues
Keywords: telegram,bot,remote-control,automation,research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# TG-DropIn: Zero-Dependency Telegram Sidecar

**Add Telegram remote control to any Python script — without rewriting anything.**

`tg-dropin` is a zero-dependency Telegram sidecar for long-running scripts, research experiments, training jobs, data pipelines, and automation.

Unlike major bot frameworks that hijack the main loop or require rewriting code around `asyncio`, `tg-dropin` acts as a lightweight sidecar that requires no changes to the existing codebase.

## Features
- **Zero Dependencies:** Uses only standard library modules.
- **Media Support:** Built-in `notify`, `send_image`, and `send_document` utility methods.
- **Exception Notifications:** Wrap code in a context manager to instantly send tracebacks on crash.
- **Security Whitelisting:** Only processes messages from explicitly specified `CHAT_ID` (or list of IDs).

## Installation

**Install via pip:**
```bash
pip install tg-dropin
```

**Or just drop it in literally:**
Copy `src/tg_dropin.py` directly into the project directory.

## Quickstart

```python
from tg_dropin import TelegramSidecar

# Initialize bot with credentials
bot = TelegramSidecar(bot_token="BOT_TOKEN", chat_id=["USER_1_ID", "USER_2_ID"])

# Optional: Register commands with descriptions for the auto-generated /help menu
@bot.command("ping", description="Check if the script is still alive")
def handle_ping(arg):
    return f"pong! Received: ping {arg}" # Handlers that return a string automatically send replies

# Fallback handler for unmatched messages
@bot.set_default_handler
def handle_unknown(text):
    return f"Unknown command: {text}"

# Start the background daemon thread manually
bot.start()

bot.notify("🚀 Script has started!")  # Broadcasts to all authorized chats
bot.send_message("Targeted message", chat_id="USER_1_ID") # Or send to a specific chat

with bot.notify_exceptions(): # Optional: Wrap code to send tracebacks to Telegram in case of an exception
    
    # Main synchronous workload ...

    x = 1/0 # Simulates a crash

bot.send_file("plot.png", caption="Training loss")

# bot.stop() # Optional: stop the bot gracefully (daemon threads exit automatically)
```

## Setup Telegram Bot
1. Open Telegram and message `@BotFather`.
2. Use `/newbot` to create a bot and get a token.
3. To get the Chat ID, send a message to the bot, then visit:
   `https://api.telegram.org/bot<BOT_TOKEN>/getUpdates`
   Look for `"chat":{"id":123456789}` in the response.

## Bonus: Bash / CLI Usage

Helper function to send notifications directly from shell scripts:

```bash
send_telegram_message() {
    export BOT_TOKEN="bot_token"
    export CHAT_ID="chat_id"
    curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
        -d "chat_id=${CHAT_ID}" \
        --data-urlencode "text=$1" > /dev/null
    
    echo "📣: $1" # prints the message to the terminal
}

# Example usage:
# python train.py && send_telegram_message "Training finished successfully!"
```
