telnoti

Send Telegram notifications from Python scripts and notebooks. Zero dependencies beyond requests.

Installation

pip install telnoti

One-time Setup

Interactive (Python):

import telnoti as tn
tn.setup()

CLI:

telnoti setup

Both prompt for your bot token (from @BotFather) and chat ID, then save to ~/.config/.telnoti.config.

Usage

Basic

import telnoti as tn

tn.init()          # load saved config
tn.send("hello")
tn.done("training complete")

try:
    1 / 0
except Exception as e:
    tn.error(e)    # sends ❌ ZeroDivisionError: ... with traceback

Training Loop with Status Updates

import telnoti as tn

tn.init()

def status():
    tn.send(f"Epoch {current_epoch}/{total_epochs}, loss={loss:.4f}")

tn.start_status(status, every_n_seconds=300)  # every 5 minutes

for epoch in range(total_epochs):
    # ... training ...
    pass

tn.stop_status()
tn.done("Training finished!")

Decorator

import telnoti as tn

tn.init()

@tn.notify(start=True, end=True, error=True)
def run_experiment():
    # ... long-running code ...
    pass

run_experiment()
# sends: ▶️ run_experiment started
# sends: ✅ run_experiment finished  (or ❌ ... on error)

Jupyter Notebook

import telnoti as tn
tn.init()

# In a cell you want to be notified when complete:
# ... heavy computation ...
tn.done("Cell finished")

Send Images

tn.send_image("plot.png", caption="Loss curve")

Catch All Unhandled Exceptions

import telnoti as tn
tn.init()
tn.catch_all()  # any uncaught exception will be sent to Telegram

Bot Commands

Send /list to your bot to see all active and recently completed runs:

Active runs
  • train.py · PID 12345 · 14:32 (running 1h 23m, 42 msgs — "Epoch 8/10")

Last 24h
  ✅ data_prep.py · PID 10022 · 09:15 (2h 41m)
  ❌ train_v2.py · PID 11500 · 11:00 (45m)
  💀 overnight.py · PID 8800 · 02:00 (7h 12m)

The polling thread starts automatically on tn.init(). Active runs are always shown; completed/errored runs appear for 24 hours. Dead runs (process killed, last seen > 5 min ago) are shown with 💀.

Version

import telnoti
print(telnoti.__version__)  # e.g. 0.2.0

telnoti --version  # telnoti 0.2.0
telnoti -V

API