maxapi-python 2.2.0__py3-none-any.whl → 2.3.1__py3-none-any.whl

pymax/dispatch/dispatcher.py

@@ -19,11 +19,19 @@ from pymax.types.events import (
 from .enums import EventType
 from .mapping import EventMapper, EventResolver
 from .router import (
+    DisconnectCallback,
+    DisconnectDecorator,
+    ErrorContext,
+    ErrorDecorator,
+    ErrorEntry,
+    ErrorScope,
+    ErrorSource,
     FilterCallback,
     HandlerCallback,
     HandlerDecorator,
     HandlerEntry,
     Router,
+    StartCallback,
     StartDecorator,
 )
 
@@ -31,11 +39,12 @@ if TYPE_CHECKING:
     from collections.abc import Generator
 
     from pymax.app import App
+    from pymax.base import BaseClient
 
 
 logger = get_logger(__name__)
 
-ClientT = TypeVar("ClientT")
+ClientT = TypeVar("ClientT", bound="BaseClient")
 
 
 class Dispatcher(Generic[ClientT]):
@@ -78,6 +87,13 @@ class Dispatcher(Generic[ClientT]):
         logger.debug("registering handler event=%s filters=%s", event, len(filters))
         return self.root_router.on(event, *filters)
 
+    def on_error(self, scope: ErrorScope = ErrorScope.GLOBAL) -> ErrorDecorator[ClientT]:
+        return self.root_router.on_error(scope)
+
+    def on_disconnect(self) -> DisconnectDecorator:
+        """Регистрирует обработчик сетевого отключения на root router."""
+        return self.root_router.on_disconnect()
+
     def on_message(
         self,
         *filters: FilterCallback[Message],
@@ -146,22 +162,62 @@ class Dispatcher(Generic[ClientT]):
         for child in router.children:
             yield from self._iter_router(child)
 
-    async def emit_start(self, client: ClientT) -> None:
-        tasks: list[asyncio.Task[Any]] = []
+    def iter_error_entries(
+        self,
+    ) -> Generator[tuple[Router[ClientT], ErrorEntry[ClientT]], Any, None]:
+        for router in self.iter_routers():
+            for entry in router.error_handlers:
+                yield router, entry
 
+    def iter_disconnect_handlers(self) -> Generator[DisconnectCallback, Any, None]:
+        """Итерирует обработчики disconnect по root router и его детям."""
         for router in self.iter_routers():
-            handler = router.on_start_handler
-            if handler is None:
+            yield from router.disconnect_handlers
+
+    def iter_error_handlers(
+        self,
+        failed_router: Router[ClientT],
+    ) -> Generator[ErrorEntry[ClientT], Any, None]:
+        for owner_router, entry in self.iter_error_entries():
+            if entry.scope is ErrorScope.LOCAL and owner_router is not failed_router:
                 continue
 
-            result = handler(client)
+            yield entry
 
-            if inspect.iscoroutine(result):
-                task = asyncio.create_task(result)
+    async def emit_start(self, client: ClientT) -> None:
+        tasks: list[asyncio.Task[Any]] = []
+
+        for router in self.iter_routers():  # TODO: create iter_on_start_handlers
+            for handler in router.on_start_handlers:
+                task = asyncio.create_task(self._run_start_handler(router, handler, client))
                 task.add_done_callback(_log_task_error)
                 tasks.append(task)
 
-        self.startup_tasks = tasks
+        self.startup_tasks.extend(tasks)
+
+    async def _run_start_handler(
+        self,
+        router: Router[ClientT],
+        handler: StartCallback[ClientT],
+        client: ClientT,
+    ) -> None:
+        try:
+            result = handler(client)
+
+            if inspect.isawaitable(result):
+                await result
+
+        except Exception as e:
+            handled = await self.emit_error(
+                e,
+                EventType.ON_START,
+                None,
+                router,
+                handler,
+            )
+
+            if not handled:
+                raise
 
     async def stop_startup_tasks(self) -> None:
         if not self.startup_tasks:
@@ -201,13 +257,18 @@ class Dispatcher(Generic[ClientT]):
         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)
+            try:
+                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)
+            except Exception as e:  # noqa: PERF203
+                handled = await self.emit_error(e, event_type, event, router, entry)
+                if not handled:
+                    raise
 
         for child in router.children:
             await self._dispatch_to_router(child, event_type, event)
@@ -240,6 +301,63 @@ class Dispatcher(Generic[ClientT]):
 
         return result
 
+    async def emit_error(
+        self,
+        exception: Exception,
+        event_type: EventType,
+        event: Any,
+        router: Router[ClientT],
+        handler: ErrorSource[ClientT] | None,
+    ) -> bool:
+        client = self.client
+        handled = False
+
+        if client is None:
+            raise RuntimeError("client is not bound to dispatcher")
+
+        ctx = ErrorContext[ClientT](
+            client=client,
+            event_type=event_type,
+            event=event,
+            router=router,
+            handler=handler,
+        )
+        for entry in self.iter_error_handlers(router):
+            handled = True
+            try:
+                result = entry.callback(exception, ctx)
+
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as e:
+                logger.exception("Error while error handling: %s", e)
+                return False
+
+        return handled
+
+    async def emit_disconnect(
+        self,
+        exception: Exception,
+        reconnect: bool,
+        delay: float,
+    ) -> None:
+        """Вызывает обработчики потери соединения.
+
+        Ошибки внутри disconnect-handler-ов логируются и не прерывают reconnect.
+        """
+
+        if self.client is None:
+            raise RuntimeError("client is not bound to dispatcher")
+
+        for handler in self.iter_disconnect_handlers():
+            try:
+                result = handler(exception, reconnect, delay)
+
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as e:
+                logger.exception("Error during disconnect handling: %s", e)
+
 
 def _callback_name(callback: Any) -> str:
     return getattr(

pymax/dispatch/enums.py

@@ -14,3 +14,4 @@ class EventType(str, Enum):
     VIDEO_READY = "video_ready"
     FILE_READY = "file_ready"
     RAW = "raw"
+    ON_START = "on_start"

pymax/dispatch/router.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 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 pymax.types import MessageDeleteEvent
@@ -10,7 +11,8 @@ from pymax.types import MessageDeleteEvent
 from .enums import EventType
 
 if TYPE_CHECKING:
-    from pymax.client import Client
+    from pymax import Client
+    from pymax.base import BaseClient
     from pymax.protocol import InboundFrame
     from pymax.types import Chat
     from pymax.types.domain import Message
@@ -22,8 +24,15 @@ if TYPE_CHECKING:
     )
 
 
+class ErrorScope(str, Enum):
+    """Область действия error-handler-а."""
+
+    GLOBAL = "global"
+    LOCAL = "local"
+
+
 _EventT = TypeVar("_EventT")
-ClientT = TypeVar("ClientT")
+ClientT = TypeVar("ClientT", bound="BaseClient")
 
 HandlerCallback: TypeAlias = Callable[
     [_EventT, ClientT],
@@ -47,12 +56,53 @@ StartDecorator: TypeAlias = Callable[
 ]
 
 
+@dataclass(slots=True)
+class ErrorContext(Generic[ClientT]):
+    """Контекст ошибки, передаваемый в ``on_error`` callback."""
+
+    client: ClientT
+    event_type: EventType
+    event: Any
+    handler: HandlerEntry[Any, ClientT] | StartCallback | None
+    router: Router[ClientT]
+
+
+ErrorCallback: TypeAlias = Callable[
+    [Exception, ErrorContext[ClientT]],
+    Awaitable[Any] | Any,
+]
+
+ErrorDecorator: TypeAlias = Callable[
+    [ErrorCallback[ClientT]],
+    ErrorCallback[ClientT],
+]
+
+DisconnectCallback: TypeAlias = Callable[
+    [Exception, bool, float],
+    Awaitable[Any] | Any,
+]
+
+DisconnectDecorator: TypeAlias = Callable[
+    [DisconnectCallback],
+    DisconnectCallback,
+]
+
+
 @dataclass(slots=True)
 class HandlerEntry(Generic[_EventT, ClientT]):
     callback: HandlerCallback[_EventT, ClientT]
     filters: tuple[FilterCallback[_EventT], ...] = ()
 
 
+@dataclass(slots=True)
+class ErrorEntry(Generic[ClientT]):
+    callback: ErrorCallback[ClientT]
+    scope: ErrorScope = ErrorScope.GLOBAL
+
+
+ErrorSource: TypeAlias = HandlerEntry[Any, ClientT] | StartCallback[ClientT]
+
+
 class Router(Generic[ClientT]):
     """Контейнер обработчиков событий PyMax.
 
@@ -85,7 +135,39 @@ class Router(Generic[ClientT]):
         ] = defaultdict(list)
 
         self.children: list[Router[ClientT]] = []
-        self.on_start_handler: StartCallback[ClientT] | None = None
+        self.on_start_handlers: list[StartCallback[ClientT]] = []
+        self.error_handlers: list[ErrorEntry[ClientT]] = []
+        self.disconnect_handlers: list[DisconnectCallback] = []
+
+    def on_error(
+        self,
+        scope: ErrorScope = ErrorScope.GLOBAL,
+    ) -> ErrorDecorator[ClientT]:
+        """Регистрирует обработчик ошибок для текущего router-а.
+
+        ``GLOBAL``-handler видит ошибки всего дерева подключенных router-ов.
+        ``LOCAL``-handler видит только ошибки своего router-а.
+        """
+        scope = ErrorScope(scope)
+
+        def decorator(callback: ErrorCallback[ClientT]) -> ErrorCallback[ClientT]:
+            self.error_handlers.append(ErrorEntry(callback=callback, scope=scope))
+            return callback
+
+        return decorator
+
+    def on_disconnect(self) -> DisconnectDecorator:
+        """Регистрирует обработчик потери соединения.
+
+        Callback вызывается как ``handler(exception, reconnect, delay)``:
+        исходная ошибка, будет ли reconnect и задержка перед ним.
+        """
+
+        def decorator(callback: DisconnectCallback) -> DisconnectCallback:
+            self.disconnect_handlers.append(callback)
+            return callback
+
+        return decorator
 
     def on(
         self,
@@ -145,7 +227,7 @@ class Router(Generic[ClientT]):
         """
 
         def decorator(handler: StartCallback) -> StartCallback:
-            self.on_start_handler = handler
+            self.on_start_handlers.append(handler)
             return handler
 
         return decorator

pymax/infra/chat.py

@@ -227,6 +227,27 @@ class ChatMixin(IClientProtocol):
         """
         await self._app.api.chats.leave_channel(chat_id)
 
+    async def delete_chat(
+        self,
+        chat_id: int,
+        last_event_time: int | None = None,
+        for_all: bool = True,
+    ) -> None:
+        """Удаляет чат.
+
+        Args:
+            chat_id: ID чата.
+            last_event_time: Время последнего события чата. Для объекта
+                ``Chat`` это поле ``Chat.last_event_time``.
+            for_all: Удалить чат для всех участников, если сервер поддерживает
+                такой режим.
+        """
+        await self._app.api.chats.delete_chat(
+            chat_id=chat_id,
+            last_event_time=last_event_time,
+            for_all=for_all,
+        )
+
     async def fetch_chats(self, marker: int | None = None) -> list[Chat]:
         """Загружает список чатов с сервера и обновляет кеш клиента.
 

pymax/infra/message.py

@@ -1,5 +1,5 @@
 from pymax.api.messages.enums import ItemType
-from pymax.api.messages.service import SendAttachment, SendAttachments
+from pymax.api.messages.service import SendAttachments
 from pymax.types import (
     FileRequest,
     Message,
@@ -62,6 +62,33 @@ class MessageMixin(IClientProtocol):
             message_id=message_id,
         )
 
+    async def forward_message(
+        self,
+        chat_id: int,
+        message_id: int | str,
+        source_chat_id: int | None = None,
+        *,
+        notify: bool = True,
+    ) -> Message | None:
+        """Пересылает существующее сообщение в чат.
+
+        Args:
+            chat_id: ID целевого чата.
+            message_id: ID пересылаемого сообщения.
+            source_chat_id: ID исходного чата. Если не указан, используется
+                целевой чат.
+            notify: Отправить ли получателям push-уведомление.
+
+        Returns:
+            Пересланное сообщение или ``None``, если сервер не вернул его.
+        """
+        return await self._app.api.messages.forward_message(
+            chat_id=chat_id,
+            message_id=message_id,
+            source_chat_id=source_chat_id,
+            notify=notify,
+        )
+
     async def get_messages(
         self,
         chat_id: int,
@@ -86,7 +113,6 @@ class MessageMixin(IClientProtocol):
         chat_id: int,
         message_id: int,
         text: str,
-        attachment: SendAttachment | None = None,
         attachments: SendAttachments = None,
     ) -> Message:
         """Редактирует текст и вложения сообщения.
@@ -95,9 +121,7 @@ class MessageMixin(IClientProtocol):
             chat_id: ID чата.
             message_id: ID сообщения.
             text: Новый текст сообщения с поддержкой markdown.
-            attachment: Одно новое вложение.
-            attachments: Список новых вложений. Имеет приоритет над
-                ``attachment``.
+            attachments: Новые файлы, фотографии или видео для сообщения.
 
         Returns:
             Отредактированное сообщение.
@@ -106,7 +130,6 @@ class MessageMixin(IClientProtocol):
             chat_id=chat_id,
             message_id=message_id,
             text=text,
-            attachment=attachment,
             attachments=attachments,
         )
 

pymax/infra/user.py

@@ -1,6 +1,6 @@
 from typing import Literal
 
-from pymax.types import Session, User
+from pymax.types import ContactInfo, Session, User
 
 from .protocol import IClientProtocol
 
@@ -94,6 +94,17 @@ class UserMixin(IClientProtocol):
         """
         return await self._app.api.users.remove_contact(contact_id)
 
+    async def import_contacts(self, contacts: list[ContactInfo]) -> list[User]:
+        """Импортирует контакты из телефонной книги.
+
+        Args:
+            contacts: Контакты с телефоном и именем.
+
+        Returns:
+            Контакты Max, найденные или созданные сервером.
+        """
+        return await self._app.api.users.import_contacts(contacts)
+
     def get_chat_id(self, first_user_id: int, second_user_id: int) -> int:
         """Вычисляет ID личного чата для пары пользователей.
 

pymax/protocol/tcp/compression.py

@@ -1,3 +1,8 @@
+from io import BytesIO
+
+import zstandard
+
+
 class Lz4BlockCompression:
     def decompress(self, src: bytes, max_output: int = 5 * 1024 * 1024) -> bytes:
         dst = bytearray()
@@ -95,3 +100,16 @@ class Lz4BlockCompression:
                 dst.extend(src[lit_start : lit_start + lit_len])
 
         return bytes(dst)
+
+
+class ZstdCompression:
+    def decompress(self, src: bytes, max_output: int = 5 * 1024 * 1024) -> bytes:
+        try:
+            with zstandard.ZstdDecompressor().stream_reader(BytesIO(src)) as reader:
+                result = reader.read(max_output + 1)
+        except zstandard.ZstdError as e:
+            raise ValueError("Zstd: failed to decompress payload") from e
+
+        if len(result) > max_output:
+            raise ValueError("Zstd: output too large")
+        return result

pymax/protocol/tcp/payload.py

@@ -5,7 +5,7 @@ import msgpack
 
 from pymax.logging import get_logger
 
-from .compression import Lz4BlockCompression
+from .compression import Lz4BlockCompression, ZstdCompression
 
 logger = get_logger(__name__)
 
@@ -70,9 +70,11 @@ class TcpPayloadDecoder:
         *,
         serializer: MsgpackPayloadCodec,
         compression: Lz4BlockCompression | None = None,
+        zstd_compression: ZstdCompression | None = None,
     ) -> None:
         self.serializer = serializer
         self.compression = compression
+        self.zstd_compression = zstd_compression
 
     def _normalize_keys(self, obj: Any) -> Any:
         if isinstance(obj, dict):
@@ -97,12 +99,26 @@ class TcpPayloadDecoder:
         if not payload_bytes:
             return {}
 
-        if flags & 0x03 and self.compression:
+        if flags == 0xFF:
+            if self.zstd_compression is None:
+                raise ValueError("Zstd-compressed TCP payload without a decoder")
+            try:
+                payload_bytes = self.zstd_compression.decompress(payload_bytes)
+                logger.debug("tcp payload decompressed with Zstd")
+            except ValueError:
+                logger.debug("tcp Zstd payload decompression failed", exc_info=True)
+                raise
+        elif flags > 0x7F:
+            raise ValueError(f"invalid TCP compression factor: {flags}")
+        elif flags > 0:
+            if self.compression is None:
+                raise ValueError("LZ4-compressed TCP payload without a decoder")
             try:
                 payload_bytes = self.compression.decompress(payload_bytes)
-                logger.debug("tcp payload decompressed flags=%s", flags)
+                logger.debug("tcp payload decompressed cof=%s", flags)
             except ValueError:
-                logger.debug("tcp payload decompress skipped flags=%s", flags)
+                logger.debug("tcp payload decompression failed cof=%s", flags, exc_info=True)
+                raise
 
         result = self.serializer.decode(payload_bytes)
         return self._normalize_keys(result)

pymax/protocol/tcp/protocol.py

@@ -7,6 +7,7 @@ from .payload import (
     Lz4BlockCompression,
     MsgpackPayloadCodec,
     TcpPayloadDecoder,
+    ZstdCompression,
 )
 
 logger = get_logger(__name__)
@@ -20,8 +21,11 @@ class TcpProtocol(BaseProtocol):
         self.framer = TcpPacketFramer()
         self.serializer = MsgpackPayloadCodec()
         self.compression = Lz4BlockCompression()
+        self.zstd_compression = ZstdCompression()
         self.payload_decoder = TcpPayloadDecoder(
-            serializer=self.serializer, compression=self.compression
+            serializer=self.serializer,
+            compression=self.compression,
+            zstd_compression=self.zstd_compression,
         )
 
     def encode(self, frame: OutboundFrame) -> bytes:

pymax/session/store.py

@@ -194,6 +194,17 @@ class SessionStore:
         await conn.commit()
         logger.info("session deleted")
 
+    async def delete_all_sessions(self) -> None:
+        conn = await self._get_connection()
+        logger.warning("deleting all sessions")
+        await conn.execute(
+            """
+            DELETE FROM sessions
+            """
+        )
+        await conn.commit()
+        logger.info("all sessions deleted")
+
     async def update_token(self, old_token: str, new_token: str) -> None:
         conn = await self._get_connection()
         logger.debug(

pymax/types/domain/__init__.py

@@ -11,4 +11,4 @@ from .presence import Presence
 from .profile import Profile
 from .session import Session
 from .sync import SyncOverrides, SyncState
-from .user import User
+from .user import ContactInfo, User

pymax/types/domain/chat.py

@@ -20,7 +20,7 @@ class Chat(CamelModel):
     Объекты чатов, полученные через клиент, обычно уже привязаны к сервисам
     сообщений и чатов. После этого можно вызывать удобные методы объекта:
     :meth:`answer`, :meth:`history`, :meth:`get_message`,
-    :meth:`get_messages`, :meth:`leave`, :meth:`invite`,
+    :meth:`get_messages`, :meth:`leave`, :meth:`delete`, :meth:`invite`,
     :meth:`remove_users`, :meth:`pin_message`, :meth:`update_settings` и
     :meth:`rework_invite_link`.
 
@@ -305,6 +305,26 @@ class Chat(CamelModel):
 
         raise ValueError("Unknown chat type=%s", self.type)
 
+    async def delete(self, *, for_all: bool = True) -> None:
+        """Удаляет этот чат.
+
+        Для ``last_event_time`` используется значение ``Chat.last_event_time``.
+
+        :param for_all: Удалить чат для всех участников, если сервер
+            поддерживает такой режим.
+        :type for_all: bool
+        :returns: ``None``.
+        :rtype: None
+        :raises RuntimeError: Если чат не привязан к клиенту.
+        """
+        _, chat_actions = self._bound()
+
+        return await chat_actions.delete_chat(
+            self.id,
+            last_event_time=self.last_event_time,
+            for_all=for_all,
+        )
+
     async def invite(
         self,
         user_ids: list[int],