Metadata-Version: 2.4
Name: maxogram
Version: 1.1.0
Summary: Async Python framework for Max Bot API, inspired by aiogram
License-Expression: MIT
License-File: LICENSE
Keywords: max,bot,api,async,framework
Author: Vadim Didenko
Author-email: didenko.it.ai@gmail.com
Requires-Python: >=3.11
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Typing :: Typed
Provides-Extra: dev
Provides-Extra: fast
Provides-Extra: i18n
Provides-Extra: mongodb
Provides-Extra: proxy
Provides-Extra: redis
Requires-Dist: aiodns (>=3.0) ; extra == "fast"
Requires-Dist: aiofiles (>=23.2,<26.0)
Requires-Dist: aiohttp (>=3.9,<4.0)
Requires-Dist: aiohttp-socks (>=0.8) ; extra == "proxy"
Requires-Dist: aresponses (>=3.0) ; extra == "dev"
Requires-Dist: babel (>=2.13) ; extra == "i18n"
Requires-Dist: certifi (>=2023.7)
Requires-Dist: fakeredis[lua] (>=2.34.1,<3.0.0) ; extra == "dev"
Requires-Dist: magic-filter (>=1.0.12,<1.1)
Requires-Dist: motor (>=3.3) ; extra == "mongodb"
Requires-Dist: mypy (>=1.8) ; extra == "dev"
Requires-Dist: pydantic (>=2.4,<3.0)
Requires-Dist: pytest (>=8.0) ; extra == "dev"
Requires-Dist: pytest-asyncio (>=0.23) ; extra == "dev"
Requires-Dist: pytest-cov (>=5.0) ; extra == "dev"
Requires-Dist: pytest-mock (>=3.12) ; extra == "dev"
Requires-Dist: pyyaml (>=6.0.3,<7.0.0) ; extra == "dev"
Requires-Dist: redis (>=5.0) ; extra == "redis"
Requires-Dist: ruff (>=0.3) ; extra == "dev"
Requires-Dist: types-pyyaml (>=6.0.12) ; extra == "dev"
Requires-Dist: uvloop (>=0.19) ; extra == "fast"
Project-URL: Changelog, https://github.com/mccalpink/maxogram/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/mccalpink/maxogram#readme
Project-URL: Homepage, https://github.com/mccalpink/maxogram
Project-URL: Issues, https://github.com/mccalpink/maxogram/issues
Project-URL: Repository, https://github.com/mccalpink/maxogram
Description-Content-Type: text/markdown

# maxogram

[![Python](https://img.shields.io/pypi/pyversions/maxogram?v=1)](https://pypi.org/project/maxogram/)
[![PyPI](https://img.shields.io/pypi/v/maxogram?v=1)](https://pypi.org/project/maxogram/)
[![Downloads](https://img.shields.io/pypi/dm/maxogram?v=1)](https://pypi.org/project/maxogram/)
[![CI](https://github.com/mccalpink/maxogram/actions/workflows/ci.yml/badge.svg)](https://github.com/mccalpink/maxogram/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![mypy](https://img.shields.io/badge/mypy-strict-blue)](https://mypy-lang.org/)

Асинхронный Python-фреймворк для [Max Bot API](https://dev.max.ru/), вдохновленный [aiogram](https://github.com/aiogram/aiogram).
Предоставляет типизированный, расширяемый интерфейс для создания ботов в мессенджере [Max](https://max.ru).

## Возможности

### Ядро фреймворка

- **Полное покрытие Max Bot API** — 30 методов, 96 типов, все 13 типов событий
- **Router + Dispatcher** — дерево роутеров с propagation событий, вложенность, lifecycle hooks
- **Фильтры** — Command, ChatType, ContentType, CallbackData, MagicFilter (DSL), ExceptionType
- **Middleware** — onion pattern, inner/outer и request-level middleware (RetryMiddleware, LoggingMiddleware)
- **FSM** — конечные автоматы с MemoryStorage, RedisStorage и MongoStorage
- **Scene** — высокоуровневый FSM для сложных диалогов (Scene, WizardScene, SceneRegistry)
- **Multi-bot** — несколько ботов в одном Dispatcher
- **Webhook** — aiohttp handler, WebhookManager с auto-resubscribe, IP whitelist security
- **Polling** — long polling с exponential backoff и graceful shutdown
- **Keyboard builder** — InlineKeyboardBuilder с `adjust()` для раскладки кнопок
- **Class-based handlers** — BaseHandler, MessageHandler, CallbackHandler
- **Flags** — декораторы метаданных на хендлерах для use-case-specific middleware
- **Dependency Injection** — автоматическое внедрение `bot`, `state`, `event` в хендлеры
- **Типизация** — `py.typed`, mypy strict, Pydantic v2 модели

### Уникальные фичи Max

- **Message Constructor** — интерактивное конструирование сообщений (нативная фича Max API)
- **Resumable Upload** — загрузка файлов до 4 GB чанками с возобновлением после сбоя

### Утилиты

- **I18n** — интернационализация через gettext (I18nMiddleware, LazyProxy)
- **Text Formatting** — Bold, Italic, Code, Link, UserMention builders
- **ChatActionSender** — автоматическая отправка typing/recording actions
- **MediaGroupBuilder** — групповая отправка медиа
- **Deep Linking** — create_start_link, encode_payload, decode_payload
- **WebApp Validation** — HMAC-SHA256 валидация initData
- **CallbackAnswerMiddleware** — автоответ на callback если хендлер не ответил

## Установка

```bash
pip install maxogram
```

Дополнительные зависимости:

```bash
pip install maxogram[redis]   # RedisStorage для FSM
pip install maxogram[mongodb]  # MongoStorage для FSM
pip install maxogram[fast]    # uvloop + aiodns
pip install maxogram[proxy]   # SOCKS-прокси
pip install maxogram[i18n]    # интернационализация (gettext)
```

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

```python
import os

from maxogram.client.bot import Bot
from maxogram.dispatcher.dispatcher import Dispatcher
from maxogram.dispatcher.router import Router
from maxogram.types.message import Message

router = Router()


@router.message_created()
async def echo(
    event: Message,
    bot: Bot,
    **kwargs: object,
) -> None:
    """Повторяет любое текстовое сообщение."""
    text = event.body.text
    chat_id = event.recipient.chat_id
    if text and chat_id:
        await bot.send_message(chat_id=chat_id, text=text)


bot = Bot(token=os.environ["MAX_BOT_TOKEN"])
dp = Dispatcher()
dp.include_router(router)
dp.run_polling(bot)
```

Больше примеров: [`examples/`](examples/)

## Основные концепции

### Router

Маршрутизатор событий. Содержит observer для каждого из 13 типов событий Max API.
Роутеры вкладываются друг в друга, образуя дерево — событие проходит по дереву до первого обработчика.

```python
main_router = Router(name="main")
admin_router = Router(name="admin")
main_router.include_router(admin_router)
```

### Filters

Фильтры определяют, какой хендлер обработает событие. Встроенные фильтры:
`Command`, `ChatTypeFilter`, `ContentTypeFilter`, `CallbackData`, `MagicData`, `ExceptionTypeFilter`.

```python
from maxogram.filters import Command

@router.message_created(Command("start"))
async def cmd_start(event, bot, command, **kwargs):
    ...
```

### Middleware

Onion-pattern middleware для pre/post обработки. Два уровня: `outer_middleware` (до фильтров) и `inner_middleware` (после фильтров, перед хендлером).

```python
from maxogram.dispatcher.middlewares.base import BaseMiddleware

class LogMiddleware(BaseMiddleware):
    async def __call__(self, handler, event, data):
        print(f"Event: {event}")
        return await handler(event, data)

router.message_created.outer_middleware.register(LogMiddleware())
```

### FSM

Конечные автоматы для диалоговых сценариев. `State` + `StatesGroup` описывают состояния, `FSMContext` управляет переходами и данными.

```python
from maxogram.fsm.state import State, StatesGroup
from maxogram.fsm.context import FSMContext

class Form(StatesGroup):
    name = State()
    age = State()

@router.message_created()
async def ask_name(event, bot, state: FSMContext, **kwargs):
    await state.set_state(Form.name)
    ...
```

### Webhook

Production-ready webhook с aiohttp. WebhookManager управляет lifecycle, auto-resubscribe и graceful shutdown.
IPWhitelistMiddleware защищает endpoint от поддельных запросов.

## Инструменты разработчика

### Schema Diff Tool

CLI-инструмент для сравнения OpenAPI-схемы Max Bot API с кодом библиотеки. Помогает отслеживать расхождения при обновлении API.

```bash
poetry run schema-diff                        # сравнить с актуальной схемой
poetry run schema-diff --schema path/to/openapi.json  # указать путь к схеме
```

Выводит: новые методы в API, удалённые методы, изменённые параметры.

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

- [Быстрый старт](docs/quickstart.md)
- [Архитектура](docs/architecture.md)
- [Примеры](examples/)
- [Max Bot API](https://dev.max.ru/)

## Требования

- Python 3.11+
- aiohttp >= 3.9
- pydantic >= 2.4
- magic-filter >= 1.0.12
- aiofiles >= 23.2
- certifi >= 2023.7

## Лицензия

[MIT](LICENSE)

