refactor(webhook): reorganize imports and update documentation for adapters

Author: m-xim

AGENTS.md

@@ -897,11 +897,14 @@ uv run pytest tests/ --cov=src --cov-report=html  # для детального
 - Для webhook показывай `SingleBotEngine`, `AiohttpAdapter` или
   `FastAPIAdapter`, `Route`, `Security`, `StaticSecret`, `collect_used_updates`
   (в `WebhookConfig(update_types=...)` для `engine.subscribe(...)`).
-- Импортируй из корня пакета: `maxo.transport.webhook` реэкспортирует
-  `SingleBotEngine`, `TokenEngine`, `Route`, `WebhookConfig`, `BotConfig`,
-  `AiohttpAdapter` и `FastAPIAdapter`. Последний - под `try/except
-  ModuleNotFoundError`, чтобы корень не требовал установленного `fastapi`;
-  добавляешь туда что-то с опциональной зависимостью - делай так же.
+- Из корня пакета `maxo.transport.webhook` реэкспортируются только
+  `SingleBotEngine`, `TokenEngine`, `Route`, `WebhookConfig` и `BotConfig`.
+  Адаптеры в корень не вынесены - каждый берётся из своего модуля:
+  `maxo.transport.webhook.web.aiohttp` и `maxo.transport.webhook.web.fastapi`.
+  Всё, что тянет опциональную зависимость, реэкспорту не подлежит: модуль
+  импортирует её сверху и вешает
+  `e.add_note("* Please run \`pip install maxo[...]\`")` (как
+  `fsm/storages/redis.py` и `integrations/magic_filter.py`).
 - `Security` и `StaticSecret` живут в `maxo.transport.webhook.security` и в
   корень не вынесены. Промежуточные `engines/__init__.py`, `configs/__init__.py`
   и `web/__init__.py` публичной поверхностью не являются: `web/__init__` отдаёт

README.md

@@ -216,12 +216,12 @@ from maxo import Bot, Dispatcher, Router
 from maxo.enums import TextFormat
 from maxo.routing.utils import collect_used_updates
 from maxo.transport.webhook import (
-    AiohttpAdapter,
     Route,
     SingleBotEngine,
     WebhookConfig,
 )
 from maxo.transport.webhook.security import Security, StaticSecret
+from maxo.transport.webhook.web.aiohttp import AiohttpAdapter
 from maxo.types import BotStarted, MessageCreated
 
 bot = Bot("TOKEN")

docs/pages/event-handling/webhooks.rst

@@ -31,7 +31,7 @@ Webhooks
 
 .. note::
 
-    Движки, ``Route``, конфиги и адаптеры импортируются из корня пакета: ``from maxo.transport.webhook import SingleBotEngine, Route, WebhookConfig, AiohttpAdapter``. ``FastAPIAdapter`` тоже лежит там, но появляется только если установлен ``fastapi`` (``maxo[fastapi]``) - без него корень импортируется как обычно. ``Security`` и ``StaticSecret`` берутся из ``maxo.transport.webhook.security``.
+    Движки, ``Route`` и конфиги импортируются из корня пакета: ``from maxo.transport.webhook import SingleBotEngine, Route, WebhookConfig``. Адаптеры лежат каждый в своём модуле - ``maxo.transport.webhook.web.aiohttp`` и ``maxo.transport.webhook.web.fastapi`` (последний требует ``maxo[fastapi]``). ``Security`` и ``StaticSecret`` берутся из ``maxo.transport.webhook.security``.
 
 Примеры использования
 ---------------------
@@ -53,12 +53,12 @@ Webhooks
             from maxo.enums import TextFormat
             from maxo.routing.utils import collect_used_updates
             from maxo.transport.webhook import (
-                AiohttpAdapter,
                 Route,
                 SingleBotEngine,
                 WebhookConfig,
             )
             from maxo.transport.webhook.security import Security, StaticSecret
+            from maxo.transport.webhook.web.aiohttp import AiohttpAdapter
             from maxo.types import MessageCreated
 
             dp = Dispatcher()
@@ -116,12 +116,12 @@ Webhooks
             from maxo.enums import TextFormat
             from maxo.routing.utils import collect_used_updates
             from maxo.transport.webhook import (
-                FastAPIAdapter,
                 Route,
                 SingleBotEngine,
                 WebhookConfig,
             )
             from maxo.transport.webhook.security import Security, StaticSecret
+            from maxo.transport.webhook.web.fastapi import FastAPIAdapter
             from maxo.types import MessageCreated
 
             dp = Dispatcher()

src/maxo/transport/webhook/__init__.py

@@ -29,22 +29,11 @@
 from maxo.transport.webhook.engines.single import SingleBotEngine
 from maxo.transport.webhook.engines.token import TokenEngine
 from maxo.transport.webhook.route.route import Route
-from maxo.transport.webhook.web.aiohttp import AiohttpAdapter
 
-__all__ = [
-    "AiohttpAdapter",
+__all__ = (
     "BotConfig",
     "Route",
     "SingleBotEngine",
     "TokenEngine",
     "WebhookConfig",
-]
-
-
-try:
-    from maxo.transport.webhook.web.fastapi import FastAPIAdapter  # noqa: F401
-
-    __all__.insert(2, "FastAPIAdapter")
-except ModuleNotFoundError as exc:
-    if exc.name != "fastapi":
-        raise
+)

src/maxo/transport/webhook/web/fastapi.py

@@ -1,9 +1,14 @@
+try:
+    from fastapi import APIRouter, FastAPI, Request, Response
+    from fastapi.responses import JSONResponse
+except ImportError as e:
+    e.add_note("* Please run `pip install maxo[fastapi]`")
+    raise
+
 from collections.abc import AsyncGenerator, Mapping
 from contextlib import asynccontextmanager
 from typing import Any
 
-from fastapi import APIRouter, FastAPI, Request, Response
-from fastapi.responses import JSONResponse
 from multidict import CIMultiDict, CIMultiDictProxy, MultiDict, MultiDictProxy
 
 from maxo.transport.webhook.web.base import (

tests/maxo_webhook/test_security.py

@@ -33,9 +33,7 @@ async def test_security_pipeline_stops_at_first_failed_check() -> None:
 
 
 @pytest.mark.asyncio
-async def test_security_pipeline_allows_request_when_secret_and_checks_pass() -> (
-    None
-):
+async def test_security_pipeline_allows_request_when_secret_and_checks_pass() -> None:
     calls: list[str] = []
     security = Security(
         RecordingCheck("check", result=True, calls=calls),