aiomax2

aiomax2 — асинхронный Python-фреймворк для разработки ботов на MAX Bot API.

Фреймворк предоставляет Bot, Dispatcher, Router, фильтры, middleware, FSM, inline-клавиатуры, Long Polling и Webhook, сохраняя модели и семантику оригинального MAX API.

Архитектура и developer experience используют знакомые подходы из aiogram 3.x, но MAX API остаётся источником истины для методов, событий, моделей и ограничений.

Документация · PyPI · Releases · MAX Bot API

Поведение wire API сверяется с актуальной OpenAPI и официальным Go SDK v2. Зафиксированные revisions и осознанные различия перечислены в upstream conformance guide.

Установка

Требуется Python 3.12+.

pip install aiomax2

Проверить установленную версию:

python -c "import aiomax2; print(aiomax2.__version__)"

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

import asyncio
import os

from aiomax2 import Bot, Dispatcher, Router
from aiomax2.filters import Command
from aiomax2.types import Message

router = Router()


@router.message(Command("start"))
async def start(message: Message) -> None:
    await message.answer("Привет из aiomax2!")


async def main() -> None:
    bot = Bot(os.environ["MAX_BOT_TOKEN"])

    dp = Dispatcher()
    dp.include_router(router)

    try:
        await dp.start_polling(bot)
    finally:
        await bot.close()
        await dp.close()


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

Запуск:

export MAX_BOT_TOKEN="..."
python bot.py

На Windows PowerShell:

$env:MAX_BOT_TOKEN="..."
python bot.py

Возможности

• полностью асинхронная работа на asyncio и aiohttp;
• типизированные модели MAX API на Pydantic 2;
• Dispatcher, вложенные Router и dependency injection;
• команды, фильтры и magic filter F;
• middleware и FSM;
• shortcuts для сообщений и callback;
• InlineKeyboardBuilder и все актуальные типы inline-кнопок MAX;
• HTML и MAX Markdown через TextFormat;
• Long Polling и Webhook;
• интеграция Webhook с FastAPI;
• загрузка изображений, видео, аудио и файлов;
• работа с подписками, чатами, сообщениями и комментариями;
• автоматическая обработка rate limits и Retry-After;
• безопасная по умолчанию TLS verification;
• дополнительный CA bundle через ca_file;
• низкоуровневый доступ к API через Bot.request().

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

from aiomax2 import F
from aiomax2.types import CallbackQuery
from aiomax2.utils.keyboard import InlineKeyboardBuilder

builder = InlineKeyboardBuilder()
builder.button(text="Подтвердить", callback_data="confirm")
builder.button(text="Отменить", callback_data="cancel")
builder.adjust(2)

await message.answer(
    "Выберите действие",
    reply_markup=builder.as_markup(),
)


@router.callback_query(F.payload == "confirm")
async def confirm(callback: CallbackQuery) -> None:
    await callback.answer(text="Подтверждено")

Подробнее: Inline-клавиатуры и Callback.

Форматирование текста

from aiomax2 import TextFormat

await message.answer(
    "<b>Жирный</b> <i>курсив</i>",
    format=TextFormat.HTML,
)

await message.answer(
    "**Жирный** _курсив_",
    format=TextFormat.MARKDOWN,
)

Подробнее: форматирование текста.

Long Polling и Webhook

Для локальной разработки можно использовать Long Polling:

await dp.start_polling(bot)

Для production доступен Webhook с FastAPI:

app.include_router(
    dp.webhook_router(
        "/webhook",
        bot=bot,
        secret=WEBHOOK_SECRET,
    )
)

Регистрация публичного URL выполняется через:

await bot.subscribe(
    "https://bot.example.ru/webhook",
    secret=WEBHOOK_SECRET,
    update_types=dp.resolve_used_update_types(),
)

Подробнее:

• Long Polling
• Webhook
• Subscriptions

TLS и сертификаты

MAX Bot API использует TLS-цепочку, для которой среда выполнения может потребовать сертификаты Национального УЦ Минцифры.

Для подключения не требуется выпускать собственный сертификат. Нужны готовые Russian Trusted Root CA и Russian Trusted Sub CA.

Сертификаты доступны на Госуслугах.

Рекомендуемый вариант — добавить их в системное trust store и использовать обычную безопасную конфигурацию:

bot = Bot(os.environ["MAX_BOT_TOKEN"])

Если изменять системное хранилище нежелательно, оба сертификата можно объединить в PEM bundle и передать только aiomax2:

bot = Bot(
    os.environ["MAX_BOT_TOKEN"],
    ca_file="/path/to/russian_trusted_ca.pem",
)

Для диагностики существует явный небезопасный режим:

bot = Bot(
    os.environ["MAX_BOT_TOKEN"],
    verify_ssl=False,
)

Подробные инструкции по установке сертификатов и созданию CA bundle: TLS и сертификаты.

Документация

Полная документация:

https://candycrimsie.github.io/aiomax2/

Основные разделы:

• Установка
• Быстрый старт
• Dispatcher и Router
• Команды и фильтры
• FSM
• Inline-клавиатуры
• Загрузка файлов
• Обработка ошибок
• Покрытие MAX API
• Live smoke-test

Готовые примеры находятся в каталоге examples.

Разработка

git clone https://github.com/CandyCrimsie/aiomax2.git
cd aiomax2

python -m pip install -e ".[dev]"

Перед отправкой изменений:

python -m ruff format --check .
python -m ruff check .
python -m mypy src/aiomax2
python -m pytest
python -m mkdocs build --strict

Правила участия в разработке: CONTRIBUTING.md.

Проект

• PyPI
• Документация
• GitHub Releases
• Changelog
• Roadmap
• Security Policy

Лицензия

aiomax2 распространяется по лицензии MIT.