Skip to main content

MaxAPI

MAX Чат • TG Чат

PyPI version PyPI downloads per month Python Version Coverage Tests Lint Mypy Package CodeQL Docs License

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

Возможности

  • Асинхронный Bot с тонкими обёртками над методами MAX Bot API.
  • Dispatcher, Router, фильтры, F и middleware в стиле aiogram.
  • FSM-контекст через MemoryContext и RedisContext.
  • Polling и webhook через aiohttp, FastAPI или Litestar.
  • Работа с медиа: загрузка, отправка и скачивание файлов.
  • Inline-кнопки, callbacks и типизированные callback payloads.

Установка из PyPI

Стабильная версия

pip install maxapi

Если проект управляется через uv:

uv add maxapi

Установка из GitHub

Свежая версия, возможны баги. Рекомендуется только для ознакомления с новыми коммитами.

pip install git+https://github.com/love-apples/maxapi.git

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

Если вы тестируете бота в чате - не забудьте дать ему права администратора!

Запуск Polling

⚠️ Long Polling ограничен по скорости и сроку хранения событий и не подходит для production-окружения. Для боевого окружения используйте Webhook.

Если у бота есть активные Webhook-подписки, события не будут приходить через start_polling. Перед переходом на polling удалите подписки через await bot.delete_webhook().

import asyncio
import logging

from maxapi import Bot, Dispatcher, F
from maxapi.filters.command import CommandStart
from maxapi.types import BotStarted, MessageCreated

logging.basicConfig(level=logging.INFO)

# Внесите токен бота в переменную окружения MAX_BOT_TOKEN
# Не забудьте загрузить переменные из .env в os.environ
# или задайте его аргументом в Bot(token='...')
bot = Bot()
dp = Dispatcher()


# Ответ бота при нажатии на кнопку "Начать"
@dp.bot_started()
async def bot_started(event: BotStarted):
    await bot.send_message(
        chat_id=event.chat_id, text="Привет! Отправь мне /start"
    )


# Ответ бота на команду /start
@dp.message_created(CommandStart())
async def hello(event: MessageCreated):
    await event.message.answer("Пример чат-бота для MAX 💙")


@dp.message_created(F.message.body.text)
async def echo(event: MessageCreated):
    await event.message.answer(event.message.body.text)


async def main():
    await dp.start_polling(bot)


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

Запуск Webhook

🔒 С 25.05.2026 прекращается поддержка получения вебхуков по HTTP и самоподписных сертификатов. Используйте HTTPS и сертификаты, выданные доверенным центром сертификации.

Webhook работает «из коробки» — aiohttp уже включён в базовый пакет:

pip install maxapi

Для проекта на uv:

uv add maxapi

Ниже простой запуск через aiohttp. Для production-интеграции с FastAPI, подпиской webhook и проверкой secret смотрите пример 09_webhook_bot.py.

import asyncio
import logging

from maxapi import Bot, Dispatcher
from maxapi.filters.command import CommandStart
from maxapi.types import MessageCreated

logging.basicConfig(level=logging.INFO)

bot = Bot()
dp = Dispatcher()


# Команда /start боту
@dp.message_created(CommandStart())
async def hello(event: MessageCreated):
    await event.message.answer("Привет из вебхука!")


async def main():
    await dp.handle_webhook(
        bot=bot,
        host="0.0.0.0",
        port=8080,
    )


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

FastAPI и Litestar

Если хотите использовать FastAPI или Litestar вместо aiohttp, установите нужную опциональную зависимость через pip:

pip install "maxapi[fastapi]"
pip install "maxapi[litestar]"

Или через uv:

uv add "maxapi[fastapi]"
uv add "maxapi[litestar]"

Пример запуска через FastAPI:

import asyncio
import uvicorn
from fastapi import FastAPI
from maxapi.webhook.fastapi import FastAPIMaxWebhook


async def main():
    webhook = FastAPIMaxWebhook(dp=dp, bot=bot)
    app = FastAPI(lifespan=webhook.lifespan)
    webhook.setup(app, path="/webhook")
    await uvicorn.Server(
        uvicorn.Config(app, host="0.0.0.0", port=8080)
    ).serve()


asyncio.run(main())

Пример запуска через Litestar:

import asyncio
import uvicorn
from maxapi.webhook.litestar import LitestarMaxWebhook


async def main():
    webhook = LitestarMaxWebhook(dp=dp, bot=bot)
    app = webhook.create_app(path="/webhook")
    await uvicorn.Server(
        uvicorn.Config(app, host="0.0.0.0", port=8080)
    ).serve()


asyncio.run(main())

Разработка и релиз

  • Окружение: uv sync. Перед PR: make run-test (ruff, mypy, pytest) и make check-ci (сборка пакета, actionlint, zizmor). Подробности и соглашения — в AGENTS.md.
  • После правки зависимостей в pyproject.toml обновите lock: uv lock. CI ставит инструменты с --locked и упадёт на рассинхроне.
  • Релиз: uv version --bump patch (или minor/major) обновляет версию в pyproject.toml и uv.lock вместе; после мержа в main публикация на PyPI, тег и GitHub Release создаются автоматически, если такой версии на PyPI ещё нет. Если шаг после загрузки на PyPI упал, помогает «Re-run failed jobs» того же run: шаги тега и release идемпотентны. Свежий запуск увидит версию на PyPI и ничего не сделает.

Metadata

Release files for maxapi 1.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for maxapi 1.2.4
File Size Uploaded Provenance Actions
maxapi-1.2.4.tar.gz 337.5 kB Without provenance Details for maxapi-1.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for maxapi 1.2.4
File Interpreter ABI Platform Actions
maxapi-1.2.4-py3-none-any.whl Python 3 none any Details for maxapi-1.2.4-py3-none-any.whl

Total release size: 579.5 kB

Release files / maxapi-1.2.4.tar.gz

Download URL maxapi-1.2.4.tar.gz
Size 337.5 kB
Tags Source
SHA-256 checksum
How to use checksums
b21aa3344785103d1d617b50f46c171f05381f2fadb6896de2c41f13bd70197f
BLAKE2b-256 checksum
How to use checksums
e93eed5a08944085933646f30d1b882204cd1f4fba91d808e892a40104e252ed
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / maxapi-1.2.4-py3-none-any.whl

Download URL maxapi-1.2.4-py3-none-any.whl
Size 242.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
432b0bb22e7d415b9923bc3073d1b18244c9153a97d56984ec25052e5b875026
BLAKE2b-256 checksum
How to use checksums
e9b18824bce8a6df6a90282eb6900a08a92c9232dad73c0c0e601803c90dfb13
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for maxapi 1.2.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.4 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page