telegram-kit

Secure Telegram Bot API notifications for any Python project. Stdlib only — no dependencies, no vendoring.

import telegram_kit

telegram_kit.notify("build finished", service="my-app", chat_id="123456789")

store = telegram_kit.CredentialStore("my-app")
token = telegram_kit.read_hidden("Telegram bot token (hidden): ")
if token and store.set("telegram_bot_token", token):
    print("stored as", telegram_kit.mask_secret(token))

Install

uv add "telegram-kit>=0.1.2,<0.2"

Published to PyPI on every v* tag (.github/workflows/release.yml). uv lock --upgrade-package telegram-kit is how every project using this kit picks up a fix — no file to copy, no diff to reapply. A project that is never published to PyPI can pin the git tag instead: uv add "telegram-kit @ git+https://github.com/weskao/telegram-kit@v0.1.2".

What it guarantees, whichever project uses it

• No plaintext fallback. CredentialStore writes to the OS credential store (macOS Keychain, Linux Secret Service, Windows DPAPI). With none available, it refuses to store rather than falling back to a plaintext file or home-rolled obfuscation.
• Each caller gets its own namespace. CredentialStore(service) keys every item under that service name, so two projects on the same machine never collide. Each Keychain / Secret Service item is labelled <service>: <key> so you can tell items apart in Keychain Access or Seahorse; an older item picks up the label the next time it's written. DPAPI items are already easy to tell apart: each one is a <key>.dpapi file.
• Credentials never touch argv or the process list — batch-mode/stdin paths are used for every backend.
• Owner-only atomic writes (write_private) for anything that must live on disk, on POSIX and Windows alike.

API

Develop

uv run python -m unittest discover -s tests -t . -v
uv run ruff check .

CI notifications

.github/workflows/ci.yml runs the test matrix (macOS/Linux/Windows) on every push and PR, then a separate notify-telegram job sends a Telegram message only when the test job fails on a push (never on green runs, never on pull_request, to avoid pinging on forks/external PRs). Configure it once per repo:

gh secret set TELEGRAM_BOT_TOKEN
gh secret set TELEGRAM_CHAT_ID

Unconfigured secrets are a valid state — the job skips quietly instead of failing a second time on top of the real failure.