pyromax 0.4

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

"The Official Pyromax Library (available on PyPI)".

Pyromax 🚀

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

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

🔥 Почему Pyromax?

В отличие от других библиотек, мы ставим 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 Dispatcher as MaxDispatcher
from pyromax.types import Message
import qrcode

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


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


async def url_callback_for_login_url(url: str):
    """
    Отрабатывает если пользователь не авторизован(т.е не передается token)
    и в него попадает авторизационная ссылка
    Необходимо привести эту ссылку к виду qr кода, и отсканировать с приложения Макса
    К примеру можно использовать модуль qrcode
    т.е pip install qrcode
    """
    
    qr = qrcode.QRCode()
    qr.add_data(url)

    img = qr.make_image()
    img.save('qr.jpg')
    
    """
    После этого появится в домашнем каталоге проекта сам файл qr кода,
    его нужно будет отсканировать, и далее бот начнет работать дальше
    """   
    


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.filters import Command, CommandStart, CommandObject
from pyromax.types import Message

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


# Регистрируем хендлер в роутер
@router.message(Command('ping'), from_me=True)
async def ping_handler(message: Message, max_api: MaxApi):
    await message.reply("Pong! 🏓")


@router.message(CommandStart())
async def start(message: Message):
    await message.answer(text='Ну начинаем?')
    
@router.message(Command('sum'), from_me=True)
async def sum_handler(message: Message, command: CommandObject) -> None:
    """
    В чате:
        >>>/sum 8 8
        
        >>>Ответ: 16
        
        
        >>>/sum 3 string
        
        >>>В аргументах могут быть только цифры
    """
    if command.args is None:
        return
    args = command.args.split()
    nums = []
    for arg in args:
        if not arg.isdigit():
            await message.reply(text = 'В аргументах могут быть только цифры')
            return
        nums.append(int(arg))
    await message.reply(text = f'Ответ: {sum(nums)}')

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("!")).

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

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

---

📞 Контакты

Telegram разработчика: ТЫК

🤝 Contributing

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

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

📄 Лицензия

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