maxapi-python 1.2.4__py3-none-any.whl → 2.0.0__py3-none-any.whl

pymax/dispatch/dispatcher.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+from contextlib import suppress
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from pymax.logging import get_logger
+from pymax.protocol import InboundFrame
+from pymax.types import Chat, MessageDeleteEvent
+from pymax.types.domain import Message
+from pymax.types.events import FileUploadSignal, VideoUploadSignal
+
+from .enums import EventType
+from .mapping import EventMapper, EventResolver
+from .router import (
+    FilterCallback,
+    HandlerCallback,
+    HandlerDecorator,
+    HandlerEntry,
+    Router,
+    StartDecorator,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from pymax.app import App
+    from pymax.client import Client
+
+
+logger = get_logger(__name__)
+
+ClientT = TypeVar("ClientT")
+
+
+class Dispatcher(Generic[ClientT]):
+    def __init__(self, app: App, root_router: Router[ClientT] | None = None) -> None:
+        self.root_router: Router[ClientT] = root_router or Router()
+        self.internal_router: Router[ClientT] = Router()
+        self.resolver = EventResolver()
+        self.mapper = EventMapper(app)
+        self.startup_tasks: list[asyncio.Task[Any]] = []
+        self.client: ClientT | None = None
+
+    def bind_client(self, client: ClientT) -> None:
+        self.client = client
+
+    def include_router(self, router: Router[ClientT]) -> None:
+        self.root_router.include_router(router)
+        logger.debug(
+            "router included handlers=%s children=%s",
+            len(router.handlers),
+            len(router.children),
+        )
+
+    def on_internal(
+        self,
+        event: EventType,
+        *filters: FilterCallback[Any],
+    ) -> HandlerDecorator[Any, ClientT]:
+        logger.debug("registering internal handler event=%s filters=%s", event, len(filters))
+        return self.internal_router.on(event, *filters)
+
+    def on(
+        self,
+        event: EventType,
+        *filters: FilterCallback[Any],
+    ) -> HandlerDecorator[Any, ClientT]:
+        logger.debug("registering handler event=%s filters=%s", event, len(filters))
+        return self.root_router.on(event, *filters)
+
+    def on_message(
+        self,
+        *filters: FilterCallback[Message],
+    ) -> HandlerDecorator[Message, ClientT]:
+        logger.debug("registering message handler filters=%s", len(filters))
+        return self.root_router.on_message(*filters)
+
+    def on_message_edit(
+        self,
+        *filters: FilterCallback[Message],
+    ) -> HandlerDecorator[Message, ClientT]:
+        logger.debug("registering message edit handler filters=%s", len(filters))
+        return self.root_router.on_message_edit(*filters)
+
+    def on_message_delete(
+        self,
+        *filters: FilterCallback[MessageDeleteEvent],
+    ) -> HandlerDecorator[MessageDeleteEvent, ClientT]:
+        return self.root_router.on_message_delete(*filters)
+
+    def on_chat_update(
+        self,
+        *filters: FilterCallback[Chat],
+    ) -> HandlerDecorator[Chat, ClientT]:
+        return self.root_router.on_chat_update(*filters)
+
+    def on_raw(
+        self,
+        *filters: FilterCallback[InboundFrame],
+    ) -> HandlerDecorator[InboundFrame, ClientT]:
+        return self.root_router.on_raw(*filters)
+
+    def on_start(self) -> StartDecorator[ClientT]:
+        return self.root_router.on_start()
+
+    def iter_routers(self) -> Generator[Router[ClientT], Any, None]:
+        yield from self._iter_router(self.root_router)
+
+    def _iter_router(self, router: Router[ClientT]) -> Generator[Router[ClientT], Any, None]:
+        yield router
+
+        for child in router.children:
+            yield from self._iter_router(child)
+
+    async def emit_start(self, client: ClientT) -> None:
+        tasks: list[asyncio.Task[Any]] = []
+
+        for router in self.iter_routers():
+            handler = router.on_start_handler
+            if handler is None:
+                continue
+
+            result = handler(client)
+
+            if inspect.iscoroutine(result):
+                task = asyncio.create_task(result)
+                task.add_done_callback(_log_task_error)
+                tasks.append(task)
+
+        self.startup_tasks = tasks
+
+    async def stop_startup_tasks(self) -> None:
+        if not self.startup_tasks:
+            return
+
+        for task in self.startup_tasks:
+            if not task.done():
+                task.cancel()
+
+        for task in self.startup_tasks:
+            with suppress(asyncio.CancelledError, Exception):
+                await task
+
+        self.startup_tasks = []
+
+    async def dispatch(self, frame: InboundFrame) -> None:
+        event_type = self.resolver.resolve(frame)
+
+        if event_type is not None:
+            logger.debug("dispatching event type=%s", event_type)
+            event = self.mapper.map(event_type, frame)
+            await self._dispatch_to_router(self.internal_router, event_type, event)
+            await self._dispatch_to_router(self.root_router, event_type, event)
+        else:
+            logger.debug("dispatching raw event only opcode=%s cmd=%s", frame.opcode, frame.cmd)
+
+        await self._dispatch_to_router(self.root_router, EventType.RAW, frame)
+
+    async def _dispatch_to_router(
+        self,
+        router: Router[ClientT],
+        event_type: EventType,
+        event: Any,
+    ) -> None:
+        for entry in router.handlers.get(event_type, []):
+            if await self._matches(entry, event):
+                logger.debug(
+                    "calling handler event=%s callback=%s",
+                    event_type,
+                    _callback_name(entry.callback),
+                )
+                await self._call(entry.callback, event)
+
+        for child in router.children:
+            await self._dispatch_to_router(child, event_type, event)
+
+    async def _matches(
+        self,
+        entry: HandlerEntry[Any, ClientT],
+        event: Any,
+    ) -> bool:
+        for flt in entry.filters:
+            result = flt(event)
+            if inspect.isawaitable(result):
+                result = await result
+            if not result:
+                logger.debug(
+                    "handler skipped by filter callback=%s",
+                    _callback_name(entry.callback),
+                )
+                return False
+        return True
+
+    async def _call(self, callback: HandlerCallback[Any, ClientT], event: Any) -> Any:
+        if self.client is None:
+            raise RuntimeError("client is not bound")
+
+        result = callback(event, self.client)
+
+        if inspect.isawaitable(result):
+            return await result
+
+        return result
+
+
+def _callback_name(callback: Any) -> str:
+    return getattr(
+        callback,
+        "__qualname__",
+        getattr(callback, "__name__", repr(callback)),
+    )
+
+
+def _log_task_error(task: asyncio.Task[Any]) -> None:
+    try:
+        task.result()
+    except asyncio.CancelledError:
+        pass
+    except Exception:
+        logger.exception("startup task failed")

pymax/dispatch/enums.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class EventType(str, Enum):
+    MESSAGE_NEW = "message_new"
+    MESSAGE_EDIT = "message_edit"
+    MESSAGE_DELETE = "message_delete"
+    CHAT_UPDATE = "chat_update"
+    USER_UPDATE = "user_update"
+    VIDEO_READY = "video_ready"
+    FILE_READY = "file_ready"
+    RAW = "raw"

pymax/dispatch/mapping.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from pymax.protocol import InboundFrame, Opcode
+from pymax.protocol.enums import Command
+from pymax.types import Chat, MessageDeleteEvent
+from pymax.types.domain import Message
+from pymax.types.events import FileUploadSignal, VideoUploadSignal
+
+from .enums import EventType
+from .resolvers import resolve_attach, resolve_chat, resolve_message, resolve_message_delete
+
+if TYPE_CHECKING:
+    from pymax.app import App
+
+Resolver = Callable[[InboundFrame], EventType | None]
+
+EVENT_MAP: dict[Opcode, Resolver] = {
+    Opcode.NOTIF_MESSAGE: resolve_message,
+    Opcode.MSG_EDIT: resolve_message,
+    Opcode.NOTIF_CHAT: resolve_chat,
+    Opcode.NOTIF_MSG_DELETE: resolve_message_delete,
+    Opcode.NOTIF_ATTACH: resolve_attach,
+}
+
+
+class EventResolver:
+    def resolve(self, frame: InboundFrame) -> EventType | None:
+        if frame.cmd != Command.EVENT:
+            return None
+
+        try:
+            opcode = Opcode(frame.opcode)
+        except ValueError:
+            return None
+
+        handler = EVENT_MAP.get(opcode)
+
+        if handler:
+            return handler(frame)
+        return None
+
+
+class EventMapper:
+    def __init__(self, app: App) -> None:
+        self.app = app
+
+    def map(self, event_type: EventType, frame: InboundFrame):
+        if frame.cmd != Command.EVENT:
+            return None
+
+        if frame.payload:
+            if event_type in (EventType.MESSAGE_NEW, EventType.MESSAGE_EDIT):
+                return Message.model_validate(frame.payload).bind(self.app.api.messages)
+            elif event_type == EventType.CHAT_UPDATE:
+                return Chat.model_validate(frame.payload["chat"]).bind(
+                    self.app.api.messages,
+                    self.app.api.chats,
+                )
+            elif event_type == EventType.MESSAGE_DELETE:
+                model = MessageDeleteEvent.model_validate(frame.payload)
+                model.chat.bind(
+                    self.app.api.messages,
+                    self.app.api.chats,
+                )
+                return model
+            elif event_type == EventType.VIDEO_READY:
+                return VideoUploadSignal.model_validate(frame.payload)
+            elif event_type == EventType.FILE_READY:
+                return FileUploadSignal.model_validate(frame.payload)
+        return frame

pymax/dispatch/resolvers.py

@@ -0,0 +1,52 @@
+from pydantic import ValidationError
+
+from pymax.logging import get_logger
+from pymax.protocol import InboundFrame
+from pymax.protocol.enums import Opcode
+from pymax.types import Message
+from pymax.types.domain.enums import MessageStatus
+from pymax.types.events import FileUploadSignal, VideoUploadSignal
+
+from .enums import EventType
+
+logger = get_logger(__name__)
+
+
+def resolve_chat(_: InboundFrame) -> EventType | None:
+    return EventType.CHAT_UPDATE
+
+
+def resolve_message_delete(_: InboundFrame) -> EventType | None:
+    return EventType.MESSAGE_DELETE
+
+
+def resolve_attach(frame: InboundFrame) -> EventType | None:
+    try:
+        FileUploadSignal.model_validate(frame.payload)
+        return EventType.FILE_READY
+    except ValidationError:
+        logger.debug("attach event is not a file upload signal")
+
+    try:
+        VideoUploadSignal.model_validate(frame.payload)
+        return EventType.VIDEO_READY
+    except ValidationError:
+        logger.debug("attach event is not a video upload signal")
+
+    return None
+
+
+def resolve_message(frame: InboundFrame) -> EventType | None:
+    if frame.opcode not in (Opcode.NOTIF_MESSAGE, Opcode.MSG_EDIT):
+        return None
+
+    try:
+        model = Message.model_validate(frame.payload)
+
+        if model.status == MessageStatus.EDITED:
+            return EventType.MESSAGE_EDIT
+        else:
+            return EventType.MESSAGE_NEW
+    except ValidationError:
+        logger.debug("failed to resolve message event", exc_info=True)
+        return None

pymax/dispatch/router.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic, TypeAlias, TypeVar
+
+from pymax.types import MessageDeleteEvent
+
+from .enums import EventType
+
+if TYPE_CHECKING:
+    from pymax.client import Client
+    from pymax.protocol import InboundFrame
+    from pymax.types import Chat
+    from pymax.types.domain import Message
+
+
+_EventT = TypeVar("_EventT")
+ClientT = TypeVar("ClientT")
+
+HandlerCallback: TypeAlias = Callable[
+    [_EventT, ClientT],
+    Awaitable[Any] | Any,
+]
+HandlerDecorator: TypeAlias = Callable[
+    [HandlerCallback[_EventT, ClientT]],
+    HandlerCallback[_EventT, ClientT],
+]
+FilterCallback: TypeAlias = Callable[
+    [_EventT],
+    Awaitable[bool] | bool,
+]
+StartCallback: TypeAlias = Callable[
+    [ClientT],
+    Awaitable[Any] | Any,
+]
+StartDecorator: TypeAlias = Callable[
+    [StartCallback[ClientT]],
+    StartCallback[ClientT],
+]
+
+
+@dataclass(slots=True)
+class HandlerEntry(Generic[_EventT, ClientT]):
+    callback: HandlerCallback[_EventT, ClientT]
+    filters: tuple[FilterCallback[_EventT], ...] = ()
+
+
+class Router(Generic[ClientT]):
+    """Контейнер обработчиков событий PyMax.
+
+    Роутер хранит обработчики и фильтры. Когда приходит событие, dispatcher
+    проходит по root router и его дочерним роутерам, проверяет фильтры и
+    вызывает подходящие callbacks как ``handler(event, client)``.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import Client, Message, Router
+
+           router = Router[Client]()
+
+           def is_start(message: Message) -> bool:
+               return message.text == "/start"
+
+           @router.on_message(is_start)
+           async def start(message: Message, client: Client) -> None:
+               await message.answer("Привет")
+
+           client = Client(phone="+79990000000")
+           client.include_router(router)
+    """
+
+    def __init__(self) -> None:
+        self.handlers: dict[
+            EventType,
+            list[HandlerEntry[Any, ClientT]],
+        ] = defaultdict(list)
+
+        self.children: list[Router[ClientT]] = []
+        self.on_start_handler: StartCallback[ClientT] | None = None
+
+    def on(
+        self,
+        event: EventType,
+        /,
+        *filters: FilterCallback[_EventT],
+    ) -> HandlerDecorator[_EventT, ClientT]:
+        """Регистрирует обработчик события по ``EventType``.
+
+        Args:
+            event: Тип события.
+            *filters: Фильтры, которые получают событие и возвращают bool.
+
+        Returns:
+            Декоратор для ``handler(event, client)``.
+
+        Example:
+            .. code-block:: python
+
+               from pymax import Client
+               from pymax.protocol import InboundFrame
+
+               @router.on(EventType.RAW)
+               async def raw(frame: InboundFrame, client: Client) -> None:
+                   print(frame.payload)
+        """
+        def decorator(
+            handler: HandlerCallback[_EventT, ClientT],
+        ) -> HandlerCallback[_EventT, ClientT]:
+            self.handlers[event].append(
+                HandlerEntry(
+                    callback=handler,
+                    filters=filters,
+                )
+            )
+            return handler
+
+        return decorator
+
+    def include_router(self, router: Router[ClientT]) -> None:
+        """Подключает дочерний роутер.
+
+        Args:
+            router: Router, обработчики которого нужно добавить в дерево.
+
+        Returns:
+            ``None``.
+        """
+        self.children.append(router)
+
+    def on_start(self) -> StartDecorator:
+        """Регистрирует обработчик старта клиента.
+
+        Returns:
+            Декоратор для ``handler(client)``.
+        """
+        def decorator(handler: StartCallback) -> StartCallback:
+            self.on_start_handler = handler
+            return handler
+
+        return decorator
+
+    def on_message(
+        self,
+        *filters: FilterCallback[Message],
+    ) -> HandlerDecorator[Message, ClientT]:
+        """Регистрирует обработчик новых сообщений.
+
+        Args:
+            *filters: Фильтры для ``Message``.
+
+        Returns:
+            Декоратор для ``handler(message, client)``.
+        """
+        return self.on(EventType.MESSAGE_NEW, *filters)
+
+    def on_message_edit(
+        self,
+        *filters: FilterCallback[Message],
+    ) -> HandlerDecorator[Message, ClientT]:
+        """Регистрирует обработчик редактирования сообщений.
+
+        Args:
+            *filters: Фильтры для ``Message``.
+
+        Returns:
+            Декоратор для ``handler(message, client)``.
+        """
+        return self.on(EventType.MESSAGE_EDIT, *filters)
+
+    def on_message_delete(
+        self,
+        *filters: FilterCallback[MessageDeleteEvent],
+    ) -> HandlerDecorator[MessageDeleteEvent, ClientT]:
+        """Регистрирует обработчик удаления сообщений.
+
+        Args:
+            *filters: Фильтры для ``MessageDeleteEvent``.
+
+        Returns:
+            Декоратор для ``handler(event, client)``.
+        """
+        return self.on(EventType.MESSAGE_DELETE, *filters)
+
+    def on_chat_update(
+        self,
+        *filters: FilterCallback[Chat],
+    ) -> HandlerDecorator[Chat, ClientT]:
+        """Регистрирует обработчик обновления чата.
+
+        Args:
+            *filters: Фильтры для ``Chat``.
+
+        Returns:
+            Декоратор для ``handler(chat, client)``.
+        """
+        return self.on(EventType.CHAT_UPDATE, *filters)
+
+    def on_raw(
+        self,
+        *filters: FilterCallback[InboundFrame],
+    ) -> HandlerDecorator[InboundFrame, ClientT]:
+        """Регистрирует обработчик исходных frame-ов.
+
+        Args:
+            *filters: Фильтры для ``InboundFrame``.
+
+        Returns:
+            Декоратор для ``handler(frame, client)``.
+        """
+        return self.on(EventType.RAW, *filters)
+
+
+ClientRouter: TypeAlias = Router["Client"]

pymax/exceptions.py

@@ -1,108 +1,41 @@
-class InvalidPhoneError(Exception):
-    """
-    Исключение, вызываемое при неверном формате номера телефона.
+from typing import Any
 
-    Args:
-        phone (str): Некорректный номер телефона.
-    """
 
-    def __init__(self, phone: str) -> None:
-        super().__init__(f"Invalid phone number format: {phone}")
+class PyMaxError(Exception):
+    pass
 
 
-class WebSocketNotConnectedError(Exception):
-    """
-    Исключение, вызываемое при попытке обращения к WebSocket,
-    если соединение не установлено.
-    """
+class UploadError(PyMaxError):
+    pass
 
-    def __init__(self) -> None:
-        super().__init__("WebSocket is not connected")
-
-
-class SocketNotConnectedError(Exception):
-    """
-    Исключение, вызываемое при попытке обращения к сокету,
-    если соединение не установлено.
-    """
-
-    def __init__(self) -> None:
-        super().__init__("Socket is not connected")
-
-
-class SocketSendError(Exception):
-    """
-    Исключение, вызываемое при ошибке отправки данных через сокет.
-    """
-
-    def __init__(self) -> None:
-        super().__init__("Send and wait failed (socket)")
-
-
-class ResponseError(Exception):
-    """
-    Исключение, вызываемое при ошибке в ответе от сервера.
-    """
-
-    def __init__(self, message: str) -> None:
-        super().__init__(f"Response error: {message}")
-
-
-class ResponseStructureError(Exception):
-    """
-    Исключение, вызываемое при неверной структуре ответа от сервера.
-    """
-
-    def __init__(self, message: str) -> None:
-        super().__init__(f"Response structure error: {message}")
-
-
-class Error(Exception):
-    """
-    Базовое исключение для ошибок PyMax.
-    """
 
+class ApiError(PyMaxError):
     def __init__(
         self,
-        error: str,
-        message: str,
-        title: str,
+        *,
+        opcode: int,
+        error: str | None = None,
+        message: str | None = None,
         localized_message: str | None = None,
+        title: str | None = None,
+        payload: dict[str, Any] | None = None,
     ) -> None:
+        self.opcode = opcode
         self.error = error
         self.message = message
-        self.title = title
         self.localized_message = localized_message
+        self.title = title
+        self.payload = payload or {}
 
         parts = []
-        if localized_message:
-            parts.append(localized_message)
-        if message:
-            parts.append(message)
+        for part in (localized_message, message):
+            if part and part not in parts:
+                parts.append(part)
         if title:
             parts.append(f"({title})")
-        parts.append(f"[{error}]")
-
-        super().__init__("PyMax Error: " + " ".join(parts))
-
-
-class RateLimitError(Error):
-    """
-    Исключение, вызываемое при превышении лимита запросов.
-    """
-
-    def __init__(
-        self, error: str, message: str, title: str, localized_message: str | None = None
-    ) -> None:
-        super().__init__(error, message, title, localized_message)
+        if error:
+            parts.append(f"[{error}]")
 
+        text = " ".join(parts) or "API request failed"
 
-class LoginError(Error):
-    """
-    Исключение, вызываемое при ошибке авторизации.
-    """
-
-    def __init__(
-        self, error: str, message: str, title: str, localized_message: str | None = None
-    ) -> None:
-        super().__init__(error, message, title, localized_message)
+        super().__init__(text)