Metadata-Version: 2.4
Name: pykodaribot
Version: 0.4.0
Summary: Python SDK для создания ботов в Kodari Messenger
License-Expression: MIT
Project-URL: Homepage, https://msg.kodari.ru
Project-URL: Documentation, https://docs.kodari.ru/
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Framework :: AsyncIO
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.9

# pykodaribot

Python SDK для создания ботов в [Kodari Messenger](https://msg.kodari.ru).

**Документация:** [docs.kodari.ru](https://docs.kodari.ru/)

## Установка

```bash
pip install pykodaribot
```

**Требования:** Python 3.9+

## Быстрый старт

```python
import asyncio
from pykodaribot import Bot, Dispatcher, filters

bot = Bot("bot_ВАШ_ТОКЕН")
dp = Dispatcher()

@dp.message(filters.command("start"))
async def start(msg):
    await msg.answer("Привет!")

@dp.message()
async def echo(msg):
    if msg.text:
        await msg.reply(msg.text)

asyncio.run(dp.start_polling(bot))
```

## Токен

Напишите @BotFather в мессенджере, введите `/newbot` и следуйте инструкциям.

## API

### Bot

| Метод | Описание |
|---|---|
| `get_me()` | Информация о боте |
| `send_message(chat_id, text, reply_to_message_id, reply_markup, message_thread_id)` | Отправить текст |
| `send_photo(chat_id, media, caption, reply_to_message_id, message_thread_id)` | Отправить фото |
| `send_document(chat_id, media, caption, reply_to_message_id, message_thread_id)` | Отправить файл |
| `send_video(chat_id, media, caption, reply_to_message_id, message_thread_id)` | Отправить видео |
| `send_audio(chat_id, media, caption, reply_to_message_id, message_thread_id)` | Отправить аудио |
| `edit_message_text(chat_id, message_id, text, reply_markup)` | Редактировать сообщение |
| `delete_message(chat_id, message_id)` | Удалить сообщение |
| `get_updates(offset, timeout, limit)` | Получить апдейты |
| `answer_callback_query(callback_query_id)` | Ответить на callback |
| `set_my_commands(commands)` | Установить команды меню |
| `get_my_commands()` | Получить команды меню |
| `set_my_name(name)` | Изменить имя бота |
| `set_my_description(description)` | Изменить описание |
| `set_my_short_description(short_description)` | Изменить краткое описание |
| `get_chat(chat_id)` | Информация о чате |
| `get_forum_topics(chat_id)` | Получить топики группы |
| `get_forum_topic(chat_id, message_thread_id)` | Получить топик |
| `create_forum_topic(chat_id, name, icon_color, icon_emoji)` | Создать топик |
| `edit_forum_topic(chat_id, message_thread_id, name, icon_color, icon_emoji)` | Изменить топик |
| `close_forum_topic(chat_id, message_thread_id)` | Закрыть топик |
| `reopen_forum_topic(chat_id, message_thread_id)` | Открыть топик заново |
| `delete_forum_topic(chat_id, message_thread_id)` | Удалить топик |

### Топики

```python
topic = await bot.create_forum_topic(
    chat_id,
    "Поддержка",
    icon_color="#6C8CFF",
    icon_emoji="🛠",
)

await bot.send_message(
    chat_id,
    "Новая заявка",
    message_thread_id=topic.message_thread_id,
)

topics = await bot.get_forum_topics(chat_id)
await bot.close_forum_topic(chat_id, topic.message_thread_id)
```

У входящего сообщения из топика заполнены `message_thread_id` и `is_topic_message`. Методы `msg.answer()` и `msg.reply()` автоматически отвечают в тот же топик.

### Dispatcher

```python
dp = Dispatcher()

@dp.message(*filters)          # новое сообщение
@dp.edited_message(*filters)   # изменённое сообщение
@dp.callback_query(*filters)   # нажатие inline-кнопки
@dp.forum_topic(*filters)
@dp.forum_status(*filters)
```

### Фильтры

```python
from pykodaribot import filters

filters.command("start", "help")        # команды /start или /help
filters.text(r"привет|hello")           # regex по тексту
filters.callback_data("yes")            # точное совпадение callback_data
filters.callback_data_prefix("action:") # callback_data начинается с префикса
```

### Inline-клавиатура

```python
from pykodaribot import InlineKeyboardMarkup, InlineKeyboardButton

keyboard = InlineKeyboardMarkup(inline_keyboard=[
    [
        InlineKeyboardButton(text="Да", callback_data="yes"),
        InlineKeyboardButton(text="Нет", callback_data="no"),
    ],
    [
        InlineKeyboardButton(text="Открыть сайт", url="https://kodari.ru"),
    ],
])

await msg.answer("Выберите:", reply_markup=keyboard)
```

### Отправка медиа

`media` принимает путь к файлу, `Path`, `bytes` или file-like объект:

```python
await bot.send_photo(chat_id, "photo.jpg", caption="Смотри!")
await bot.send_photo(chat_id, Path("/tmp/image.png"))
await bot.send_document(chat_id, open("report.pdf", "rb"))

with open("clip.mp4", "rb") as f:
    await bot.send_video(chat_id, f, caption="Видео")
```

## Примеры

- [`examples/echo_bot.py`](examples/echo_bot.py) — эхо-бот
- [`examples/inline_bot.py`](examples/inline_bot.py) — inline-кнопки и счётчик
- [`examples/commands_bot.py`](examples/commands_bot.py) — команды меню
- [`examples/topics_bot.py`](examples/topics_bot.py) — создание топика и ответы внутри него
