No description
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Johan Wassberg f28ffa4a6a Update link
2026-11-22 14:14:24 +01:00
src/gnapy Initial commit 2026-11-22 13:03:21 +01:00
tests Initial commit 2026-11-22 13:03:21 +01:00
.gitignore Initial commit 2026-11-22 13:03:21 +01:00
pyproject.toml Initial commit 2026-11-22 13:03:21 +01:00
README.md Update link 2026-11-22 14:14:24 +01:00
uv.lock Initial commit 2026-11-22 13:03:21 +01:00

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 a Path, sent along with the message;
  • attachments=: IDs or Attachments from client.upload(...);
  • image_url=: a URL the server fetches. If that fails, the message is still sent and message.image_fetch_error says 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. commands matches text that starts with /name, case-insensitively.
  • @bot.callback_handler(data=..., func=...): data is 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 stable code (e.g. empty_message, send_only) and detail. retryable is true for 5xx.
  • NetworkError: no answer (connection failure, timeout). send is 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.