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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 2.2.0
+Version: 2.3.1
 Summary: Python wrapper для API мессенджера Max
 Project-URL: Homepage, https://github.com/MaxApiTeam/PyMax
 Project-URL: Repository, https://github.com/MaxApiTeam/PyMax
@@ -31,6 +31,7 @@ Requires-Dist: pydantic>=2.10.0
 Requires-Dist: python-socks[asyncio]>=2.8.1
 Requires-Dist: qrcode>=8.2
 Requires-Dist: websockets>=16.0
+Requires-Dist: zstandard>=0.25.0
 Description-Content-Type: text/markdown
 
 # PyMax

{maxapi_python-2.2.0 → maxapi_python-2.3.1}/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.1}/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.1}/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
@@ -277,18 +300,18 @@ Debug-логи показывают handshake, login, входящие собы
 Клиент собирает несколько API-направлений:
 
 Сообщения
-   ``send_message()``, ``fetch_history()``, ``delete_message()``,
-   ``pin_message()``, ``read_message()``, реакции и получение URL для входящих
-   файлов/видео.
+   ``send_message()``, ``forward_message()``, ``fetch_history()``,
+   ``delete_message()``, ``pin_message()``, ``read_message()``, реакции и
+   получение URL для входящих файлов/видео.
 
 Чаты
    ``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.1}/docs/index.rst

@@ -22,6 +22,8 @@ PyMax - асинхронная Python-библиотека для Max API. Он
    :maxdepth: 1
    :caption: Новости
 
+   release-2-3-1
+   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.1}/docs/messages.rst

@@ -51,6 +51,7 @@ Messages
 
 Через клиент то же редактирование доступно как
 ``client.edit_message(chat_id, message_id, text, ...)``.
+Новые вложения передаются через ``attachments``.
 
 Отправлять сообщения
 --------------------
@@ -69,6 +70,18 @@ Messages
    async def on_message(message: Message, client: Client) -> None:
        await message.answer("Ответ в тот же чат")
        await message.reply("Ответ реплаем")
+       await message.forward(chat_id=654321)
+
+Переслать сообщение напрямую через клиент можно с указанием исходного и
+целевого чатов:
+
+.. code-block:: python
+
+   await client.forward_message(
+       chat_id=654321,
+       message_id=987654,
+       source_chat_id=123456,
+   )
 
 Ответ, реакции, удаление и прочтение
 ----------------------------------------
@@ -99,7 +112,7 @@ Messages
 Служебные события
 -----------------
 
-В ``2.2.0`` доступны отдельные обработчики набора текста, присутствия,
+Начиная с ``2.2.0`` доступны отдельные обработчики набора текста, присутствия,
 прочтения и реакций:
 
 .. code-block:: python

maxapi_python-2.3.1/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.3.1/docs/release-2-3-1.rst

@@ -0,0 +1,23 @@
+PyMax 2.3.1
+===========
+
+Изменения относительно ``2.3.0``.
+
+Добавлено
+---------
+
+* ``forward_message()`` на клиенте и ``Message.forward()`` на bound-объекте
+  сообщения. Для пересылки между разными чатами укажите ``source_chat_id``.
+
+Исправлено
+----------
+
+* Декодирование сжатых TCP payload-ов: коэффициенты LZ4 теперь обрабатываются
+  корректно, а payload-ы с флагом ``0xFF`` декодируются через Zstandard.
+* Разбор профилей bot-аккаунтов, в которых ``gender`` приходит числом, а
+  ``web_app`` — URL-строкой.
+
+Зависимости
+-----------
+
+* Добавлена runtime-зависимость ``zstandard`` для декодирования TCP payload-ов.

{maxapi_python-2.2.0 → maxapi_python-2.3.1}/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.1/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.1}/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.1}/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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "maxapi-python"
-version = "2.2.0"
+version = "2.3.1"
 description = "Python wrapper для API мессенджера Max"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -31,6 +31,7 @@ dependencies = [
   "python-socks[asyncio]>=2.8.1",
   "qrcode>=8.2",
   "websockets>=16.0",
+  "zstandard>=0.25.0",
 ]
 
 [project.urls]

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

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

{maxapi_python-2.2.0 → maxapi_python-2.3.1}/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.1}/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.1}/src/pymax/api/messages/payloads.py

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import Field
 
@@ -46,6 +46,26 @@ class SendMessagePayload(CamelModel):
     notify: bool = False
 
 
+class ForwardLink(CamelModel):
+    type: Literal["FORWARD"] = "FORWARD"
+    message_id: str
+    chat_id: int
+
+
+class ForwardMessagePayloadMessage(CamelModel):
+    cid: int
+    link: ForwardLink
+    attaches: list[AttachPhotoPayload | VideoAttachPayload | AttachFilePayload] = Field(
+        default_factory=list
+    )
+
+
+class ForwardMessagePayload(CamelModel):
+    chat_id: int
+    message: ForwardMessagePayloadMessage
+    notify: bool = True
+
+
 class ChatHistoryPayload(CamelModel):
     chat_id: int
     forward: int

{maxapi_python-2.2.0 → maxapi_python-2.3.1}/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
@@ -35,6 +36,9 @@ from .payloads import (
     ChatHistoryPayload,
     DeleteMessagePayload,
     EditMessagePayload,
+    ForwardLink,
+    ForwardMessagePayload,
+    ForwardMessagePayloadMessage,
     GetFilePayload,
     GetMessagesPayload,
     GetReactionsPayload,
@@ -52,7 +56,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__)
 
@@ -138,6 +142,42 @@ class MessageService:
         logger.info("message sent chat_id=%s", chat_id)
         return message
 
+    async def forward_message(
+        self,
+        chat_id: int,
+        message_id: int | str,
+        source_chat_id: int | None = None,
+        *,
+        notify: bool = True,
+    ) -> Message | None:
+        source_chat_id = chat_id if source_chat_id is None else source_chat_id
+        logger.info(
+            "forwarding message source_chat_id=%s chat_id=%s message_id=%s",
+            source_chat_id,
+            chat_id,
+            message_id,
+        )
+
+        frame = ForwardMessagePayload(
+            chat_id=chat_id,
+            message=ForwardMessagePayloadMessage(
+                cid=-self._next_cid(),
+                link=ForwardLink(
+                    message_id=str(message_id),
+                    chat_id=source_chat_id,
+                ),
+            ),
+            notify=notify,
+        )
+
+        response = await self.app.invoke(Opcode.MSG_SEND, frame.to_payload())
+        message = bind_api_model(
+            self.app,
+            require_payload_model(response, Message),
+        )
+        logger.info("message forwarded source_chat_id=%s chat_id=%s", source_chat_id, chat_id)
+        return message
+
     async def get_messages(
         self,
         chat_id: int,
@@ -169,24 +209,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.1/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.1}/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.1}/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)