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.
CredentialStorewrites 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>.dpapifile. - 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
| Function | Purpose |
|---|---|
CredentialStore(service, dpapi_dir=None) |
Get/set/delete a secret in the OS store. |
resolve_credentials(token, chat_id, environ=None) |
Configured value, else TG_BOT_TOKEN/TG_CHAT_ID. |
send_message(token, chat_id, text, timeout=10) |
One sendMessage call. Inside tmux the text ends with a tmux_line() on its own line (a send_photo caption too). False on any failure. |
send_photo(token, chat_id, photo, caption="", timeout=30) |
Image + caption in one sendPhoto message. A caption over 1024 UTF-16 units is sent right after the image as a sendMessage. False on any failure. |
notify(text, service, chat_id="", token_key=..., store=None) |
Resolve + send in one call. |
read_hidden(prompt, ask=None) |
Hidden input; None if the terminal can't hide it. |
mask_secret(secret) |
******** plus at most the last 4 characters. |
tmux_line() |
🪟 Tmux: <session> inside tmux, else "". |
write_private(target, content) |
Atomic, owner-only file write. |
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.
Metadata
Release files for telegram-kit 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| telegram_kit-0.2.2.tar.gz | 21.4 kB | Without provenance | Details for telegram_kit-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| telegram_kit-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for telegram_kit-0.2.2-py3-none-any.whl |
Total release size: 32.1 kB
Release files / telegram_kit-0.2.2.tar.gz
| Download URL | telegram_kit-0.2.2.tar.gz |
|---|---|
| Size | 21.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4706da2d145db427ee7a41a382316886e449d52bec6381390186c197a156276d
|
|
BLAKE2b-256 checksum How to use checksums |
0c2fcde074208fc1349be6a20a9bfe1a21a3fc38c5c2075e04156ffa0d8e2c3b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / telegram_kit-0.2.2-py3-none-any.whl
| Download URL | telegram_kit-0.2.2-py3-none-any.whl |
|---|---|
| Size | 10.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a73ab2ae1c81a03be359ff50975a311aef4c803b2eda674b8272102616ce305a
|
|
BLAKE2b-256 checksum How to use checksums |
a059841180442f43848a3bb6dd21ad617bb69f15a78be0c7a10947073acd7513
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for telegram-kit 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.