maxapi-python 2.4.0__py3-none-any.whl → 2.5.0__py3-none-any.whl

pymax/dispatch/router.py

@@ -4,17 +4,28 @@ from collections import defaultdict
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Generic, TypeAlias, TypeVar
-
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Concatenate,
+    Generic,
+    ParamSpec,
+    Protocol,
+    TypeAlias,
+    TypeVar,
+)
+
+from pymax.filters import Filter
 from pymax.types import MessageDeleteEvent
 
 from .enums import EventType
 
 if TYPE_CHECKING:
-    from pymax import Client
     from pymax.base import BaseClient
+    from pymax.client import Client
+    from pymax.dispatch.middleware import Middleware
     from pymax.protocol import InboundFrame
-    from pymax.types import Chat
+    from pymax.types import Chat, StoryPreview
     from pymax.types.domain import Message
     from pymax.types.events import (
         MessageReadEvent,
@@ -33,19 +44,33 @@ class ErrorScope(str, Enum):
 
 _EventT = TypeVar("_EventT")
 ClientT = TypeVar("ClientT", bound="BaseClient")
+_P = ParamSpec("_P")
 
 HandlerCallback: TypeAlias = Callable[
     [_EventT, ClientT],
     Awaitable[Any] | Any,
 ]
-HandlerDecorator: TypeAlias = Callable[
-    [HandlerCallback[_EventT, ClientT]],
-    HandlerCallback[_EventT, ClientT],
-]
-FilterCallback: TypeAlias = Callable[
-    [_EventT],
-    Awaitable[bool] | bool,
-]
+# HandlerDecorator: TypeAlias = Callable[
+#     [HandlerCallback[_EventT, ClientT]],
+#     HandlerCallback[_EventT, ClientT],
+# ]
+
+HandlerResult: TypeAlias = Awaitable[Any] | Any
+
+
+class HandlerDecorator(Protocol, Generic[_EventT, ClientT]):
+    def __call__(
+        self,
+        handler: Callable[
+            Concatenate[_EventT, ClientT, _P],
+            HandlerResult,
+        ],
+    ) -> Callable[
+        Concatenate[_EventT, ClientT, _P],
+        HandlerResult,
+    ]: ...
+
+
 StartCallback: TypeAlias = Callable[
     [ClientT],
     Awaitable[Any] | Any,
@@ -91,7 +116,7 @@ DisconnectDecorator: TypeAlias = Callable[
 @dataclass(slots=True)
 class HandlerEntry(Generic[_EventT, ClientT]):
     callback: HandlerCallback[_EventT, ClientT]
-    filters: tuple[FilterCallback[_EventT], ...] = ()
+    filters: tuple[Filter, ...] = ()
 
 
 @dataclass(slots=True)
@@ -107,20 +132,20 @@ class Router(Generic[ClientT]):
     """Контейнер обработчиков событий PyMax.
 
     Роутер хранит обработчики и фильтры. Когда приходит событие, dispatcher
-    проходит по root router и его дочерним роутерам, проверяет фильтры и
-    вызывает подходящие callbacks как ``handler(event, client)``.
+    проверяет обработчики в порядке регистрации и вызывает первый подходящий
+    в каждом роутере, затем обходит его дочерние роутеры. Первые два аргумента
+    обработчика — ``event`` и ``client``; дополнительные обязательные параметры
+    разрешаются по аннотациям типов через DI.
 
     Example:
         .. code-block:: python
 
            from pymax import Client, Message, Router
+           from pymax.filters import Command
 
            router = Router[Client]()
 
-           def is_start(message: Message) -> bool:
-               return message.text == "/start"
-
-           @router.on_message(is_start)
+           @router.on_message(Command("start"))
            async def start(message: Message, client: Client) -> None:
                await message.answer("Привет")
 
@@ -135,6 +160,7 @@ class Router(Generic[ClientT]):
         ] = defaultdict(list)
 
         self.children: list[Router[ClientT]] = []
+        self.middlewares: list[Middleware[ClientT]] = []
         self.on_start_handlers: list[StartCallback[ClientT]] = []
         self.error_handlers: list[ErrorEntry[ClientT]] = []
         self.disconnect_handlers: list[DisconnectCallback] = []
@@ -147,6 +173,8 @@ class Router(Generic[ClientT]):
 
         ``GLOBAL``-handler видит ошибки всего дерева подключенных router-ов.
         ``LOCAL``-handler видит только ошибки своего router-а.
+        Callback получает ``handler(exception, context)``. При обработке
+        событий сюда передаются ошибки фильтров, middleware и handler-ов.
         """
         scope = ErrorScope(scope)
 
@@ -173,13 +201,15 @@ class Router(Generic[ClientT]):
         self,
         event: EventType,
         /,
-        *filters: FilterCallback[_EventT],
+        *filters: Filter[_EventT, ClientT],
     ) -> HandlerDecorator[_EventT, ClientT]:
         """Регистрирует обработчик события по ``EventType``.
 
         Args:
             event: Тип события.
-            *filters: Фильтры, которые получают событие и возвращают bool.
+            *filters: Экземпляры ``Filter``, вызываемые как
+                ``filter(event, client)``. Все фильтры должны вернуть ``True``;
+                async-результаты ожидаются автоматически.
 
         Returns:
             Декоратор для ``handler(event, client)``.
@@ -187,7 +217,7 @@ class Router(Generic[ClientT]):
         Example:
             .. code-block:: python
 
-               from pymax import Client
+               from pymax import Client, EventType
                from pymax.protocol import InboundFrame
 
                @router.on(EventType.RAW)
@@ -196,8 +226,14 @@ class Router(Generic[ClientT]):
         """
 
         def decorator(
-            handler: HandlerCallback[_EventT, ClientT],
-        ) -> HandlerCallback[_EventT, ClientT]:
+            handler: Callable[
+                Concatenate[_EventT, ClientT, _P],
+                HandlerResult,
+            ],
+        ) -> Callable[
+            Concatenate[_EventT, ClientT, _P],
+            HandlerResult,
+        ]:
             self.handlers[event].append(
                 HandlerEntry(
                     callback=handler,
@@ -234,7 +270,7 @@ class Router(Generic[ClientT]):
 
     def on_message(
         self,
-        *filters: FilterCallback[Message],
+        *filters: Filter[Message, ClientT],
     ) -> HandlerDecorator[Message, ClientT]:
         """Регистрирует обработчик новых сообщений.
 
@@ -248,7 +284,7 @@ class Router(Generic[ClientT]):
 
     def on_message_edit(
         self,
-        *filters: FilterCallback[Message],
+        *filters: Filter[Message, ClientT],
     ) -> HandlerDecorator[Message, ClientT]:
         """Регистрирует обработчик редактирования сообщений.
 
@@ -262,7 +298,7 @@ class Router(Generic[ClientT]):
 
     def on_message_delete(
         self,
-        *filters: FilterCallback[MessageDeleteEvent],
+        *filters: Filter[MessageDeleteEvent, ClientT],
     ) -> HandlerDecorator[MessageDeleteEvent, ClientT]:
         """Регистрирует обработчик удаления сообщений.
 
@@ -276,35 +312,38 @@ class Router(Generic[ClientT]):
 
     def on_message_read(
         self,
-        *filters: FilterCallback[MessageReadEvent],
+        *filters: Filter[MessageReadEvent, ClientT],
     ) -> HandlerDecorator[MessageReadEvent, ClientT]:
         """Регистрирует обработчик изменения отметки прочтения."""
         return self.on(EventType.MESSAGE_READ, *filters)
 
     def on_typing(
         self,
-        *filters: FilterCallback[TypingEvent],
+        *filters: Filter[TypingEvent, ClientT],
     ) -> HandlerDecorator[TypingEvent, ClientT]:
         """Регистрирует обработчик набора текста."""
         return self.on(EventType.TYPING, *filters)
 
     def on_presence(
         self,
-        *filters: FilterCallback[PresenceEvent],
+        *filters: Filter[PresenceEvent, ClientT],
     ) -> HandlerDecorator[PresenceEvent, ClientT]:
         """Регистрирует обработчик изменения присутствия пользователя."""
         return self.on(EventType.PRESENCE, *filters)
 
     def on_reaction_update(
         self,
-        *filters: FilterCallback[ReactionUpdateEvent],
+        *filters: Filter[ReactionUpdateEvent, ClientT],
     ) -> HandlerDecorator[ReactionUpdateEvent, ClientT]:
-        """Регистрирует обработчик обновления реакций сообщения."""
+        """Регистрирует обработчик ``ReactionUpdateEvent``.
+
+        Получает обновления счетчиков реакций и реакции текущего пользователя.
+        """
         return self.on(EventType.REACTION_UPDATE, *filters)
 
     def on_chat_update(
         self,
-        *filters: FilterCallback[Chat],
+        *filters: Filter[Chat, ClientT],
     ) -> HandlerDecorator[Chat, ClientT]:
         """Регистрирует обработчик обновления чата.
 
@@ -316,12 +355,25 @@ class Router(Generic[ClientT]):
         """
         return self.on(EventType.CHAT_UPDATE, *filters)
 
+    def on_story_update(
+        self,
+        *filters: Filter[StoryPreview, ClientT],
+    ) -> HandlerDecorator[StoryPreview, ClientT]:
+        """Регистрирует обработчик обновления ``StoryPreview`` владельца.
+
+        Первый аргумент handler-а содержит сводное превью, а не ``Story``.
+        """
+        return self.on(EventType.STORY_UPDATE, *filters)
+
     def on_raw(
         self,
-        *filters: FilterCallback[InboundFrame],
+        *filters: Filter[InboundFrame, ClientT],
     ) -> HandlerDecorator[InboundFrame, ClientT]:
         """Регистрирует обработчик исходных frame-ов.
 
+        Вызывается после типизированной обработки, даже если тип события
+        неизвестен или его обработка завершилась ошибкой.
+
         Args:
             *filters: Фильтры для ``InboundFrame``.
 

pymax/files/base.py

@@ -1,10 +1,16 @@
 import os
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator
+from io import BytesIO
 
 import aiofiles
 import aiohttp
 
+try:
+    from tinytag import TinyTag
+except ImportError:
+    TinyTag = None
+
 
 class BaseFile(ABC):
     def __init__(
@@ -56,7 +62,7 @@ class BaseFile(ABC):
 
         if self.url:
             async with aiohttp.ClientSession() as session:  # noqa: SIM117
-                async with session.head(self.url) as resp:
+                async with session.head(self.url, allow_redirects=True) as resp:
                     return int(resp.headers["Content-Length"])
         else:
             raise ValueError("Path or Url must be provided")
@@ -85,3 +91,54 @@ class BaseFile(ABC):
                     resp.raise_for_status()
                     async for chunk in resp.content.iter_chunked(size):
                         yield chunk
+
+
+class TimedMediaFile(BaseFile):
+    def __init__(
+        self,
+        raw: bytes | None = None,
+        *,
+        path: str | None,
+        url: str | None,
+        name: str | None,
+        duration: int | None,
+    ) -> None:
+        self.duration = duration
+        super().__init__(raw, path=path, url=url, name=name)
+
+    async def get_duration(self) -> int:
+        if self.duration is not None:
+            return self.duration
+
+        if not TinyTag:
+            raise RuntimeError(
+                "Automatic video duration detection requires the 'video' extra. "
+                "Install it with `uv add 'maxapi-python[video]'` "
+                "or pass duration manually."
+            )
+
+        if self.raw:
+            tag = TinyTag.get(
+                filename=self.name,
+                file_obj=BytesIO(self.raw),
+                tags=False,
+                duration=True,
+            )
+        elif self.path:
+            tag = TinyTag.get(
+                filename=self.path,
+                tags=False,
+                duration=True,
+            )
+        else:
+            tag = TinyTag.get(
+                filename=self.name,
+                file_obj=BytesIO(await self.read()),
+                tags=False,
+                duration=True,
+            )
+
+        if tag.duration is None:
+            raise ValueError("Failed to determine video duration.")
+
+        return round(tag.duration * 1000)

pymax/files/video.py

@@ -1,13 +1,7 @@
 from collections.abc import AsyncGenerator
-from io import BytesIO
 from pathlib import Path
 
-from .base import BaseFile
-
-try:
-    from tinytag import TinyTag
-except ImportError:
-    TinyTag = None
+from .base import BaseFile, TimedMediaFile
 
 
 class Video(BaseFile):
@@ -80,12 +74,23 @@ class Video(BaseFile):
         return super().iter_chunks(size)
 
 
-class VideoNote(Video):
+class VideoNote(TimedMediaFile):
     """Круглое видеосообщение для отправки.
 
     Принимает те же источники, что и ``Video``. Длительность задается в
     миллисекундах. Если она не передана, требуется extra ``video`` для
     автоматического определения длительности.
+
+    Args:
+        raw: Байты видеосообщения.
+        url: URL видеосообщения.
+        path: Локальный путь к видеосообщению.
+        name: Имя файла. Обязательно для ``raw``.
+        duration: Длительность в миллисекундах. ``None`` включает
+            автоматическое определение через extra ``video``.
+
+    Raises:
+        RuntimeError: При определении длительности без extra ``video``.
     """
 
     def __init__(
@@ -98,35 +103,22 @@ class VideoNote(Video):
         duration: int | None = None,
     ) -> None:
         self.duration = duration
-        super().__init__(raw, url=url, path=path, name=name)
-
-    async def get_duration(self) -> int:
-        if self.duration is not None:
-            return self.duration
-
-        if not TinyTag:
-            raise RuntimeError(
-                "Automatic video duration detection requires the 'video' extra. "
-                "Install it with `uv add 'maxapi-python[video]'` "
-                "or pass duration manually."
-            )
-
-        if self.raw:
-            tag = TinyTag.get(
-                filename=self.name,
-                file_obj=BytesIO(self.raw),
-                tags=False,
-                duration=True,
-            )
-        else:
-            tag = TinyTag.get(
-                filename=self.name,
-                file_obj=BytesIO(await self.read()),
-                tags=False,
-                duration=True,
-            )
-
-        if tag.duration is None:
-            raise ValueError("Failed to determine video duration.")
-
-        return round(tag.duration * 1000)
+        self.name: str = name or ""
+        if not self.name and path:
+            self.name = Path(path).name
+        elif not self.name and url:
+            self.name = Path(url).name
+
+        if not self.name:
+            raise ValueError("Either name, url or path must be provided.")
+
+        super().__init__(raw, url=url, path=path, name=self.name, duration=self.duration)
+
+    async def read(self) -> bytes:
+        return await super().read()
+
+    def iter_chunks(self, size: int) -> AsyncGenerator[bytes, None]:
+        return super().iter_chunks(size)
+
+    async def size(self) -> int:
+        return await super().size()

pymax/files/voice.py

@@ -1,14 +1,26 @@
 from collections.abc import AsyncGenerator
 from pathlib import Path
 
-from .base import BaseFile
+from .base import TimedMediaFile
 
 
-class Voice(BaseFile):
+class Voice(TimedMediaFile):
     """Голосовое сообщение в формате OGG для отправки.
 
     Принимает ``path``, ``url`` или ``raw``. Для ``raw`` необходимо явно
-    передать имя файла.
+    передать имя файла. Длительность задается в миллисекундах; если она не
+    передана, требуется extra ``video`` для автоматического определения.
+
+    Args:
+        raw: Байты голосового сообщения.
+        path: Локальный путь к OGG-файлу.
+        url: URL OGG-файла.
+        name: Имя файла. Обязательно для ``raw``.
+        duration: Длительность в миллисекундах. ``None`` включает
+            автоматическое определение через extra ``video``.
+
+    Raises:
+        RuntimeError: При определении длительности без extra ``video``.
     """
 
     def __init__(
@@ -18,8 +30,10 @@ class Voice(BaseFile):
         path: str | None = None,
         url: str | None = None,
         name: str | None = None,
+        duration: int | None = None,
     ) -> None:
         self.name: str = name or ""
+        self.duration = duration
         if not self.name and path:
             self.name = Path(path).name
         elif not self.name and url:
@@ -27,7 +41,7 @@ class Voice(BaseFile):
 
         if not self.name:
             raise ValueError("Either name, url or path must be provided.")
-        super().__init__(raw=raw, url=url, path=path, name=self.name)
+        super().__init__(raw=raw, url=url, path=path, name=self.name, duration=self.duration)
 
     async def read(self) -> bytes:
         return await super().read()

pymax/filters/__init__.py

@@ -0,0 +1,15 @@
+from .base import Filter
+from .magic import MagicFilter
+from .presets import Command, Forwarded, FromMe, HasAttachment, Reply
+
+F = MagicFilter()
+
+__all__ = (
+    "Command",
+    "Filter",
+    "Forwarded",
+    "FromMe",
+    "HasAttachment",
+    "MagicFilter",
+    "Reply",
+)