maxapi-python 2.1.3__py3-none-any.whl → 2.3.0__py3-none-any.whl

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,14 +11,28 @@ 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
+    from pymax.types.events import (
+        MessageReadEvent,
+        PresenceEvent,
+        ReactionUpdateEvent,
+        TypingEvent,
+    )
+
+
+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],
@@ -41,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.
 
@@ -79,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,
@@ -139,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
@@ -186,6 +274,34 @@ class Router(Generic[ClientT]):
         """
         return self.on(EventType.MESSAGE_DELETE, *filters)
 
+    def on_message_read(
+        self,
+        *filters: FilterCallback[MessageReadEvent],
+    ) -> HandlerDecorator[MessageReadEvent, ClientT]:
+        """Регистрирует обработчик изменения отметки прочтения."""
+        return self.on(EventType.MESSAGE_READ, *filters)
+
+    def on_typing(
+        self,
+        *filters: FilterCallback[TypingEvent],
+    ) -> HandlerDecorator[TypingEvent, ClientT]:
+        """Регистрирует обработчик набора текста."""
+        return self.on(EventType.TYPING, *filters)
+
+    def on_presence(
+        self,
+        *filters: FilterCallback[PresenceEvent],
+    ) -> HandlerDecorator[PresenceEvent, ClientT]:
+        """Регистрирует обработчик изменения присутствия пользователя."""
+        return self.on(EventType.PRESENCE, *filters)
+
+    def on_reaction_update(
+        self,
+        *filters: FilterCallback[ReactionUpdateEvent],
+    ) -> HandlerDecorator[ReactionUpdateEvent, ClientT]:
+        """Регистрирует обработчик обновления реакций сообщения."""
+        return self.on(EventType.REACTION_UPDATE, *filters)
+
     def on_chat_update(
         self,
         *filters: FilterCallback[Chat],

pymax/formatting/markdown.py

@@ -2,6 +2,10 @@ from pymax.types.domain.element import Element, ElementAttributes
 
 
 class Formatter:
+    # Characters above this value are encoded as surrogate pairs in UTF-16,
+    # occupying 2 code units instead of 1.
+    BMP_MAX = 0xFFFF
+
     MARKERS = {
         "```": "CODE",
         "**": "STRONG",
@@ -14,6 +18,10 @@ class Formatter:
 
     MARKER_ORDER = ["```", "**", "__", "~~", "`", "_", "*"]
 
+    @staticmethod
+    def _code_units_len(text: str) -> int:
+        return len(text.encode("utf-16-le")) // 2
+
     @staticmethod
     def _parse_link(
         text: str,
@@ -64,15 +72,16 @@ class Formatter:
                 label, url, next_i = parsed_link
 
                 start = clean_pos
+                utf16_label_len = Formatter._code_units_len(label)
 
                 clean_text += label
-                clean_pos += len(label)
+                clean_pos += utf16_label_len
 
                 entities.append(
                     Element(
                         type="LINK",
                         from_=start,
-                        length=len(label),
+                        length=utf16_label_len,
                         attributes=ElementAttributes(url=url),
                     )
                 )
@@ -93,9 +102,10 @@ class Formatter:
                     start = clean_pos
 
                     while i < len(text) and text[i] != "\n":
-                        clean_text += text[i]
+                        ch = text[i]
+                        clean_text += ch
                         i += 1
-                        clean_pos += 1
+                        clean_pos += 2 if ord(ch) > Formatter.BMP_MAX else 1
 
                     length = clean_pos - start
 
@@ -123,9 +133,10 @@ class Formatter:
                 start = clean_pos
 
                 while i < len(text) and text[i] != "\n":
-                    clean_text += text[i]
+                    ch = text[i]
+                    clean_text += ch
                     i += 1
-                    clean_pos += 1
+                    clean_pos += 2 if ord(ch) > Formatter.BMP_MAX else 1
 
                 length = clean_pos - start
 
@@ -151,10 +162,7 @@ class Formatter:
                     if marker == "```":
                         closing_index = text.find(marker, i + marker_len)
 
-                        if (
-                            closing_index == -1
-                            or closing_index == i + marker_len
-                        ):
+                        if closing_index == -1 or closing_index == i + marker_len:
                             clean_text += marker
                             clean_pos += marker_len
                             i += marker_len
@@ -211,10 +219,11 @@ class Formatter:
                 line_start = False
                 continue
 
-            clean_text += text[i]
-            line_start = text[i] == "\n"
+            ch = text[i]
+            clean_text += ch
+            line_start = ch == "\n"
 
             i += 1
-            clean_pos += 1
+            clean_pos += 2 if ord(ch) > Formatter.BMP_MAX else 1
 
         return clean_text, entities

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]:
         """Загружает список чатов с сервера и обновляет кеш клиента.
 
@@ -339,3 +360,15 @@ class ChatMixin(IClientProtocol):
             chat_id=chat_id,
             user_id=user_id,
         )
+
+    async def join_channel(self, link: str) -> Chat:
+        """Вступает в канал по ссылке.
+
+        Args:
+            link: Полная ссылка на канал, invite-ссылка или ее часть с
+                join-токеном Max.
+
+        Returns:
+            Канал, в который вступил клиент.
+        """
+        return await self._app.api.chats.join_channel(link=link)

pymax/infra/message.py

@@ -43,6 +43,69 @@ class MessageMixin(IClientProtocol):
             notify=notify,
         )
 
+    async def get_message(
+        self,
+        chat_id: int,
+        message_id: int,
+    ) -> Message | None:
+        """Возвращает сообщение по ID.
+
+        Args:
+            chat_id: ID чата.
+            message_id: ID сообщения.
+
+        Returns:
+            Сообщение или ``None``, если сервер его не вернул.
+        """
+        return await self._app.api.messages.get_message(
+            chat_id=chat_id,
+            message_id=message_id,
+        )
+
+    async def get_messages(
+        self,
+        chat_id: int,
+        message_ids: list[int],
+    ) -> list[Message]:
+        """Возвращает сообщения по ID.
+
+        Args:
+            chat_id: ID чата.
+            message_ids: ID сообщений.
+
+        Returns:
+            Список найденных сообщений.
+        """
+        return await self._app.api.messages.get_messages(
+            chat_id=chat_id,
+            message_ids=message_ids,
+        )
+
+    async def edit_message(
+        self,
+        chat_id: int,
+        message_id: int,
+        text: str,
+        attachments: SendAttachments = None,
+    ) -> Message:
+        """Редактирует текст и вложения сообщения.
+
+        Args:
+            chat_id: ID чата.
+            message_id: ID сообщения.
+            text: Новый текст сообщения с поддержкой markdown.
+            attachments: Новые файлы, фотографии или видео для сообщения.
+
+        Returns:
+            Отредактированное сообщение.
+        """
+        return await self._app.api.messages.edit_message(
+            chat_id=chat_id,
+            message_id=message_id,
+            text=text,
+            attachments=attachments,
+        )
+
     async def fetch_history(
         self,
         chat_id: int,
@@ -236,11 +299,15 @@ class MessageMixin(IClientProtocol):
             message_id=message_id,
         )
 
-    async def read_message(self, message_id: int, chat_id: int) -> ReadState:
+    async def read_message(self, message_id: int | str, chat_id: int) -> ReadState:
         """Отмечает сообщение как прочитанное.
 
+        У Max различается wire-формат ``message_id`` для отметки прочтения:
+        TCP-клиент ожидает ``int``, WebSocket-клиент - ``str``.
+
         Args:
-            message_id: ID сообщения.
+            message_id: ID сообщения. Передавайте ``int`` для ``Client`` и
+                ``str`` для ``WebClient``.
             chat_id: ID чата.
 
         Returns:

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/logging.py

@@ -85,6 +85,8 @@ def configure_logging(
            configure_logging("DEBUG", use_colors=False)
     """
     stream = stream or sys.stderr
+    if stream is None:
+        raise RuntimeError("No logging stream is available")
 
     if use_colors is None:
         use_colors = hasattr(stream, "isatty") and stream.isatty()

pymax/protocol/tcp/compression.py

@@ -1,7 +1,5 @@
 class Lz4BlockCompression:
-    def decompress(
-        self, src: bytes, max_output: int = 5 * 1024 * 1024
-    ) -> bytes:
+    def decompress(self, src: bytes, max_output: int = 5 * 1024 * 1024) -> bytes:
         dst = bytearray()
         pos = 0
 

pymax/protocol/tcp/framing.py

@@ -31,9 +31,7 @@ class TcpPacketFramer:
         if len(data) < self.HEADER_SIZE:
             return None
 
-        ver, cmd, seq, opcode, packed_len = self.HEADER_STRUCT.unpack_from(
-            data, 0
-        )
+        ver, cmd, seq, opcode, packed_len = self.HEADER_STRUCT.unpack_from(data, 0)
         flags = (packed_len >> 24) & 0xFF
         payload_len = packed_len & 0x00FFFFFF
 

pymax/protocol/ws/protocol.py

@@ -20,14 +20,8 @@ class WsProtocol(BaseProtocol):
             data = json.loads(raw)
             return InboundFrame.model_validate(data)
         except json.JSONDecodeError:
-            logger.debug(
-                "failed to decode websocket frame json", exc_info=True
-            )
-            return InboundFrame(
-                opcode=0, cmd=0, seq=None, payload=None, raw=None
-            )
+            logger.debug("failed to decode websocket frame json", exc_info=True)
+            return InboundFrame(opcode=0, cmd=0, seq=None, payload=None, raw=None)
         except ValidationError:
             logger.debug("failed to validate websocket frame", exc_info=True)
-            return InboundFrame(
-                opcode=0, cmd=0, seq=None, payload=None, raw=None
-            )
+            return InboundFrame(opcode=0, cmd=0, seq=None, payload=None, raw=None)

pymax/session/protocol.py

@@ -8,11 +8,7 @@ class StoreProtocol(Protocol):
     async def save_session(self, session_info: SessionInfo) -> None: ...
     async def update_token(self, old_token: str, new_token: str) -> None: ...
     async def load_session(self) -> SessionInfo | None: ...
-    async def load_session_by_device_id(
-        self, device_id: str
-    ) -> SessionInfo | None: ...
-    async def load_session_by_phone(
-        self, phone: str
-    ) -> SessionInfo | None: ...
+    async def load_session_by_device_id(self, device_id: str) -> SessionInfo | None: ...
+    async def load_session_by_phone(self, phone: str) -> SessionInfo | None: ...
     async def delete_session(self, token: str) -> None: ...
     async def close(self) -> None: ...

pymax/session/store.py

@@ -55,24 +55,12 @@ class SessionStore:
             )
             """
         )
-        await self._ensure_column(
-            conn, "mt_instance_id", "TEXT NOT NULL DEFAULT ''"
-        )
-        await self._ensure_column(
-            conn, "chats_sync", "INTEGER NOT NULL DEFAULT -1"
-        )
-        await self._ensure_column(
-            conn, "contacts_sync", "INTEGER NOT NULL DEFAULT -1"
-        )
-        await self._ensure_column(
-            conn, "drafts_sync", "INTEGER NOT NULL DEFAULT -1"
-        )
-        await self._ensure_column(
-            conn, "presence_sync", "INTEGER NOT NULL DEFAULT -1"
-        )
-        await self._ensure_column(
-            conn, "config_hash", "TEXT NOT NULL DEFAULT ''"
-        )
+        await self._ensure_column(conn, "mt_instance_id", "TEXT NOT NULL DEFAULT ''")
+        await self._ensure_column(conn, "chats_sync", "INTEGER NOT NULL DEFAULT -1")
+        await self._ensure_column(conn, "contacts_sync", "INTEGER NOT NULL DEFAULT -1")
+        await self._ensure_column(conn, "drafts_sync", "INTEGER NOT NULL DEFAULT -1")
+        await self._ensure_column(conn, "presence_sync", "INTEGER NOT NULL DEFAULT -1")
+        await self._ensure_column(conn, "config_hash", "TEXT NOT NULL DEFAULT ''")
         await conn.execute(
             """
             UPDATE sessions
@@ -93,9 +81,7 @@ class SessionStore:
             columns = {row["name"] for row in await cursor.fetchall()}
 
         if name not in columns:
-            await conn.execute(
-                f"ALTER TABLE sessions ADD COLUMN {name} {definition}"
-            )
+            await conn.execute(f"ALTER TABLE sessions ADD COLUMN {name} {definition}")
 
     async def save_session(self, session_info: SessionInfo) -> None:
         conn = await self._get_connection()
@@ -158,9 +144,7 @@ class SessionStore:
         )
         return self._row_to_session(row)
 
-    async def load_session_by_device_id(
-        self, device_id: str
-    ) -> SessionInfo | None:
+    async def load_session_by_device_id(self, device_id: str) -> SessionInfo | None:
         conn = await self._get_connection()
         logger.debug("loading session by device_id=%s", device_id)
         async with conn.execute(
@@ -210,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/telemetry/navigation.py

@@ -155,9 +155,7 @@ class NavigationPlanner:
             self.current_screen = self.history.pop()
             return self.current_screen
 
-        next_screen = self._weighted_choice(
-            self.rules.graph[self.current_screen]
-        )
+        next_screen = self._weighted_choice(self.rules.graph[self.current_screen])
         if next_screen != self.current_screen:
             self.history.append(self.current_screen)
             if len(self.history) > 4:

pymax/telemetry/service.py

@@ -82,20 +82,14 @@ class TelemetryService:
     async def _run(self) -> None:
         try:
             await asyncio.sleep(self._between(self._timing.startup_delay))
-            await self._send_events(
-                [self._payloads.login(self._user_id, self._session_id)]
-            )
+            await self._send_events([self._payloads.login(self._user_id, self._session_id)])
 
             while True:
                 self._session_id += 1
-                events = await self._collect_session_events(
-                    self._planner.new_profile()
-                )
+                events = await self._collect_session_events(self._planner.new_profile())
                 await self._send_events(events)
                 self._planner.reset_to_background()
-                await asyncio.sleep(
-                    self._between(self._timing.session_idle_delay)
-                )
+                await asyncio.sleep(self._between(self._timing.session_idle_delay))
 
         except asyncio.CancelledError:
             raise
@@ -163,9 +157,7 @@ class TelemetryService:
         except Exception:
             logger.debug("telemetry send failed", exc_info=True)
 
-    def _nav_event(
-        self, screen_from: Screen, screen_to: Screen
-    ) -> TelemetryEvent:
+    def _nav_event(self, screen_from: Screen, screen_to: Screen) -> TelemetryEvent:
         event = self._payloads.navigation(
             user_id=self._user_id,
             session_id=self._session_id,
@@ -212,11 +204,7 @@ class TelemetryService:
 
     @property
     def _ready(self) -> bool:
-        return (
-            self.app.started
-            and self.app.me is not None
-            and self.app.connection.is_open
-        )
+        return self.app.started and self.app.me is not None and self.app.connection.is_open
 
     @property
     def _user_id(self) -> int:

pymax/transport/tcp.py

@@ -10,9 +10,7 @@ logger = get_logger(__name__)
 
 
 class TCPTransport(Transport):
-    def __init__(
-        self, host: str, port: int, proxy: str | None, use_ssl: bool = True
-    ) -> None:
+    def __init__(self, host: str, port: int, proxy: str | None, use_ssl: bool = True) -> None:
         self._host = host
         self._port = port
         self._proxy = proxy

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/attachments/unknown.py

@@ -30,8 +30,6 @@ class UnknownAttachment(CamelModel):
 
         attachment_type = value.get("_type", value.get("type"))
         if attachment_type in KNOWN_ATTACHMENT_TYPES:
-            raise ValueError(
-                "Known attachment type should be parsed by its own model"
-            )
+            raise ValueError("Known attachment type should be parsed by its own model")
 
         return value