Добавлена вики

2025-07-15 18:29:54 +03:00 · 2025-07-15 18:29:54 +03:00 · b6c11cd28a
commit b6c11cd28a
parent 12f64f0805
4 changed files with 480 additions and 0 deletions
--- a/wiki/bot_methods.md
+++ 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 и токен.
+
+**Возвращает:** статус загрузки
--- a/wiki/events.md
+++ 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-кнопку
--- a/wiki/handlers.md
+++ 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())```
--- a/wiki/memory_context.md
+++ 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)}")
+```