maxapi-python 2.2.0__tar.gz → 2.3.0__tar.gz

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 2.2.0
+Version: 2.3.0
 Summary: Python wrapper для API мессенджера Max
 Project-URL: Homepage, https://github.com/MaxApiTeam/PyMax
 Project-URL: Repository, https://github.com/MaxApiTeam/PyMax

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/docs/api/router.rst

@@ -5,6 +5,12 @@ Router API
    :members:
    :show-inheritance:
 
+.. autoclass:: pymax.dispatch.ErrorScope
+   :members:
+
+.. autoclass:: pymax.dispatch.ErrorContext
+   :members:
+
 .. autodata:: pymax.ClientRouter
 
 .. autodata:: pymax.WebRouter

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/docs/chats.rst

@@ -142,6 +142,22 @@ login/sync, а также методы для загрузки, создания
 ``leave()`` зависит от типа чата: для группы вызывает выход из группы, для
 канала - выход из канала. Из личного диалога выйти нельзя.
 
+Удалить чат
+-----------
+
+.. code-block:: python
+
+   await client.delete_chat(chat_id=123456)
+
+Через объект ``Chat`` PyMax использует ``chat.last_event_time``:
+
+.. code-block:: python
+
+   chat = await client.get_chat(123456)
+   await chat.delete(for_all=True)
+
+После успешного удаления чат убирается из локального кеша ``client.chats``.
+
 Invite-ссылки
 -------------
 

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/docs/client.rst

@@ -231,6 +231,21 @@ PyMax потеряет token и попросит авторизацию снов
 сессии можно удалить файл ``work_dir/session_name``; тогда потребуется новая
 авторизация.
 
+Повторная авторизация
+---------------------
+
+Если нужно сбросить текущую локальную сессию и пройти авторизацию заново,
+используйте ``relogin()``:
+
+.. code-block:: python
+
+   await client.relogin()
+
+``relogin()`` удаляет загруженную сессию из store, закрывает текущий runtime и
+по умолчанию сразу запускает клиента снова. Если token был передан через
+``ExtraConfig(token=...)``, он тоже сбрасывается; это можно отключить через
+``drop_config_token=False``.
+
 Reconnect
 ---------
 
@@ -242,6 +257,14 @@ Reconnect
 а новый ``App`` снова получает тот же root router. ``on_start`` вызывается
 после каждого успешного reconnect.
 
+Перед повторным подключением можно зарегистрировать ``on_disconnect``:
+
+.. code-block:: python
+
+   @client.on_disconnect()
+   async def disconnected(exc: Exception, reconnect: bool, delay: float) -> None:
+       print("connection lost:", exc, reconnect, delay)
+
 Отключить reconnect:
 
 .. code-block:: python
@@ -283,12 +306,12 @@ Debug-логи показывают handshake, login, входящие собы
 
 Чаты
    ``get_chat()``, ``fetch_chats()``, создание групп, invite-ссылки,
-   участники, настройки групп и выход из групп/каналов.
+   участники, настройки групп, удаление чатов и выход из групп/каналов.
 
 Пользователи
    ``get_user()``, ``get_users()``, ``fetch_users()``, ``search_by_phone()``,
-   ``add_contact()``, ``remove_contact()`` и ``get_chat_id()``. Подробнее:
-   :doc:`users`.
+   ``add_contact()``, ``remove_contact()``, ``import_contacts()`` и
+   ``get_chat_id()``. Подробнее: :doc:`users`.
 
 Аккаунт
    ``change_profile()``, папки чатов, активные сессии, ``logout()`` и

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/docs/index.rst

@@ -22,6 +22,7 @@ PyMax - асинхронная Python-библиотека для Max API. Он
    :maxdepth: 1
    :caption: Новости
 
+   release-2-3-0
    release-2-2-0
    release-2-1-3
    release-2-1-2

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/docs/messages.rst

@@ -51,6 +51,7 @@ Messages
 
 Через клиент то же редактирование доступно как
 ``client.edit_message(chat_id, message_id, text, ...)``.
+Новые вложения передаются через ``attachments``.
 
 Отправлять сообщения
 --------------------
@@ -99,7 +100,7 @@ Messages
 Служебные события
 -----------------
 
-В ``2.2.0`` доступны отдельные обработчики набора текста, присутствия,
+Начиная с ``2.2.0`` доступны отдельные обработчики набора текста, присутствия,
 прочтения и реакций:
 
 .. code-block:: python

maxapi_python-2.3.0/docs/release-2-3-0.rst

@@ -0,0 +1,40 @@
+PyMax 2.3.0
+===========
+
+Изменения относительно ``2.2.0``.
+
+Добавлено
+---------
+
+* Несколько ``on_start``-обработчиков на одном клиенте или роутере. Все
+  зарегистрированные callbacks запускаются после успешного login.
+* ``on_error()`` для централизованной обработки ошибок из handler-ов,
+  фильтров, ``on_start`` и login на этапе запуска.
+* ``ErrorScope.GLOBAL`` и ``ErrorScope.LOCAL`` для выбора области действия
+  error-handler-а.
+* ``on_disconnect()`` для реакции на сетевое отключение перед reconnect. В
+  callback передаются исходная ошибка, флаг reconnect и задержка.
+* ``relogin()`` для удаления текущей локальной сессии и повторной авторизации.
+* ``delete_chat()`` на клиенте и ``Chat.delete()`` на bound-объекте чата.
+* ``import_contacts()`` и ``ContactInfo`` для импорта контактов из телефонной
+  книги.
+* ``SessionStore.delete_all_sessions()`` для очистки встроенного SQLite-store.
+
+Изменилось
+----------
+
+* ``edit_message()`` и ``Message.edit()`` принимают новые вложения только через
+  ``attachments=[...]``.
+* Тип ``attachments`` для отправки и редактирования сообщений теперь принимает
+  любую ``Sequence`` из ``Photo``, ``File`` и ``Video``.
+* Обработанные login-ошибки на этапе ``start`` больше не приводят к запуску
+  ``on_start``.
+
+Миграция
+--------
+
+* В ``edit_message()`` и ``Message.edit()`` используйте ``attachments=[...]``.
+  Параметр ``attachment`` удален.
+* Если error-handler зарегистрирован и успешно отработал, исходная ошибка
+  считается обработанной. Если сам error-handler падает, исходная ошибка
+  продолжает распространяться.

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/docs/router.rst

@@ -158,7 +158,54 @@ Handler всегда вызывается как ``handler(event, client)``. Э
        print(client.me)
 
 Если включен reconnect, ``on_start`` будет вызван после каждого успешного
-переподключения.
+переподключения. На одном клиенте или роутере можно зарегистрировать несколько
+``on_start``-обработчиков; PyMax запустит каждый из них.
+
+Ошибки handler-ов
+-----------------
+
+``on_error`` перехватывает ошибки из фильтров, handler-ов, ``on_start`` и login
+на этапе запуска.
+
+.. code-block:: python
+
+   from pymax import ApiError, Client, ClientRouter
+   from pymax.dispatch import ErrorContext, ErrorScope
+
+   client = Client(phone="+79990000000", work_dir="cache")
+
+
+   @client.on_error(scope=ErrorScope.GLOBAL)
+   async def on_err(e: Exception, ctx: ErrorContext[Client]) -> None:
+       if isinstance(e, ApiError) and e.message == "FAIL_LOGIN_TOKEN":
+           await ctx.client.relogin()
+
+
+   router = ClientRouter()
+
+
+   @router.on_error(scope=ErrorScope.LOCAL)
+   async def router_error(e: Exception, ctx: ErrorContext[Client]) -> None:
+       print("router failed:", e)
+
+``ErrorScope.GLOBAL`` получает ошибки из всего дерева подключенных роутеров.
+``ErrorScope.LOCAL`` получает только ошибки того router-а, на котором
+зарегистрирован error-handler.
+
+Если error-handler успешно отработал, исходная ошибка считается обработанной.
+Если упал сам error-handler, исходная ошибка продолжит распространяться.
+
+Отключение
+----------
+
+``on_disconnect`` вызывается при сетевой ошибке перед reconnect или перед
+пробросом ошибки, если reconnect отключен.
+
+.. code-block:: python
+
+   @client.on_disconnect()
+   async def disconnected(exc: Exception, reconnect: bool, delay: float) -> None:
+       print(exc, reconnect, delay)
 
 Raw events
 ----------

maxapi_python-2.3.0/docs/types/contact_info.rst

@@ -0,0 +1,6 @@
+ContactInfo
+===========
+
+.. autoclass:: pymax.types.domain.user.ContactInfo
+   :members:
+   :show-inheritance:

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/docs/types/index.rst

@@ -37,6 +37,9 @@ Types
 ``User`` и ``Profile``
    Пользователи и профиль текущего аккаунта.
 
+``ContactInfo``
+   Контакт телефонной книги для ``import_contacts()``.
+
 ``PhotoAttachment``, ``VideoAttachment``, ``FileAttachment`` и другие
    Входящие вложения в ``message.attaches``.
 
@@ -95,6 +98,7 @@ API reference
    element
    name
    user
+   contact_info
    profile
    session
    folder

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/docs/users.rst

@@ -71,6 +71,25 @@ PyMax хранит контакты, которые Max вернул на login/
        await user.add_contact()
        await user.remove_contact()
 
+Импортировать контакты из телефонной книги:
+
+.. code-block:: python
+
+   from pymax.types import ContactInfo
+
+   contacts = await client.import_contacts(
+       [
+           ContactInfo(
+               phone="+79990000000",
+               first_name="Ada",
+               last_name="Lovelace",
+           )
+       ]
+   )
+
+``last_name`` хранится в ``ContactInfo``, но текущий payload импорта Max
+использует только телефон и имя.
+
 Личный чат
 ----------
 

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "maxapi-python"
-version = "2.2.0"
+version = "2.3.0"
 description = "Python wrapper для API мессенджера Max"
 readme = "README.md"
 requires-python = ">=3.10"

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/src/pymax/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 
 from .auth import (

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/src/pymax/api/chats/payloads.py

@@ -115,3 +115,9 @@ class JoinRequestActionPayload(CamelModel):
     type: str = "JOIN_REQUEST"  # TODO: ENUMM!!!
     show_history: bool | None = True
     operation: ChatMemberOperation
+
+
+class DeleteChatPayload(CamelModel):
+    chat_id: int
+    last_event_time: int
+    for_all: bool = True

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/src/pymax/api/chats/service.py

@@ -23,6 +23,7 @@ from .payloads import (
     CreateGroupAttach,
     CreateGroupMessage,
     CreateGroupPayload,
+    DeleteChatPayload,
     FetchChatsPayload,
     FetchJoinRequests,
     GetChatInfoPayload,
@@ -362,3 +363,20 @@ class ChatService:
             chat_id=chat_id,
             user_ids=[user_id],
         )
+
+    async def delete_chat(
+        self,
+        chat_id: int,
+        last_event_time: int | None = None,
+        for_all: bool = True,
+    ) -> None:
+        frame = DeleteChatPayload(
+            chat_id=chat_id,
+            last_event_time=(
+                last_event_time if last_event_time is not None else int(time.time() * 1000)
+            ),
+            for_all=for_all,
+        )
+
+        await self.app.invoke(Opcode.CHAT_DELETE, frame.to_payload())
+        self._remove_cached_chat(chat_id)

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/src/pymax/api/messages/service.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import time
+from collections.abc import Sequence
 from typing import TYPE_CHECKING, TypeAlias
 
 from pymax.api.binding import bind_api_model, bind_api_models
@@ -52,7 +53,7 @@ if TYPE_CHECKING:
     from pymax.app import App
 
 SendAttachment: TypeAlias = Photo | File | Video
-SendAttachments: TypeAlias = list[SendAttachment] | None
+SendAttachments: TypeAlias = Sequence[SendAttachment] | None
 
 logger = get_logger(__name__)
 
@@ -169,24 +170,15 @@ class MessageService:
         chat_id: int,
         message_id: int,
         text: str,
-        attachment: SendAttachment | None = None,
         attachments: SendAttachments = None,
     ) -> Message:
-        if attachment is not None and attachments:
-            logger.warning("both attachment and attachments provided; using attachments")
-            attachment = None
-
-        edit_attachments = attachments
-        if attachment is not None:
-            edit_attachments = [attachment]
-
         clean_text, elements = Formatter.format_markdown(text)
         frame = EditMessagePayload(
             chat_id=chat_id,
             message_id=message_id,
             text=clean_text,
             elements=elements,
-            attachments=await self._upload_attachments(edit_attachments),
+            attachments=await self._upload_attachments(attachments),
         )
 
         response = await self.app.invoke(Opcode.MSG_EDIT, frame.to_payload())

maxapi_python-2.3.0/src/pymax/api/users/payloads.py

@@ -0,0 +1,38 @@
+from collections.abc import Iterable
+
+from pymax.api.models import CamelModel
+from pymax.types.domain import ContactInfo
+
+from .enums import ContactAction
+
+
+class FetchContactsPayload(CamelModel):
+    contact_ids: list[int]
+
+
+class SearchByPhonePayload(CamelModel):
+    phone: str
+
+
+class ContactActionPayload(CamelModel):
+    contact_id: int
+    action: ContactAction
+
+
+class _ContactPayload(CamelModel):
+    first_name: str
+
+
+class ImportContactsPayload(CamelModel):
+    contact_list: dict[str, _ContactPayload]  # phone -> contact payload
+
+    @classmethod
+    def from_contacts(cls, contacts: Iterable[ContactInfo]) -> "ImportContactsPayload":
+        return cls(
+            contact_list={
+                contact.phone: _ContactPayload(
+                    first_name=contact.first_name,
+                )
+                for contact in contacts
+            }
+        )

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/src/pymax/api/users/service.py

@@ -10,12 +10,13 @@ from pymax.api.response import (
 )
 from pymax.logging import get_logger
 from pymax.protocol import InboundFrame, Opcode
-from pymax.types.domain import Session, User
+from pymax.types.domain import ContactInfo, Session, User
 
 from .enums import ContactAction, UserPayloadKey
 from .payloads import (
     ContactActionPayload,
     FetchContactsPayload,
+    ImportContactsPayload,
     SearchByPhonePayload,
 )
 
@@ -122,5 +123,17 @@ class UserService:
         self.app.users.pop(contact_id, None)
         return True
 
+    async def import_contacts(self, contacts: list[ContactInfo]) -> list[User]:
+        frame = ImportContactsPayload.from_contacts(contacts)
+
+        response = await self.app.invoke(Opcode.SYNC, frame.to_payload())
+
+        users = parse_payload_list(
+            response, UserPayloadKey.CONTACTS, User
+        )  # TODO: maybe also return phone mapping?
+
+        # {contacts: [...], phones: {data[0]: server_phone}}
+        return [self._cache_user(user) for user in users]
+
     def get_chat_id(self, first_user_id: int, second_user_id: int) -> int:
         return first_user_id ^ second_user_id

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/src/pymax/app.py

@@ -1,12 +1,12 @@
 import asyncio
-from typing import Any, Generic, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 from pymax.api import ApiFacade
 from pymax.auth import AuthFlow
 from pymax.config import ClientConfig
 from pymax.connection import ConnectionManager
 from pymax.dispatch import Dispatcher
-from pymax.dispatch.router import Router
+from pymax.dispatch.router import EventType, Router
 from pymax.exceptions import ApiError
 from pymax.logging import get_logger
 from pymax.protocol import Command, InboundFrame, OutboundFrame
@@ -17,8 +17,11 @@ from pymax.telemetry import TelemetryService
 from pymax.types import MaxApiError, Message
 from pymax.types.domain import Chat, Profile, User
 
+if TYPE_CHECKING:
+    from pymax.base import BaseClient
+
 logger = get_logger(__name__)
-ClientT = TypeVar("ClientT")
+ClientT = TypeVar("ClientT", bound="BaseClient")
 
 
 class App(Generic[ClientT]):
@@ -124,9 +127,26 @@ class App(Generic[ClientT]):
         self.session = session_data
 
         logger.debug("logging in")
-        response = await self.api.auth.login(
-            self.config.device.user_agent,
-        )
+
+        try:
+            response = await self.api.auth.login(
+                self.config.device.user_agent,
+            )
+        except Exception as e:
+            handled = False
+            if self.dispatcher.client is not None:
+                handled = await self.dispatcher.emit_error(
+                    e,
+                    EventType.ON_START,
+                    None,
+                    self.dispatcher.root_router,
+                    None,
+                )
+            if not handled:
+                raise
+
+            await self.close()
+            return
 
         if response.token is not None and response.token != self.session.token:
             await self.store.update_token(self.session.token, response.token)

{maxapi_python-2.2.0 → maxapi_python-2.3.0}/src/pymax/base.py

@@ -5,7 +5,8 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
 from uuid import uuid4
 
-from pymax.dispatch import Router
+from pymax.dispatch import ErrorScope, Router
+from pymax.dispatch.router import DisconnectDecorator, ErrorDecorator
 from pymax.infra import BaseMixin
 from pymax.logging import get_logger
 
@@ -128,6 +129,10 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
         while True:
             try:
                 await self._app.start()
+                if not self._app.started:
+                    await self.close()
+                    return
+
                 await self._app.dispatcher.emit_start(self)
                 await self._connection.wait_closed()
             except asyncio.CancelledError:
@@ -138,14 +143,21 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
                 EOFError,
                 OSError,
                 TimeoutError,
-            ):
+            ) as e:
                 await self.close()
+                await self._app.dispatcher.emit_disconnect(
+                    e,
+                    self.extra_config.reconnect,
+                    self.extra_config.reconnect_delay,
+                )
+
                 if not self.extra_config.reconnect:
                     raise
 
-                logger.exception(
+                logger.debug(
                     "client connection failed; reconnecting in %s seconds",
                     self.extra_config.reconnect_delay,
+                    exc_info=True,
                 )
                 await asyncio.sleep(self.extra_config.reconnect_delay)
                 self._reset_runtime()
@@ -237,6 +249,39 @@ class BaseClient(BaseMixin, ABC, Generic[ClientT]):
         """Регистрирует обработчик исходных входящих frame-ов."""
         return self._router.on_raw(*filters)
 
+    def on_error(self, scope: ErrorScope = ErrorScope.GLOBAL) -> ErrorDecorator[ClientT]:
+        """Регистрирует обработчик ошибок dispatch-а и запуска клиента."""
+        return self._router.on_error(scope)
+
+    def on_disconnect(self) -> DisconnectDecorator:
+        """Регистрирует обработчик сетевого отключения перед reconnect."""
+        return self._router.on_disconnect()
+
     def include_router(self, router: Router[ClientT]) -> None:
         """Подключает дочерний router к root router клиента."""
         self._router.include_router(router)
+
+    async def relogin(self: ClientT, drop_config_token: bool = True, start: bool = True) -> None:  # noqa: PYI019
+        """Удаляет текущую локальную сессию и запускает авторизацию заново.
+
+        Args:
+            drop_config_token: Сбросить token, переданный через ``ExtraConfig``.
+            start: Сразу запустить клиента после сброса runtime.
+        """
+        store = self._app.store
+        session = self._app.session
+
+        if session is None:
+            raise RuntimeError("Cannot relogin before session is loaded")
+
+        await store.delete_session(session.token)
+        await self.close()
+
+        if drop_config_token:
+            self.extra_config.token = None
+            self._config.token = None
+
+        self._reset_runtime()
+
+        if start:
+            await self.start()

maxapi_python-2.3.0/src/pymax/dispatch/__init__.py

@@ -0,0 +1,21 @@
+from .dispatcher import Dispatcher
+from .enums import EventType
+from .router import (
+    ClientRouter,
+    DisconnectCallback,
+    DisconnectDecorator,
+    ErrorContext,
+    ErrorScope,
+    Router,
+)
+
+__all__ = (
+    "ClientRouter",
+    "DisconnectCallback",
+    "DisconnectDecorator",
+    "Dispatcher",
+    "ErrorContext",
+    "ErrorScope",
+    "EventType",
+    "Router",
+)