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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 2.3.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.3.0 → maxapi_python-2.3.1}/docs/client.rst

@@ -300,9 +300,9 @@ 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-ссылки,

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

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

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

@@ -70,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,
+   )
 
 Ответ, реакции, удаление и прочтение
 ----------------------------------------

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

@@ -1,6 +1,6 @@
 [project]
 name = "maxapi-python"
-version = "2.3.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.3.0 → maxapi_python-2.3.1}/src/pymax/__init__.py

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

{maxapi_python-2.3.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.3.0 → maxapi_python-2.3.1}/src/pymax/api/messages/service.py

@@ -36,6 +36,9 @@ from .payloads import (
     ChatHistoryPayload,
     DeleteMessagePayload,
     EditMessagePayload,
+    ForwardLink,
+    ForwardMessagePayload,
+    ForwardMessagePayloadMessage,
     GetFilePayload,
     GetMessagesPayload,
     GetReactionsPayload,
@@ -139,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,

{maxapi_python-2.3.0 → maxapi_python-2.3.1}/src/pymax/infra/message.py

@@ -62,6 +62,33 @@ class MessageMixin(IClientProtocol):
             message_id=message_id,
         )
 
+    async def forward_message(
+        self,
+        chat_id: int,
+        message_id: int | str,
+        source_chat_id: int | None = None,
+        *,
+        notify: bool = True,
+    ) -> Message | None:
+        """Пересылает существующее сообщение в чат.
+
+        Args:
+            chat_id: ID целевого чата.
+            message_id: ID пересылаемого сообщения.
+            source_chat_id: ID исходного чата. Если не указан, используется
+                целевой чат.
+            notify: Отправить ли получателям push-уведомление.
+
+        Returns:
+            Пересланное сообщение или ``None``, если сервер не вернул его.
+        """
+        return await self._app.api.messages.forward_message(
+            chat_id=chat_id,
+            message_id=message_id,
+            source_chat_id=source_chat_id,
+            notify=notify,
+        )
+
     async def get_messages(
         self,
         chat_id: int,

{maxapi_python-2.3.0 → maxapi_python-2.3.1}/src/pymax/protocol/tcp/compression.py

@@ -1,3 +1,8 @@
+from io import BytesIO
+
+import zstandard
+
+
 class Lz4BlockCompression:
     def decompress(self, src: bytes, max_output: int = 5 * 1024 * 1024) -> bytes:
         dst = bytearray()
@@ -95,3 +100,16 @@ class Lz4BlockCompression:
                 dst.extend(src[lit_start : lit_start + lit_len])
 
         return bytes(dst)
+
+
+class ZstdCompression:
+    def decompress(self, src: bytes, max_output: int = 5 * 1024 * 1024) -> bytes:
+        try:
+            with zstandard.ZstdDecompressor().stream_reader(BytesIO(src)) as reader:
+                result = reader.read(max_output + 1)
+        except zstandard.ZstdError as e:
+            raise ValueError("Zstd: failed to decompress payload") from e
+
+        if len(result) > max_output:
+            raise ValueError("Zstd: output too large")
+        return result

{maxapi_python-2.3.0 → maxapi_python-2.3.1}/src/pymax/protocol/tcp/payload.py

@@ -5,7 +5,7 @@ import msgpack
 
 from pymax.logging import get_logger
 
-from .compression import Lz4BlockCompression
+from .compression import Lz4BlockCompression, ZstdCompression
 
 logger = get_logger(__name__)
 
@@ -70,9 +70,11 @@ class TcpPayloadDecoder:
         *,
         serializer: MsgpackPayloadCodec,
         compression: Lz4BlockCompression | None = None,
+        zstd_compression: ZstdCompression | None = None,
     ) -> None:
         self.serializer = serializer
         self.compression = compression
+        self.zstd_compression = zstd_compression
 
     def _normalize_keys(self, obj: Any) -> Any:
         if isinstance(obj, dict):
@@ -97,12 +99,26 @@ class TcpPayloadDecoder:
         if not payload_bytes:
             return {}
 
-        if flags & 0x03 and self.compression:
+        if flags == 0xFF:
+            if self.zstd_compression is None:
+                raise ValueError("Zstd-compressed TCP payload without a decoder")
+            try:
+                payload_bytes = self.zstd_compression.decompress(payload_bytes)
+                logger.debug("tcp payload decompressed with Zstd")
+            except ValueError:
+                logger.debug("tcp Zstd payload decompression failed", exc_info=True)
+                raise
+        elif flags > 0x7F:
+            raise ValueError(f"invalid TCP compression factor: {flags}")
+        elif flags > 0:
+            if self.compression is None:
+                raise ValueError("LZ4-compressed TCP payload without a decoder")
             try:
                 payload_bytes = self.compression.decompress(payload_bytes)
-                logger.debug("tcp payload decompressed flags=%s", flags)
+                logger.debug("tcp payload decompressed cof=%s", flags)
             except ValueError:
-                logger.debug("tcp payload decompress skipped flags=%s", flags)
+                logger.debug("tcp payload decompression failed cof=%s", flags, exc_info=True)
+                raise
 
         result = self.serializer.decode(payload_bytes)
         return self._normalize_keys(result)

{maxapi_python-2.3.0 → maxapi_python-2.3.1}/src/pymax/protocol/tcp/protocol.py

@@ -7,6 +7,7 @@ from .payload import (
     Lz4BlockCompression,
     MsgpackPayloadCodec,
     TcpPayloadDecoder,
+    ZstdCompression,
 )
 
 logger = get_logger(__name__)
@@ -20,8 +21,11 @@ class TcpProtocol(BaseProtocol):
         self.framer = TcpPacketFramer()
         self.serializer = MsgpackPayloadCodec()
         self.compression = Lz4BlockCompression()
+        self.zstd_compression = ZstdCompression()
         self.payload_decoder = TcpPayloadDecoder(
-            serializer=self.serializer, compression=self.compression
+            serializer=self.serializer,
+            compression=self.compression,
+            zstd_compression=self.zstd_compression,
         )
 
     def encode(self, frame: OutboundFrame) -> bytes:

{maxapi_python-2.3.0 → maxapi_python-2.3.1}/src/pymax/types/domain/message.py

@@ -93,8 +93,9 @@ class Message(CamelModel):
 
     Сообщения, полученные через клиент, обычно уже привязаны к сервису
     сообщений. После этого можно вызывать удобные методы объекта:
-    :meth:`reply`, :meth:`answer`, :meth:`edit`, :meth:`pin`, :meth:`delete`,
-    :meth:`read`, :meth:`react`, :meth:`unreact` и :meth:`get_reactions`.
+    :meth:`reply`, :meth:`answer`, :meth:`forward`, :meth:`edit`, :meth:`pin`,
+    :meth:`delete`, :meth:`read`, :meth:`react`, :meth:`unreact` и
+    :meth:`get_reactions`.
 
     Используйте ``Message`` в обработчиках ``on_message`` и при работе с
     историей. Некоторые поля могут быть ``None``, потому что Max присылает
@@ -244,6 +245,32 @@ class Message(CamelModel):
             notify=notify,
         )
 
+    async def forward(
+        self,
+        chat_id: int,
+        *,
+        notify: bool = True,
+    ) -> Message | None:
+        """Пересылает это сообщение в другой чат.
+
+        :param chat_id: ID целевого чата.
+        :type chat_id: int
+        :param notify: Отправить ли получателям push-уведомление.
+        :type notify: bool
+        :returns: Пересланное сообщение или ``None``, если сервер его не вернул.
+        :rtype: Message | None
+        :raises RuntimeError: Если сообщение не привязано к сервису или не
+            содержит ``chat_id``.
+        """
+        actions, source_chat_id = self._bound()
+
+        return await actions.forward_message(
+            chat_id=chat_id,
+            message_id=self.id,
+            source_chat_id=source_chat_id,
+            notify=notify,
+        )
+
     async def pin(self, notify_pin: bool = True) -> bool:
         """Закрепляет это сообщение в чате.
 

{maxapi_python-2.3.0 → maxapi_python-2.3.1}/src/pymax/types/domain/user.py

@@ -49,11 +49,11 @@ class User(CamelModel):
     :ivar description: Описание профиля.
     :vartype description: str | None
     :ivar gender: Пол пользователя.
-    :vartype gender: str | None
+    :vartype gender: str | int | None
     :ivar link: Ссылка на профиль.
     :vartype link: str | None
     :ivar web_app: Данные связанного web-приложения, если есть.
-    :vartype web_app: dict[str, Any] | None
+    :vartype web_app: dict[str, Any] | str | None
     :ivar menu_button: Данные кнопки меню профиля, если есть.
     :vartype menu_button: dict[str, Any] | None
     """
@@ -71,9 +71,11 @@ class User(CamelModel):
     phone: int | None = None
     status: str | None = None
     description: str | None = None
-    gender: str | None = None
+    # Bots may send ``gender`` as a numeric code and ``web_app`` as a URL
+    # string instead of an object; accept these so profile parsing won't fail.
+    gender: str | int | None = None
     link: str | None = None
-    web_app: dict[str, Any] | None = None
+    web_app: dict[str, Any] | str | None = None
     menu_button: dict[str, Any] | None = None
 
     _actions: UserService | None = PrivateAttr(default=None)

{maxapi_python-2.3.0 → maxapi_python-2.3.1}/tests/api/test_message_service.py

@@ -56,6 +56,48 @@ async def test_send_message_raises_when_attachment_upload_fails() -> None:
     assert app.calls == []
 
 
+@pytest.mark.asyncio
+async def test_forward_message_builds_payload_and_binds_result(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr("pymax.api.messages.service.time.time", lambda: 1000.0)
+    app = FakeApp([frame(message_payload(55, 200, "forwarded"))])
+
+    result = await app.api.messages.forward_message(
+        chat_id=200,
+        message_id=116742887450236083,
+        source_chat_id=100,
+        notify=False,
+    )
+
+    assert result is not None
+    assert result.id == 55
+    assert result._actions is app.api.messages
+    assert app.calls[0].opcode == Opcode.MSG_SEND
+    assert app.calls[0].payload == {
+        "chatId": 200,
+        "message": {
+            "cid": -1000001,
+            "link": {
+                "type": "FORWARD",
+                "messageId": "116742887450236083",
+                "chatId": 100,
+            },
+            "attaches": [],
+        },
+        "notify": False,
+    }
+
+
+@pytest.mark.asyncio
+async def test_forward_message_defaults_source_to_target_chat() -> None:
+    app = FakeApp([frame(message_payload(55, 200, "forwarded"))])
+
+    await app.api.messages.forward_message(chat_id=200, message_id="55")
+
+    assert app.calls[0].payload["message"]["link"]["chatId"] == 200
+
+
 @pytest.mark.asyncio
 async def test_upload_attachments_handles_file_video_and_empty_lists() -> None:
     app = FakeApp()

{maxapi_python-2.3.0 → maxapi_python-2.3.1}/tests/domain/test_bound_models.py

@@ -14,6 +14,10 @@ class MessageActions:
         self.calls.append(("send_message", args, kwargs))
         return "sent"
 
+    async def forward_message(self, *args, **kwargs):
+        self.calls.append(("forward_message", args, kwargs))
+        return "forwarded"
+
     async def get_message(self, *args, **kwargs):
         self.calls.append(("get_message", args, kwargs))
         return "message"
@@ -106,6 +110,7 @@ async def test_message_bound_methods_delegate_with_chat_and_message_ids() -> Non
 
     assert await message.reply("reply") == "sent"
     assert await message.answer("answer", reply_to=9) == "sent"
+    assert await message.forward(200, notify=False) == "forwarded"
     assert (
         await message.edit(
             "edited",
@@ -122,10 +127,16 @@ async def test_message_bound_methods_delegate_with_chat_and_message_ids() -> Non
 
     assert actions.calls[0][2]["reply_to"] == 10
     assert actions.calls[1][2]["reply_to"] == 9
-    assert actions.calls[2][2]["message_id"] == 10
-    assert actions.calls[2][2]["attachments"] == ["file"]
-    assert actions.calls[4][2]["message_ids"] == [10]
-    assert actions.calls[6][2]["message_id"] == "10"
+    assert actions.calls[2][2] == {
+        "chat_id": 200,
+        "message_id": 10,
+        "source_chat_id": 100,
+        "notify": False,
+    }
+    assert actions.calls[3][2]["message_id"] == 10
+    assert actions.calls[3][2]["attachments"] == ["file"]
+    assert actions.calls[5][2]["message_ids"] == [10]
+    assert actions.calls[7][2]["message_id"] == "10"
 
 
 @pytest.mark.asyncio

maxapi_python-2.3.1/tests/domain/test_user_models.py

@@ -0,0 +1,35 @@
+from pymax.types.domain import User
+
+
+def test_user_parses_bot_gender_int_and_web_app_url() -> None:
+    """Bot accounts send ``gender`` as a numeric code and ``web_app`` as a URL
+    string (observed for the "Алиса AI" bot); the profile must still parse."""
+    payload = {
+        "id": 6738397,
+        "names": [{"name": "Алиса AI", "type": "NICK"}],
+        "gender": 1,
+        "webApp": "https://alice.yandex.ru/max_onboarding",
+    }
+
+    user = User.model_validate(payload)
+
+    assert user.gender == 1
+    assert user.web_app == "https://alice.yandex.ru/max_onboarding"
+
+
+def test_user_parses_human_without_optional_fields() -> None:
+    """Regular users come without ``gender`` and ``web_app``."""
+    payload = {"id": 1, "names": [{"name": "Test User", "type": "NICK"}]}
+
+    user = User.model_validate(payload)
+
+    assert user.gender is None
+    assert user.web_app is None
+
+
+def test_user_still_accepts_dict_web_app() -> None:
+    """The dict type for ``web_app`` is kept from the original PyMax schema
+    (no real example of this format was seen, but we keep compatibility)."""
+    user = User.model_validate({"id": 2, "webApp": {}})
+
+    assert user.web_app == {}

{maxapi_python-2.3.0 → maxapi_python-2.3.1}/tests/protocol/test_protocols.py

@@ -2,10 +2,11 @@ from __future__ import annotations
 
 import msgpack
 import pytest
+import zstandard
 
 from pymax.api.messages.enums import ItemType
 from pymax.protocol import Command, InboundFrame, Opcode, OutboundFrame
-from pymax.protocol.tcp.compression import Lz4BlockCompression
+from pymax.protocol.tcp.compression import Lz4BlockCompression, ZstdCompression
 from pymax.protocol.tcp.framing import TcpPacketFramer
 from pymax.protocol.tcp.payload import MsgpackPayloadCodec, TcpPayloadDecoder
 from pymax.protocol.tcp.protocol import TcpProtocol
@@ -128,6 +129,49 @@ def test_msgpack_codec_uses_first_dict_when_stream_has_extra_data() -> None:
     assert codec.decode(encoded) == {"ok": True}
 
 
+def test_tcp_payload_decoder_decompresses_lz4_for_compression_factor_four() -> None:
+    # This is a raw LZ4 block produced by the official-compatible compressor.
+    # Its first byte is 0xF4, which MsgPack reads as -12 when decompression is
+    # incorrectly skipped for cof=4.
+    compressed = bytes.fromhex(
+        "f40a84a6707265666978a27878a464617461b0664a73436c4b437508008f"
+        "a47461696cd92a79010016dfa6726570656174d9684142434404004c5044"
+        "41424344"
+    )
+    decoder = TcpPayloadDecoder(
+        serializer=MsgpackPayloadCodec(),
+        compression=Lz4BlockCompression(),
+    )
+
+    decoded = decoder.decode(compressed, flags=4)
+
+    assert decoded == {
+        "prefix": "xx",
+        "data": "fJsClKCufJsClKCu",
+        "tail": "y" * 42,
+        "repeat": "ABCD" * 26,
+    }
+
+
+def test_tcp_payload_decoder_decompresses_zstd() -> None:
+    expected = {"error": "FAIL_LOGIN_TOKEN", "message": "Token expired"}
+    compressed = zstandard.ZstdCompressor().compress(msgpack.packb(expected, use_bin_type=True))
+    decoder = TcpPayloadDecoder(
+        serializer=MsgpackPayloadCodec(),
+        compression=Lz4BlockCompression(),
+        zstd_compression=ZstdCompression(),
+    )
+
+    assert decoder.decode(compressed, flags=0xFF) == expected
+
+
+def test_zstd_decompression_rejects_oversized_output() -> None:
+    compressed = zstandard.ZstdCompressor().compress(b"x" * 128)
+
+    with pytest.raises(ValueError, match="output too large"):
+        ZstdCompression().decompress(compressed, max_output=64)
+
+
 def test_lz4_decompresses_literals_and_rejects_invalid_blocks() -> None:
     compression = Lz4BlockCompression()