Async Python SDK + bot-фреймворк для мессенджера MAX (https://platform-api.max.ru). Стиль
вдохновлён aiogram: Bot, Dispatcher, Router, F, фильтры, middleware, FSM.
maxapi/bot.py—Bot(BaseConnection). Тонкие async-обёртки (bot.send_message,bot.edit_chat, …), каждая инстанцирует класс изmethods/и делает.fetch(). Токен берётся изMAX_BOT_TOKEN, если не передан явно.Bot.resolve_format/_resolve_notify/_resolve_disable_link_previewсливают глобальные дефолты с per-call. Конструктор принимает дополнительные параметры загрузки медиа:after_input_media_delay,after_upload_attempts,after_upload_retry_delay,after_upload_give_up_timeout; настройки polling:marker_updates,auto_check_subscriptions; конфигурацию HTTP-соединения:default_connection: DefaultConnectionProperties.maxapi/client/default.py—DefaultConnectionProperties: настройки aiohttp-клиента (таймауты,max_retries,retry_on_statuses,retry_backoff_factor). Передаётся вBot(default_connection=DefaultConnectionProperties(...)). Остальные**kwargsуходят вClientSessionчерезclient/ssl.py. Владение коннектором: переданный пользователемconnector— чужой,with_default_connector/connector_kwargsпроставляют емуconnector_owner=False, поэтому ниclose_session(), ни временные сессииupload_file*его не закрывают. Собственный дефолтный коннектор создаётся под каждую сессию сconnector_owner=True.maxapi/methods/<verb>.py— один класс на эндпоинт (SendMessage,EditChat, …). Конструктор валидирует/нормализует,async def fetch()собираетparams/jsonи вызываетsuper().request(method=HTTPMethod.X, path=ApiPath.Y, model=<PydanticResponse>, …). Новый API-метод = новый файл здесь + проксирующий метод вBot+ типы ответа вmethods/types/. См.methods/send_message.pyкак канонический пример (включая retry наattachment.not.ready).maxapi/connection/base.py—BaseConnection.request(): единый HTTP-pipe caiohttp, backoff-ретраями серверных 5xx иClientConnectionError, парсингом ответа в pydantic-модель, выбросомMaxApiError/InvalidToken/MaxConnection. Разделяемую сессиюrequest()не закрывает — её жизненный цикл принадлежитBot(close_session); на 401 тело ответа читается в текстInvalidToken, уходит вhandle_raw_responseи ответ освобождается черезresp.release(). Сессия берётся внутри retry-цикла, а не до него.download_file— потоковое скачивание чанкамиDOWNLOAD_CHUNK_SIZE=64KiB.maxapi/dispatcher.py—Dispatcher/Router(Router = подкласс Dispatcher). Регистрация черезEvent-декораторы (@dp.message_created(...),@dp.bot_started()…).Dispatcher.handle()строит глобальный outer → роутерный outer →_check_handler_match→ inner-цепочку (global inner + router inner + handler-level) → handler. Два списка middleware:outer_middlewares(до проверки фильтров handler, на каждое событие) иinner_middlewares(только когда конкретный handler прошёл все фильтры). Регистрация:dp.register_outer_middleware(mw)/dp.register_inner_middleware(mw). Старыеdp.middleware()/dp.outer_middleware()— deprecated-алиасы. Inner-mw «выпекается» вhandler.mw_chainпри_prepare_handlers(). Цепочки и индексhandlers_by_type: dict[UpdateType, list[Handler]]кешируются при__ready()(start_polling/startup). Подробности и инварианты, включая router-scoped inner middleware —doc/router_inner_middleware.md(читать перед рефакторингом dispatcher/middleware).maxapi/types/updates/— pydantic-модели входящих событий, объединённые вUpdateUnion. После парсингаutils/updates.py::enrich_eventчерез 3 хелпера (_resolve_chat,_resolve_from_user,_inject_bot) проставляетevent.chat,event.from_user,event.bot. ПриBot(auto_requests=False)тяжёлые поля остаются какLazyRef/ChatRef/FromUserRef(types/fetchable.py) — пользователь делаетawait ref.fetch()сам. Актуальные update-типы (помимо базовых):dialog_cleared,dialog_muted,dialog_unmuted,dialog_removed,bot_admin_permissions_changed(по данным MAX API — только Webhook),comment_created,comment_edited,comment_removed(полеmessage—CommentMessage, приходят только боту-админу канала сread_all_messages),raw_api_response,on_started(pseudo-тип дляstartup-callback);message_chat_createdпомечен deprecated с 0.9.14.maxapi/filters/—BaseFilter(async__call__ → bool | dict; возвращённый dict мёржится в kwargs хендлера),BaseMiddleware(async __call__(handler, event, data)),Handler( классифицирует переданные в декоратор*argsпо типу:MagicFilter→filters,BaseFilter→base_filters,State/None→states,BaseMiddleware→middlewares).F = MagicFilter()экспортируется изmaxapi. Встроенные фильтры:Command/CommandStart(filters/command.py),StateFilter(filters/state.py— явная проверка FSM-state без параметраstates=),ChannelPostFilter(filters/channel_post.py— фильтрует сообщения из каналов),Contact/ContactFilter(filters/contact.py— инжектируетcontact: ContactAttachmentв kwargs handler),CallbackPayload/PayloadFilter(filters/callback_payload.py— см. Patterns).maxapi/context/—BaseContext+MemoryContext(default, LRU 10_000 вDispatcher.contexts) иRedisContext. Оба поддерживаютttl: float | None— истёкший TTL сбрасывает state и данные; реализован черезTTLTracker(context/ttl.py). FSM:State()+StatesGroupвstate_machine.py(имя автоматически"Group:attr"). Изоляция событий (context/isolation.py, порт из aiogram, MIT-нотис в шапке файла):Dispatcher(event_isolation=SimpleEventIsolation())сериализует конкурентные апдейты одного(chat_id, user_id)— весьhandle()идёт под per-key локом;RedisEventIsolation— для нескольких процессов. По умолчанию отключена (DisabledEventIsolation), как в aiogram.maxapi/webhook/—BaseMaxWebhook+ три бэкенда:aiohttp.py(default, в основной зависимости),fastapi.py,litestar.py(опц. экстры[fastapi]/[litestar]). Все валидируют заголовокX-Max-Bot-Api-Secret, если в конструктор переданsecret. Вход parsитсяprocess_update_webhook, диспатч идентичный polling.
- Окружение:
uv sync(группаdevставится по умолчанию) →source .venv/bin/activate. Python ≥ 3.10, target — 3.10. Менеджер — uv, не pip/poetry.uv.lockкоммитится и фиксирует dev-инструменты: lint, mypy и docs в CI ставятся с--locked, поэтому после правкиpyproject.tomlобновляйте lock (uv lock). Тесты в CI резолвят зависимости заново (lowest-directиhighestс--upgrade), чтобы ловить поломки от новых релизов зависимостей, как у пользователей. - Git — всегда с
--no-pagerили через перенаправление (| cat), чтобы пагинатор не подвешивал выполнение:git --no-pager log,git --no-pager diff,git --no-pager branch, и т.д. - Полная проверка перед PR:
make run-test— параллельно запускаетruff check .,ruff format . --check,mypy maxapi,pytest -q. Форматирование —make format.make check-ci— остальное, что проверяет CI: сборка пакета (twine check,check-wheel-contents),actionlintиzizmorпо workflow; инструменты — группаci. Обе цели запускаютuv run --locked: рассинхронuv.lockсpyproject.tomlвалит их, как и CI. Онлайн-аудиты zizmor берут токен изgh auth token, еслиghавторизован. - Релиз:
uv version --bump patch|minor|majorменяет версию вpyproject.tomlиuv.lockвместе (ручной bump безuv lockуронит гейты на--locked). После мержа вmainpublish.ymlспрашивает PyPI, есть ли такая версия, и если нет — прогоняет гейты, публикует черезuv publish, создаёт тег и GitHub Release. Если шаг после загрузки на PyPI упал, чинит «Re-run failed jobs» (шаги тега и release идемпотентны); свежий запуск увидит версию на PyPI и корректно ничего не сделает. - Тесты:
pytest -q [tests/test_X.py].asyncio_mode = "auto"— async-тесты не нуждаются в декораторах. Маркер@pytest.mark.integrationавтоматически пропускается безMAX_BOT_TOKENв env (см.tests/conftest.py::pytest_collection_modifyitems). Фикстуры событий —tests/fixtures/updates.py, параметризованнаяupdateпокрывает всеUpdateType..envподхватывается автоматически. - Документация: MkDocs Material (
mkdocs.yml,docs/), генерится из docstring черезmkdocstrings[python]. - Каноничные сценарии использования —
examples/<NN>_*.py(echo, formatting, keyboard, FSM, media, admin, router, middleware, webhook, callback_payload, comment moderation).
- Совместимость с паттернами aiogram: для максимального упрощения жизни пользователей, переходящих с aiogram, придерживайтесь его паттернов там, где это не противоречит особенностям MAX API и не является антипаттерном. Это касается именования методов, сигнатур middleware, структуры фильтров, FSM-интерфейса и т.д. При расхождении — документируйте решение явно.
- Язык docstring — русский, формат — PEP 257,
"""…"""обязательны на публичных модулях/классах/функциях как соглашение проекта. Актуальные автоматические проверки смотрите вpyproject.toml, дополнительные рекомендации по разработке — вdoc/dev.md. Длина строки 79 (pyproject.toml::tool.ruff), docstring — 72. - Типы в секциях
Args/Attributes/Returnsне дублируем — mkdocstrings читает их из аннотаций Python. Пишем только имя и описание:name: Описание., но неname (type): Описание. ruffсконфигурён сselect = ["ALL"]и широкимignore. Смотриpyproject.tomlперед добавлением# noqa— многие категории (D, ANN, COM, EM, …) уже отключены глобально.- Все runtime-импорты внутри пакета — относительные (
from ..enums.api_path import ApiPath). Импорты только для типизации — подif TYPE_CHECKING:+from __future__ import annotations. - Параметры с дефолтами на стороне
Bot(format,notify,disable_link_preview) не передавайте напрямую в методы — резолвьте черезbot.resolve_format(...)/bot._resolve_notify(...).parse_modeпомечен Deprecated, новые места — толькоformat: TextFormat. - Устаревшее API не удаляем молча:
warnings.warn(..., DeprecationWarning, stacklevel=2|3)(см.bot.change_info,Dispatcher.init_serve,Event.registerдля deprecated update-типов). - Ошибки бизнес-уровня — наследники
MaxApiError/InvalidToken/MaxConnectionизexceptions/max.py; диспетчерные —HandlerException/MiddlewareExceptionизexceptions/dispatcher.py(всегда оборачивают исходноеcause=eи кладут снапшот FSMmemory_context). - Логирование — именованные логгеры
logger_bot/logger_dpизmaxapi/loggers.py, неlogging.getLogger(__name__)в коде SDK. - Опциональная параллельная обработка событий —
Dispatcher(use_create_task=True); задачи держатся в_background_tasks(без этого GC может потерять task).stop_polling()дожидается ихasyncio.gather.
- Регистрация хендлера:
@dp.message_created(Command("start"), F.message.body.text == "ok", states=MyFSM.waiting)— порядок аргументов произвольный, тип определяется вfilters/handler.py::Handler.__init__. - Высокоуровневые шорткаты на самих типах:
await event.message.answer("..."),await event.bot.send_message(...)(см.types/shortcuts.py,types/bot_mixin.py— bot инжектится вenrich_event). - Регистрация нового update-типа: модель в
types/updates/, добавить вUpdateUnion, вenums/update.py, обработать вutils/updates.py::_resolve_chat/_resolve_from_user, добавитьEventвDispatcher.__init__, добавить фикстуру вtests/fixtures/и запись в_FIXTURE_NAME_BY_UPDATEвtests/conftest.py(иначеtest_fixtures_update_mapping.pyупадёт — это by design). - Typed callback payload: наследуйтесь от
CallbackPayload(pydantic-модель) сprefix/separatorClass-vars.instance.pack()→ строка ≤ 1024 байт;MyPayload.unpack(str)→ объект.MyPayload.filter(rule)возвращаетPayloadFilter, вставляемый в декоратор хендлера — совпавший payload инжектируется какpayload: MyPayloadв kwargs handler. - Middleware: используйте
dp.register_outer_middleware(mw)(outer — до фильтров handler) /dp.register_inner_middleware(mw)(inner — только когда handler реально вызван). То же наrouter. Старыеdp.middleware()/dp.outer_middleware()/router.middleware()/router.outer_middleware()даютDeprecationWarning.