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

pymax/app.py

@@ -9,11 +9,12 @@ from pymax.dispatch import Dispatcher
 from pymax.dispatch.router import EventType, Router
 from pymax.exceptions import ApiError
 from pymax.fingerprint import FingerprintGenerator
+from pymax.fsm import InMemoryFSMStorage
 from pymax.logging import get_logger
 from pymax.protocol import Command, InboundFrame, OutboundFrame
 from pymax.protocol.enums import Opcode
-from pymax.session import SessionStore
-from pymax.session.models import SessionInfo
+from pymax.session import InMemoryStore, SessionStore
+from pymax.session.models import SessionInfo, resolve_session_user_agent
 from pymax.telemetry import TelemetryService
 from pymax.types import MaxApiError, Message
 from pymax.types.domain import Chat, HandshakeResponse, Login2Response, Profile, User
@@ -38,9 +39,16 @@ class App(Generic[ClientT]):
         self.dispatcher: Dispatcher[ClientT] = Dispatcher(self, root_router)
         self.api = ApiFacade(self)
         self.config = config
-        self.store = self.config.store or SessionStore(config.work_dir, config.session_name)
+        self.store = (
+            (self.config.store or SessionStore(config.work_dir, config.session_name))
+            if self.config.persist_session
+            else InMemoryStore()
+        )
+        self.fsm_storage: InMemoryFSMStorage = InMemoryFSMStorage()
         self.auth_flow = auth_flow
-        self.fingerprint_generator = FingerprintGenerator()
+        self.fingerprint_generator: FingerprintGenerator | None = (
+            FingerprintGenerator(self.config.fingering) if self.config.fingering else None
+        )
 
         self.me: Profile | None = None
         self.chats: list[Chat] | None = None
@@ -51,7 +59,7 @@ class App(Generic[ClientT]):
         self.session: SessionInfo | None = None
         self.handshake_response: HandshakeResponse | None = None
 
-        self.started = False
+        self.started: bool = False
         self._ping_task: asyncio.Task[None] | None = None
         self._telemetry = TelemetryService(self) if config.telemetry else None
 
@@ -77,6 +85,17 @@ class App(Generic[ClientT]):
             else:
                 session_data.mt_instance_id = self.config.device.mt_instance_id
 
+            if self.config.restore_user_agent_from_session:
+                user_agent = resolve_session_user_agent(
+                    self.config.device.user_agent,
+                    session_data.user_agent,
+                )
+            else:
+                user_agent = self.config.device.user_agent
+            self.config.device.user_agent = user_agent
+            if session_data.user_agent != user_agent:
+                session_data = session_data.model_copy(update={"user_agent": user_agent})
+
         try:
             logger.debug("opening connection")
             await self.connection.open()
@@ -105,6 +124,7 @@ class App(Generic[ClientT]):
                         device_id=self.config.device.device_id,
                         phone=self.config.phone or "",
                         mt_instance_id=self.config.device.mt_instance_id,
+                        user_agent=self.config.device.user_agent,
                     )
                 )
             else:
@@ -120,6 +140,7 @@ class App(Generic[ClientT]):
                         device_id=self.config.device.device_id,
                         phone=self.config.phone or "",
                         mt_instance_id=self.config.device.mt_instance_id,
+                        user_agent=self.config.device.user_agent,
                     )
                 )
                 logger.info("new session saved")
@@ -167,7 +188,7 @@ class App(Generic[ClientT]):
             if not handled:
                 raise
 
-            await self.close()
+            await self.disconnect()
             return
 
         if login_response.token is not None and login_response.token != self.session.token:
@@ -189,6 +210,7 @@ class App(Generic[ClientT]):
         self.messages = login_response.messages
 
         self.started = True
+
         logger.info(
             "client started profile=%s chats=%s",
             self.me.contact.id,
@@ -230,7 +252,7 @@ class App(Generic[ClientT]):
         logger.debug("handshake completed device_id=%s", device_id)
         return response
 
-    async def close(self) -> None:
+    async def disconnect(self) -> None:
         if self._telemetry:
             await self._telemetry.stop()
 
@@ -239,6 +261,7 @@ class App(Generic[ClientT]):
             self._ping_task = None
             if not task.done():
                 task.cancel()
+
             try:
                 await task
             except asyncio.CancelledError:
@@ -248,10 +271,13 @@ class App(Generic[ClientT]):
 
         await self.dispatcher.stop_startup_tasks()
         await self.connection.close()
-        await self.store.close()
 
         self.started = False
 
+    async def close(self):
+        await self.disconnect()
+        await self.store.close()
+
     async def invoke(
         self,
         opcode: int,
@@ -355,6 +381,11 @@ class App(Generic[ClientT]):
         )
         return exc
 
+    def bind_connection(self, connection: ConnectionManager) -> None:
+        self.connection = connection
+        self.connection.on_event = self.on_event
+        self.connection.on_close = self.on_connection_lost
+
     async def on_event(self, frame: InboundFrame) -> None:
         logger.debug(
             "event received opcode=%s cmd=%s seq=%s",

pymax/auth/__init__.py

@@ -1,4 +1,5 @@
 from .base import AuthFlow
+from .exceptions import PasswordAttemptsExceededError
 from .providers import (
     ConsolePasswordProvider,
     ConsoleQrHandler,
@@ -17,6 +18,7 @@ __all__ = (
     "ConsoleQrHandler",
     "ConsoleSmsCodeProvider",
     "EmailCodeProvider",
+    "PasswordAttemptsExceededError",
     "PasswordProvider",
     "QrAuthFlow",
     "QrHandler",

pymax/auth/exceptions.py

@@ -0,0 +1,9 @@
+class PasswordAttemptsExceededError(Exception):
+    """Исчерпан лимит попыток ввода пароля 2FA.
+
+    Наследуется напрямую от ``Exception`` и не перехватывается как
+    ``PyMaxError``.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("2FA password attempts exhausted")

pymax/auth/providers.py

@@ -113,7 +113,11 @@ class EmailCodeProvider(Protocol):
 
 
 class ConsoleEmailCodeProvider:
-    """Консольный provider кода подтверждения email для 2FA."""
+    """Консольный provider кода подтверждения email для 2FA.
+
+    Блокирующий ``input()`` выполняется в worker thread и не останавливает
+    asyncio event loop.
+    """
 
     async def get_code(self, email: str) -> str:
         """Запрашивает email-код в консоли.
@@ -124,4 +128,4 @@ class ConsoleEmailCodeProvider:
         Returns:
             Введенный пользователем код.
         """
-        return input(f"Enter 2FA email code for {email}: ").strip()
+        return (await asyncio.to_thread(input, f"Enter 2FA email code for {email}: ")).strip()

pymax/auth/qr.py

@@ -5,6 +5,7 @@ import time
 from typing import TYPE_CHECKING
 
 from pymax.auth.base import AuthFlow
+from pymax.auth.exceptions import PasswordAttemptsExceededError
 from pymax.exceptions import ApiError
 from pymax.logging import get_logger
 
@@ -107,7 +108,10 @@ class QrAuthFlow(AuthFlow):
         hint: str | None,
     ) -> str:
         logger.info("starting 2fa password authentication")
-        while True:
+        attempt = 0
+        while (
+            app.config.password_max_attempts is None or app.config.password_max_attempts > attempt
+        ):
             password = await self.password_provider.get_password(hint)
             logger.debug(
                 "2fa password provider returned password_set=%s",
@@ -115,16 +119,19 @@ class QrAuthFlow(AuthFlow):
             )
             if not password:
                 logger.warning("2fa password is empty; retrying")
+                attempt += 1
                 continue
 
             try:
                 response = await app.api.auth.check_password(track_id, password)
             except ApiError as e:
                 logger.error("2fa password check failed: %s", e)
+                attempt += 1
                 continue
 
             if response.error:
                 logger.error("2fa password check failed error=%s", response.error)
+                attempt += 1
                 continue
 
             if response.login_token:
@@ -132,3 +139,6 @@ class QrAuthFlow(AuthFlow):
                 return response.login_token
 
             logger.error("2fa password response did not contain login token; retrying")
+            attempt += 1
+
+        raise PasswordAttemptsExceededError

pymax/auth/sms.py

@@ -6,6 +6,7 @@ from pymax.auth.base import AuthFlow
 from pymax.exceptions import ApiError
 from pymax.logging import get_logger
 
+from .exceptions import PasswordAttemptsExceededError
 from .models import AuthResult
 from .providers import (
     ConsolePasswordProvider,
@@ -116,7 +117,10 @@ class SmsAuthFlow(AuthFlow):
         hint: str | None,
     ) -> str:
         logger.info("starting 2fa password authentication")
-        while True:
+        attempt = 0
+        while (
+            app.config.password_max_attempts is None or app.config.password_max_attempts > attempt
+        ):
             password = await self.password_provider.get_password(hint)
             logger.debug(
                 "2fa password provider returned password_set=%s",
@@ -124,16 +128,19 @@ class SmsAuthFlow(AuthFlow):
             )
             if not password:
                 logger.warning("2fa password is empty; retrying")
+                attempt += 1
                 continue
 
             try:
                 response = await app.api.auth.check_password(track_id, password)
             except ApiError as e:
                 logger.error("2fa password check failed: %s", e)
+                attempt += 1
                 continue
 
             if response.error:
                 logger.error("2fa password check failed error=%s", response.error)
+                attempt += 1
                 continue
 
             if response.login_token:
@@ -141,3 +148,6 @@ class SmsAuthFlow(AuthFlow):
                 return response.login_token
 
             logger.error("2fa password response did not contain login token; retrying")
+            attempt += 1
+
+        raise PasswordAttemptsExceededError

pymax/base.py

@@ -3,23 +3,23 @@ from __future__ import annotations
 import asyncio
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
-from uuid import uuid4
 
-from pymax.dispatch import ErrorScope, Router
+from pymax.dispatch import ErrorScope, Middleware, Router
 from pymax.dispatch.router import DisconnectDecorator, ErrorDecorator
 from pymax.exceptions import ApiError
+from pymax.filters import Filter
+from pymax.fingerprint.models import ApkBuildFingerprint
 from pymax.infra import BaseMixin
 from pymax.logging import get_logger
 
 from .app import App
-from .config import ClientConfig, DeviceConfig, ExtraConfig
+from .config import ClientConfig, DeviceConfig, ExtraConfig, generate_device_id
 
 if TYPE_CHECKING:
     from pymax.api.session.payloads import MobileUserAgentPayload
     from pymax.auth import AuthFlow
     from pymax.connection import ConnectionManager
     from pymax.dispatch.router import (
-        FilterCallback,
         HandlerDecorator,
         StartDecorator,
     )
@@ -30,6 +30,7 @@ if TYPE_CHECKING:
         MessageReadEvent,
         PresenceEvent,
         ReactionUpdateEvent,
+        StoryPreview,
         TypingEvent,
         User,
     )
@@ -47,11 +48,21 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
     _connection: ConnectionManager
     _auth_flow: AuthFlow
     _router: Router[ClientT]
-    _app: App[ClientT]
+    __app: App[ClientT] | None = None
+
+    @property
+    def _app(self) -> App[ClientT]:
+        if self.__app is None:
+            raise RuntimeError("Client runtime is not initialized")
+        return self.__app
+
+    @_app.setter
+    def _app(self, value: App[ClientT]) -> None:
+        self.__app = value
 
     @property
     def me(self) -> Profile | None:
-        """Профиль текущего аккаунта после успешного ``start``."""
+        """Профиль текущего аккаунта после успешного login."""
         return self._app.me
 
     @property
@@ -69,11 +80,17 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
         """Сообщения, которые Max вернул на login/sync."""
         return self._app.messages
 
+    @property
+    def is_connected(self) -> bool:
+        return self.__app is not None and self.__app.connection.is_open
+
     def _build_config(
         self,
         *,
         phone: str | None,
         user_agent: MobileUserAgentPayload,
+        version: str | None,
+        fingerprint: ApkBuildFingerprint | None,
     ) -> ClientConfig:
         logger.debug(
             "building client config token_set=%s",
@@ -94,9 +111,15 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
             store=self.extra_config.store,
             proxy=self.extra_config.proxy,
             registration_config=self.extra_config.registration_config,
+            upload_timeout=self.extra_config.upload_timeout,
+            password_max_attempts=self.extra_config.password_max_attempts,
+            relogin=self.extra_config.relogin,
+            app_version=version,
+            fingering=fingerprint,
+            persist_session=self.extra_config.persist_session,
             device=DeviceConfig(
                 mt_instance_id=self.extra_config.mt_instance_id,
-                device_id=self.extra_config.device_id or str(uuid4()),
+                device_id=self.extra_config.device_id or generate_device_id(),
                 user_agent=user_agent,
             ),
         )
@@ -105,6 +128,23 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
     def _build_connection(self) -> ConnectionManager:
         raise NotImplementedError
 
+    @abstractmethod
+    async def _prepare_config(self) -> ClientConfig:
+        raise NotImplementedError
+
+    async def _ensure_runtime(self: ClientT) -> None:  # noqa: PYI019
+        if getattr(self, "_config", None) is None:
+            self._config = await self._prepare_config()
+
+        if self.__app is not None and self.__app.connection.is_open:
+            return
+
+        self._connection = self._build_connection()
+        if self.__app is not None:
+            self._app.bind_connection(self._connection)
+        else:
+            self._app = self._build_app()
+
     def _init_runtime(self: ClientT, *, auth_flow: AuthFlow) -> None:  # noqa: PYI019
         self._connection = self._build_connection()
         self._auth_flow = auth_flow
@@ -121,38 +161,94 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
         app.dispatcher.bind_client(self)
         return app
 
-    def _reset_runtime(self: ClientT) -> None:  # noqa: PYI019
+    def _reset_connection(self: ClientT) -> None:  # noqa: PYI019
         self._connection = self._build_connection()
-        self._app = self._build_app()
+        self._app.bind_connection(self._connection)
+        # self._app = self._build_app()
+
+    async def connect(self: ClientT) -> None:  # noqa: PYI019
+        """Подключает клиента один раз и запускает ``on_start``-обработчики.
+
+        Обработчики старта выполняются в отдельных задачах; метод не ждет
+        их завершения. После возврата соединение остается открытым. В отличие от
+        :meth:`start`, метод не ожидает закрытия соединения и не запускает
+        reconnect loop; завершите работу через :meth:`stop` или :meth:`close`.
+        """
+        try:
+            await self._ensure_runtime()
+            await self._app.start()
+            if not self._app.started:
+                await self.close()
+                return
+
+            await self._app.dispatcher.emit_start(self)
+        except asyncio.CancelledError:
+            await self.close()
+            raise
+        except (ConnectionError, EOFError, OSError, TimeoutError, ApiError) as e:
+            if self.__app is None:
+                raise
+
+            await self.close()
+
+            await self._app.dispatcher.emit_disconnect(
+                e,
+                self.extra_config.reconnect,
+                self.extra_config.reconnect_delay,
+            )
+            raise
+        except Exception:
+            await self.close()
+            raise
 
     async def start(self: ClientT) -> None:  # noqa: PYI019
-        """Запускает клиента и слушает события до закрытия соединения."""
+        """Запускает клиента и слушает события до закрытия соединения.
+
+        При сетевых ошибках повторяет подключение, если ``reconnect=True``.
+        Отозванный login token автоматически сбрасывается при ``relogin=True``.
+        Если новый token тоже отклонен, ошибка передается вызывающему коду.
+        """
+        relogin_attempted = False
         while True:
             try:
+                await self._ensure_runtime()
                 await self._app.start()
                 if not self._app.started:
                     await self.close()
                     return
 
+                relogin_attempted = False
                 await self._app.dispatcher.emit_start(self)
                 await self._connection.wait_closed()
             except asyncio.CancelledError:
                 await self.close()
                 raise
             except ApiError as e:
-                if not self._app._is_invalid_login_token_error(e):
+                if (
+                    not self._app._is_invalid_login_token_error(e)
+                    or not self.extra_config.relogin
+                    or relogin_attempted
+                ):
                     await self.close()
                     raise
 
                 logger.warning("login token was revoked; starting authentication again")
+                relogin_attempted = True
                 await self.relogin(start=False)
-            except (  # noqa: PERF203
+            except (
                 ConnectionError,
                 EOFError,
                 OSError,
                 TimeoutError,
             ) as e:
-                await self.close()
+                if self.__app is None:
+                    raise
+
+                if self.extra_config.reconnect:
+                    await self._app.disconnect()
+                else:
+                    await self.close()
+
                 await self._app.dispatcher.emit_disconnect(
                     e,
                     self.extra_config.reconnect,
@@ -168,7 +264,7 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
                     exc_info=True,
                 )
                 await asyncio.sleep(self.extra_config.reconnect_delay)
-                self._reset_runtime()
+                self._reset_connection()
             except Exception:
                 await self.close()
                 raise
@@ -178,7 +274,10 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
 
     async def close(self) -> None:
         """Закрывает соединение, фоновые задачи и файл сессии."""
-        await self._app.close()
+        if self.__app is None:
+            return
+
+        await self.__app.close()
 
     async def stop(self) -> None:
         """Останавливает клиента."""
@@ -196,63 +295,70 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
 
     def on_message(
         self,
-        *filters: FilterCallback[Message],
+        *filters: Filter[Message, ClientT],
     ) -> HandlerDecorator[Message, ClientT]:
         """Регистрирует обработчик новых сообщений."""
         return self._router.on_message(*filters)
 
     def on_message_edit(
         self,
-        *filters: FilterCallback[Message],
+        *filters: Filter[Message, ClientT],
     ) -> HandlerDecorator[Message, ClientT]:
         """Регистрирует обработчик редактирования сообщений."""
         return self._router.on_message_edit(*filters)
 
     def on_message_delete(
         self,
-        *filters: FilterCallback[MessageDeleteEvent],
+        *filters: Filter[MessageDeleteEvent, ClientT],
     ) -> HandlerDecorator[MessageDeleteEvent, ClientT]:
         """Регистрирует обработчик удаления сообщений."""
         return self._router.on_message_delete(*filters)
 
     def on_message_read(
         self,
-        *filters: FilterCallback[MessageReadEvent],
+        *filters: Filter[MessageReadEvent, ClientT],
     ) -> HandlerDecorator[MessageReadEvent, ClientT]:
         """Регистрирует обработчик изменения отметки прочтения."""
         return self._router.on_message_read(*filters)
 
     def on_typing(
         self,
-        *filters: FilterCallback[TypingEvent],
+        *filters: Filter[TypingEvent, ClientT],
     ) -> HandlerDecorator[TypingEvent, ClientT]:
         """Регистрирует обработчик набора текста."""
         return self._router.on_typing(*filters)
 
     def on_presence(
         self,
-        *filters: FilterCallback[PresenceEvent],
+        *filters: Filter[PresenceEvent, ClientT],
     ) -> HandlerDecorator[PresenceEvent, ClientT]:
         """Регистрирует обработчик изменения присутствия пользователя."""
         return self._router.on_presence(*filters)
 
     def on_reaction_update(
         self,
-        *filters: FilterCallback[ReactionUpdateEvent],
+        *filters: Filter[ReactionUpdateEvent, ClientT],
     ) -> HandlerDecorator[ReactionUpdateEvent, ClientT]:
         """Регистрирует обработчик обновления реакций сообщения."""
         return self._router.on_reaction_update(*filters)
 
     def on_chat_update(
         self,
-        *filters: FilterCallback[Chat],
+        *filters: Filter[Chat, ClientT],
     ) -> HandlerDecorator[Chat, ClientT]:
         """Регистрирует обработчик обновления чата."""
         return self._router.on_chat_update(*filters)
 
+    def on_story_update(
+        self,
+        *filters: Filter[StoryPreview, ClientT],
+    ) -> HandlerDecorator[StoryPreview, ClientT]:
+        """Регистрирует обработчик обновления превью сторис владельца."""
+        return self._router.on_story_update(*filters)
+
     def on_raw(
         self,
-        *filters: FilterCallback[InboundFrame],
+        *filters: Filter[InboundFrame, ClientT],
     ) -> HandlerDecorator[InboundFrame, ClientT]:
         """Регистрирует обработчик исходных входящих frame-ов."""
         return self._router.on_raw(*filters)
@@ -269,12 +375,23 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
         """Подключает дочерний router к root router клиента."""
         self._router.include_router(router)
 
+    def add_middleware(self, middleware: Middleware[ClientT]) -> None:
+        """Добавляет middleware в цепочку обработчиков клиента.
+
+        Middleware вызываются в порядке регистрации после проверки фильтров.
+        Регистрация доступна до запуска клиента и сохраняется при reconnect.
+        """
+        if middleware not in self._router.middlewares:
+            self._router.middlewares.append(middleware)
+        else:
+            logger.warning(f"Middleware {middleware.__class__.__name__} is already registered")
+
     async def relogin(self: ClientT, drop_config_token: bool = True, start: bool = True) -> None:  # noqa: PYI019
         """Удаляет текущую локальную сессию и запускает авторизацию заново.
 
         Args:
             drop_config_token: Сбросить token, переданный через ``ExtraConfig``.
-            start: Сразу запустить клиента после сброса runtime.
+            start: Сразу запустить клиента после сброса сессии.
         """
         store = self._app.store
         session = self._app.session
@@ -283,13 +400,15 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
             raise RuntimeError("Cannot relogin before session is loaded")
 
         await store.delete_session(session.token)
-        await self.close()
+        await self._app.disconnect()
 
         if drop_config_token:
             self.extra_config.token = None
             self._config.token = None
 
-        self._reset_runtime()
+        self._reset_connection()
+
+        self._app.session = None
 
         if start:
             await self.start()