- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| src/gnapy | ||
| tests | ||
| .gitignore | ||
| pyproject.toml | ||
| README.md | ||
| uv.lock | ||
gnapy
Write Gná bots in Python. Synchronous, built on httpx, shaped like pyTelegramBotAPI.
Gná, the messenger of Norse mythology who carries Frigg's errands between the worlds, carries
messages between you and your bots. gnapy is her Python side.
import os
from gnapy import Bot, Button
bot = Bot("https://gna.example.com", os.environ["GNA_TOKEN"], cursor="gna-cursor.txt")
@bot.message_handler(commands=["ping"])
def ping(message):
bot.reply_to(message, "pong")
@bot.message_handler(regexp=r"^https?://\S+")
def link(message):
bot.reply_to(message, f"Got {message.text}")
@bot.callback_handler(data="lock")
def lock(callback):
bot.reply_to(callback, "Locked.")
bot.send(
"Front door is unlocked. Lock it?",
notification_buttons="yes_no",
buttons=[[Button.callback("Lock", "lock"), Button.callback("Ignore", "ignore")]],
)
bot.infinity_polling()
Sending
bot.send(text, ...) (or Client.send) takes the fields of POST /messages: silent,
reply_to (an ID or a Message), buttons (rows of Button.callback(label, data) and
Button.link(label, url)), buttons_single_use, notification_buttons, and one way to add
images:
image=: bytes, an open binary file or aPath, sent along with the message;attachments=: IDs orAttachments fromclient.upload(...);image_url=: a URL the server fetches. If that fails, the message is still sent andmessage.image_fetch_errorsays why.
bot.reply_to(message_or_callback, text, ...) quotes the message (for a callback, the message
its button is on).
Receiving
Handlers are checked in the order they were registered and the first match runs:
@bot.message_handler(commands=[...], regexp=..., func=...): all the given conditions must hold.commandsmatches text that starts with/name, case-insensitively.@bot.callback_handler(data=..., func=...):datais a value or a list of values.
bot.infinity_polling() long-polls /updates until bot.stop(). It retries network trouble
and server errors with a growing pause, and raises ApiError for what retrying cannot fix: a
revoked token (401), a send-only token (403), or a rejected request. A handler that raises is
logged on the gnapy logger and its event counts as handled.
Give the bot a cursor. The server does not remember how far a bot got: a bot that starts
from 0 again gets every event the server still holds a second time. cursor="path" keeps it in
a file (any object with load() and save(after) works too). Without one, the bot logs a
warning and keeps the cursor in memory.
Sending from other threads while the bot polls is fine.
Errors
Everything gnapy raises about the server is a GnaError:
ApiError: the server said no.status, the stablecode(e.g.empty_message,send_only) anddetail.retryableis true for 5xx.NetworkError: no answer (connection failure, timeout).sendis not retried for you: the message may or may not have arrived.ProtocolError: the answer was not what the API describes.
Development
uv run pytest
uv run ruff check . && uv run black --check . && uv run isort --check .
Not supported yet: encrypted conversations.