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

pymax/base.py

@@ -3,16 +3,16 @@ 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.router import DisconnectDecorator, ErrorDecorator
 from pymax.exceptions import ApiError
+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
@@ -47,11 +47,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 +79,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,17 +110,38 @@ 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,
             ),
         )
 
     @abstractmethod
     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()
+        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
@@ -125,10 +162,43 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
         self._connection = self._build_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:
+            await self.close()
+
+            await self._app.dispatcher.emit_disconnect(
+                e,
+                self.extra_config.reconnect,
+                self.extra_config.reconnect_delay,
+            )
+            raise
+
     async def start(self: ClientT) -> None:  # noqa: PYI019
-        """Запускает клиента и слушает события до закрытия соединения."""
+        """Запускает клиента и слушает события до закрытия соединения.
+
+        При сетевых ошибках повторяет подключение, если ``reconnect=True``.
+        Отозванный login token автоматически сбрасывается при ``relogin=True``.
+        """
         while True:
             try:
+                await self._ensure_runtime()
                 await self._app.start()
                 if not self._app.started:
                     await self.close()
@@ -145,8 +215,9 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
                     raise
 
                 logger.warning("login token was revoked; starting authentication again")
-                await self.relogin(start=False)
-            except (  # noqa: PERF203
+                if self.extra_config.relogin:
+                    await self.relogin(start=False)
+            except (
                 ConnectionError,
                 EOFError,
                 OSError,
@@ -178,7 +249,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:
         """Останавливает клиента."""

pymax/client.py

@@ -7,12 +7,15 @@ from pymax.auth import (
     SmsAuthFlow,
     SmsCodeProvider,
 )
+from pymax.config import ClientConfig
 from pymax.connection import ConnectionManager
 from pymax.connection.readers import TCPReader
+from pymax.dispatch import Router
 from pymax.logging import configure_logging, get_logger
 from pymax.protocol.tcp import TcpProtocol
 from pymax.protocol.tcp.framing import TcpPacketFramer
 from pymax.transport.tcp import TCPTransport
+from pymax.versions.catalog import VersionCatalog
 
 from .base import BaseClient
 from .config import ExtraConfig
@@ -37,6 +40,15 @@ class Client(BaseClient["Client"]):
         auth_flow: Полностью пользовательский сценарий авторизации.
         sms_code_provider: Провайдер SMS-кода для стандартного ``SmsAuthFlow``.
         password_provider: Провайдер пароля 2FA, если аккаунт его требует.
+        app_version: Версия Android-клиента для user-agent и fingerprint.
+            По умолчанию используется ``VersionCatalog.recommended()``.
+        catalog: Каталог fingerprints. Если не передан, используется
+            встроенный каталог. Каталог и версия разрешаются при
+            :meth:`connect` или :meth:`start`.
+
+    Raises:
+        VersionNotFoundError: При запуске, если ``app_version`` отсутствует в
+            итоговом каталоге.
     """
 
     def __init__(  # noqa: PLR0913
@@ -48,12 +60,16 @@ class Client(BaseClient["Client"]):
         auth_flow: AuthFlow | None = None,
         sms_code_provider: SmsCodeProvider | None = None,
         password_provider: PasswordProvider | None = None,
+        app_version: str = VersionCatalog.RECOMMENDED_APP_VERSION,
+        catalog: VersionCatalog | None = None,
     ) -> None:
 
-        self.phone = phone
-        self.extra_config = extra_config or ExtraConfig()
-        self.session_name = session_name
-        self.work_dir = work_dir
+        self.phone: str = phone
+        self.extra_config: ExtraConfig = extra_config or ExtraConfig()
+        self.session_name: str = session_name
+        self.work_dir: str = work_dir
+        self.app_version: str = app_version
+        self.catalog: VersionCatalog = catalog or VersionCatalog()
 
         configure_logging(self.extra_config.log_level)
         logger.debug(
@@ -65,17 +81,13 @@ class Client(BaseClient["Client"]):
             self.extra_config.reconnect,
         )
 
-        self._config = self._build_config(
-            phone=phone,
-            user_agent=(self.extra_config.user_agent or self.extra_config.generate_user_agent()),
-        )
-
         if auth_flow is None:
             auth_flow = SmsAuthFlow(
                 sms_code_provider or ConsoleSmsCodeProvider(),
                 password_provider,
             )
-        self._init_runtime(auth_flow=auth_flow)
+        self._auth_flow = auth_flow
+        self._router = Router()
 
         logger.debug(
             "client created transport=tcp host=%s port=%s",
@@ -83,6 +95,23 @@ class Client(BaseClient["Client"]):
             self.extra_config.port,
         )
 
+    async def _prepare_config(self) -> ClientConfig:
+        catalog = await self.catalog.load()
+        fingerprint = catalog.resolve(self.app_version)
+
+        user_agent = self.extra_config.user_agent or self.extra_config.generate_user_agent(
+            self.app_version, fingerprint.build_number
+        )
+
+        config = self._build_config(
+            phone=self.phone,
+            user_agent=user_agent,
+            version=self.app_version,
+            fingerprint=fingerprint,
+        )
+        config.restore_user_agent_from_session = self.extra_config.user_agent is None
+        return config
+
     def _build_connection(self) -> ConnectionManager:
         logger.debug(
             "building tcp connection host=%s port=%s ssl=%s",

pymax/client_web.py

@@ -5,12 +5,13 @@ from pymax.auth.providers import ConsoleQrHandler, QrHandler
 from pymax.auth.qr import QrAuthFlow
 from pymax.connection import ConnectionManager
 from pymax.connection.readers import WSReader
+from pymax.dispatch import Router
 from pymax.logging import configure_logging, get_logger
 from pymax.protocol.tcp import TcpProtocol
 from pymax.transport.websocket import WebSocketTransport
 
 from .base import BaseClient
-from .config import ExtraConfig
+from .config import ClientConfig, ExtraConfig
 
 logger = get_logger(__name__)
 
@@ -38,9 +39,9 @@ class WebClient(BaseClient["WebClient"]):
         auth_flow: AuthFlow | None = None,
         qr_provider: QrHandler | None = None,
     ) -> None:
-        self.extra_config = extra_config or ExtraConfig()
-        self.session_name = session_name
-        self.work_dir = work_dir
+        self.extra_config: ExtraConfig = extra_config or ExtraConfig()
+        self.session_name: str = session_name
+        self.work_dir: str = work_dir
 
         configure_logging(self.extra_config.log_level)
         logger.debug(
@@ -51,22 +52,24 @@ class WebClient(BaseClient["WebClient"]):
             self.extra_config.reconnect,
         )
 
-        self._config = self._build_config(
-            phone=None,
-            user_agent=(
-                self.extra_config.user_agent or self.extra_config.generate_web_user_agent()
-            ),
-        )
-
         if auth_flow is None:
             auth_flow = QrAuthFlow(qr_provider or ConsoleQrHandler())
-        self._init_runtime(auth_flow=auth_flow)
+        self._auth_flow = auth_flow
+        self._router = Router()
 
         logger.debug(
             "web client created transport=ws url=%s",
             self.extra_config.url,
         )
 
+    async def _prepare_config(self) -> ClientConfig:
+        user_agent = self.extra_config.user_agent or self.extra_config.generate_web_user_agent()
+        config = self._build_config(
+            phone=None, user_agent=user_agent, version=None, fingerprint=None
+        )
+        config.restore_user_agent_from_session = self.extra_config.user_agent is None
+        return config
+
     def _build_connection(self) -> ConnectionManager:
         logger.debug(
             "building websocket connection url=%s",

pymax/config.py

@@ -1,5 +1,5 @@
-from random import choice, randint, random
-from uuid import uuid4
+import secrets
+from random import choice, randint
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -8,8 +8,10 @@ from pymax.api.session.payloads import (
     DEFAULT_WEB_HEADER_USER_AGENT,
     MobileUserAgentPayload,
 )
+from pymax.fingerprint.models import ApkBuildFingerprint
 from pymax.session import StoreProtocol
 from pymax.types.domain.sync import SyncOverrides
+from pymax.versions.catalog import VersionCatalog
 
 MIN_PREFERRED_BUILD = 6712
 APP_VERSIONS: tuple[tuple[str, int], ...] = (
@@ -47,12 +49,12 @@ APP_VERSIONS: tuple[tuple[str, int], ...] = (
     ("26.12.2", 6681),
     ("26.12.1", 6679),
     ("26.12.0", 6676),
-    ("26.11.3", 6670),
-    ("26.11.2", 6669),
-    ("26.11.1", 6665),
-    ("26.10.1", 6653),
-    ("26.10.0", 6648),
-    ("26.9.1", 6643),
+    # ("26.11.3", 6670), # Not supported TODO: delete maybe
+    # ("26.11.2", 6669),
+    # ("26.11.1", 6665),
+    # ("26.10.1", 6653),
+    # ("26.10.0", 6648),
+    # ("26.9.1", 6643),
 )
 ANDROID_DEVICES: tuple[tuple[str, str, str, str], ...] = (
     ("Samsung SM-A525F", "Android 13", "405dpi 405dpi 1080x2400", "arm64-v8a"),
@@ -104,17 +106,21 @@ LOCALE_TIMEZONES: tuple[tuple[str, str], ...] = (
     ("ru", "Asia/Yakutsk"),
     ("ru", "Asia/Vladivostok"),
 )
-WEB_APP_VERSION = "26.7.15"
+WEB_APP_VERSION = "26.8.4"
 WEB_SCREEN = "1080x1920 1.0x"
 
 PREFERRED_VERSION = [version for version in APP_VERSIONS if version[1] >= MIN_PREFERRED_BUILD]
 LEGACY_VERSIONS = [version for version in APP_VERSIONS if version[1] < MIN_PREFERRED_BUILD]
 
 
+def generate_device_id() -> str:
+    return secrets.token_hex(8)
+
+
 class DeviceConfig(BaseModel):
     mt_instance_id: str
     user_agent: MobileUserAgentPayload
-    device_id: str = Field(default_factory=lambda: str(uuid4()))
+    device_id: str = Field(default_factory=generate_device_id)
     client_session_id: int = Field(default_factory=lambda: randint(1, 70))
 
 
@@ -136,6 +142,9 @@ class RegistrationConfig(BaseModel):
 class ClientConfig(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
+    app_version: str | None = VersionCatalog.RECOMMENDED_APP_VERSION
+    fingering: ApkBuildFingerprint | None
+
     phone: str | None = None
     work_dir: str = "."
     session_name: str = "session.db"
@@ -143,17 +152,21 @@ class ClientConfig(BaseModel):
     token: str | None = None
     proxy: str | None = None
     registration_config: RegistrationConfig | None = None
-
-    host: str = "api.oneme.ru"
+    upload_timeout: int = 900
+    relogin: bool = True
+    host: str = "api2.oneme.ru"
     port: int = 443
     use_ssl: bool = True
+    persist_session: bool = True
 
+    password_max_attempts: int | None = None
     protocol_version: int = 10
     request_timeout: float = 30.0
     log_level: str = "INFO"
     telemetry: bool = False
 
     interactive: bool = True
+    restore_user_agent_from_session: bool = True
 
     store: StoreProtocol | None = None
 
@@ -181,13 +194,35 @@ class ExtraConfig(BaseModel):
         proxy: Proxy URL для TCP- или WebSocket-транспорта.
         reconnect: Переподключаться после сетевых ошибок.
         reconnect_delay: Пауза перед reconnect.
-        device_id: Явный device ID. Если не передан, генерируется UUID.
+        upload_timeout: Общий timeout HTTP-загрузки файлов, видео, голосовых и
+            видеосообщений в секундах. По умолчанию ``900``; не применяется к
+            фотографиям и 60-секундному ожиданию обработки вложения. ``0`` и
+            отрицательные значения отключают общий timeout, но не отдельный
+            60-секундный socket/read timeout.
+        relogin: Автоматически сбрасывать сессию и повторять авторизацию, если
+            Max отозвал login token. По умолчанию ``True``.
+        password_max_attempts: Максимальное число попыток ввода пароля 2FA.
+            ``None`` означает отсутствие лимита; ``0`` и отрицательные значения
+            сразу завершают авторизацию с ``PasswordAttemptsExceededError``.
+        persist_session: Сохранять token, device/user-agent и sync-state между
+            runtime в SQLite или переданном ``store``. По умолчанию ``True``.
+            При ``False`` используется отдельный ``InMemoryStore`` и значение
+            ``store`` игнорируется; после пересоздания runtime, в том числе при
+            reconnect, сохраненная сессия недоступна.
+        device_id: Явный device ID. Если не передан, генерируется строка из
+            16 шестнадцатеричных символов.
         device_type: Тип устройства для mobile user-agent.
-        user_agent: Полностью заданный user-agent payload.
-        mt_instance_id: Instance ID устройства.
+        user_agent: Полностью заданный user-agent payload. Явное значение имеет
+            приоритет над user-agent из сохраненной сессии. Автоматически
+            сгенерированный user-agent восстанавливает характеристики устройства
+            из сессии, сохраняя версию приложения и build number текущего запуска.
+        mt_instance_id: Instance ID устройства. По умолчанию генерируется
+            строка из 16 шестнадцатеричных символов.
         request_timeout: Timeout API-запросов в секундах.
         log_level: Уровень логов ``pymax``.
         telemetry: Отправлять telemetry-события Max.
+        store: Пользовательское хранилище сессии. Используется только при
+            ``persist_session=True``.
         sync: Переопределения sync-маркеров для login.
 
     Example:
@@ -210,18 +245,22 @@ class ExtraConfig(BaseModel):
     token: str | None = None
     registration_config: RegistrationConfig | None = None
 
-    host: str = "api.oneme.ru"
+    host: str = "api2.oneme.ru"
     port: int = 443
     url: str = "wss://api.oneme.ru/websocket"
     use_ssl: bool = True
     proxy: str | None = None
     reconnect: bool = True
     reconnect_delay: float = 1.0
+    upload_timeout: int = 900
+    relogin: bool = True
+    password_max_attempts: int | None = None
+    persist_session: bool = True
 
     device_id: str | None = None
     device_type: DeviceType = DeviceType.ANDROID
     user_agent: MobileUserAgentPayload | None = None
-    mt_instance_id: str = Field(default_factory=lambda: str(uuid4()))
+    mt_instance_id: str = Field(default_factory=generate_device_id)
 
     request_timeout: float = 30.0
     log_level: str = "INFO"
@@ -231,14 +270,17 @@ class ExtraConfig(BaseModel):
 
     sync: SyncOverrides = Field(default_factory=SyncOverrides)
 
-    def generate_user_agent(self) -> MobileUserAgentPayload:
+    def generate_user_agent(self, app_version: str, build_number: int) -> MobileUserAgentPayload:
         """Создает mobile user-agent payload для TCP-клиента.
 
+        Args:
+            app_version: Версия Android-клиента Max.
+            build_number: Build number той же версии из ``VersionCatalog``.
+
         Returns:
-            Случайная, но правдоподобная конфигурация Android-клиента Max.
+            Случайная конфигурация Android-устройства с переданными версией и
+            build number.
         """
-        versions = PREFERRED_VERSION if random() < 0.9 else LEGACY_VERSIONS
-        app_version, build_number = choice(versions)
         device_name, os_version, screen, arch = choice(ANDROID_DEVICES)
         locale, timezone = choice(LOCALE_TIMEZONES)
 

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()