maxapi-sdk 0.12.0__py3-none-any.whl

maxapi/filters/common.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..callback_schema import extract_callback_value
+from .base import BaseFilter
+
+
+class ChatId(BaseFilter):
+    def __init__(self, *chat_ids: int) -> None:
+        self.chat_ids = set(chat_ids)
+
+    async def __call__(self, event: Any) -> bool:
+        chat_id = getattr(event, "chat_id", None)
+        return chat_id in self.chat_ids
+
+
+class UserId(BaseFilter):
+    def __init__(self, *user_ids: int) -> None:
+        self.user_ids = set(user_ids)
+
+    async def __call__(self, event: Any) -> bool:
+        user_id = getattr(event, "user_id", None)
+        return user_id in self.user_ids
+
+
+class CallbackData(BaseFilter):
+    def __init__(
+        self,
+        value: str,
+        *,
+        case_sensitive: bool = True,
+        startswith: bool = False,
+        contains: bool = False,
+    ) -> None:
+        self.value = value
+        self.case_sensitive = case_sensitive
+        self.startswith = startswith
+        self.contains = contains
+
+    async def __call__(self, event: Any) -> bool:
+        callback = getattr(getattr(event, "update", None), "callback", None)
+        payload = getattr(callback, "payload", None)
+        payload_value = extract_callback_value(payload)
+        if payload_value is None:
+            return False
+        return self._compare(payload_value)
+
+    def _compare(self, other: str) -> bool:
+        left = other if self.case_sensitive else other.lower()
+        right = self.value if self.case_sensitive else self.value.lower()
+        if self.startswith:
+            return left.startswith(right)
+        if self.contains:
+            return right in left
+        return left == right
+
+
+class HasAttachments(BaseFilter):
+    async def __call__(self, event: Any) -> bool:
+        message = getattr(event, "message", None)
+        if message is None or getattr(message, "body", None) is None:
+            return False
+        attachments = getattr(message.body, "attachments", None)
+        return bool(attachments)
+
+
+class ChatType(BaseFilter):
+    def __init__(self, *chat_types: str) -> None:
+        self.chat_types = {value.lower() for value in chat_types}
+
+    async def __call__(self, event: Any) -> bool:
+        message = getattr(event, "message", None)
+        recipient = getattr(message, "recipient", None) if message is not None else None
+        recipient_type = getattr(recipient, "type", None)
+        if recipient_type is None:
+            return False
+        return recipient_type.lower() in self.chat_types

maxapi/filters/text.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Pattern
+
+from .base import BaseFilter
+
+
+class Text(BaseFilter):
+    """Точное совпадение текста сообщения."""
+
+    def __init__(self, value: str, *, case_sensitive: bool = False, strip: bool = True) -> None:
+        self.value = value
+        self.case_sensitive = case_sensitive
+        self.strip = strip
+
+    async def __call__(self, event: Any) -> bool:
+        text = _get_message_text(event)
+        if text is None:
+            return False
+        if self.strip:
+            text = text.strip()
+        if self.case_sensitive:
+            return text == self.value
+        return text.lower() == self.value.lower()
+
+
+class TextContains(BaseFilter):
+    def __init__(self, value: str, *, case_sensitive: bool = False) -> None:
+        self.value = value
+        self.case_sensitive = case_sensitive
+
+    async def __call__(self, event: Any) -> bool:
+        text = _get_message_text(event)
+        if text is None:
+            return False
+        if self.case_sensitive:
+            return self.value in text
+        return self.value.lower() in text.lower()
+
+
+class TextStartsWith(BaseFilter):
+    def __init__(self, value: str, *, case_sensitive: bool = False) -> None:
+        self.value = value
+        self.case_sensitive = case_sensitive
+
+    async def __call__(self, event: Any) -> bool:
+        text = _get_message_text(event)
+        if text is None:
+            return False
+        if self.case_sensitive:
+            return text.startswith(self.value)
+        return text.lower().startswith(self.value.lower())
+
+
+class Regex(BaseFilter):
+    def __init__(self, pattern: str | Pattern[str], *, flags: int = 0) -> None:
+        self.pattern = re.compile(pattern, flags) if isinstance(pattern, str) else pattern
+
+    async def __call__(self, event: Any) -> bool:
+        text = _get_message_text(event)
+        if text is None:
+            return False
+        return self.pattern.search(text) is not None
+
+
+def _get_message_text(event: Any) -> str | None:
+    message = getattr(event, "message", None)
+    if message is None or getattr(message, "body", None) is None:
+        return None
+    return getattr(message.body, "text", None)

maxapi/fsm/__init__.py

@@ -0,0 +1,17 @@
+from .context import FSMContext
+from .filters import StateFilter
+from .middleware import FSMMiddleware
+from .state import State, StatesGroup
+from .storage.base import BaseStorage, StorageKey
+from .storage.memory import MemoryStorage
+
+__all__ = [
+    "BaseStorage",
+    "FSMContext",
+    "FSMMiddleware",
+    "MemoryStorage",
+    "State",
+    "StateFilter",
+    "StatesGroup",
+    "StorageKey",
+]

maxapi/fsm/context.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .storage.base import BaseStorage, StorageKey
+from .state import State
+
+
+class FSMContext:
+    """Контекст состояния для конкретного chat_id/user_id."""
+
+    def __init__(self, *, storage: BaseStorage, key: StorageKey) -> None:
+        self.storage = storage
+        self.key = key
+
+    async def get_state(self) -> str | None:
+        return await self.storage.get_state(self.key)
+
+    async def set_state(self, state: State | str | None) -> None:
+        normalized = _normalize_state(state)
+        await self.storage.set_state(self.key, normalized)
+
+    async def get_data(self) -> dict[str, Any]:
+        return await self.storage.get_data(self.key)
+
+    async def set_data(self, data: dict[str, Any]) -> None:
+        await self.storage.set_data(self.key, data)
+
+    async def update_data(self, **kwargs: Any) -> dict[str, Any]:
+        return await self.storage.update_data(self.key, kwargs)
+
+    async def clear(self) -> None:
+        await self.storage.clear(self.key)
+
+
+def _normalize_state(state: State | str | None) -> str | None:
+    if state is None:
+        return None
+    if isinstance(state, State):
+        return str(state)
+    return state

maxapi/fsm/filters.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..filters.base import BaseFilter
+from .middleware import build_storage_key
+from .state import State
+
+
+class StateFilter(BaseFilter):
+    def __init__(self, *states: State | str) -> None:
+        self.states = {_normalize_state(item) for item in states}
+
+    async def __call__(self, event: Any) -> bool:
+        bot = getattr(event, "bot", None)
+        dispatcher = getattr(bot, "dispatcher", None)
+        storage = getattr(dispatcher, "fsm_storage", None)
+        if storage is None:
+            return False
+        key = build_storage_key(event)
+        if key is None:
+            return False
+        current_state = await storage.get_state(key)
+        return current_state in self.states
+
+
+def _normalize_state(state: State | str) -> str:
+    if isinstance(state, State):
+        return str(state)
+    return state

maxapi/fsm/middleware.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..middlewares import BaseMiddleware, MiddlewareHandler
+from .context import FSMContext
+from .storage.base import BaseStorage, StorageKey
+
+
+class FSMMiddleware(BaseMiddleware):
+    """Middleware, который внедряет FSMContext в handlers."""
+
+    def __init__(self, storage: BaseStorage) -> None:
+        self.storage = storage
+
+    async def __call__(
+        self,
+        handler: MiddlewareHandler,
+        event: Any,
+        data: dict[str, Any],
+    ) -> Any:
+        key = build_storage_key(event)
+        if key is None:
+            data.setdefault("state", None)
+            data.setdefault("fsm_context", None)
+            data.setdefault("raw_state", None)
+            data.setdefault("state_data", {})
+            return await handler(event, data)
+        context = FSMContext(storage=self.storage, key=key)
+        data["fsm_context"] = context
+        data["state"] = context
+        data["raw_state"] = await context.get_state()
+        data["state_data"] = await context.get_data()
+        return await handler(event, data)
+
+
+def build_storage_key(event: Any) -> StorageKey | None:
+    chat_id = getattr(event, "chat_id", None)
+    user_id = getattr(event, "user_id", None)
+    if chat_id is None and user_id is None:
+        return None
+    return StorageKey(chat_id=chat_id, user_id=user_id)

maxapi/fsm/state.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class State:
+    """Описание состояния FSM."""
+
+    def __init__(self) -> None:
+        self.state: str | None = None
+
+    def __set_name__(self, owner: type[StatesGroup], name: str) -> None:
+        self.state = f"{owner.__name__}:{name}"
+
+    def __get__(self, instance: Any, owner: type[StatesGroup]) -> "State":
+        return self
+
+    def __str__(self) -> str:
+        if self.state is None:
+            raise RuntimeError("Состояние ещё не связано с классом StatesGroup.")
+        return self.state
+
+
+class StatesGroup:
+    """Базовый контейнер состояний."""
+
+    @classmethod
+    def states(cls) -> list[State]:
+        values: list[State] = []
+        for item in cls.__dict__.values():
+            if isinstance(item, State):
+                values.append(item)
+        return values

maxapi/fsm/storage/__init__.py

@@ -0,0 +1,4 @@
+from .base import BaseStorage, StorageKey
+from .memory import MemoryStorage
+
+__all__ = ["BaseStorage", "MemoryStorage", "StorageKey"]

maxapi/fsm/storage/base.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class StorageKey:
+    chat_id: int | None
+    user_id: int | None
+
+
+class BaseStorage(Protocol):
+    async def get_state(self, key: StorageKey) -> str | None:
+        ...
+
+    async def set_state(self, key: StorageKey, state: str | None) -> None:
+        ...
+
+    async def get_data(self, key: StorageKey) -> dict[str, Any]:
+        ...
+
+    async def set_data(self, key: StorageKey, data: dict[str, Any]) -> None:
+        ...
+
+    async def update_data(self, key: StorageKey, data: dict[str, Any]) -> dict[str, Any]:
+        ...
+
+    async def clear(self, key: StorageKey) -> None:
+        ...

maxapi/fsm/storage/memory.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .base import StorageKey
+
+
+class MemoryStorage:
+    """In-memory storage для FSM."""
+
+    def __init__(self) -> None:
+        self._states: dict[StorageKey, str | None] = {}
+        self._data: dict[StorageKey, dict[str, Any]] = {}
+
+    async def get_state(self, key: StorageKey) -> str | None:
+        return self._states.get(key)
+
+    async def set_state(self, key: StorageKey, state: str | None) -> None:
+        if state is None:
+            self._states.pop(key, None)
+            return
+        self._states[key] = state
+
+    async def get_data(self, key: StorageKey) -> dict[str, Any]:
+        return dict(self._data.get(key, {}))
+
+    async def set_data(self, key: StorageKey, data: dict[str, Any]) -> None:
+        self._data[key] = dict(data)
+
+    async def update_data(self, key: StorageKey, data: dict[str, Any]) -> dict[str, Any]:
+        current = await self.get_data(key)
+        current.update(data)
+        await self.set_data(key, current)
+        return current
+
+    async def clear(self, key: StorageKey) -> None:
+        self._states.pop(key, None)
+        self._data.pop(key, None)

maxapi/middlewares/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseMiddleware, FunctionMiddleware, MiddlewareHandler
+
+__all__ = ["BaseMiddleware", "FunctionMiddleware", "MiddlewareHandler"]

maxapi/middlewares/base.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any, Awaitable, Callable
+
+MiddlewareHandler = Callable[[Any, dict[str, Any]], Awaitable[Any]]
+
+
+class BaseMiddleware:
+    """Базовый middleware."""
+
+    async def __call__(
+        self,
+        handler: MiddlewareHandler,
+        event: Any,
+        data: dict[str, Any],
+    ) -> Any:
+        return await handler(event, data)
+
+
+class FunctionMiddleware(BaseMiddleware):
+    def __init__(self, callback: Callable[[MiddlewareHandler, Any, dict[str, Any]], Any]) -> None:
+        self.callback = callback
+
+    async def __call__(
+        self,
+        handler: MiddlewareHandler,
+        event: Any,
+        data: dict[str, Any],
+    ) -> Any:
+        result = self.callback(handler, event, data)
+        if inspect.isawaitable(result):
+            return await result
+        return result

maxapi/plugins/__init__.py

@@ -0,0 +1,3 @@
+from .base import BasePlugin, PluginProtocol
+
+__all__ = ["BasePlugin", "PluginProtocol"]

maxapi/plugins/base.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class PluginProtocol(Protocol):
+    name: str
+
+    def setup(self, router) -> None:
+        ...
+
+
+class BasePlugin:
+    """Базовый плагин для расширения Router/Dispatcher."""
+
+    name = "base"
+
+    def setup(self, router) -> None:  # pragma: no cover - interface hook
+        raise NotImplementedError

maxapi/py.typed

@@ -0,0 +1 @@
+

maxapi/runners/__init__.py

@@ -0,0 +1,4 @@
+from .polling import PollingRunner
+from .webhook import WebhookRunner
+
+__all__ = ["PollingRunner", "WebhookRunner"]

maxapi/runners/polling.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Iterable
+
+from ..types import UpdateType
+
+
+class PollingRunner:
+    """Отдельный runtime-класс для long polling."""
+
+    def __init__(
+        self,
+        *,
+        bot,
+        dispatcher,
+        limit: int = 100,
+        timeout: int = 30,
+        allowed_updates: Iterable[UpdateType | str] | None = None,
+        retry_delay: float = 2.0,
+        raise_exceptions: bool = False,
+    ) -> None:
+        self.bot = bot
+        self.dispatcher = dispatcher
+        self.limit = limit
+        self.timeout = timeout
+        self.allowed_updates = list(allowed_updates or [])
+        self.retry_delay = retry_delay
+        self.raise_exceptions = raise_exceptions
+        self._stop_event = asyncio.Event()
+
+    async def run_once(self) -> None:
+        page = await self.bot.get_updates(
+            marker=self.bot.marker_updates,
+            limit=self.limit,
+            timeout=self.timeout,
+            types=self.allowed_updates or None,
+        )
+        for update in page.updates:
+            await self.dispatcher.process_update(update, bot=self.bot)
+        self.bot.marker_updates = page.marker
+
+    async def start(self) -> None:
+        while not self._stop_event.is_set():
+            try:
+                await self.run_once()
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                if self.raise_exceptions:
+                    raise
+                await asyncio.sleep(self.retry_delay)
+
+    async def stop(self) -> None:
+        self._stop_event.set()

maxapi/runners/webhook.py

@@ -0,0 +1,72 @@
+from typing import Any
+
+from ..exceptions import MaxConnection
+
+try:  # pragma: no cover - optional dependency at import time
+    from fastapi import FastAPI, Header, HTTPException, Request
+except ImportError:  # pragma: no cover
+    FastAPI = None
+    Header = None
+    HTTPException = None
+    Request = None
+
+
+class WebhookRunner:
+    """Отдельный runtime-класс для webhook."""
+
+    def __init__(
+        self,
+        *,
+        bot,
+        dispatcher,
+        path: str = "/webhook",
+        secret: str | None = None,
+        host: str = "127.0.0.1",
+        port: int = 8080,
+        log_level: str = "info",
+    ) -> None:
+        self.bot = bot
+        self.dispatcher = dispatcher
+        self.path = path
+        self.secret = secret
+        self.host = host
+        self.port = port
+        self.log_level = log_level
+
+    def create_app(self):
+        if FastAPI is None or Header is None or HTTPException is None or Request is None:
+            raise MaxConnection(
+                "Для webhook runtime требуется fastapi. Установите maxapi[webhook]."
+            )
+
+        app = FastAPI()
+
+        @app.post(self.path)
+        async def handle_update(
+            request: Request,
+            x_max_bot_api_secret: str | None = Header(default=None),
+        ) -> dict[str, Any]:
+            if self.secret is not None and x_max_bot_api_secret != self.secret:
+                raise HTTPException(status_code=403, detail="Invalid webhook secret")
+            payload = await request.json()
+            await self.dispatcher.process_update(payload, bot=self.bot)
+            return {"ok": True}
+
+        return app
+
+    async def start(self) -> None:
+        try:
+            import uvicorn
+        except ImportError as exc:  # pragma: no cover
+            raise MaxConnection(
+                "Для webhook runtime требуется uvicorn. Установите maxapi[webhook]."
+            ) from exc
+        app = self.create_app()
+        config = uvicorn.Config(
+            app=app,
+            host=self.host,
+            port=self.port,
+            log_level=self.log_level,
+        )
+        server = uvicorn.Server(config)
+        await server.serve()

maxapi/transport/__init__.py

@@ -0,0 +1,13 @@
+from .client import MaxApiTransport, TransportResult
+from .config import RetryPolicy, TransportConfig
+from .errors import RateLimitExceededError, ResponseDecodeError, ServerResponseError
+
+__all__ = [
+    "MaxApiTransport",
+    "RateLimitExceededError",
+    "ResponseDecodeError",
+    "RetryPolicy",
+    "ServerResponseError",
+    "TransportConfig",
+    "TransportResult",
+]