Telegram bot with python-telegram-bot

# AGENTS.md: Telegram bot (python-telegram-bot)

Telegram bot in Python with python-telegram-bot v22 (asyncio), managed with uv.

## Commands
- Run locally (long polling): `uv run python -m bot`. Tests: `uv run pytest -q`. Lint: `uv run ruff check .`.
- Done means: tests and ruff pass, and you tried the command in a private chat with a test bot.

## Secrets
- The bot token comes from the `TELEGRAM_BOT_TOKEN` environment variable (local: `.env`, gitignored). Never hard-code,
  log, print or commit it, and never paste it into an issue or a test.
- If a token may have leaked, tell the human to revoke it with @BotFather straight away.
- Use a separate test bot for development, never the production token.

## Structure
- `bot/__main__.py` builds the `Application` and registers handlers. One module per feature in `bot/handlers/`.
- Business logic in plain functions that take values and return values, so it can be tested without Telegram.
- Handlers are `async def name(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None`. Never block the event loop:
  no `time.sleep`, no `requests`; use `httpx.AsyncClient` or run blocking work with `asyncio.to_thread`.

## Behaviour
- Register an error handler with `application.add_error_handler(...)`; log the exception, reply with a short apology.
- Treat every message as untrusted input: validate arguments, cap lengths, never `eval` or build shell commands from it.
- Group chats: respond only to commands or mentions; check `update.effective_chat.type` before doing anything noisy.
- Admin-only commands check the user id against an allow-list from the environment.
- Respect Telegram's rate limits: no loops that send to many chats without delays; use the job queue for broadcasts.
- Formatting: `ParseMode.HTML` with `telegram.helpers.escape` for user text, or plain text. Never put raw user input
  into Markdown or HTML.

## Production
- Webhooks in production: `run_webhook(..., secret_token=...)` with a secret from the environment, behind HTTPS.
- Use the `add-bot-command` skill for new commands.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `add-bot-command`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Telegram bot with python-telegram-bot" v1.0.0 — https://loadout.jnw-it.com/loadouts/telegram-bot-python/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `add-bot-command`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Telegram bot with python-telegram-bot" v1.0.0 — https://loadout.jnw-it.com/loadouts/telegram-bot-python/ -->

---
name: add-bot-command
description: Add a python-telegram-bot command with logic in a testable plain function, validated arguments, escaped output and a unit test. Use when adding or changing a bot command.
---

# Add a bot command

1. Write the logic as a plain function first (no Telegram types), like `parse_split` in `references/split.py`.
   It validates input and raises `ValueError` with a message the user can read.
2. Write the handler: read `context.args`, call the function, reply with the result. Catch `ValueError` and reply with
   its message plus usage. Escape any user text with `telegram.helpers.escape` if you reply in HTML.
3. Register it in `bot/__main__.py`: `application.add_handler(CommandHandler("split", split_command))`.
4. Add the command to the BotFather command list text in the README, so the human can update it.
5. Tests like `references/test_split.py`: the plain function (valid, invalid, edge cases) and that the application
   registers the handler. No network, no token.
6. Run `uv run pytest -q` and `uv run ruff check .`, then try it with the test bot.

"""Example command: /split <amount> <people> splits a bill. Logic is a plain function; the handler is a thin wrapper."""

from decimal import ROUND_HALF_UP, Decimal, InvalidOperation

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes

USAGE = "Usage: /split <amount> <people>, for example /split 42.50 3"


def parse_split(args: list[str]) -> str:
    if len(args) != 2:
        raise ValueError(USAGE)
    try:
        amount = Decimal(args[0].replace("£", ""))
        people = int(args[1])
    except (InvalidOperation, ValueError):
        raise ValueError(USAGE) from None
    if amount <= 0 or amount > Decimal("100000"):
        raise ValueError("Amount must be between 0 and 100,000.")
    if not 1 <= people <= 100:
        raise ValueError("People must be between 1 and 100.")
    share = (amount / people).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
    return f"£{amount:.2f} split {people} ways is £{share} each."


async def split_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    if update.message is None:
        return
    try:
        text = parse_split(context.args or [])
    except ValueError as err:
        text = str(err)
    await update.message.reply_text(text)


def register(application: Application) -> None:
    application.add_handler(CommandHandler("split", split_command))

import pytest
from telegram.ext import Application, CommandHandler

from bot.handlers.split import USAGE, parse_split, register


def test_even_split():
    assert parse_split(["42.50", "3"]) == "£42.50 split 3 ways is £14.17 each."


def test_pound_sign_allowed():
    assert parse_split(["£10", "4"]) == "£10.00 split 4 ways is £2.50 each."


@pytest.mark.parametrize("args", [[], ["10"], ["ten", "2"], ["10", "two"], ["10", "2", "3"]])
def test_bad_arguments_show_usage(args):
    with pytest.raises(ValueError, match="Usage"):
        parse_split(args)


@pytest.mark.parametrize("args, message", [(["0", "2"], "Amount"), (["10", "0"], "People"), (["10", "1000"], "People")])
def test_out_of_range(args, message):
    with pytest.raises(ValueError, match=message):
        parse_split(args)


def test_usage_mentions_command():
    assert "/split" in USAGE


def test_handler_is_registered_without_network():
    app = Application.builder().token("123456:TEST-TOKEN-NOT-REAL").build()
    register(app)
    commands = [c for h in app.handlers[0] if isinstance(h, CommandHandler) for c in h.commands]
    assert "split" in commands