From b6c11cd28acff40f0a1765c4991151c2a3fd54ad Mon Sep 17 00:00:00 2001 From: Denis Date: Tue, 15 Jul 2025 18:29:54 +0300 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B0=20=D0=B2=D0=B8=D0=BA=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- wiki/bot_methods.md | 284 +++++++++++++++++++++++++++++++++++++++++ wiki/events.md | 35 +++++ wiki/handlers.md | 64 ++++++++++ wiki/memory_context.md | 97 ++++++++++++++ 4 files changed, 480 insertions(+) create mode 100644 wiki/bot_methods.md create mode 100644 wiki/events.md create mode 100644 wiki/handlers.md create mode 100644 wiki/memory_context.md diff --git a/wiki/bot_methods.md b/wiki/bot_methods.md new file mode 100644 index 0000000..3e390d2 --- /dev/null +++ b/wiki/bot_methods.md @@ -0,0 +1,284 @@ +# Методы класса Bot + +## 💬 Работа с сообщениями + +### `send_message(...)` + +**Описание:** Отправить сообщение в чат или пользователю. + +**Аргументы:** + +* `chat_id` *(int)* — ID чата. Обязателен, если не указан `user_id`. +* `user_id` *(int)* — ID пользователя. Обязателен, если не указан `chat_id`. +* `text` *(str)* — текст сообщения. +* `attachments` *(List\[Attachment])* — вложения (фото, видео и т.д.). +* `link` *(NewMessageLink)* — объект для создания ссылочного сообщения. +* `notify` *(bool)* — отправлять ли уведомление (по умолчанию берётся из настроек бота). +* `parse_mode` *(ParseMode)* — форматирование текста (например, `ParseMode.HTML`). + +**Возвращает:** `SendedMessage` — объект отправленного сообщения. + +--- + +### `edit_message(...)` + +**Описание:** Редактировать существующее сообщение. + +**Аргументы:** + +* `message_id` *(str)* — ID сообщения, полученное ранее в `SendedMessage.id`. +* `text`, `attachments`, `link`, `notify`, `parse_mode` — см. `send_message`. + +**Возвращает:** `EditedMessage` — объект изменённого сообщения. + +--- + +### `delete_message(message_id)` + +**Описание:** Удалить сообщение по его ID. + +**Аргументы:** + +* `message_id` *(str)* — ID сообщения. + +**Возвращает:** `DeletedMessage` — результат удаления. + +--- + +### `get_messages(...)` + +**Описание:** Получить список сообщений. + +**Аргументы:** + +* `chat_id` *(int)* — ID чата. +* `message_ids` *(List\[str])* — список ID сообщений. +* `from_time` / `to_time` *(datetime | int)* — диапазон по времени. +* `count` *(int)* — сколько сообщений вернуть (по умолчанию 50). + +**Возвращает:** `Messages` — список объектов сообщений. + +--- + +### `get_message(message_id)` + +**Описание:** Получить одно сообщение по ID. + +**Аргументы:** + +* `message_id` *(str)* — ID сообщения. + +**Возвращает:** `Messages` — содержит одно сообщение в списке. + +--- + +### `pin_message(...)` + +**Описание:** Закрепить сообщение в чате. + +**Аргументы:** + +* `chat_id` *(int)* — ID чата. +* `message_id` *(str)* — ID сообщения. +* `notify` *(bool)* — уведомление. + +**Возвращает:** `PinnedMessage` + +--- + +### `delete_pin_message(chat_id)` + +**Описание:** Удалить закреплённое сообщение. + +**Аргументы:** + +* `chat_id` *(int)* — ID чата. + +**Возвращает:** `DeletedPinMessage` + +--- + +## 🤖 Информация о боте + +### `get_me()` + +**Описание:** Получить объект бота. + +**Возвращает:** `User` — текущий бот. + +--- + +### `change_info(...)` + +**Описание:** Изменить профиль бота. + +**Аргументы:** + +* `name` *(str)* — новое имя. +* `description` *(str)* — описание. +* `commands` *(List\[BotCommand])* — команды (name + description). +* `photo` *(Dict)* — `{ "url": ..., "token": ... }` — загруженное изображение. URL можно получить через `get_upload_url(...)`. + +**Возвращает:** `User` + +--- + +### `set_my_commands(*commands)` + +**Описание:** Установить команды бота. + +**Аргументы:** + +* `commands` *(BotCommand)* — команды, например `BotCommand(name="help", description="Справка")` + +**Возвращает:** `User` + +--- + +## 👥 Работа с чатами + +### `get_chats(...)` + +**Описание:** Получить список чатов. + +**Аргументы:** + +* `count` *(int)* — количество (по умолчанию 50). +* `marker` *(int)* — маркер страницы. + +**Возвращает:** `Chats` + +--- + +### `get_chat_by_id(id)` / `get_chat_by_link(link)` + +**Описание:** Получить объект чата по ID или публичной ссылке. + +**Возвращает:** `Chat` + +--- + +### `edit_chat(...)` + +**Описание:** Изменить чат. + +**Аргументы:** + +* `chat_id`, `title`, `pin`, `notify` — как выше. +* `icon` *(PhotoAttachmentRequestPayload)* — вложение фото, загруженное через `get_upload_url(...)` и `download_file(...)`. + +**Возвращает:** `Chat` + +--- + +### `delete_chat(chat_id)` + +Удаляет чат. + +**Возвращает:** `DeletedChat` + +--- + +## 👤 Работа с участниками чатов + +### `get_chat_members(...)` / `get_chat_member(...)` + +**Описание:** Получить одного или нескольких участников. + +**Возвращает:** `GettedMembersChat` (у него есть `.members`) + +--- + +### `add_chat_members(...)` + +**Описание:** Добавить участников. + +**Аргументы:** + +* `chat_id`, `user_ids` *(List\[str])* — список строковых ID. + +**Возвращает:** `AddedMembersChat` + +--- + +### `kick_chat_member(...)` + +**Описание:** Исключить и опционально заблокировать. + +**Возвращает:** `RemovedMemberChat` + +--- + +### `get_list_admin_chat(...)` / `add_list_admin_chat(...)` / `remove_admin(...)` + +**Описание:** Управление администраторами. + +**Возвращают:** `GettedListAdminChat`, `AddedListAdminChat`, `RemovedAdmin` + +--- + +### `get_me_from_chat(...)` + +**Описание:** Получить, кем является бот в чате. + +**Возвращает:** `ChatMember` + +### `delete_me_from_chat(...)` + +**Удаляет бота из чата.** + +**Возвращает:** `DeletedBotFromChat` + +--- + +## 🔄 Обновления и действия + +### `get_updates()` + +**Описание:** Получить события (новости, сообщения и т.д.). + +**Возвращает:** `UpdateUnion` + +--- + +### `send_action(...)` + +**Описание:** Отправить "печатает..." и т.д. + +**Аргументы:** + +* `chat_id`, `action` *(SenderAction)* — например, `SenderAction.TYPING_ON` + +**Возвращает:** `SendedAction` + +--- + +### `send_callback(...)` + +**Описание:** Ответ на callback-кнопку. + +**Аргументы:** + +* `callback_id`, `message`, `notification` + +**Возвращает:** `SendedCallback` + +--- + +## 📎 Медиа и файлы + +### `get_video(video_token)` + +**Возвращает:** `Video` + +### `get_upload_url(type)` + +**Аргументы:** `type` *(UploadType)* — например, `UploadType.IMAGE` + +**Возвращает:** `GettedUploadUrl` (у него есть `.url`) + +### `download_file(path, url, token)` (НЕАКТУАЛЬНО) + +**Описание:** Скачивает файл, используя URL и токен. + +**Возвращает:** статус загрузки diff --git a/wiki/events.md b/wiki/events.md new file mode 100644 index 0000000..4156f44 --- /dev/null +++ b/wiki/events.md @@ -0,0 +1,35 @@ +# События + +Для обработки разных типов обновлений используются события (Event). Ниже перечислены основные события и их назначение. + +| Событие | Описание | +|-----------------------|----------------------------------------------------------------------------------------------| +| `message_created` | Создание нового сообщения (пользователь отправил сообщение) | +| `bot_added` | Бот добавлен в чат | +| `bot_removed` | Бот удалён из чата | +| `bot_started` | Пользователь запустил бота | +| `chat_title_changed` | Изменено название чата | +| `message_callback` | Пользователь нажал на callback-кнопку (inline button) | +| `message_chat_created`| Срабатывает когда пользователь нажал на кнопку с действием "Создать чат" (работает некорректно со стороны API MAX, ждем исправлений) | +| `message_edited` | Сообщение было отредактировано | +| `message_removed` | Сообщение было удалено | +| `user_added` | Пользователь добавлен в чат | +| `user_removed` | Пользователь удалён из чата | +| `on_started` | Бот запущен (**внутреннее** событие библиотеки) | + +--- + +## Пример использования + +```python +@dp.message_created() +async def on_message(event: MessageCreated): + ... # обработка нового сообщения + +@dp.bot_added() +async def on_bot_added(event: BotAdded): + ... # логика при добавлении бота + +@dp.message_callback() +async def on_callback(event: MessageCallback): + ... # обработка нажатия на callback-кнопку diff --git a/wiki/handlers.md b/wiki/handlers.md new file mode 100644 index 0000000..487cd3b --- /dev/null +++ b/wiki/handlers.md @@ -0,0 +1,64 @@ +# Философия хендлеров или как задается хендлер в maxapi + +Для регистрации хендлера в maxapi используется объект `Dispatcher` или `Router` и декоратор с указанием типа события и фильтра. + +## Общий синтаксис + +```python +@dp.<тип_события>(<фильтры>) +async def <имя_функции>(event: <тип_события>): + ... +``` + +* `dp` — экземпляр `Dispatcher` + +* `<тип_события>` — тип события (например, `message_created`) + +* `<фильтр>` — условие `MagicFilter`, по которому срабатывает хендлер (например, наличие текста в сообщении) + +* `event` — объект события с данными (например, `MessageCreated`) + +## Пример + +```python +@dp.message_created(F.message.body.text) +async def echo(event: MessageCreated): + await event.message.answer(f"Повторяю за вами: {event.message.body.text}") +``` + +* `@dp.message_created` — хендлер на событие создания сообщения + +* `F.message.body.text` — фильтр: сработает только если в сообщении есть текст + +* `echo` — асинхронная функция-обработчик, которая принимает событие `MessageCreated` + +* В теле функции вызывается метод `answer` для отправки ответа с повтором текста + + +## Полный код + +```python +import asyncio +import logging + +from maxapi import Bot, Dispatcher +from maxapi.filters import F +from maxapi.types import MessageCreated + +logging.basicConfig(level=logging.INFO) + +bot = Bot('тут_ваш_токен') +dp = Dispatcher() + + +@dp.message_created(F.message.body.text) +async def echo(event: MessageCreated): + await event.message.answer(f"Повторяю за вами: {event.message.body.text}") + + +async def main(): + await dp.start_polling(bot) + + +if __name__ == '__main__': + asyncio.run(main())``` \ No newline at end of file diff --git a/wiki/memory_context.md b/wiki/memory_context.md new file mode 100644 index 0000000..17ca52b --- /dev/null +++ b/wiki/memory_context.md @@ -0,0 +1,97 @@ +# MemoryContext + +Контекст данных пользователя с поддержкой асинхронных блокировок. Используется для хранения и управления состоянием пользователя в рамках сессии. + +## Класс: `MemoryContext` + +```python +MemoryContext(chat_id: int, user_id: int) +```` + +### Аргументы: + +* `chat_id` (`int`): Идентификатор чата. +* `user_id` (`int`): Идентификатор пользователя. + + +## Методы + +### `async def get_data() -> dict[str, Any]` + +Возвращает текущие данные контекста. + +#### Возвращает: + +* `dict[str, Any]`: Словарь с текущими данными пользователя. + +--- + +### `async def set_data(data: dict[str, Any])` + +Полностью заменяет контекст данных. + +#### Аргументы: + +* `data` (`dict[str, Any]`): Новый словарь данных, заменяющий текущий. + +--- + +### `async def update_data(**kwargs)` + +Обновляет текущий контекст, добавляя или изменяя переданные пары ключ-значение. + +#### Аргументы: + +* `**kwargs`: Ключи и значения для обновления контекста. + +--- + +### `async def set_state(state: State | str = None)` + +Устанавливает новое состояние пользователя или сбрасывает его. + +#### Аргументы: + +* `state` (`State | str | None`): Новое состояние. Если `None` — состояние будет сброшено. + +--- + +### `async def get_state() -> State | None` + +Возвращает текущее состояние пользователя. + +#### Возвращает: + +* `State | None`: Текущее состояние или `None`, если не установлено. + +--- + +### `async def clear()` + +Очищает все данные контекста и сбрасывает состояние. + +--- + +## Пример использования + +[Полный пример](https://github.com/love-apples/maxapi/tree/main/examples/router_with_input_media) + +```python +@dp.message_created(Command('clear')) +async def hello(event: MessageCreated, context: MemoryContext): + await context.clear() + await event.message.answer(f"Ваш контекст был очищен!") + + +@dp.message_created(Command('data')) +async def hello(event: MessageCreated, context: MemoryContext): + data = await context.get_data() + await event.message.answer(f"Ваша контекстная память: {str(data)}") + + +@dp.message_created(Command('context')) +@dp.message_created(Command('state')) +async def hello(event: MessageCreated, context: MemoryContext): + data = await context.get_state() + await event.message.answer(f"Ваше контекстное состояние: {str(data)}") +``` \ No newline at end of file