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

pymax/fsm/storage.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, AsyncGenerator
+
+from pymax.fsm.context import FSMContext, FSMKey
+from pymax.types.domain.message import Message
+
+from .protocol import FSMStorage
+from .state import State
+
+if TYPE_CHECKING:
+    from pymax.base import BaseClient
+    from pymax.dispatch import DispatchEvent
+
+
+class InMemoryFSMStorage:
+    def __init__(self) -> None:
+        self.records: dict[FSMKey, InMemoryFSM] = {}
+        self.locks: dict[FSMKey, asyncio.Lock] = {}
+
+    def resolve_key(
+        self,
+        client: BaseClient,
+        event: DispatchEvent,
+    ) -> FSMKey | None:
+        if not isinstance(event, Message):
+            return None
+
+        if event.chat_id is None or event.sender is None:
+            return None
+
+        return FSMKey(
+            client_id=hash(client),
+            user_id=event.sender,
+            chat_id=event.chat_id,
+        )
+
+    def get_context(
+        self,
+        client: BaseClient,
+        event: Message,
+    ) -> FSMContext | None:
+        if not event.chat_id or not event.sender:
+            return None
+
+        key = self.resolve_key(client, event)
+
+        if not key:
+            return None
+
+        record = self.records.get(key)
+        if record is None:
+            record = InMemoryFSM()
+            self.records[key] = record
+
+        return FSMContext(storage=record, key=key)
+
+    @asynccontextmanager
+    async def isolate(
+        self,
+        client: BaseClient,
+        event: DispatchEvent,
+    ) -> AsyncGenerator[None]:
+        key = self.resolve_key(client, event)
+
+        if key is None:
+            yield
+            return
+
+        lock = self.locks.setdefault(key, asyncio.Lock())
+
+        async with lock:
+            yield
+
+
+@dataclass
+class FsmState:
+    value: str | None = None
+    created_at: datetime = datetime.now()
+    ttl: int | None = None
+
+
+class InMemoryFSM(FSMStorage):
+    """Состояние и данные одного FSM-контекста в памяти процесса.
+
+    В обработчике это хранилище доступно как ``ctx.storage``.
+    """
+
+    def __init__(self) -> None:
+        self.state: FsmState = FsmState()
+        self.data: dict[str, Any] = {}
+        self.lock = asyncio.Lock()
+
+    async def get_state(self) -> str | None:
+        """Возвращает имя состояния или ``None``, если оно не задано или истек TTL.
+
+        Истечение TTL сбрасывает только состояние, сохраняя данные контекста.
+        """
+        async with self.lock:
+            if self.state.ttl is None:
+                return self.state.value
+
+            expires_at = self.state.created_at.timestamp() + self.state.ttl
+
+            if datetime.now().timestamp() >= expires_at:
+                self.state = FsmState()
+                return None
+
+            return self.state.value
+
+    async def set_state(self, state: str | State | None, ttl: int | None = None) -> None:
+        """Устанавливает состояние, сохраняя данные контекста.
+
+        Args:
+            state: Состояние, его строковое имя или ``None`` для сброса.
+            ttl: Срок действия в секундах с момента установки.
+                ``None`` означает отсутствие срока действия.
+        """
+        async with self.lock:
+            if state is None:
+                self.state = FsmState()
+                return
+
+            self.state.value = str(state)
+            self.state.ttl = ttl
+            self.state.created_at = datetime.now()
+
+    async def get_data(self) -> dict[str, Any]:
+        """Возвращает поверхностную копию словаря данных контекста."""
+        async with self.lock:
+            return self.data.copy()
+
+    async def set_data(self, key: str, value: Any) -> None:
+        """Записывает одно значение, сохраняя остальные ключи данных."""
+        async with self.lock:
+            self.data[key] = value
+
+    async def update_data(self, **data: Any) -> None:
+        """Добавляет или перезаписывает переданные ключи данных."""
+        async with self.lock:
+            self.data.update(data)
+
+    async def clear(self) -> None:
+        """Сбрасывает состояние и удаляет все данные текущего контекста."""
+        async with self.lock:
+            self.state = FsmState()
+            self.data.clear()

pymax/infra/base.py

@@ -3,6 +3,7 @@ from .bots import BotsMixin
 from .chat import ChatMixin
 from .message import MessageMixin
 from .self import SelfMixin
+from .stories import StoriesMixin
 from .user import UserMixin
 
 
@@ -13,5 +14,6 @@ class BaseMixin(
     MessageMixin,
     BotsMixin,
     AuthMixin,
+    StoriesMixin,
 ):
     """Собирает публичные API-методы клиента."""

pymax/infra/bots.py

@@ -1,3 +1,4 @@
+from pymax.types import ButtonType, CallbackResponse
 from pymax.types.domain import InitData
 
 from .protocol import IClientProtocol
@@ -31,3 +32,22 @@ class BotsMixin(IClientProtocol):
             chat_id=chat_id,
             start_param=start_param,
         )
+
+    async def send_callback(
+        self,
+        callback_id: str,
+        type: ButtonType,
+        payload: str | None = None,
+    ) -> CallbackResponse:
+        """Передает нажатие inline-кнопки бота.
+
+        Args:
+            callback_id: ID из ``InlineKeyboardAttachment.callback_id``.
+            type: Тип нажатой кнопки.
+            payload: Данные кнопки, если они есть.
+
+        Returns:
+            Результат нажатия. ``message`` и ``chat`` содержатся в нем,
+            только если Max вернул эти объекты.
+        """
+        return await self._app.api.bots.send_callback(callback_id, type, payload)

pymax/infra/chat.py

@@ -1,4 +1,5 @@
 from pymax.api.chats import ChannelPermissions
+from pymax.files import Photo
 from pymax.types import Chat, Member, Message
 
 from .protocol import IClientProtocol
@@ -131,20 +132,23 @@ class ChatMixin(IClientProtocol):
     async def change_group_profile(
         self,
         chat_id: int,
-        name: str | None,
+        name: str | None = None,
         description: str | None = None,
+        photo: Photo | None = None,
     ) -> None:
-        """Обновляет название и описание группы.
+        """Обновляет название, описание или фотографию группы.
+
+        ``None`` исключает соответствующее поле из запроса. Фотография
+        автоматически загружается перед обновлением профиля.
 
         Args:
             chat_id: ID группы.
             name: Новое название.
             description: Новое описание.
+            photo: Новая фотография группы.
         """
         await self._app.api.chats.change_group_profile(
-            chat_id=chat_id,
-            name=name,
-            description=description,
+            chat_id=chat_id, name=name, description=description, photo=photo
         )
 
     async def join_group(self, link: str) -> Chat:
@@ -410,3 +414,31 @@ class ChatMixin(IClientProtocol):
             permissions: Непустой список прав администратора.
         """
         return await self._app.api.chats.add_admin(chat_id, user_id, permissions)
+
+    async def set_channel_comments(self, chat_id: int, enabled: bool) -> None:
+        """Включает или выключает комментарии канала."""
+        return await self._app.api.chats.set_channel_comments(
+            chat_id=chat_id,
+            enabled=enabled,
+        )
+
+    async def block_comment_author(
+        self,
+        chat_id: int,
+        post_id: int,
+        user_ids: list[int],
+        message_id: int,
+        clean_msg_period: int = 0,
+    ) -> bool:
+        """Блокирует авторов в комментариях.
+
+        ``message_id`` — ID комментария для модерации.
+        ``clean_msg_period=0`` сохраняет комментарии, ``-1`` также удаляет их.
+        """
+        return await self._app.api.chats.block_comment_author(
+            chat_id=chat_id,
+            post_id=post_id,
+            user_ids=user_ids,
+            message_id=message_id,
+            clean_msg_period=clean_msg_period,
+        )

pymax/infra/message.py

@@ -1,6 +1,8 @@
+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,
@@ -23,6 +25,7 @@ class MessageMixin(IClientProtocol):
         attachments: SendAttachments = None,
         *,
         notify: bool = True,
+        send_at: DateTimeUnion | None = None,
     ) -> Message:
         """Отправляет сообщение в чат.
 
@@ -32,6 +35,9 @@ class MessageMixin(IClientProtocol):
             reply_to: ID сообщения для ответа.
             attachments: Файлы, фотографии, видео или опросы для отправки.
             notify: Отправить ли получателям push-уведомление.
+            send_at: Время отложенной отправки: ``datetime`` для абсолютного
+                времени, ``timedelta`` для задержки или Unix time в секундах
+                как ``int``. ``None`` и ``0`` отправляют сообщение сразу.
 
         Returns:
             Отправленное сообщение.
@@ -45,6 +51,7 @@ class MessageMixin(IClientProtocol):
             reply_to,
             attachments,
             notify=notify,
+            send_at=send_at,
         )
 
     async def get_message(
@@ -272,7 +279,7 @@ class MessageMixin(IClientProtocol):
     async def add_reaction(
         self,
         chat_id: int,
-        message_id: str,
+        message_id: int,
         reaction: str,
     ) -> ReactionInfo | None:
         """Добавляет реакцию к сообщению.
@@ -294,7 +301,7 @@ class MessageMixin(IClientProtocol):
     async def get_reactions(
         self,
         chat_id: int,
-        message_ids: list[str],
+        message_ids: list[int],
     ) -> dict[str, ReactionInfo] | None:
         """Возвращает реакции для нескольких сообщений.
 
@@ -314,7 +321,7 @@ class MessageMixin(IClientProtocol):
     async def remove_reaction(
         self,
         chat_id: int,
-        message_id: str,
+        message_id: int,
     ) -> ReactionInfo | None:
         """Удаляет свою реакцию с сообщения.
 
@@ -330,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:
@@ -373,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/protocol.py

@@ -6,4 +6,8 @@ from pymax.app import App
 class IClientProtocol(Protocol):
     """Описывает минимальный клиент, нужный infra-миксинам."""
 
-    _app: App
+    @property
+    def _app(self) -> App: ...
+
+    @_app.setter
+    def _app(self, value: App) -> None: ...