polis-bot 0.2.1

Async Python client for the Polis Bot API

polis-bot

Async Python client for the Polis Bot API — build bots for the Polis messaging platform.

Installation

pip install -e ./polis-bot-python
# or from the package once published:
# pip install polis-bot

Quick Start

import asyncio
from polis_bot import PolisBot

bot = PolisBot(token="your-bot-api-token")

async def main():
    # Get bot info
    me = await bot.get_me()
    print(f"I am {me.display_name} (@{me.botname})")

    # Register commands
    await bot.set_commands([
        {"command": "start", "description": "Start the bot"},
        {"command": "help", "description": "Show help"},
    ])

    # Poll for updates
    async for update in bot.poll():
        print(f"Update from {update.user.display_name}: {update.type}")

        if update.message and update.message.is_command:
            if update.message.command_name == "start":
                await bot.send_message(
                    user_id=update.user.id,
                    content="Welcome to my bot! 🤖"
                )
            elif update.message.command_name == "help":
                await bot.send_message(
                    user_id=update.user.id,
                    content="**Commands:**\n- /start — Start\n- /help — This message"
                )
        elif update.message and update.message.content:
            # Echo
            await bot.send_message(
                user_id=update.user.id,
                content=f"You said: {update.message.content}"
            )

asyncio.run(main())

Long Polling

The poll() method uses long-polling by default (30s timeout). Customize:

async for update in bot.poll(timeout=10, limit=50):
    ...

File Uploads

await bot.send_file(
    user_id=user_id,
    file_path="image.png",
    content_type="image/png"
)

Acknowledge Updates

Updates are automatically acknowledged after processing in poll(). For manual control:

updates = await bot.get_updates(limit=10)
if updates:
    await bot.acknowledge_updates([u.update_id for u in updates])

API Reference

PolisBot(token, base_url)

Method	Description
get_me()	Get bot info
send_message(user_id, content, reply_to_id=None)	Send text message
send_file(user_id, file_path, content_type)	Send a file
get_updates(limit, offset, timeout)	Get pending updates
acknowledge_updates(update_ids)	Mark updates as delivered
set_commands(commands)	Register bot commands
poll(limit, timeout)	Async generator for long-polling
close()	Close the HTTP client