Metadata-Version: 2.4
Name: polis-bot
Version: 0.1.0
Summary: Async Python client for the Polis Bot API
Author: Polis Team
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.5
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: respx>=0.22; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"

# polis-bot

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

## Installation

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

## Quick Start

```python
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:

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

## File Uploads

```python
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:

```python
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 |
