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

pymax/infra/message.py

@@ -2,6 +2,7 @@ from pymax.api.messages import DateTimeUnion
 from pymax.api.messages.enums import ItemType
 from pymax.api.messages.service import SendAttachments
 from pymax.types import (
+    CommentsInfoUpdate,
     FileRequest,
     Message,
     PollState,
@@ -336,15 +337,11 @@ class MessageMixin(IClientProtocol):
             message_id=message_id,
         )
 
-    async def read_message(self, message_id: int | str, chat_id: int) -> ReadState:
+    async def read_message(self, message_id: int, chat_id: int) -> ReadState:
         """Отмечает сообщение как прочитанное.
 
-        У Max различается wire-формат ``message_id`` для отметки прочтения:
-        TCP-клиент ожидает ``int``, WebSocket-клиент - ``str``.
-
         Args:
-            message_id: ID сообщения. Передавайте ``int`` для ``Client`` и
-                ``str`` для ``WebClient``.
+            message_id: ID сообщения как ``int`` для ``Client`` и ``WebClient``.
             chat_id: ID чата.
 
         Returns:
@@ -379,3 +376,195 @@ class MessageMixin(IClientProtocol):
             poll_id=poll_id,
             answer_ids=answer_ids,
         )
+
+    async def send_comment(
+        self,
+        chat_id: int,
+        post_id: int,
+        text: str | None = None,
+        reply_to: int | None = None,
+        attachments: SendAttachments = None,
+        *,
+        notify: bool = True,
+    ) -> Message:
+        """Отправляет комментарий к посту канала.
+
+        Args:
+            chat_id: ID канала.
+            post_id: ID поста в канале.
+            text: Текст комментария с поддержкой Markdown.
+            reply_to: ID комментария, на который нужно ответить.
+            attachments: Вложения комментария.
+            notify: Отправить уведомление о комментарии.
+
+        Returns:
+            Опубликованный комментарий как ``Message``.
+        """
+        return await self._app.api.messages.send_comment(
+            chat_id=chat_id,
+            post_id=post_id,
+            text=text,
+            reply_to=reply_to,
+            attachments=attachments,
+            notify=notify,
+        )
+
+    async def fetch_comments(
+        self,
+        chat_id: int,
+        post_id: int,
+        from_: int | None = None,
+        backward: int = 30,
+        get_messages: bool = True,
+        forward: int = 0,
+    ) -> list[Message]:
+        """Возвращает страницу комментариев поста канала.
+
+        ``chat_id`` задает канал, ``post_id`` — пост внутри него.
+        ``backward`` и ``forward`` задают количество комментариев по сторонам
+        от ``from_``. При ``from_=None`` используется начальная позиция Max.
+        """
+        return await self._app.api.messages.fetch_comments(
+            chat_id=chat_id,
+            post_id=post_id,
+            from_=from_,
+            backward=backward,
+            get_messages=get_messages,
+            forward=forward,
+        )
+
+    async def get_comments(
+        self,
+        chat_id: int,
+        post_id: int,
+        message_ids: list[int],
+    ) -> list[Message]:
+        """Возвращает конкретные комментарии поста по их ID.
+
+        ``chat_id`` задает канал, ``post_id`` — пост, а ``message_ids`` —
+        ID запрашиваемых комментариев.
+        """
+        return await self._app.api.messages.get_comments(
+            chat_id=chat_id,
+            post_id=post_id,
+            message_ids=message_ids,
+        )
+
+    async def get_comment(
+        self,
+        chat_id: int,
+        post_id: int,
+        message_id: int,
+    ) -> Message | None:
+        """Возвращает комментарий по ID или ``None``, если он не найден."""
+        return await self._app.api.messages.get_comment(
+            chat_id=chat_id,
+            post_id=post_id,
+            message_id=message_id,
+        )
+
+    async def edit_comment(
+        self,
+        chat_id: int,
+        post_id: int,
+        message_id: int,
+        text: str | None = None,
+        attachments: SendAttachments = None,
+    ) -> Message:
+        """Редактирует текст и вложения комментария. Текст поддерживает markdown."""
+        return await self._app.api.messages.edit_comment(
+            chat_id=chat_id,
+            post_id=post_id,
+            message_id=message_id,
+            text=text,
+            attachments=attachments,
+        )
+
+    async def delete_comment(
+        self,
+        chat_id: int,
+        post_id: int,
+        message_ids: list[int],
+        for_me: bool = False,
+    ) -> bool:
+        """Удаляет комментарии поста. По умолчанию удаляет для всех."""
+        return await self._app.api.messages.delete_comment(
+            chat_id=chat_id,
+            post_id=post_id,
+            message_ids=message_ids,
+            for_me=for_me,
+        )
+
+    async def add_comment_reaction(
+        self,
+        chat_id: int,
+        post_id: int,
+        message_id: int,
+        reaction: str,
+    ) -> ReactionInfo | None:
+        """Добавляет или заменяет свою emoji-реакцию на комментарии."""
+        return await self._app.api.messages.add_comment_reaction(
+            chat_id=chat_id,
+            post_id=post_id,
+            message_id=message_id,
+            reaction=reaction,
+        )
+
+    async def remove_comment_reaction(
+        self,
+        chat_id: int,
+        post_id: int,
+        message_id: int,
+    ) -> ReactionInfo | None:
+        """Удаляет свою реакцию с комментария."""
+        return await self._app.api.messages.remove_comment_reaction(
+            chat_id=chat_id,
+            post_id=post_id,
+            message_id=message_id,
+        )
+
+    async def subscribe_comments(
+        self,
+        chat_id: int,
+        post_id: int,
+        subscribe: bool = True,
+    ) -> None:
+        """Подписывается на события ветки комментариев.
+
+        Для поддержания подписки повторяйте вызов раз в минуту.
+        ``subscribe=False`` отменяет подписку.
+        """
+        return await self._app.api.messages.subscribe_comments(
+            chat_id=chat_id,
+            post_id=post_id,
+            subscribe=subscribe,
+        )
+
+    async def get_comments_info(
+        self,
+        chat_id: int,
+        post_ids: list[int],
+    ) -> list[CommentsInfoUpdate]:
+        """Возвращает список обновлений счетчиков комментариев постов."""
+        return await self._app.api.messages.get_comments_info(
+            chat_id=chat_id,
+            post_ids=post_ids,
+        )
+
+    async def delete_user_comments(
+        self,
+        chat_id: int,
+        post_id: int,
+        user_id: int,
+        message_id: int,
+    ) -> bool:
+        """Удаляет комментарии автора в ветке указанного поста.
+
+        ``message_id`` — ID комментария этого автора.
+        """
+        return await self._app.api.messages.delete_user_comments(
+            chat_id=chat_id,
+            post_id=post_id,
+            user_id=user_id,
+            message_id=message_id,
+        )

pymax/infra/stories.py

@@ -0,0 +1,205 @@
+from pymax.api.stories import StoryStatsFilter
+from pymax.files import Photo, Video
+from pymax.types.domain import Story, StoryDetailedStats, StoryPreview
+
+from .protocol import IClientProtocol
+
+
+class StoriesMixin(IClientProtocol):
+    """Методы клиента для публикации, чтения и удаления сторис."""
+
+    async def send_story(
+        self,
+        media: Photo | Video,
+        *,
+        duration: int | None = None,
+        link: str | None = None,
+    ) -> Story:
+        """Публикует фото или видео в сторис на 48 часов.
+
+        Args:
+            media: Фото или видео. Принимает локальный файл, URL или байты
+                через ``Photo`` или ``Video``.
+            duration: Положительная длительность видео в миллисекундах.
+                Обязательна для ``Video``; автоматически не определяется.
+            link: Необязательная ссылка в нижней части кадра.
+
+        Returns:
+            Опубликованная сторис.
+
+        Raises:
+            ValueError: Если длительность видео не задана или неположительна.
+            TypeError: Если передан неподдерживаемый тип медиа.
+        """
+        return await self._app.api.stories.send_story(
+            media=media,
+            duration=duration,
+            link=link,
+        )
+
+    async def get_stories(self, owner_id: int, owner_type: int = 0) -> list[Story]:
+        """Возвращает сторис указанного владельца.
+
+        Args:
+            owner_id: ID владельца, чьи сторис нужно получить.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            Список сторис. Если сторис нет, возвращается пустой список.
+        """
+        return await self._app.api.stories.get_stories(owner_id=owner_id, owner_type=owner_type)
+
+    async def delete_story(self, story_id: int) -> bool:
+        """Удаляет сторис по ее ID.
+
+        Args:
+            story_id: ID удаляемой сторис.
+
+        Returns:
+            ``True``, если запрос завершился без API-ошибки.
+        """
+        return await self._app.api.stories.delete_story(story_id=story_id)
+
+    async def get_stories_feed(
+        self,
+        cursor: str = "0",
+        count: int = 15,
+    ) -> tuple[list[StoryPreview], str]:
+        """Возвращает страницу превью владельцев сторис.
+
+        Превью не содержит ID отдельных сторис. Для их получения используйте
+        ``get_stories(preview.owner.owner_id, preview.owner.type)``.
+
+        Args:
+            cursor: Курсор страницы. ``"0"`` запрашивает первую страницу.
+            count: Количество превью в запрашиваемой странице.
+
+        Returns:
+            ``(previews, next_cursor)``. Передайте ``next_cursor`` в следующий
+            вызов. Пустая строка означает, что дальше страниц нет.
+        """
+        return await self._app.api.stories.get_stories_feed(cursor=cursor, count=count)
+
+    async def get_stories_by_id(
+        self,
+        owner_id: int,
+        story_ids: list[int],
+        owner_type: int = 0,
+    ) -> list[Story]:
+        """Возвращает конкретные сторис владельца по их ID.
+
+        Args:
+            owner_id: ID владельца сторис.
+            story_ids: ID запрашиваемых сторис.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            Список найденных сторис.
+        """
+        return await self._app.api.stories.get_stories_by_id(
+            owner_id=owner_id,
+            story_ids=story_ids,
+            owner_type=owner_type,
+        )
+
+    async def get_story_detailed_stats(
+        self,
+        story_id: int,
+        filter: StoryStatsFilter,
+        marker: int = 0,
+    ) -> tuple[list[StoryDetailedStats], int]:
+        """Возвращает страницу подробной статистики сторис.
+
+        Args:
+            story_id: ID сторис.
+            filter: ``StoryStatsFilter.VIEWS`` — просмотры,
+                ``StoryStatsFilter.REACTIONS`` — реакции.
+            marker: Маркер страницы. ``0`` запрашивает первую страницу.
+
+        Returns:
+            ``(stats, next_marker)``. Нулевой маркер означает конец списка.
+        """
+        return await self._app.api.stories.get_story_detailed_stats(
+            story_id=story_id,
+            filter=filter,
+            marker=marker,
+        )
+
+    async def read_story(self, story_id: int, owner_id: int, owner_type: int = 0) -> bool:
+        """Отмечает сторис просмотренной.
+
+        Args:
+            story_id: ID просмотренной сторис.
+            owner_id: ID владельца сторис.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            ``True``, если запрос завершился без API-ошибки.
+        """
+        return await self._app.api.stories.read_story(
+            story_id=story_id,
+            owner_id=owner_id,
+            owner_type=owner_type,
+        )
+
+    async def edit_story(self, story_id: int, settings: int) -> Story:
+        """Меняет настройки опубликованной сторис.
+
+        Args:
+            story_id: ID редактируемой сторис.
+            settings: Битовая маска настроек в формате Max.
+
+        Returns:
+            Обновленная сторис.
+        """
+        return await self._app.api.stories.edit_story(story_id=story_id, settings=settings)
+
+    async def add_story_reaction(
+        self,
+        owner_id: int,
+        story_id: int,
+        reaction: str,
+        reaction_type: int = 0,
+        owner_type: int = 0,
+    ) -> bool:
+        """Добавляет или заменяет свою реакцию на сторис.
+
+        Args:
+            owner_id: ID владельца сторис.
+            story_id: ID сторис.
+            reaction: Эмодзи или строковый ID реакции.
+            reaction_type: ``0`` для эмодзи, ``1`` для реакции по ID.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            Значение ``success`` из ответа Max.
+        """
+        return await self._app.api.stories.add_story_reaction(
+            owner_id=owner_id,
+            story_id=story_id,
+            reaction=reaction,
+            reaction_type=reaction_type,
+            owner_type=owner_type,
+        )
+
+    async def remove_story_reaction(
+        self,
+        owner_id: int,
+        story_id: int,
+        owner_type: int = 0,
+    ) -> bool:
+        """Снимает свою реакцию со сторис.
+
+        Args:
+            owner_id: ID владельца сторис.
+            story_id: ID сторис.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            Значение ``success`` из ответа Max.
+        """
+        return await self._app.api.stories.remove_story_reaction(
+            owner_id=owner_id,
+            story_id=story_id,
+            owner_type=owner_type,
+        )

pymax/integrations/dishka.py

@@ -0,0 +1,109 @@
+from pymax import Router
+
+try:
+    from dishka import AsyncContainer
+    from dishka.integrations.base import is_dishka_injected, wrap_injection
+except ImportError as e:
+    raise RuntimeError(
+        "Dishka integration requires the 'dishka' extra. "
+        "Install it with `uv add 'maxapi-python[dishka]'`"
+    ) from e
+
+from collections.abc import Callable, Generator
+from typing import Any, ParamSpec, TypeVar
+from weakref import WeakKeyDictionary
+
+from pymax.base import BaseClient
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+_containers: WeakKeyDictionary[BaseClient[Any], AsyncContainer] = WeakKeyDictionary()
+ClientT = TypeVar("ClientT", bound=BaseClient)
+
+
+def _get_client(
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> BaseClient[Any]:
+    client = kwargs.get("client")
+
+    if isinstance(client, BaseClient):
+        return client
+
+    for arg in reversed(args):
+        if isinstance(arg, BaseClient):
+            return arg
+
+    raise RuntimeError("Cannot resolve PyMax client for Dishka injection")
+
+
+def _get_container(
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> AsyncContainer:
+    client = _get_client(args, kwargs)
+
+    try:
+        return _containers[client]
+    except KeyError:
+        raise RuntimeError(
+            "Dishka is not configured for this client. Call setup_dishka(container, client)."
+        ) from None
+
+
+def inject(func: Callable[P, T]) -> Callable[P, T]:
+    """Внедряет параметры ``FromDishka[T]`` в обработчик события.
+
+    Размещайте ``@inject`` под декоратором регистрации обработчика,
+    например ``@router.on_message()``. Контейнер для переданного в обработчик
+    клиента должен быть зарегистрирован через ``setup_dishka()``.
+    """
+    return wrap_injection(
+        func=func,
+        is_async=True,
+        container_getter=_get_container,
+    )
+
+
+def inject_router(router: Router[ClientT]) -> None:
+    """Оборачивает уже зарегистрированные обработчики роутера и его детей.
+
+    Пропускает обработчики, уже обернутые через ``inject``. Не затрагивает
+    ``on_start``, ``on_error``, ``on_disconnect`` и последующие регистрации.
+    """
+    for current_router in _iter_routers(router):
+        for entries in current_router.handlers.values():
+            for entry in entries:
+                if not is_dishka_injected(entry.callback):
+                    entry.callback = inject(entry.callback)
+
+
+def _iter_routers(router: Router[ClientT]) -> Generator[Router[ClientT] | Any, Any, None]:
+    yield router
+
+    for child in router.children:
+        yield from _iter_routers(child)
+
+
+def setup_dishka(
+    container: AsyncContainer,
+    client: BaseClient[Any],
+    *,
+    auto_inject: bool = False,
+) -> None:
+    """Привязывает контейнер Dishka к клиенту.
+
+    Args:
+        container: Контейнер, из которого обработчики получают зависимости.
+        client: Клиент, для которого включается интеграция.
+        auto_inject: Обернуть уже зарегистрированные обработчики всего дерева
+            роутеров клиента. По умолчанию используется явный ``@inject``.
+
+    Интеграция не открывает отдельный scope для события, не добавляет событие
+    или клиента в контекст Dishka и не закрывает контейнер автоматически.
+    """
+    _containers[client] = container
+
+    if auto_inject:
+        inject_router(client._router)

pymax/protocol/enums.py

@@ -85,7 +85,9 @@ class Opcode(int, Enum):
     FILE_UPLOAD = 87
     FILE_DOWNLOAD = 88
     LINK_INFO = 89
+    MSG_GET_COMMENTS_INFO = 91
     MSG_DELETE_RANGE = 92
+    MSG_DELETE_USER_COMMENTS = 94
     SESSIONS_INFO = 96
     SESSIONS_CLOSE = 97
     PHONE_BIND_REQUEST = 98

pymax/protocol/tcp/payload.py

@@ -128,8 +128,6 @@ class TcpPayloadDecoder:
             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")

pymax/types/domain/__init__.py

@@ -1,15 +1,37 @@
 from .attachments import *
 from .bots import InitData
+from .callback import CallbackResponse
 from .chat import Chat
+from .comment import CommentsInfo, CommentsInfoUpdate
 from .error import MaxApiError
 from .folder import Folder, FolderList, FolderUpdate
 from .handshake import HandshakeResponse
 from .login import Login2Flags, Login2Response, LoginResponse
 from .member import Member
-from .message import Message, ReactionCounter, ReactionInfo, ReadState
+from .message import (
+    ForwardLink,
+    LinkType,
+    Message,
+    ReactionCounter,
+    ReactionInfo,
+    ReadState,
+    ReplyLink,
+)
 from .name import Name
 from .presence import Presence
 from .profile import Profile
 from .session import Session
+from .story import (
+    Story,
+    StoryClickableLink,
+    StoryCoordinates,
+    StoryDetailedStats,
+    StoryLayer,
+    StoryMedia,
+    StoryOwner,
+    StoryPhotoMedia,
+    StoryPreview,
+    StoryVideoMedia,
+)
 from .sync import SyncOverrides, SyncState
 from .user import ContactInfo, User

pymax/types/domain/attachments/__init__.py

@@ -4,7 +4,7 @@ from .contact import ContactAttachment
 from .control import ControlAttachment
 from .enums import AttachmentType, PollFlags
 from .file import FileAttachment, FileRequest
-from .keyboards import InlineKeyboardAttachment
+from .keyboards import Button, ButtonType, InlineKeyboardAttachment
 from .photo import PhotoAttachment
 from .poll import Poll, PollAnswer, PollAttachment, PollState
 from .share import ShareAttachment

pymax/types/domain/attachments/keyboards/__init__.py

@@ -1 +1 @@
-from .inline import InlineKeyboardAttachment
+from .inline import Button, ButtonType, InlineKeyboardAttachment

pymax/types/domain/attachments/keyboards/enums.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class ButtonType(str, Enum):
+    CALLBACK = "CALLBACK"
+    LINK = "LINK"
+    CHAT = "CHAT"
+    REQUEST_GEO_LOCATION = "REQUEST_GEO_LOCATION"
+    REQUEST_CONTACT = "REQUEST_CONTACT"
+    OPEN_APP = "OPEN_APP"
+    MESSAGE = "MESSAGE"
+    CLIPBOARD = "CLIPBOARD"