pyromax 0.1.0

Асинхронный, модульный фреймворк для юзерботов в MAX Messenger

MaxUserBotLib 🚀

Асинхронный, модульный и современный фреймворк для создания юзерботов в MAX Messenger.

MaxUserBotLib создан для тех, кто устал от "лапши" в одном файле. Мы перенесли лучшие практики из aiogram 3.x в мир MAX: роутеры, строгая типизация и удобная архитектура.

🔥 Почему MaxUserBotLib?

В отличие от других библиотек, мы ставим Developer Experience (DX) на первое место:

• 📦 Система Роутеров (Routers): Разбивайте бота на файлы и плагины. Никаких файлов на 2000 строк.
• ⚡ Скорость: Полностью асинхронное ядро на aiohttp и websockets.
• clean_code: Архитектура, вдохновленная aiogram. Если вы писали ботов для Telegram, вы будете чувствовать себя как дома.
• 🛠 Гибкость: Встроенный Dispatcher и Observer паттерн.

---

📦 Установка

Библиотека поддерживает современные менеджеры пакетов, включая uv.

Через pip

pip install pyromax

🚀 Быстрый старт

Простой эхо-бот:

import asyncio
import logging
import os
from pyromax.api import MaxApi
from pyromax.api.observer import Router as MaxDispatcher
from pyromax.types import Update

# Инициализация диспетчера
dp = MaxDispatcher()


# Регистрация хендлера (обрабатываем все сообщения, включая свои)
@dp.register_handler(pattern=lambda update: True, from_me=True)
async def echo_handler(update: Update, max_api: MaxApi):
    # Отвечаем на сообщение тем же текстом и вложениями
    await update.reply(text=update.text, attaches=update.attaches)


async def url_callback_for_login_url(url: str):
    """
    Отрабатывает если пользователь не авторизован(т.е не передается token)
     и в него попадает авторизационная ссылка
     """
    print(f'Авторизуйтесь в Max с помощью ссылки: {url}')


async def main():
    logging.basicConfig(level=logging.INFO)

    # Получаем токен из переменных окружения
    token = os.getenv('MaxApiToken')

    # Создаем экземпляр API
    bot = await MaxApi(url_callback_for_login_url, token=token)

    # Запускаем бота с диспетчером
    await bot.reload_if_connection_broke(dp)


if __name__ == "__main__":
    asyncio.run(main())

🧩 Модульность и Роутеры (Killer Feature)

1. Создайте модуль (например, handlers/admin.py)

from pyromax.api import MaxApi
from pyromax.api.observer import Router
from pyromax.types import Update

# Создаем отдельный роутер
router = Router()


# Регистрируем хендлер в роутер
@router.register_handler(pattern=lambda update: update.text == '!ping')
async def ping_handler(update: Update, max_api: MaxApi):
    await update.reply("Pong! 🏓")

2. Подключите его в главном файле (main.py)

from pyromax.api.observer import Dispatcher as MaxDispatcher
from handlers.admin import router as admin_router

dp = MaxDispatcher()

# Подключаем роутер к главному диспетчеру
dp.include_router(admin_router)
# ... далее запуск бота как в примере выше

Теперь ваш код чист, структурирован и легко масштабируется!

🗺 Roadmap (Планы развития)

Мы активно развиваем библиотеку и стремимся сделать её стандартом для MAX.

📍 Текущий статус (Alpha)

• Core: Полностью асинхронное ядро (MaxApi, Dispatcher).
• Routers: Модульная система (разбиение бота на файлы).
• Types: Строгая типизация всех объектов (Update, Message, Attachments).
• Observer: Система паттернов и фильтров для хендлеров.

🚧 В разработке

• FSM (Finite State Machine): Машина состояний для создания сценариев (опросы, диалоги, формы).
• Middlewares: Перехват событий до хендлеров (логирование, анти-флуд, базы данных).
• Magic Filters: Удобный синтаксис фильтров (как F.text.startswith("!")).

🔮 Планы на будущее

• Документация: Полноценный сайт с документацией и примерами.
• Плагины: Готовые модули для администрирования чатов.

---

🤝 Contributing

Мы рады любой помощи! Если вы хотите предложить фичу или исправить баг:

1. Форкните репозиторий.
2. Создайте ветку (git checkout -b feature/NewFeature).
3. Откройте Pull Request.

📄 Лицензия

MIT License. Свободно используйте в своих проектах.