From 3eaf39e5c2276800bd1c782138d567d5537e99e4 Mon Sep 17 00:00:00 2001 From: Emre K <110906681+kocaemre@users.noreply.github.com> Date: Thu, 3 Sep 2026 04:39:21 +0200 Subject: [PATCH 01/31] fix: preserve intraword markdown markers Signed-off-by: Emre K <110906681+kocaemre@users.noreply.github.com> --- src/pymax/formatting/markdown.py | 28 +++++++++++++++++++++++- tests/files/test_files_and_formatting.py | 26 ++++++++++++++++++++++ 2 files changed, 53 insertions(+), 1 deletion(-) diff --git a/src/pymax/formatting/markdown.py b/src/pymax/formatting/markdown.py index d84cbdf..868f9d5 100644 --- a/src/pymax/formatting/markdown.py +++ b/src/pymax/formatting/markdown.py @@ -51,6 +51,29 @@ def _parse_link( return label, url, url_end + 1 + @staticmethod + def _is_intraword_single_marker(text: str, i: int, marker: str) -> bool: + if marker not in {"_", "*"}: + return False + if i == 0 or i + 1 >= len(text): + return False + return text[i - 1].isalnum() and text[i + 1].isalnum() + + @staticmethod + def _find_closing_marker( + text: str, + marker: str, + start: int, + end: int | None = None, + ) -> int: + while True: + closing_index = text.find(marker, start, len(text) if end is None else end) + if closing_index == -1: + return -1 + if not Formatter._is_intraword_single_marker(text, closing_index, marker): + return closing_index + start = closing_index + len(marker) + @staticmethod def format_markdown(text: str) -> tuple[str, list[Element]]: clean_text = "" @@ -155,6 +178,8 @@ def format_markdown(text: str) -> tuple[str, list[Element]]: for marker in Formatter.MARKER_ORDER: if not text.startswith(marker, i): continue + if Formatter._is_intraword_single_marker(text, i, marker): + continue marker_len = len(marker) @@ -180,7 +205,8 @@ def format_markdown(text: str) -> tuple[str, list[Element]]: break end = text.find("\n", i + marker_len) - closing_index = text.find( + closing_index = Formatter._find_closing_marker( + text, marker, i + marker_len, None if end == -1 else end, diff --git a/tests/files/test_files_and_formatting.py b/tests/files/test_files_and_formatting.py index d73a3eb..fcdde03 100644 --- a/tests/files/test_files_and_formatting.py +++ b/tests/files/test_files_and_formatting.py @@ -70,3 +70,29 @@ def test_markdown_formatter_extracts_functional_entities() -> None: ] assert entities[-1].attributes is not None assert entities[-1].attributes.url == "https://example.com" + + +def test_markdown_formatter_preserves_intraword_single_markers() -> None: + text = "https://max.ru/channel_iclub_new snake_case_name цена 5*2 = 10" + + clean, entities = Formatter.format_markdown(text) + + assert clean == text + assert entities == [] + + +def test_markdown_formatter_preserves_unclosed_single_marker_before_intraword_marker() -> None: + clean, entities = Formatter.format_markdown("_foo_bar") + + assert clean == "_foo_bar" + assert entities == [] + + +def test_markdown_formatter_still_parses_delimited_single_marker_emphasis() -> None: + clean, entities = Formatter.format_markdown("Hello _world_ and *again*") + + assert clean == "Hello world and again" + assert [(entity.type, entity.from_, entity.length) for entity in entities] == [ + ("EMPHASIZED", 6, 5), + ("EMPHASIZED", 16, 5), + ] From 884ace5ce15c2c375ce06096d2d0228d516441ca Mon Sep 17 00:00:00 2001 From: Emre K <110906681+kocaemre@users.noreply.github.com> Date: Mon, 7 Sep 2026 00:20:09 +0200 Subject: [PATCH 02/31] fix: keep intraword asterisk emphasis Signed-off-by: Emre K <110906681+kocaemre@users.noreply.github.com> --- src/pymax/formatting/markdown.py | 2 +- tests/files/test_files_and_formatting.py | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/src/pymax/formatting/markdown.py b/src/pymax/formatting/markdown.py index 868f9d5..f0b12c7 100644 --- a/src/pymax/formatting/markdown.py +++ b/src/pymax/formatting/markdown.py @@ -53,7 +53,7 @@ def _parse_link( @staticmethod def _is_intraword_single_marker(text: str, i: int, marker: str) -> bool: - if marker not in {"_", "*"}: + if marker != "_": return False if i == 0 or i + 1 >= len(text): return False diff --git a/tests/files/test_files_and_formatting.py b/tests/files/test_files_and_formatting.py index fcdde03..598cc2e 100644 --- a/tests/files/test_files_and_formatting.py +++ b/tests/files/test_files_and_formatting.py @@ -96,3 +96,12 @@ def test_markdown_formatter_still_parses_delimited_single_marker_emphasis() -> N ("EMPHASIZED", 6, 5), ("EMPHASIZED", 16, 5), ] + + +def test_markdown_formatter_still_parses_intraword_asterisk_emphasis() -> None: + clean, entities = Formatter.format_markdown("foo*bar*baz") + + assert clean == "foobarbaz" + assert [(entity.type, entity.from_, entity.length) for entity in entities] == [ + ("EMPHASIZED", 3, 3), + ] From 7186a30a79c1fdb24c26133ffc6107fdb816f699 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Wed, 5 Aug 2026 19:50:14 +0300 Subject: [PATCH 03/31] feat: add callback and message link support --- src/pymax/api/bots/payloads.py | 8 +++ src/pymax/api/bots/service.py | 13 +++- src/pymax/infra/bots.py | 9 +++ src/pymax/types/domain/__init__.py | 11 ++- .../types/domain/attachments/__init__.py | 2 +- .../domain/attachments/keyboards/__init__.py | 2 +- .../domain/attachments/keyboards/enums.py | 12 ++++ .../domain/attachments/keyboards/inline.py | 70 ++++++++++++++++++- src/pymax/types/domain/callback.py | 12 ++++ src/pymax/types/domain/message.py | 9 ++- 10 files changed, 140 insertions(+), 8 deletions(-) create mode 100644 src/pymax/types/domain/attachments/keyboards/enums.py create mode 100644 src/pymax/types/domain/callback.py diff --git a/src/pymax/api/bots/payloads.py b/src/pymax/api/bots/payloads.py index 34a99a3..38ac3d4 100644 --- a/src/pymax/api/bots/payloads.py +++ b/src/pymax/api/bots/payloads.py @@ -1,7 +1,15 @@ from pymax.api.models import CamelModel +from pymax.types import ButtonType class RequestInitDataPayload(CamelModel): bot_id: int chat_id: int | None = None start_param: str | None = None + + +class SendCallbackPayload(CamelModel): + callback_id: str + type: ButtonType + payload: str | None = None + timestamp: int diff --git a/src/pymax/api/bots/service.py b/src/pymax/api/bots/service.py index ecb5c9e..24ccd90 100644 --- a/src/pymax/api/bots/service.py +++ b/src/pymax/api/bots/service.py @@ -1,13 +1,15 @@ from __future__ import annotations +import time from typing import TYPE_CHECKING from pymax.api.response import require_payload_model from pymax.logging import get_logger from pymax.protocol import Opcode +from pymax.types import ButtonType, CallbackResponse from pymax.types.domain import InitData -from .payloads import RequestInitDataPayload +from .payloads import RequestInitDataPayload, SendCallbackPayload if TYPE_CHECKING: from pymax.app import App @@ -29,3 +31,12 @@ async def get_init_data( frame = RequestInitDataPayload(bot_id=bot_id, chat_id=chat_id, start_param=start_param) response = await self.app.invoke(Opcode.WEB_APP_INIT_DATA, frame.to_payload()) return require_payload_model(response, InitData) + + async def send_callback( + self, callback_id: str, type: ButtonType, payload: str | None = None + ) -> CallbackResponse: + frame = SendCallbackPayload( + callback_id=callback_id, type=type, payload=payload, timestamp=int(time.time() * 1000) + ) + response = await self.app.invoke(Opcode.MSG_SEND_CALLBACK, frame.to_payload()) + return require_payload_model(response, CallbackResponse) diff --git a/src/pymax/infra/bots.py b/src/pymax/infra/bots.py index 8688acb..9ea9828 100644 --- a/src/pymax/infra/bots.py +++ b/src/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,11 @@ async def get_bot_init_data( chat_id=chat_id, start_param=start_param, ) + + async def send_callback( + self, + callback_id: str, + type: ButtonType, + payload: str | None = None, + ) -> CallbackResponse: + return await self._app.api.bots.send_callback(callback_id, type, payload) diff --git a/src/pymax/types/domain/__init__.py b/src/pymax/types/domain/__init__.py index 7e1d0c4..dbe4603 100644 --- a/src/pymax/types/domain/__init__.py +++ b/src/pymax/types/domain/__init__.py @@ -1,12 +1,21 @@ from .attachments import * from .bots import InitData +from .callback import CallbackResponse from .chat import Chat 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 diff --git a/src/pymax/types/domain/attachments/__init__.py b/src/pymax/types/domain/attachments/__init__.py index 0aac71c..d700d02 100644 --- a/src/pymax/types/domain/attachments/__init__.py +++ b/src/pymax/types/domain/attachments/__init__.py @@ -4,7 +4,7 @@ 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 diff --git a/src/pymax/types/domain/attachments/keyboards/__init__.py b/src/pymax/types/domain/attachments/keyboards/__init__.py index 8360f4a..3e9ab16 100644 --- a/src/pymax/types/domain/attachments/keyboards/__init__.py +++ b/src/pymax/types/domain/attachments/keyboards/__init__.py @@ -1 +1 @@ -from .inline import InlineKeyboardAttachment +from .inline import Button, ButtonType, InlineKeyboardAttachment diff --git a/src/pymax/types/domain/attachments/keyboards/enums.py b/src/pymax/types/domain/attachments/keyboards/enums.py new file mode 100644 index 0000000..e2f59c9 --- /dev/null +++ b/src/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" diff --git a/src/pymax/types/domain/attachments/keyboards/inline.py b/src/pymax/types/domain/attachments/keyboards/inline.py index c749888..52c6352 100644 --- a/src/pymax/types/domain/attachments/keyboards/inline.py +++ b/src/pymax/types/domain/attachments/keyboards/inline.py @@ -1,10 +1,75 @@ -from typing import Any, Literal +from typing import Annotated, Any, Literal, TypeAlias from pydantic import Field from pymax.types.domain.attachments import AttachmentType from pymax.types.domain.base import CamelModel +from .enums import ButtonType + + +class BaseButton(CamelModel): + text: str + + +class CallbackButton(BaseButton): + type: Literal[ButtonType.CALLBACK] = ButtonType.CALLBACK + text: str + payload: str + intent: str + + +class LinkButton(BaseButton): + type: Literal[ButtonType.LINK] = ButtonType.LINK + url: str + + +class ChatButton(BaseButton): + type: Literal[ButtonType.CHAT] = ButtonType.CHAT + payload: str + + +class GeoLocationButton(BaseButton): + type: Literal[ButtonType.REQUEST_GEO_LOCATION] = ButtonType.REQUEST_GEO_LOCATION + quick: bool | None = None + + +class RequestContactButton(BaseButton): + type: Literal[ButtonType.REQUEST_CONTACT] = ButtonType.REQUEST_CONTACT + + +class OpenAppButton(BaseButton): + type: Literal[ButtonType.OPEN_APP] = ButtonType.OPEN_APP + contact_id: int | None = None + payload: str | None = None + web_app: str | None = None + + +class MessageButton(BaseButton): + type: Literal[ButtonType.MESSAGE] = ButtonType.MESSAGE + + +class ClipboardButton(BaseButton): + type: Literal[ButtonType.CLIPBOARD] = ButtonType.CLIPBOARD + payload: str + + +Button: TypeAlias = Annotated[ + CallbackButton + | ChatButton + | LinkButton + | RequestContactButton + | GeoLocationButton + | OpenAppButton + | MessageButton + | ClipboardButton, + Field(discriminator="type"), +] + + +class InlineKeyboard(CamelModel): + buttons: list[Button] + class InlineKeyboardAttachment(CamelModel): """Вложение inline-клавиатуры. @@ -16,4 +81,5 @@ class InlineKeyboardAttachment(CamelModel): """ type: Literal[AttachmentType.INLINE_KEYBOARD] = Field(alias="_type") - keyboard: dict[str, Any] + keyboard: InlineKeyboard + callback_id: str diff --git a/src/pymax/types/domain/callback.py b/src/pymax/types/domain/callback.py new file mode 100644 index 0000000..d0c5d30 --- /dev/null +++ b/src/pymax/types/domain/callback.py @@ -0,0 +1,12 @@ +from .base import CamelModel +from .chat import Chat +from .message import Message + + +class CallbackResponse(CamelModel): + success: bool + unread: int + mark: int + message: Message | None = None + chat: Chat | None = None + chat_access_token: str | None = None diff --git a/src/pymax/types/domain/message.py b/src/pymax/types/domain/message.py index 23bc362..c5b22f8 100644 --- a/src/pymax/types/domain/message.py +++ b/src/pymax/types/domain/message.py @@ -50,6 +50,11 @@ Link: TypeAlias = Annotated["ReplyLink | ForwardLink", Field(discriminator="type")] +class MessageLink(CamelModel): + message: Message + chat_id: int + + class ReactionCounter(CamelModel): """Счетчик одной реакции на сообщение. @@ -98,7 +103,7 @@ class DelayedAttributes(CamelModel): notify_opponents: bool -class ReplyLink(CamelModel): +class ReplyLink(MessageLink): """Источник сообщения, отправленного как reply. :ivar message: Сообщение, на которое ответили. @@ -112,7 +117,7 @@ class ReplyLink(CamelModel): chat_id: int -class ForwardLink(CamelModel): +class ForwardLink(MessageLink): """Источник пересланного сообщения. Помимо исходного сообщения содержит доступные в payload-е имя, ссылку, From e11d91db6664837fd415fe729c5f1002d5737744 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Wed, 5 Aug 2026 19:51:03 +0300 Subject: [PATCH 04/31] feat: add composable event filters --- src/pymax/base.py | 20 +- src/pymax/dispatch/dispatcher.py | 33 ++-- src/pymax/dispatch/router.py | 30 ++- src/pymax/filters/__init__.py | 7 + src/pymax/filters/base.py | 212 ++++++++++++++++++++ src/pymax/filters/containers/__init__.py | 2 + src/pymax/filters/containers/chat.py | 240 +++++++++++++++++++++++ src/pymax/filters/containers/message.py | 147 ++++++++++++++ src/pymax/filters/filters.py | 211 ++++++++++++++++++++ src/pymax/filters/magic.py | 13 ++ src/pymax/filters/presets.py | 63 ++++++ src/pymax/filters/refs.py | 56 ++++++ tests/dispatch/test_dispatcher.py | 28 ++- tests/filters/test_magic.py | 139 +++++++++++++ 14 files changed, 1158 insertions(+), 43 deletions(-) create mode 100644 src/pymax/filters/__init__.py create mode 100644 src/pymax/filters/base.py create mode 100644 src/pymax/filters/containers/__init__.py create mode 100644 src/pymax/filters/containers/chat.py create mode 100644 src/pymax/filters/containers/message.py create mode 100644 src/pymax/filters/filters.py create mode 100644 src/pymax/filters/magic.py create mode 100644 src/pymax/filters/presets.py create mode 100644 src/pymax/filters/refs.py create mode 100644 tests/filters/test_magic.py diff --git a/src/pymax/base.py b/src/pymax/base.py index cb7393f..b4e92dc 100644 --- a/src/pymax/base.py +++ b/src/pymax/base.py @@ -7,6 +7,7 @@ from pymax.dispatch import ErrorScope, Router from pymax.dispatch.router import DisconnectDecorator, ErrorDecorator from pymax.exceptions import ApiError +from pymax.filters import Filter from pymax.fingerprint.models import ApkBuildFingerprint from pymax.infra import BaseMixin from pymax.logging import get_logger @@ -19,7 +20,6 @@ from pymax.auth import AuthFlow from pymax.connection import ConnectionManager from pymax.dispatch.router import ( - FilterCallback, HandlerDecorator, StartDecorator, ) @@ -270,63 +270,63 @@ def on_start(self) -> StartDecorator[ClientT]: def on_message( self, - *filters: FilterCallback[Message], + *filters: Filter[Message, ClientT], ) -> HandlerDecorator[Message, ClientT]: """Регистрирует обработчик новых сообщений.""" return self._router.on_message(*filters) def on_message_edit( self, - *filters: FilterCallback[Message], + *filters: Filter[Message, ClientT], ) -> HandlerDecorator[Message, ClientT]: """Регистрирует обработчик редактирования сообщений.""" return self._router.on_message_edit(*filters) def on_message_delete( self, - *filters: FilterCallback[MessageDeleteEvent], + *filters: Filter[MessageDeleteEvent, ClientT], ) -> HandlerDecorator[MessageDeleteEvent, ClientT]: """Регистрирует обработчик удаления сообщений.""" return self._router.on_message_delete(*filters) def on_message_read( self, - *filters: FilterCallback[MessageReadEvent], + *filters: Filter[MessageReadEvent, ClientT], ) -> HandlerDecorator[MessageReadEvent, ClientT]: """Регистрирует обработчик изменения отметки прочтения.""" return self._router.on_message_read(*filters) def on_typing( self, - *filters: FilterCallback[TypingEvent], + *filters: Filter[TypingEvent, ClientT], ) -> HandlerDecorator[TypingEvent, ClientT]: """Регистрирует обработчик набора текста.""" return self._router.on_typing(*filters) def on_presence( self, - *filters: FilterCallback[PresenceEvent], + *filters: Filter[PresenceEvent, ClientT], ) -> HandlerDecorator[PresenceEvent, ClientT]: """Регистрирует обработчик изменения присутствия пользователя.""" return self._router.on_presence(*filters) def on_reaction_update( self, - *filters: FilterCallback[ReactionUpdateEvent], + *filters: Filter[ReactionUpdateEvent, ClientT], ) -> HandlerDecorator[ReactionUpdateEvent, ClientT]: """Регистрирует обработчик обновления реакций сообщения.""" return self._router.on_reaction_update(*filters) def on_chat_update( self, - *filters: FilterCallback[Chat], + *filters: Filter[Chat, ClientT], ) -> HandlerDecorator[Chat, ClientT]: """Регистрирует обработчик обновления чата.""" return self._router.on_chat_update(*filters) def on_raw( self, - *filters: FilterCallback[InboundFrame], + *filters: Filter[InboundFrame, ClientT], ) -> HandlerDecorator[InboundFrame, ClientT]: """Регистрирует обработчик исходных входящих frame-ов.""" return self._router.on_raw(*filters) diff --git a/src/pymax/dispatch/dispatcher.py b/src/pymax/dispatch/dispatcher.py index afba6d2..7fdcb0d 100644 --- a/src/pymax/dispatch/dispatcher.py +++ b/src/pymax/dispatch/dispatcher.py @@ -5,6 +5,7 @@ from contextlib import suppress from typing import TYPE_CHECKING, Any, Generic, TypeVar +from pymax.filters import Filter from pymax.logging import get_logger from pymax.protocol import InboundFrame from pymax.types import Chat, MessageDeleteEvent @@ -26,7 +27,6 @@ ErrorEntry, ErrorScope, ErrorSource, - FilterCallback, HandlerCallback, HandlerDecorator, HandlerEntry, @@ -45,6 +45,7 @@ logger = get_logger(__name__) ClientT = TypeVar("ClientT", bound="BaseClient") +EventT = TypeVar("EventT") class Dispatcher(Generic[ClientT]): @@ -70,7 +71,7 @@ def include_router(self, router: Router[ClientT]) -> None: def on_internal( self, event: EventType, - *filters: FilterCallback[Any], + *filters: Filter[Any, ClientT], ) -> HandlerDecorator[Any, ClientT]: logger.debug( "registering internal handler event=%s filters=%s", @@ -82,7 +83,7 @@ def on_internal( def on( self, event: EventType, - *filters: FilterCallback[Any], + *filters: Filter[Any, ClientT], ) -> HandlerDecorator[Any, ClientT]: logger.debug("registering handler event=%s filters=%s", event, len(filters)) return self.root_router.on(event, *filters) @@ -96,57 +97,57 @@ def on_disconnect(self) -> DisconnectDecorator: def on_message( self, - *filters: FilterCallback[Message], + *filters: Filter[Message, ClientT], ) -> HandlerDecorator[Message, ClientT]: logger.debug("registering message handler filters=%s", len(filters)) return self.root_router.on_message(*filters) def on_message_edit( self, - *filters: FilterCallback[Message], + *filters: Filter[Message, ClientT], ) -> HandlerDecorator[Message, ClientT]: logger.debug("registering message edit handler filters=%s", len(filters)) return self.root_router.on_message_edit(*filters) def on_message_delete( self, - *filters: FilterCallback[MessageDeleteEvent], + *filters: Filter[MessageDeleteEvent, ClientT], ) -> HandlerDecorator[MessageDeleteEvent, ClientT]: return self.root_router.on_message_delete(*filters) def on_message_read( self, - *filters: FilterCallback[MessageReadEvent], + *filters: Filter[MessageReadEvent, ClientT], ) -> HandlerDecorator[MessageReadEvent, ClientT]: return self.root_router.on_message_read(*filters) def on_typing( self, - *filters: FilterCallback[TypingEvent], + *filters: Filter[TypingEvent, ClientT], ) -> HandlerDecorator[TypingEvent, ClientT]: return self.root_router.on_typing(*filters) def on_presence( self, - *filters: FilterCallback[PresenceEvent], + *filters: Filter[PresenceEvent, ClientT], ) -> HandlerDecorator[PresenceEvent, ClientT]: return self.root_router.on_presence(*filters) def on_reaction_update( self, - *filters: FilterCallback[ReactionUpdateEvent], + *filters: Filter[ReactionUpdateEvent, ClientT], ) -> HandlerDecorator[ReactionUpdateEvent, ClientT]: return self.root_router.on_reaction_update(*filters) def on_chat_update( self, - *filters: FilterCallback[Chat], + *filters: Filter[Chat, ClientT], ) -> HandlerDecorator[Chat, ClientT]: return self.root_router.on_chat_update(*filters) def on_raw( self, - *filters: FilterCallback[InboundFrame], + *filters: Filter[InboundFrame, ClientT], ) -> HandlerDecorator[InboundFrame, ClientT]: return self.root_router.on_raw(*filters) @@ -279,9 +280,11 @@ async def _matches( event: Any, ) -> bool: for flt in entry.filters: - result = flt(event) - if inspect.isawaitable(result): - result = await result + if not self.client: + return False + filter_match = flt(event, self.client) + result = await flt.resolve_filter_result(filter_match) + if not result: logger.debug( "handler skipped by filter callback=%s", diff --git a/src/pymax/dispatch/router.py b/src/pymax/dispatch/router.py index a053012..30286f0 100644 --- a/src/pymax/dispatch/router.py +++ b/src/pymax/dispatch/router.py @@ -6,13 +6,14 @@ from enum import Enum from typing import TYPE_CHECKING, Any, Generic, TypeAlias, TypeVar +from pymax.filters import Filter from pymax.types import MessageDeleteEvent from .enums import EventType if TYPE_CHECKING: - from pymax import Client from pymax.base import BaseClient + from pymax.client import Client from pymax.protocol import InboundFrame from pymax.types import Chat from pymax.types.domain import Message @@ -34,6 +35,7 @@ class ErrorScope(str, Enum): _EventT = TypeVar("_EventT") ClientT = TypeVar("ClientT", bound="BaseClient") + HandlerCallback: TypeAlias = Callable[ [_EventT, ClientT], Awaitable[Any] | Any, @@ -42,10 +44,6 @@ class ErrorScope(str, Enum): [HandlerCallback[_EventT, ClientT]], HandlerCallback[_EventT, ClientT], ] -FilterCallback: TypeAlias = Callable[ - [_EventT], - Awaitable[bool] | bool, -] StartCallback: TypeAlias = Callable[ [ClientT], Awaitable[Any] | Any, @@ -91,7 +89,7 @@ class ErrorContext(Generic[ClientT]): @dataclass(slots=True) class HandlerEntry(Generic[_EventT, ClientT]): callback: HandlerCallback[_EventT, ClientT] - filters: tuple[FilterCallback[_EventT], ...] = () + filters: tuple[Filter, ...] = () @dataclass(slots=True) @@ -173,7 +171,7 @@ def on( self, event: EventType, /, - *filters: FilterCallback[_EventT], + *filters: Filter[_EventT, ClientT], ) -> HandlerDecorator[_EventT, ClientT]: """Регистрирует обработчик события по ``EventType``. @@ -234,7 +232,7 @@ def decorator(handler: StartCallback) -> StartCallback: def on_message( self, - *filters: FilterCallback[Message], + *filters: Filter[Message, ClientT], ) -> HandlerDecorator[Message, ClientT]: """Регистрирует обработчик новых сообщений. @@ -248,7 +246,7 @@ def on_message( def on_message_edit( self, - *filters: FilterCallback[Message], + *filters: Filter[Message, ClientT], ) -> HandlerDecorator[Message, ClientT]: """Регистрирует обработчик редактирования сообщений. @@ -262,7 +260,7 @@ def on_message_edit( def on_message_delete( self, - *filters: FilterCallback[MessageDeleteEvent], + *filters: Filter[MessageDeleteEvent, ClientT], ) -> HandlerDecorator[MessageDeleteEvent, ClientT]: """Регистрирует обработчик удаления сообщений. @@ -276,35 +274,35 @@ def on_message_delete( def on_message_read( self, - *filters: FilterCallback[MessageReadEvent], + *filters: Filter[MessageReadEvent, ClientT], ) -> HandlerDecorator[MessageReadEvent, ClientT]: """Регистрирует обработчик изменения отметки прочтения.""" return self.on(EventType.MESSAGE_READ, *filters) def on_typing( self, - *filters: FilterCallback[TypingEvent], + *filters: Filter[TypingEvent, ClientT], ) -> HandlerDecorator[TypingEvent, ClientT]: """Регистрирует обработчик набора текста.""" return self.on(EventType.TYPING, *filters) def on_presence( self, - *filters: FilterCallback[PresenceEvent], + *filters: Filter[PresenceEvent, ClientT], ) -> HandlerDecorator[PresenceEvent, ClientT]: """Регистрирует обработчик изменения присутствия пользователя.""" return self.on(EventType.PRESENCE, *filters) def on_reaction_update( self, - *filters: FilterCallback[ReactionUpdateEvent], + *filters: Filter[ReactionUpdateEvent, ClientT], ) -> HandlerDecorator[ReactionUpdateEvent, ClientT]: """Регистрирует обработчик обновления реакций сообщения.""" return self.on(EventType.REACTION_UPDATE, *filters) def on_chat_update( self, - *filters: FilterCallback[Chat], + *filters: Filter[Chat, ClientT], ) -> HandlerDecorator[Chat, ClientT]: """Регистрирует обработчик обновления чата. @@ -318,7 +316,7 @@ def on_chat_update( def on_raw( self, - *filters: FilterCallback[InboundFrame], + *filters: Filter[InboundFrame, ClientT], ) -> HandlerDecorator[InboundFrame, ClientT]: """Регистрирует обработчик исходных frame-ов. diff --git a/src/pymax/filters/__init__.py b/src/pymax/filters/__init__.py new file mode 100644 index 0000000..0f240a0 --- /dev/null +++ b/src/pymax/filters/__init__.py @@ -0,0 +1,7 @@ +from .base import Filter +from .magic import MagicFilter +from .presets import Command, Forwarded, FromMe, HasAttachment, Reply + +F = MagicFilter() + +__all__ = ("Command", "Filter", "Forwarded", "FromMe", "HasAttachment", "MagicFilter", "Reply") diff --git a/src/pymax/filters/base.py b/src/pymax/filters/base.py new file mode 100644 index 0000000..e986441 --- /dev/null +++ b/src/pymax/filters/base.py @@ -0,0 +1,212 @@ +from __future__ import annotations + +from abc import ABC, abstractmethod +from inspect import isawaitable +from typing import TYPE_CHECKING, Any, Generic, TypeVar + +if TYPE_CHECKING: + from collections.abc import Awaitable + + from pymax.base import BaseClient + + +MISSING = object() + +EventT = TypeVar("EventT") +ClientT_contra = TypeVar("ClientT_contra", bound="BaseClient", contravariant=True) + + +class Filter(ABC, Generic[EventT, ClientT_contra]): + @abstractmethod + def __call__( + self, + event: EventT, + client: ClientT_contra, + /, + ) -> bool | Awaitable[bool]: ... + def __and__(self, other: Filter[EventT, ClientT_contra]) -> AndFilter: + return AndFilter(self, other) + + def __or__(self, value: Filter[EventT, ClientT_contra]) -> OrFilter: + return OrFilter(self, value) + + def __invert__(self) -> NotFilter: + return NotFilter(self) + + async def resolve_filter_result( + self, + result: bool | Awaitable[bool], + ) -> bool: + if isawaitable(result): + return await result + + return result + + +class PathResolver: + def __init__(self, path: list[str]) -> None: + self.path = path + + def resolve_path(self, event: Any) -> Any | None: + value = event + + for attr in self.path: + value = getattr(value, attr, MISSING) + + if value is MISSING: + return MISSING + + return value + + +class IsNoneFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + ) -> None: + super().__init__(path) + self.expected_type = expected_type + self.path = path + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if value is MISSING: + return False + + return value is None + + +class IsEmptyFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + ) -> None: + super().__init__(path) + self.expected_type = expected_type + self.path = path + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + return value == [] + + +class FieldRef(Filter[EventT, ClientT_contra], PathResolver): + def __init__(self, path: list[str], expected_type: type[EventT]) -> None: + super().__init__(path) + self.expected_type: type[EventT] = expected_type + self.path = path + + def __eq__(self, value: object) -> EqFilter: # pyright: ignore[reportIncompatibleMethodOverride] # ty: ignore[invalid-method-override] + return EqFilter(self.path, self.expected_type, value) + + def __ne__(self, value: object) -> NeFilter: # pyright: ignore[reportIncompatibleMethodOverride] # ty: ignore[invalid-method-override] + return NeFilter(self.path, self.expected_type, value) + + def is_none(self) -> IsNoneFilter: + return IsNoneFilter(self.path, expected_type=self.expected_type) + + def is_empty(self) -> IsEmptyFilter: + return IsEmptyFilter(self.path, expected_type=self.expected_type) + + def __call__(self, event: EventT, _: ClientT_contra, /) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if value is MISSING: + return False + + return bool(value) + + +class BinaryFilter(Filter[EventT, ClientT_contra]): + def __init__( + self, left: Filter[EventT, ClientT_contra], right: Filter[EventT, ClientT_contra] + ) -> None: + self.left = left + self.right = right + + +class NotFilter(Filter[EventT, ClientT_contra]): + def __init__(self, filter_instance: Filter[EventT, ClientT_contra]) -> None: + self.filter = filter_instance + + async def __call__(self, event: EventT, client: ClientT_contra) -> bool: + return not await self.resolve_filter_result(self.filter(event, client)) + + +class NeFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + expected: object, + ) -> None: + self.path: list[str] = path + self.expected_type = expected_type + self.expected: object = expected + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if value is MISSING: + return False + + return value != self.expected + + +class AndFilter(BinaryFilter[EventT, ClientT_contra]): + async def __call__(self, event: EventT, client: ClientT_contra) -> bool: + left = await self.resolve_filter_result(self.left(event, client)) + + if not left: + return False + + return await self.resolve_filter_result(self.right(event, client)) + + +class OrFilter(BinaryFilter[EventT, ClientT_contra]): + async def __call__(self, event: EventT, client: ClientT_contra) -> bool: + left = await self.resolve_filter_result(self.left(event, client)) + + if left: + return True + + return await self.resolve_filter_result(self.right(event, client)) + + +class EqFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + expected: object, + ) -> None: + self.path: list[str] = path + self.expected_type = expected_type + self.expected: object = expected + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if value is MISSING: + return False + + return value == self.expected diff --git a/src/pymax/filters/containers/__init__.py b/src/pymax/filters/containers/__init__.py new file mode 100644 index 0000000..226c05d --- /dev/null +++ b/src/pymax/filters/containers/__init__.py @@ -0,0 +1,2 @@ +from .chat import ChatContainer +from .message import MessageContainer diff --git a/src/pymax/filters/containers/chat.py b/src/pymax/filters/containers/chat.py new file mode 100644 index 0000000..00984a6 --- /dev/null +++ b/src/pymax/filters/containers/chat.py @@ -0,0 +1,240 @@ +from __future__ import annotations + +import builtins +from typing import TYPE_CHECKING, Any, TypeVar + +from pymax.filters.base import ClientT_contra, Filter, PathResolver +from pymax.filters.refs import FieldRef, NumberFieldRef, TextFieldRef + +from .message import MessageContainer + +if TYPE_CHECKING: + from pymax.base import BaseClient + +EventT = TypeVar("EventT") + + +class ChatContainer(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + expected_type: builtins.type[EventT], + path: list[str] | None = None, + ) -> None: + self.expected_type: type[EventT] = expected_type + self.path = path or [] + + @property + def id(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "id"], + expected_type=self.expected_type, + ) + + @property + def type(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "type"], + expected_type=self.expected_type, + ) + + @property + def status(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "status"], + expected_type=self.expected_type, + ) + + @property + def owner(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "owner"], + expected_type=self.expected_type, + ) + + @property + def participants(self) -> FieldRef: + return FieldRef( + path=[*self.path, "participants"], + expected_type=self.expected_type, + ) + + @property + def title(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "title"], + expected_type=self.expected_type, + ) + + @property + def base_raw_icon_url(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "base_raw_icon_url"], + expected_type=self.expected_type, + ) + + @property + def base_icon_url(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "base_icon_url"], + expected_type=self.expected_type, + ) + + @property + def last_message(self) -> MessageContainer: + return MessageContainer( + path=[*self.path, "last_message"], + expected_type=self.expected_type, + ) + + @property + def last_event_time(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "last_event_time"], + expected_type=self.expected_type, + ) + + @property + def last_delayed_update_time(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "last_delayed_update_time"], + expected_type=self.expected_type, + ) + + @property + def last_fire_delayed_error_time(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "last_fire_delayed_error_time"], + expected_type=self.expected_type, + ) + + @property + def created(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "created"], + expected_type=self.expected_type, + ) + + @property + def new_messages(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "new_messages"], + expected_type=self.expected_type, + ) + + @property + def link(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "link"], + expected_type=self.expected_type, + ) + + @property + def access(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "access"], + expected_type=self.expected_type, + ) + + @property + def restrictions(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "restrictions"], + expected_type=self.expected_type, + ) + + @property + def pinned_message(self) -> MessageContainer: + return MessageContainer( + path=[*self.path, "pinned_message"], + expected_type=self.expected_type, + ) + + @property + def participants_count(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "participants_count"], + expected_type=self.expected_type, + ) + + @property + def description(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "description"], + expected_type=self.expected_type, + ) + + @property + def options(self) -> FieldRef: + return FieldRef( + path=[*self.path, "options"], + expected_type=self.expected_type, + ) + + @property + def join_time(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "join_time"], + expected_type=self.expected_type, + ) + + @property + def invited_by(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "invited_by"], + expected_type=self.expected_type, + ) + + @property + def modified(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "modified"], + expected_type=self.expected_type, + ) + + @property + def messages_count(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "messages_count"], + expected_type=self.expected_type, + ) + + @property + def has_bots(self) -> FieldRef: + return FieldRef( + path=[*self.path, "has_bots"], + expected_type=self.expected_type, + ) + + @property + def prev_message_id(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "prev_message_id"], + expected_type=self.expected_type, + ) + + @property + def admin_participants(self) -> FieldRef: + return FieldRef( + path=[*self.path, "admin_participants"], + expected_type=self.expected_type, + ) + + @property + def admins(self) -> FieldRef: + return FieldRef( + path=[*self.path, "admins"], + expected_type=self.expected_type, + ) + + @property + def cid(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "cid"], + expected_type=self.expected_type, + ) + + def __call__(self, event: Any, client: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + return bool(self.resolve_path(event)) diff --git a/src/pymax/filters/containers/message.py b/src/pymax/filters/containers/message.py new file mode 100644 index 0000000..32293d3 --- /dev/null +++ b/src/pymax/filters/containers/message.py @@ -0,0 +1,147 @@ +from __future__ import annotations + +import builtins +from typing import TYPE_CHECKING, Any, TypeVar + +from pymax.filters.base import ClientT_contra, Filter, PathResolver +from pymax.filters.refs import FieldRef, NumberFieldRef, TextFieldRef + +if TYPE_CHECKING: + from pymax.base import BaseClient + +EventT = TypeVar("EventT") + + +class MessageContainer(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + expected_type: builtins.type[EventT], + path: list[str] | None = None, + ) -> None: + self.expected_type: type[EventT] = expected_type + self.path = path or [] + + @property + def text(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "text"], + expected_type=self.expected_type, + ) + + @property + def id(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "id"], + expected_type=self.expected_type, + ) + + @property + def chat_id(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "chat_id"], + expected_type=self.expected_type, + ) + + @property + def sender(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "sender"], + expected_type=self.expected_type, + ) + + @property + def time(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "time"], + expected_type=self.expected_type, + ) + + @property + def type(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "type"], + expected_type=self.expected_type, + ) + + @property + def cid(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "cid"], + expected_type=self.expected_type, + ) + + @property + def attaches(self) -> FieldRef: + return FieldRef( + path=[*self.path, "attaches"], + expected_type=self.expected_type, + ) + + @property + def stats(self) -> FieldRef: + return FieldRef( + path=[*self.path, "stats"], + expected_type=self.expected_type, + ) + + @property + def status(self) -> TextFieldRef: + return TextFieldRef( + path=[*self.path, "status"], + expected_type=self.expected_type, + ) + + @property + def reaction_info(self) -> FieldRef: + return FieldRef( + path=[*self.path, "reaction_info"], + expected_type=self.expected_type, + ) + + @property + def options(self) -> FieldRef: + return FieldRef( + path=[*self.path, "options"], + expected_type=self.expected_type, + ) + + @property + def prev_message_id(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "prev_message_id"], + expected_type=self.expected_type, + ) + + @property + def ttl(self) -> FieldRef: + return FieldRef( + path=[*self.path, "ttl"], + expected_type=self.expected_type, + ) + + @property + def unread(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "unread"], + expected_type=self.expected_type, + ) + + @property + def mark(self) -> NumberFieldRef: + return NumberFieldRef( + path=[*self.path, "mark"], + expected_type=self.expected_type, + ) + + @property + def elements(self) -> FieldRef: + return FieldRef( + path=[*self.path, "elements"], + expected_type=self.expected_type, + ) + + def __call__(self, event: Any, client: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + return bool(self.resolve_path(event)) diff --git a/src/pymax/filters/filters.py b/src/pymax/filters/filters.py new file mode 100644 index 0000000..4942ce2 --- /dev/null +++ b/src/pymax/filters/filters.py @@ -0,0 +1,211 @@ +from __future__ import annotations + +from typing import TYPE_CHECKING, Any, TypeVar + +from .base import ClientT_contra, Filter, PathResolver + +if TYPE_CHECKING: + from pymax.base import BaseClient + +EventT = TypeVar("EventT") + + +class ContainsFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + text: str, + ignore_case: bool, + ) -> None: + self.path = path + self.expected_type = expected_type + self.text = text + self.ignore_case = ignore_case + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if not isinstance(value, str): + return False + + if self.ignore_case: + return self.text.casefold() in value.casefold() + + return self.text in value + + +class StartsWithFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + text: str, + ignore_case: bool, + ) -> None: + self.path = path + self.expected_type = expected_type + self.text = text + self.ignore_case = ignore_case + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if not isinstance(value, str): + return False + + if self.ignore_case: + return value.casefold().startswith(self.text.casefold()) + + return value.startswith(self.text) + + +class EndsWithFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + text: str, + ignore_case: bool, + ) -> None: + self.path = path + self.expected_type = expected_type + self.text = text + self.ignore_case = ignore_case + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if not isinstance(value, str): + return False + + if self.ignore_case: + return value.casefold().endswith(self.text.casefold()) + + return value.endswith(self.text) + + +class LessThanFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + expected: float, + ) -> None: + self.path = path + self.expected_type = expected_type + self.expected = expected + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if not isinstance(value, int | float) or isinstance(value, bool): + return False + + return value < self.expected + + +class LessThanOrEqualFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + expected: float, + ) -> None: + self.path = path + self.expected_type = expected_type + self.expected = expected + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if not isinstance(value, int | float) or isinstance(value, bool): + return False + + return value <= self.expected + + +class GreaterThanFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + expected: float, + ) -> None: + self.path = path + self.expected_type = expected_type + self.expected = expected + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if not isinstance(value, int | float) or isinstance(value, bool): + return False + + return value > self.expected + + +class GreaterThanOrEqualFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + expected: float, + ) -> None: + self.path = path + self.expected_type = expected_type + self.expected = expected + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if not isinstance(value, int | float) or isinstance(value, bool): + return False + + return value >= self.expected + + +class BetweenFilter(Filter[EventT, ClientT_contra], PathResolver): + def __init__( + self, + path: list[str], + expected_type: type[EventT], + minimum: float, + maximum: float, + ) -> None: + self.path = path + self.expected_type = expected_type + self.minimum = minimum + self.maximum = maximum + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if not isinstance(value, int | float) or isinstance(value, bool): + return False + + return self.minimum <= value <= self.maximum diff --git a/src/pymax/filters/magic.py b/src/pymax/filters/magic.py new file mode 100644 index 0000000..aa44491 --- /dev/null +++ b/src/pymax/filters/magic.py @@ -0,0 +1,13 @@ +from pymax.types import Chat, Message + +from .containers import ChatContainer, MessageContainer + + +class MagicFilter: + @property + def message(self) -> MessageContainer: + return MessageContainer(Message) + + @property + def chat(self) -> ChatContainer: + return ChatContainer(Chat) diff --git a/src/pymax/filters/presets.py b/src/pymax/filters/presets.py new file mode 100644 index 0000000..a0848f5 --- /dev/null +++ b/src/pymax/filters/presets.py @@ -0,0 +1,63 @@ +from __future__ import annotations + +from typing import TYPE_CHECKING + +from pymax.types import LinkType, Message + +from .base import Filter + +if TYPE_CHECKING: + from pymax.base import BaseClient + from pymax.types.domain.message import Attachment + + +class Command(Filter[Message, "BaseClient"]): + def __init__(self, command: str, prefix: str | tuple[str, ...] = "/") -> None: + self.prefixes = (prefix,) if isinstance(prefix, str) else prefix + + for prefix_ in self.prefixes: + self.command = command.removeprefix(prefix_) + + def __call__(self, message: Message, _: BaseClient) -> bool: + if not message.text: + return False + + for prefix in self.prefixes: + dirty_command = message.text.split(maxsplit=1)[0] + + if message.text.startswith(prefix) and dirty_command[len(prefix) :] == self.command: + return True + + return False + + +class Reply(Filter[Message, "BaseClient"]): + def __call__(self, message: Message, _: BaseClient) -> bool: + if not message.link: + return False + + return message.link.type == LinkType.REPLY + + +class Forwarded(Filter[Message, "BaseClient"]): + def __call__(self, message: Message, _: BaseClient) -> bool: + if not message.link: + return False + + return message.link.type == LinkType.FORWARD + + +class FromMe(Filter[Message, "BaseClient"]): + def __call__(self, message: Message, client: BaseClient) -> bool: + if not message.sender or not client.me: + return False + + return message.sender == client.me.contact.id + + +class HasAttachment(Filter[Message, "BaseClient"]): + def __init__(self, *attachment_types: type[Attachment]) -> None: + self.expected_types = attachment_types + + def __call__(self, message: Message, _: BaseClient) -> bool: + return any(isinstance(attach, self.expected_types) for attach in message.attaches) diff --git a/src/pymax/filters/refs.py b/src/pymax/filters/refs.py new file mode 100644 index 0000000..4e0d99f --- /dev/null +++ b/src/pymax/filters/refs.py @@ -0,0 +1,56 @@ +from __future__ import annotations + +from typing import TypeVar + +from .base import MISSING, ClientT_contra, FieldRef +from .filters import ( + BetweenFilter, + ContainsFilter, + EndsWithFilter, + GreaterThanFilter, + GreaterThanOrEqualFilter, + LessThanFilter, + LessThanOrEqualFilter, + StartsWithFilter, +) + +EventT = TypeVar("EventT") + + +class TextFieldRef(FieldRef[EventT, ClientT_contra]): + def contains(self, text: str, *, ignore_case: bool = False) -> ContainsFilter: + return ContainsFilter(self.path, self.expected_type, text, ignore_case) + + def startswith(self, text: str, *, ignore_case: bool = False) -> StartsWithFilter: + return StartsWithFilter(self.path, self.expected_type, text, ignore_case) + + def endswith(self, text: str, *, ignore_case: bool = False) -> EndsWithFilter: + return EndsWithFilter(self.path, self.expected_type, text, ignore_case) + + def __call__(self, event: EventT, _: ClientT_contra) -> bool: + if not isinstance(event, self.expected_type): + return False + + value = self.resolve_path(event) + + if value is MISSING: + return False + + return bool(value) + + +class NumberFieldRef(FieldRef[EventT, ClientT_contra]): + def __lt__(self, value: float) -> LessThanFilter: + return LessThanFilter(self.path, self.expected_type, value) + + def __le__(self, value: float) -> LessThanOrEqualFilter: + return LessThanOrEqualFilter(self.path, self.expected_type, value) + + def __gt__(self, value: float) -> GreaterThanFilter: + return GreaterThanFilter(self.path, self.expected_type, value) + + def __ge__(self, value: float) -> GreaterThanOrEqualFilter: + return GreaterThanOrEqualFilter(self.path, self.expected_type, value) + + def between(self, minimum: float, maximum: float) -> BetweenFilter: + return BetweenFilter(self.path, self.expected_type, minimum, maximum) diff --git a/tests/dispatch/test_dispatcher.py b/tests/dispatch/test_dispatcher.py index c340692..181cc73 100644 --- a/tests/dispatch/test_dispatcher.py +++ b/tests/dispatch/test_dispatcher.py @@ -4,6 +4,7 @@ from pymax.dispatch import Dispatcher, Router from pymax.dispatch.enums import EventType +from pymax.filters import F from pymax.protocol import Command, Opcode from tests.conftest import FakeApp, chat_payload, frame, message_payload @@ -16,10 +17,10 @@ async def test_dispatcher_routes_message_events_through_filters_and_raw_handler( dispatcher.bind_client("client") seen: list[tuple[str, int | str]] = [] - def is_start(message): + def is_start(message, _client): return message.text == "/start" - async def has_chat(message): + def has_chat(message, _client): return message.chat_id == 100 @router.on_message(is_start, has_chat) @@ -44,6 +45,29 @@ def on_raw(raw_frame, client): ] +@pytest.mark.asyncio +async def test_dispatcher_evaluates_all_magic_filters() -> None: + app = FakeApp() + router: Router[str] = Router() + dispatcher: Dispatcher[str] = Dispatcher(app, router) + dispatcher.bind_client("client") + seen: list[int] = [] + + @router.on_message(F.message.text.contains("start"), F.message.chat_id == 200) + async def on_message(message, _client): + seen.append(message.id) + + await dispatcher.dispatch( + frame( + {"chatId": 100, "message": message_payload(1, 100, "/start")}, + opcode=Opcode.NOTIF_MESSAGE, + cmd=Command.REQUEST, + ) + ) + + assert seen == [] + + @pytest.mark.asyncio async def test_dispatcher_maps_chat_delete_and_internal_attach_events() -> None: app = FakeApp() diff --git a/tests/filters/test_magic.py b/tests/filters/test_magic.py new file mode 100644 index 0000000..d9486a3 --- /dev/null +++ b/tests/filters/test_magic.py @@ -0,0 +1,139 @@ +from types import SimpleNamespace + +from pymax.filters import Command, F, FromMe, HasAttachment +from pymax.types import Chat, Message, PhotoAttachment + + +def make_message(**kwargs) -> Message: + return Message( + id=kwargs.pop("id", 1), + chat_id=kwargs.pop("chat_id", 100), + sender=kwargs.pop("sender", 10), + text=kwargs.pop("text", "hello world"), + time=kwargs.pop("time", 1_700_000_000), + type=kwargs.pop("type", "USER"), + **kwargs, + ) + + +def make_chat(**kwargs) -> Chat: + return Chat( + id=kwargs.pop("id", 100), + type=kwargs.pop("type", "CHAT"), + status=kwargs.pop("status", "ACTIVE"), + owner=kwargs.pop("owner", 10), + title=kwargs.pop("title", "PyMax developers"), + **kwargs, + ) + + +def make_client(user_id: int = 10) -> SimpleNamespace: + return SimpleNamespace(me=SimpleNamespace(contact=SimpleNamespace(id=user_id))) + + +def make_photo() -> PhotoAttachment: + return PhotoAttachment( + base_url="https://example.com/photo.jpg", + height=100, + width=100, + photo_id=1, + photo_token="photo-token", + _type="PHOTO", + ) + + +def test_message_container_exposes_all_message_fields() -> None: + fields = {name for name, value in vars(type(F.message)).items() if isinstance(value, property)} + + assert fields == set(Message.model_fields) + + +def test_chat_container_exposes_all_chat_fields() -> None: + fields = {name for name, value in vars(type(F.chat)).items() if isinstance(value, property)} + + assert fields == set(Chat.model_fields) + + +def test_message_field_filters_support_comparison_and_logical_operations() -> None: + message = make_message() + client = make_client() + filter_ = F.message.text.contains("hello") & ~(F.message.sender == 20) + + assert filter_(message, client) is True + assert (F.message.chat_id == 100)(message, client) is True + assert (F.message.chat_id == 200)(message, client) is False + + +def test_chat_field_filters_support_comparison_and_logical_operations() -> None: + chat = make_chat() + client = make_client() + filter_ = F.chat.title.contains("PyMax") & (F.chat.owner == 10) + + assert filter_(chat, client) is True + assert (F.chat.status == "INACTIVE")(chat, client) is False + + +def test_containers_and_fields_reject_another_event_type() -> None: + message = make_message() + chat = make_chat() + client = make_client() + + assert F.message(chat, client) is False + assert F.chat(message, client) is False + assert (F.message.id == 100)(chat, client) is False + assert (F.chat.id == 1)(message, client) is False + + +def test_nested_message_containers_resolve_chat_message_fields() -> None: + client = make_client() + chat = make_chat( + last_message=make_message(text="Last message"), + pinned_message=make_message(id=2, text="Pinned message"), + ) + + assert F.chat.last_message(chat, client) is True + assert F.chat.last_message.text.startswith("Last")(chat, client) is True + assert (F.chat.last_message.sender == 10)(chat, client) is True + assert F.chat.pinned_message.text.endswith("message")(chat, client) is True + assert F.chat.last_message(make_chat(), client) is False + + +def test_number_field_filters_support_comparisons_and_inclusive_between() -> None: + message = make_message(time=100) + client = make_client() + + assert (F.message.time > 99)(message, client) is True + assert (F.message.time >= 100)(message, client) is True + assert (F.message.time < 101)(message, client) is True + assert (F.message.time <= 100)(message, client) is True + assert F.message.time.between(100, 100)(message, client) is True + assert F.message.time.between(101, 200)(message, client) is False + assert F.message.id.between(1, 10)(message, client) is True + + +def test_text_field_filters_support_case_sensitive_and_insensitive_matching() -> None: + message = make_message(text="Hello PyMax") + client = make_client() + + assert F.message.text.contains("hello")(message, client) is False + assert F.message.text.contains("hello", ignore_case=True)(message, client) is True + assert F.message.text.startswith("HELLO", ignore_case=True)(message, client) is True + assert F.message.text.endswith("PYMAX", ignore_case=True)(message, client) is True + + +def test_presets_support_and_composition() -> None: + client = make_client() + filter_ = HasAttachment(PhotoAttachment) & FromMe() + + assert filter_(make_message(attaches=[make_photo()]), client) is True + assert filter_(make_message(sender=20, attaches=[make_photo()]), client) is False + assert filter_(make_message(), client) is False + + +def test_presets_support_or_composition() -> None: + client = make_client() + filter_ = Command("start") | HasAttachment(PhotoAttachment) + + assert filter_(make_message(text="/start"), client) is True + assert filter_(make_message(text="hello", attaches=[make_photo()]), client) is True + assert filter_(make_message(text="hello"), client) is False From d0f9bfdcec56a6523e85b441262633aa9f0b96c9 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Mon, 21 Sep 2026 20:05:12 +0300 Subject: [PATCH 05/31] feat: add channel comments support --- src/pymax/api/chats/enums.py | 1 + src/pymax/api/chats/payloads.py | 19 ++ src/pymax/api/chats/service.py | 34 +++ src/pymax/api/messages/enums.py | 1 + src/pymax/api/messages/payloads.py | 46 ++++ src/pymax/api/messages/service.py | 330 +++++++++++++++++++++++++++-- src/pymax/infra/chat.py | 28 +++ src/pymax/infra/message.py | 175 +++++++++++++++ src/pymax/protocol/enums.py | 2 + src/pymax/types/domain/__init__.py | 1 + src/pymax/types/domain/comment.py | 24 +++ 11 files changed, 638 insertions(+), 23 deletions(-) create mode 100644 src/pymax/types/domain/comment.py diff --git a/src/pymax/api/chats/enums.py b/src/pymax/api/chats/enums.py index d924529..22c397b 100644 --- a/src/pymax/api/chats/enums.py +++ b/src/pymax/api/chats/enums.py @@ -11,6 +11,7 @@ class ChatMemberOperation(str, Enum): class ChatOption(str, Enum): + COMMENTS = "COMMENTS" ONLY_OWNER_CAN_CHANGE_ICON_TITLE = "ONLY_OWNER_CAN_CHANGE_ICON_TITLE" ALL_CAN_PIN_MESSAGE = "ALL_CAN_PIN_MESSAGE" ONLY_ADMIN_CAN_ADD_MEMBER = "ONLY_ADMIN_CAN_ADD_MEMBER" diff --git a/src/pymax/api/chats/payloads.py b/src/pymax/api/chats/payloads.py index 1017c30..e980ad5 100644 --- a/src/pymax/api/chats/payloads.py +++ b/src/pymax/api/chats/payloads.py @@ -137,3 +137,22 @@ class AddAdminPayload(CamelModel): type: PermType = PermType.ADMIN operation: str = "add" permissions: int + + +class ChannelCommentsOptions(CamelModel): + comments: bool = Field(serialization_alias=ChatOption.COMMENTS.value) + + +class SetChannelCommentsPayload(CamelModel): + chat_id: int + options: ChannelCommentsOptions + + +class BlockCommentAuthorPayload(CamelModel): + chat_id: int + post_id: int + user_ids: list[int] + message_id: int + type: Literal["COMMENTS_BLACKLIST"] = "COMMENTS_BLACKLIST" + operation: ChatMemberOperation = ChatMemberOperation.ADD + clean_msg_period: int = 0 diff --git a/src/pymax/api/chats/service.py b/src/pymax/api/chats/service.py index 9b88b18..5c67716 100644 --- a/src/pymax/api/chats/service.py +++ b/src/pymax/api/chats/service.py @@ -22,9 +22,11 @@ from .enums import ChannelPermissions, ChatLinkPrefix, ChatMemberOperation, ChatPayloadKey from .payloads import ( AddAdminPayload, + BlockCommentAuthorPayload, ChangeGroupProfilePayload, ChangeGroupSettingsOptions, ChangeGroupSettingsPayload, + ChannelCommentsOptions, CreateGroupAttach, CreateGroupMessage, CreateGroupPayload, @@ -40,6 +42,7 @@ LinkInfoPayload, RemoveUsersPayload, ReworkInviteLinkPayload, + SetChannelCommentsPayload, ) if TYPE_CHECKING: @@ -422,3 +425,34 @@ async def add_admin( ) await self.app.invoke(Opcode.CHAT_MEMBERS_UPDATE, frame.to_payload()) + + async def set_channel_comments(self, chat_id: int, enabled: bool) -> None: + frame = SetChannelCommentsPayload( + chat_id=chat_id, + options=ChannelCommentsOptions(comments=enabled), + ) + response = await self.app.invoke(Opcode.CHAT_UPDATE, frame.to_payload()) + chat = parse_payload_item_model(response, ChatPayloadKey.CHAT, Chat) + if chat: + self._cache_chat(chat) + + 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: + frame = BlockCommentAuthorPayload( + chat_id=chat_id, + post_id=post_id, + user_ids=user_ids, + message_id=message_id, + clean_msg_period=clean_msg_period, + ) + response = await self.app.invoke(Opcode.CHAT_MEMBERS_UPDATE, frame.to_payload()) + chat = parse_payload_item_model(response, ChatPayloadKey.CHAT, Chat) + if chat: + self._cache_chat(chat) + return True diff --git a/src/pymax/api/messages/enums.py b/src/pymax/api/messages/enums.py index dd51701..221b375 100644 --- a/src/pymax/api/messages/enums.py +++ b/src/pymax/api/messages/enums.py @@ -16,3 +16,4 @@ class MessagePayloadKey(str, Enum): MESSAGES = "messages" REACTION_INFO = "reactionInfo" MESSAGES_REACTIONS = "messagesReactions" + COMMENTS_INFO_UPDATES = "commentsInfoUpdates" diff --git a/src/pymax/api/messages/payloads.py b/src/pymax/api/messages/payloads.py index 3a1c2fe..dca658b 100644 --- a/src/pymax/api/messages/payloads.py +++ b/src/pymax/api/messages/payloads.py @@ -18,6 +18,10 @@ class GetMessagesPayload(CamelModel): message_ids: list[int] +class GetCommentsPayload(GetMessagesPayload): + post_id: int + + class EditMessagePayload(CamelModel): chat_id: int message_id: int @@ -28,6 +32,10 @@ class EditMessagePayload(CamelModel): ) +class EditCommentPayload(EditMessagePayload): + post_id: int + + class ReplyLink(CamelModel): type: str = "REPLY" # TODO: enum? message_id: int @@ -53,6 +61,10 @@ class SendMessagePayload(CamelModel): notify: bool = False +class SendCommentPayload(SendMessagePayload): + post_id: int + + class ForwardLink(CamelModel): type: Literal["FORWARD"] = "FORWARD" message_id: str @@ -86,6 +98,10 @@ class ChatHistoryPayload(CamelModel): interactive: bool = False +class CommentsHistoryPayload(ChatHistoryPayload): + post_id: int + + class DeleteMessagePayload(CamelModel): chat_id: int message_ids: list[int] @@ -143,3 +159,33 @@ class VotePollPayload(CamelModel): message_id: int poll_id: int answers_ids: list[int] + + +class DeleteCommentPayload(DeleteMessagePayload): + post_id: int + + +class AddCommentReactionPayload(AddReactionPayload): + post_id: int + + +class RemoveCommentReactionPayload(RemoveReactionPayload): + post_id: int + + +class SubscribeCommentsPayload(CamelModel): + chat_id: int + post_id: int + subscribe: bool = True + + +class GetCommentsInfoPayload(CamelModel): + chat_id: int + post_ids: list[int] + + +class DeleteUserCommentsPayload(CamelModel): + chat_id: int + post_id: int + user_id: int + message_id: int diff --git a/src/pymax/api/messages/service.py b/src/pymax/api/messages/service.py index 1543fa2..0a79aab 100644 --- a/src/pymax/api/messages/service.py +++ b/src/pymax/api/messages/service.py @@ -27,6 +27,7 @@ from pymax.logging import get_logger from pymax.protocol import Opcode from pymax.types.domain import ( + CommentsInfoUpdate, FileRequest, Message, Poll, @@ -38,14 +39,21 @@ from .enums import ItemType, MessagePayloadKey, ReadAction from .payloads import ( + AddCommentReactionPayload, AddReactionPayload, ChatHistoryPayload, + CommentsHistoryPayload, DelayedAttributes, + DeleteCommentPayload, DeleteMessagePayload, + DeleteUserCommentsPayload, + EditCommentPayload, EditMessagePayload, ForwardLink, ForwardMessagePayload, ForwardMessagePayloadMessage, + GetCommentsInfoPayload, + GetCommentsPayload, GetFilePayload, GetMessagesPayload, GetReactionsPayload, @@ -53,10 +61,13 @@ PinMessagePayload, ReactionInfoPayload, ReadMessagesPayload, + RemoveCommentReactionPayload, RemoveReactionPayload, ReplyLink, + SendCommentPayload, SendMessagePayload, SendMessagePayloadMessage, + SubscribeCommentsPayload, VotePollPayload, ) @@ -85,6 +96,40 @@ def _next_cid(self) -> int: logger.debug("generated message cid=%s", e) return e + async def _prepare_message( + self, + text: str | None, + reply_to: int | None, + attachments: SendAttachments, + *, + delayed_attributes: DelayedAttributes | None = None, + ) -> tuple[ + SendMessagePayloadMessage, + list[ + AttachPhotoPayload | VideoAttachPayload | AttachFilePayload | VoiceAttachPayload | Poll + ], + ]: + if not text and not attachments: + raise ValueError("Either text or attachments must be provided") + + if text: + clean_text, elements = Formatter.format_markdown(text) + else: + clean_text, elements = None, [] + + attaches = await self._upload_attachments(attachments) + + message = SendMessagePayloadMessage( + text=clean_text, + cid=self._next_cid(), + elements=elements, + attaches=attaches, + link=ReplyLink(message_id=reply_to) if reply_to else None, + delayed_attributes=delayed_attributes, + ) + + return message, attaches + async def _upload_attachments( self, attachments: SendAttachments ) -> list[ @@ -202,32 +247,21 @@ async def send_message( ) -> Message: logger.info("sending message chat_id=%s text_len=%s", chat_id, len(text) if text else 0) - if not text and not attachments: - logger.error("send_message failed: no text or attachments provided") - raise ValueError("Either text or attachments must be provided") - - if text: - clean_text, elements = Formatter.format_markdown(text) - else: - clean_text, elements = None, [] - - attaches = await self._upload_attachments(attachments) + message, attaches = await self._prepare_message( + text, + reply_to, + attachments, + delayed_attributes=DelayedAttributes( + time_to_fire=self._convert_time(send_at), + notify_sender=notify, + ) + if send_at + else None, + ) frame = SendMessagePayload( chat_id=chat_id, - message=SendMessagePayloadMessage( - text=clean_text, - cid=self._next_cid(), - elements=elements, - attaches=attaches, - link=ReplyLink(message_id=reply_to) if reply_to else None, - delayed_attributes=DelayedAttributes( - time_to_fire=self._convert_time(send_at), - notify_sender=notify, - ) - if send_at - else None, - ), + message=message, notify=notify, ) @@ -390,6 +424,33 @@ async def fetch_history( ) return messages + 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]: + frame = CommentsHistoryPayload( + chat_id=chat_id, + forward=forward, + backward=backward, + post_id=post_id, + from_=-1 if from_ is None else from_, + get_messages=get_messages, + ) + response = await self.app.invoke( + Opcode.CHAT_HISTORY, + payload=frame.to_payload(), + ) + messages = bind_api_models( + self.app, + parse_payload_list(response, MessagePayloadKey.MESSAGES, Message), + ) + return messages + async def delete_message( self, chat_id: int, @@ -580,3 +641,226 @@ async def vote_poll( response = await self.app.invoke(Opcode.SEND_VOTE, frame.to_payload()) return require_payload_item_model(response, "state", PollState) + + 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: + message, attaches = await self._prepare_message(text, reply_to, attachments) + + frame = SendCommentPayload( + chat_id=chat_id, + post_id=post_id, + notify=notify, + message=message, + ) + + try: + response = await self.app.invoke(Opcode.MSG_SEND, frame.to_payload()) + except ApiError as e: + if e.error == "attachment.not.ready": + await self._process_attachment_error(attaches) + response = await self.app.invoke(Opcode.MSG_SEND, frame.to_payload()) + else: + raise + + return bind_api_model( + self.app, + require_payload_model(response, Message), + ) + + async def get_comments( + self, + chat_id: int, + post_id: int, + message_ids: list[int], + ) -> list[Message]: + frame = GetCommentsPayload( + chat_id=chat_id, + post_id=post_id, + message_ids=message_ids, + ) + + response = await self.app.invoke(Opcode.MSG_GET, frame.to_payload()) + messages = parse_payload_list(response, MessagePayloadKey.MESSAGES, Message) + for message in messages: + if message.chat_id is None: + message.chat_id = chat_id + + return bind_api_models(self.app, messages) + + async def get_comment( + self, + chat_id: int, + post_id: int, + message_id: int, + ) -> Message | None: + messages = await self.get_comments(chat_id, post_id, [message_id]) + return messages[0] if messages else None + + async def edit_comment( + self, + chat_id: int, + post_id: int, + message_id: int, + text: str | None = None, + attachments: SendAttachments = None, + ) -> Message: + if not text and not attachments: + logger.error("edit_comment failed: no text or attachments provided") + raise ValueError("Either text or attachments must be provided") + + if text: + clean_text, elements = Formatter.format_markdown(text) + else: + clean_text, elements = None, [] + + attaches = await self._upload_attachments(attachments) + + frame = EditCommentPayload( + chat_id=chat_id, + post_id=post_id, + message_id=message_id, + text=clean_text, + elements=elements, + attachments=attaches, + ) + try: + response = await self.app.invoke(Opcode.MSG_EDIT, frame.to_payload()) + except ApiError as e: + if e.error == "attachment.not.ready": + await self._process_attachment_error(attaches) + + response = await self.app.invoke(Opcode.MSG_EDIT, frame.to_payload()) + else: + raise + + message = require_payload_item_model( + response, + MessagePayloadKey.MESSAGE, + Message, + ) + if message.chat_id is None: + message.chat_id = chat_id + + return bind_api_model(self.app, message) + + async def delete_comment( + self, + chat_id: int, + post_id: int, + message_ids: list[int], + for_me: bool = False, + ) -> bool: + logger.info( + "deleting messages chat_id=%s ids=%s for_me=%s", + chat_id, + message_ids, + for_me, + ) + frame = DeleteCommentPayload( + chat_id=chat_id, + post_id=post_id, + message_ids=message_ids, + for_me=for_me, + ) + + await self.app.invoke(Opcode.MSG_DELETE, frame.to_payload()) + logger.info("messages deleted chat_id=%s count=%s", chat_id, len(message_ids)) + return True + + async def add_comment_reaction( + self, + chat_id: int, + post_id: int, + message_id: int, + reaction: str, + ) -> ReactionInfo | None: + logger.info( + "adding reaction chat_id=%s message_id=%s reaction=%s", + chat_id, + message_id, + reaction, + ) + frame = AddCommentReactionPayload( + chat_id=chat_id, + post_id=post_id, + message_id=message_id, + reaction=ReactionInfoPayload(id=reaction), + ) + + response = await self.app.invoke(Opcode.MSG_REACTION, frame.to_payload()) + reaction_info = payload_item(response, MessagePayloadKey.REACTION_INFO) + if reaction_info: + return ReactionInfo.model_validate(reaction_info) + + return None + + async def remove_comment_reaction( + self, + chat_id: int, + post_id: int, + message_id: int, + ) -> ReactionInfo | None: + logger.info( + "removing reaction chat_id=%s message_id=%s", + chat_id, + message_id, + ) + frame = RemoveCommentReactionPayload( + chat_id=chat_id, post_id=post_id, message_id=message_id + ) + + response = await self.app.invoke( + Opcode.MSG_CANCEL_REACTION, + frame.to_payload(), + ) + reaction_info = payload_item(response, MessagePayloadKey.REACTION_INFO) + if reaction_info: + return ReactionInfo.model_validate(reaction_info) + + return None + + async def subscribe_comments( + self, + chat_id: int, + post_id: int, + subscribe: bool = True, + ) -> None: + frame = SubscribeCommentsPayload(chat_id=chat_id, post_id=post_id, subscribe=subscribe) + await self.app.invoke(Opcode.CHAT_SUBSCRIBE, frame.to_payload()) + + async def get_comments_info( + self, + chat_id: int, + post_ids: list[int], + ) -> list[CommentsInfoUpdate]: + frame = GetCommentsInfoPayload(chat_id=chat_id, post_ids=post_ids) + response = await self.app.invoke(Opcode.MSG_GET_COMMENTS_INFO, frame.to_payload()) + return parse_payload_list( + response, + MessagePayloadKey.COMMENTS_INFO_UPDATES, + CommentsInfoUpdate, + ) + + async def delete_user_comments( + self, + chat_id: int, + post_id: int, + user_id: int, + message_id: int, + ) -> bool: + frame = DeleteUserCommentsPayload( + chat_id=chat_id, + post_id=post_id, + user_id=user_id, + message_id=message_id, + ) + await self.app.invoke(Opcode.MSG_DELETE_USER_COMMENTS, frame.to_payload()) + return True diff --git a/src/pymax/infra/chat.py b/src/pymax/infra/chat.py index 06363e1..b4cf583 100644 --- a/src/pymax/infra/chat.py +++ b/src/pymax/infra/chat.py @@ -414,3 +414,31 @@ async def add_admin( 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, + ) diff --git a/src/pymax/infra/message.py b/src/pymax/infra/message.py index 366c171..9701f15 100644 --- a/src/pymax/infra/message.py +++ b/src/pymax/infra/message.py @@ -2,6 +2,7 @@ from pymax.api.messages.enums import ItemType from pymax.api.messages.service import SendAttachments from pymax.types import ( + CommentsInfoUpdate, FileRequest, Message, PollState, @@ -379,3 +380,177 @@ async def vote_poll( 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: + """Отправляет комментарий к посту канала. + + ``reply_to`` задает ID комментария для ответа; текст поддерживает markdown. + """ + 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]: + """Возвращает комментарии к посту канала.""" + 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.""" + 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, + ) diff --git a/src/pymax/protocol/enums.py b/src/pymax/protocol/enums.py index ac46316..e432229 100644 --- a/src/pymax/protocol/enums.py +++ b/src/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 diff --git a/src/pymax/types/domain/__init__.py b/src/pymax/types/domain/__init__.py index dbe4603..27a813f 100644 --- a/src/pymax/types/domain/__init__.py +++ b/src/pymax/types/domain/__init__.py @@ -2,6 +2,7 @@ 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 diff --git a/src/pymax/types/domain/comment.py b/src/pymax/types/domain/comment.py new file mode 100644 index 0000000..f47fc39 --- /dev/null +++ b/src/pymax/types/domain/comment.py @@ -0,0 +1,24 @@ +from .base import CamelModel + + +class CommentsInfo(CamelModel): + """Счетчики комментариев поста. + + :ivar total_count: Общее количество комментариев. + :vartype total_count: int + """ + + total_count: int + + +class CommentsInfoUpdate(CamelModel): + """Обновление счетчиков комментариев поста. + + :ivar post_id: ID поста. + :vartype post_id: int + :ivar comments_info: Счетчики комментариев поста. + :vartype comments_info: CommentsInfo + """ + + post_id: int + comments_info: CommentsInfo From 899e7d969bc6ccbfaf91e2be0ce8d1bc8fe7a6a6 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Fri, 25 Sep 2026 15:50:43 +0300 Subject: [PATCH 06/31] fix: parse inline keyboard buttons as rows --- src/pymax/types/domain/attachments/keyboards/inline.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/pymax/types/domain/attachments/keyboards/inline.py b/src/pymax/types/domain/attachments/keyboards/inline.py index 52c6352..6e3c45f 100644 --- a/src/pymax/types/domain/attachments/keyboards/inline.py +++ b/src/pymax/types/domain/attachments/keyboards/inline.py @@ -1,4 +1,4 @@ -from typing import Annotated, Any, Literal, TypeAlias +from typing import Annotated, Literal, TypeAlias from pydantic import Field @@ -65,10 +65,11 @@ class ClipboardButton(BaseButton): | ClipboardButton, Field(discriminator="type"), ] +ButtonRow: TypeAlias = list[Button] class InlineKeyboard(CamelModel): - buttons: list[Button] + buttons: list[ButtonRow] class InlineKeyboardAttachment(CamelModel): From 90316a5c994ad92d4886763a186ca58edd5ce01a Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:24:47 +0300 Subject: [PATCH 07/31] fix: allow null comments info in updates --- src/pymax/types/domain/comment.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pymax/types/domain/comment.py b/src/pymax/types/domain/comment.py index f47fc39..a831030 100644 --- a/src/pymax/types/domain/comment.py +++ b/src/pymax/types/domain/comment.py @@ -21,4 +21,4 @@ class CommentsInfoUpdate(CamelModel): """ post_id: int - comments_info: CommentsInfo + comments_info: CommentsInfo | None From 190e391152150a0971cae13a573218dc41f1b80b Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Fri, 25 Sep 2026 21:43:42 +0300 Subject: [PATCH 08/31] fix: comments info model fix --- src/pymax/types/domain/comment.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pymax/types/domain/comment.py b/src/pymax/types/domain/comment.py index a831030..3fefda9 100644 --- a/src/pymax/types/domain/comment.py +++ b/src/pymax/types/domain/comment.py @@ -8,7 +8,7 @@ class CommentsInfo(CamelModel): :vartype total_count: int """ - total_count: int + total_count: int = 0 class CommentsInfoUpdate(CamelModel): From 6625579986f9918bc77f9ff14709c526f5710388 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:03:46 +0300 Subject: [PATCH 09/31] fix: normalize reaction updates and route self reactions --- src/pymax/dispatch/mapping.py | 1 + src/pymax/types/events/reaction.py | 28 ++++++++++++++++++++++++++-- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/src/pymax/dispatch/mapping.py b/src/pymax/dispatch/mapping.py index bdbb3fe..b35b528 100644 --- a/src/pymax/dispatch/mapping.py +++ b/src/pymax/dispatch/mapping.py @@ -44,6 +44,7 @@ Opcode.NOTIF_MARK: resolve_message_read, Opcode.NOTIF_PRESENCE: resolve_presence, Opcode.NOTIF_MSG_REACTIONS_CHANGED: resolve_reaction_update, + Opcode.NOTIF_MSG_YOU_REACTED: resolve_reaction_update, } diff --git a/src/pymax/types/events/reaction.py b/src/pymax/types/events/reaction.py index 2693f15..719676b 100644 --- a/src/pymax/types/events/reaction.py +++ b/src/pymax/types/events/reaction.py @@ -1,3 +1,7 @@ +from typing import Any + +from pydantic import model_validator + from pymax.types.domain.base import CamelModel from pymax.types.domain.message import ReactionCounter @@ -6,16 +10,36 @@ class ReactionUpdateEvent(CamelModel): """Событие обновления реакций сообщения. :ivar message_id: ID сообщения. - :vartype message_id: str + :vartype message_id: int :ivar chat_id: ID чата. :vartype chat_id: int :ivar counters: Счетчики реакций по типам. :vartype counters: list[ReactionCounter] :ivar total_count: Общее количество реакций. :vartype total_count: int + :ivar your_reaction: Реакция текущего пользователя, если она есть. + :vartype your_reaction: str | None """ - message_id: str + message_id: int chat_id: int counters: list[ReactionCounter] | None = None total_count: int = 0 + your_reaction: str | None = None + + @model_validator(mode="before") + @classmethod + def _unwrap_reaction_info(cls, value: Any) -> Any: + if not isinstance(value, dict): + return value + + reaction_info = value.get("reactionInfo") + if not isinstance(reaction_info, dict): + return value + + data = value.copy() + for field in ("counters", "totalCount", "yourReaction"): + if field in reaction_info: + data[field] = reaction_info[field] + + return data From e31682e1b88035d4819805ff2f803430acdc7aab Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:03:51 +0300 Subject: [PATCH 10/31] fix: dispatch raw frames when typed dispatch fails --- src/pymax/dispatch/dispatcher.py | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/src/pymax/dispatch/dispatcher.py b/src/pymax/dispatch/dispatcher.py index 7fdcb0d..8a17b48 100644 --- a/src/pymax/dispatch/dispatcher.py +++ b/src/pymax/dispatch/dispatcher.py @@ -235,21 +235,22 @@ async def stop_startup_tasks(self) -> None: self.startup_tasks = [] async def dispatch(self, frame: InboundFrame) -> None: - event_type = self.resolver.resolve(frame) - - if event_type is not None: - logger.debug("dispatching event type=%s", event_type) - event = self.mapper.map(event_type, frame) - await self._dispatch_to_router(self.internal_router, event_type, event) - await self._dispatch_to_router(self.root_router, event_type, event) - else: - logger.debug( - "dispatching raw event only opcode=%s cmd=%s", - frame.opcode, - frame.cmd, - ) - - await self._dispatch_to_router(self.root_router, EventType.RAW, frame) + try: + event_type = self.resolver.resolve(frame) + + if event_type is not None: + logger.debug("dispatching event type=%s", event_type) + event = self.mapper.map(event_type, frame) + await self._dispatch_to_router(self.internal_router, event_type, event) + await self._dispatch_to_router(self.root_router, event_type, event) + else: + logger.debug( + "dispatching raw event only opcode=%s cmd=%s", + frame.opcode, + frame.cmd, + ) + finally: + await self._dispatch_to_router(self.root_router, EventType.RAW, frame) async def _dispatch_to_router( self, From 91aea444c9a593f394c1c29ee16818755ab43f1f Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:03:56 +0300 Subject: [PATCH 11/31] refactor: align filter typing and test usage --- src/pymax/filters/__init__.py | 10 ++++- src/pymax/filters/base.py | 50 ++++++++++++------------- src/pymax/filters/containers/chat.py | 8 ++-- src/pymax/filters/containers/message.py | 8 ++-- src/pymax/filters/filters.py | 38 +++++++++---------- src/pymax/filters/refs.py | 8 ++-- tests/dispatch/test_dispatcher.py | 14 ++++--- tests/filters/test_magic.py | 34 ++++++++++------- 8 files changed, 92 insertions(+), 78 deletions(-) diff --git a/src/pymax/filters/__init__.py b/src/pymax/filters/__init__.py index 0f240a0..af91ccf 100644 --- a/src/pymax/filters/__init__.py +++ b/src/pymax/filters/__init__.py @@ -4,4 +4,12 @@ F = MagicFilter() -__all__ = ("Command", "Filter", "Forwarded", "FromMe", "HasAttachment", "MagicFilter", "Reply") +__all__ = ( + "Command", + "Filter", + "Forwarded", + "FromMe", + "HasAttachment", + "MagicFilter", + "Reply", +) diff --git a/src/pymax/filters/base.py b/src/pymax/filters/base.py index e986441..fece961 100644 --- a/src/pymax/filters/base.py +++ b/src/pymax/filters/base.py @@ -13,21 +13,21 @@ MISSING = object() EventT = TypeVar("EventT") -ClientT_contra = TypeVar("ClientT_contra", bound="BaseClient", contravariant=True) +ClientT = TypeVar("ClientT", bound="BaseClient") -class Filter(ABC, Generic[EventT, ClientT_contra]): +class Filter(ABC, Generic[EventT, ClientT]): @abstractmethod def __call__( self, event: EventT, - client: ClientT_contra, + client: ClientT, /, ) -> bool | Awaitable[bool]: ... - def __and__(self, other: Filter[EventT, ClientT_contra]) -> AndFilter: + def __and__(self, other: Filter[EventT, ClientT]) -> AndFilter: return AndFilter(self, other) - def __or__(self, value: Filter[EventT, ClientT_contra]) -> OrFilter: + def __or__(self, value: Filter[EventT, ClientT]) -> OrFilter: return OrFilter(self, value) def __invert__(self) -> NotFilter: @@ -59,7 +59,7 @@ def resolve_path(self, event: Any) -> Any | None: return value -class IsNoneFilter(Filter[EventT, ClientT_contra], PathResolver): +class IsNoneFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -69,7 +69,7 @@ def __init__( self.expected_type = expected_type self.path = path - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -81,7 +81,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return value is None -class IsEmptyFilter(Filter[EventT, ClientT_contra], PathResolver): +class IsEmptyFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -91,7 +91,7 @@ def __init__( self.expected_type = expected_type self.path = path - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -100,7 +100,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return value == [] -class FieldRef(Filter[EventT, ClientT_contra], PathResolver): +class FieldRef(Filter[EventT, ClientT], PathResolver): def __init__(self, path: list[str], expected_type: type[EventT]) -> None: super().__init__(path) self.expected_type: type[EventT] = expected_type @@ -118,7 +118,7 @@ def is_none(self) -> IsNoneFilter: def is_empty(self) -> IsEmptyFilter: return IsEmptyFilter(self.path, expected_type=self.expected_type) - def __call__(self, event: EventT, _: ClientT_contra, /) -> bool: + def __call__(self, event: EventT, _: ClientT, /) -> bool: if not isinstance(event, self.expected_type): return False @@ -130,23 +130,21 @@ def __call__(self, event: EventT, _: ClientT_contra, /) -> bool: return bool(value) -class BinaryFilter(Filter[EventT, ClientT_contra]): - def __init__( - self, left: Filter[EventT, ClientT_contra], right: Filter[EventT, ClientT_contra] - ) -> None: +class BinaryFilter(Filter[EventT, ClientT]): + def __init__(self, left: Filter[EventT, ClientT], right: Filter[EventT, ClientT]) -> None: self.left = left self.right = right -class NotFilter(Filter[EventT, ClientT_contra]): - def __init__(self, filter_instance: Filter[EventT, ClientT_contra]) -> None: +class NotFilter(Filter[EventT, ClientT]): + def __init__(self, filter_instance: Filter[EventT, ClientT]) -> None: self.filter = filter_instance - async def __call__(self, event: EventT, client: ClientT_contra) -> bool: + async def __call__(self, event: EventT, client: ClientT) -> bool: return not await self.resolve_filter_result(self.filter(event, client)) -class NeFilter(Filter[EventT, ClientT_contra], PathResolver): +class NeFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -157,7 +155,7 @@ def __init__( self.expected_type = expected_type self.expected: object = expected - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -169,8 +167,8 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return value != self.expected -class AndFilter(BinaryFilter[EventT, ClientT_contra]): - async def __call__(self, event: EventT, client: ClientT_contra) -> bool: +class AndFilter(BinaryFilter[EventT, ClientT]): + async def __call__(self, event: EventT, client: ClientT) -> bool: left = await self.resolve_filter_result(self.left(event, client)) if not left: @@ -179,8 +177,8 @@ async def __call__(self, event: EventT, client: ClientT_contra) -> bool: return await self.resolve_filter_result(self.right(event, client)) -class OrFilter(BinaryFilter[EventT, ClientT_contra]): - async def __call__(self, event: EventT, client: ClientT_contra) -> bool: +class OrFilter(BinaryFilter[EventT, ClientT]): + async def __call__(self, event: EventT, client: ClientT) -> bool: left = await self.resolve_filter_result(self.left(event, client)) if left: @@ -189,7 +187,7 @@ async def __call__(self, event: EventT, client: ClientT_contra) -> bool: return await self.resolve_filter_result(self.right(event, client)) -class EqFilter(Filter[EventT, ClientT_contra], PathResolver): +class EqFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -200,7 +198,7 @@ def __init__( self.expected_type = expected_type self.expected: object = expected - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False diff --git a/src/pymax/filters/containers/chat.py b/src/pymax/filters/containers/chat.py index 00984a6..480615c 100644 --- a/src/pymax/filters/containers/chat.py +++ b/src/pymax/filters/containers/chat.py @@ -3,18 +3,18 @@ import builtins from typing import TYPE_CHECKING, Any, TypeVar -from pymax.filters.base import ClientT_contra, Filter, PathResolver +from pymax.filters.base import ClientT, Filter, PathResolver from pymax.filters.refs import FieldRef, NumberFieldRef, TextFieldRef from .message import MessageContainer if TYPE_CHECKING: - from pymax.base import BaseClient + pass EventT = TypeVar("EventT") -class ChatContainer(Filter[EventT, ClientT_contra], PathResolver): +class ChatContainer(Filter[EventT, ClientT], PathResolver): def __init__( self, expected_type: builtins.type[EventT], @@ -233,7 +233,7 @@ def cid(self) -> NumberFieldRef: expected_type=self.expected_type, ) - def __call__(self, event: Any, client: ClientT_contra) -> bool: + def __call__(self, event: Any, client: ClientT) -> bool: if not isinstance(event, self.expected_type): return False diff --git a/src/pymax/filters/containers/message.py b/src/pymax/filters/containers/message.py index 32293d3..6d03656 100644 --- a/src/pymax/filters/containers/message.py +++ b/src/pymax/filters/containers/message.py @@ -3,16 +3,16 @@ import builtins from typing import TYPE_CHECKING, Any, TypeVar -from pymax.filters.base import ClientT_contra, Filter, PathResolver +from pymax.filters.base import ClientT, Filter, PathResolver from pymax.filters.refs import FieldRef, NumberFieldRef, TextFieldRef if TYPE_CHECKING: - from pymax.base import BaseClient + pass EventT = TypeVar("EventT") -class MessageContainer(Filter[EventT, ClientT_contra], PathResolver): +class MessageContainer(Filter[EventT, ClientT], PathResolver): def __init__( self, expected_type: builtins.type[EventT], @@ -140,7 +140,7 @@ def elements(self) -> FieldRef: expected_type=self.expected_type, ) - def __call__(self, event: Any, client: ClientT_contra) -> bool: + def __call__(self, event: Any, client: ClientT) -> bool: if not isinstance(event, self.expected_type): return False diff --git a/src/pymax/filters/filters.py b/src/pymax/filters/filters.py index 4942ce2..d6115b1 100644 --- a/src/pymax/filters/filters.py +++ b/src/pymax/filters/filters.py @@ -1,16 +1,16 @@ from __future__ import annotations -from typing import TYPE_CHECKING, Any, TypeVar +from typing import TYPE_CHECKING, TypeVar -from .base import ClientT_contra, Filter, PathResolver +from .base import ClientT, Filter, PathResolver if TYPE_CHECKING: - from pymax.base import BaseClient + pass EventT = TypeVar("EventT") -class ContainsFilter(Filter[EventT, ClientT_contra], PathResolver): +class ContainsFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -23,7 +23,7 @@ def __init__( self.text = text self.ignore_case = ignore_case - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -38,7 +38,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return self.text in value -class StartsWithFilter(Filter[EventT, ClientT_contra], PathResolver): +class StartsWithFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -51,7 +51,7 @@ def __init__( self.text = text self.ignore_case = ignore_case - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -66,7 +66,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return value.startswith(self.text) -class EndsWithFilter(Filter[EventT, ClientT_contra], PathResolver): +class EndsWithFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -79,7 +79,7 @@ def __init__( self.text = text self.ignore_case = ignore_case - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -94,7 +94,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return value.endswith(self.text) -class LessThanFilter(Filter[EventT, ClientT_contra], PathResolver): +class LessThanFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -105,7 +105,7 @@ def __init__( self.expected_type = expected_type self.expected = expected - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -117,7 +117,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return value < self.expected -class LessThanOrEqualFilter(Filter[EventT, ClientT_contra], PathResolver): +class LessThanOrEqualFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -128,7 +128,7 @@ def __init__( self.expected_type = expected_type self.expected = expected - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -140,7 +140,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return value <= self.expected -class GreaterThanFilter(Filter[EventT, ClientT_contra], PathResolver): +class GreaterThanFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -151,7 +151,7 @@ def __init__( self.expected_type = expected_type self.expected = expected - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -163,7 +163,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return value > self.expected -class GreaterThanOrEqualFilter(Filter[EventT, ClientT_contra], PathResolver): +class GreaterThanOrEqualFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -174,7 +174,7 @@ def __init__( self.expected_type = expected_type self.expected = expected - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -186,7 +186,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return value >= self.expected -class BetweenFilter(Filter[EventT, ClientT_contra], PathResolver): +class BetweenFilter(Filter[EventT, ClientT], PathResolver): def __init__( self, path: list[str], @@ -199,7 +199,7 @@ def __init__( self.minimum = minimum self.maximum = maximum - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False diff --git a/src/pymax/filters/refs.py b/src/pymax/filters/refs.py index 4e0d99f..a2944a6 100644 --- a/src/pymax/filters/refs.py +++ b/src/pymax/filters/refs.py @@ -2,7 +2,7 @@ from typing import TypeVar -from .base import MISSING, ClientT_contra, FieldRef +from .base import MISSING, ClientT, FieldRef from .filters import ( BetweenFilter, ContainsFilter, @@ -17,7 +17,7 @@ EventT = TypeVar("EventT") -class TextFieldRef(FieldRef[EventT, ClientT_contra]): +class TextFieldRef(FieldRef[EventT, ClientT]): def contains(self, text: str, *, ignore_case: bool = False) -> ContainsFilter: return ContainsFilter(self.path, self.expected_type, text, ignore_case) @@ -27,7 +27,7 @@ def startswith(self, text: str, *, ignore_case: bool = False) -> StartsWithFilte def endswith(self, text: str, *, ignore_case: bool = False) -> EndsWithFilter: return EndsWithFilter(self.path, self.expected_type, text, ignore_case) - def __call__(self, event: EventT, _: ClientT_contra) -> bool: + def __call__(self, event: EventT, _: ClientT) -> bool: if not isinstance(event, self.expected_type): return False @@ -39,7 +39,7 @@ def __call__(self, event: EventT, _: ClientT_contra) -> bool: return bool(value) -class NumberFieldRef(FieldRef[EventT, ClientT_contra]): +class NumberFieldRef(FieldRef[EventT, ClientT]): def __lt__(self, value: float) -> LessThanFilter: return LessThanFilter(self.path, self.expected_type, value) diff --git a/tests/dispatch/test_dispatcher.py b/tests/dispatch/test_dispatcher.py index 181cc73..305174d 100644 --- a/tests/dispatch/test_dispatcher.py +++ b/tests/dispatch/test_dispatcher.py @@ -4,7 +4,7 @@ from pymax.dispatch import Dispatcher, Router from pymax.dispatch.enums import EventType -from pymax.filters import F +from pymax.filters import F, Filter from pymax.protocol import Command, Opcode from tests.conftest import FakeApp, chat_payload, frame, message_payload @@ -17,13 +17,15 @@ async def test_dispatcher_routes_message_events_through_filters_and_raw_handler( dispatcher.bind_client("client") seen: list[tuple[str, int | str]] = [] - def is_start(message, _client): - return message.text == "/start" + class IsStart(Filter): + def __call__(self, message, _client): + return message.text == "/start" - def has_chat(message, _client): - return message.chat_id == 100 + class HasChat(Filter): + async def __call__(self, message, _client): + return message.chat_id == 100 - @router.on_message(is_start, has_chat) + @router.on_message(IsStart(), HasChat()) async def on_message(message, client): seen.append((client, message.id)) diff --git a/tests/filters/test_magic.py b/tests/filters/test_magic.py index d9486a3..207141c 100644 --- a/tests/filters/test_magic.py +++ b/tests/filters/test_magic.py @@ -1,5 +1,7 @@ from types import SimpleNamespace +import pytest + from pymax.filters import Command, F, FromMe, HasAttachment from pymax.types import Chat, Message, PhotoAttachment @@ -42,10 +44,10 @@ def make_photo() -> PhotoAttachment: ) -def test_message_container_exposes_all_message_fields() -> None: +def test_message_container_exposes_supported_message_fields() -> None: fields = {name for name, value in vars(type(F.message)).items() if isinstance(value, property)} - assert fields == set(Message.model_fields) + assert fields == set(Message.model_fields) - {"link"} def test_chat_container_exposes_all_chat_fields() -> None: @@ -54,22 +56,24 @@ def test_chat_container_exposes_all_chat_fields() -> None: assert fields == set(Chat.model_fields) -def test_message_field_filters_support_comparison_and_logical_operations() -> None: +@pytest.mark.asyncio +async def test_message_field_filters_support_comparison_and_logical_operations() -> None: message = make_message() client = make_client() filter_ = F.message.text.contains("hello") & ~(F.message.sender == 20) - assert filter_(message, client) is True + assert await filter_(message, client) is True assert (F.message.chat_id == 100)(message, client) is True assert (F.message.chat_id == 200)(message, client) is False -def test_chat_field_filters_support_comparison_and_logical_operations() -> None: +@pytest.mark.asyncio +async def test_chat_field_filters_support_comparison_and_logical_operations() -> None: chat = make_chat() client = make_client() filter_ = F.chat.title.contains("PyMax") & (F.chat.owner == 10) - assert filter_(chat, client) is True + assert await filter_(chat, client) is True assert (F.chat.status == "INACTIVE")(chat, client) is False @@ -121,19 +125,21 @@ def test_text_field_filters_support_case_sensitive_and_insensitive_matching() -> assert F.message.text.endswith("PYMAX", ignore_case=True)(message, client) is True -def test_presets_support_and_composition() -> None: +@pytest.mark.asyncio +async def test_presets_support_and_composition() -> None: client = make_client() filter_ = HasAttachment(PhotoAttachment) & FromMe() - assert filter_(make_message(attaches=[make_photo()]), client) is True - assert filter_(make_message(sender=20, attaches=[make_photo()]), client) is False - assert filter_(make_message(), client) is False + assert await filter_(make_message(attaches=[make_photo()]), client) is True + assert await filter_(make_message(sender=20, attaches=[make_photo()]), client) is False + assert await filter_(make_message(), client) is False -def test_presets_support_or_composition() -> None: +@pytest.mark.asyncio +async def test_presets_support_or_composition() -> None: client = make_client() filter_ = Command("start") | HasAttachment(PhotoAttachment) - assert filter_(make_message(text="/start"), client) is True - assert filter_(make_message(text="hello", attaches=[make_photo()]), client) is True - assert filter_(make_message(text="hello"), client) is False + assert await filter_(make_message(text="/start"), client) is True + assert await filter_(make_message(text="hello", attaches=[make_photo()]), client) is True + assert await filter_(make_message(text="hello"), client) is False From 141ec84c4eb236c873c531e1014769a710b6d8ea Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:04:00 +0300 Subject: [PATCH 12/31] chore: update Android device profiles --- src/pymax/config.py | 70 ++++++++++++++++++++++++--------------------- 1 file changed, 38 insertions(+), 32 deletions(-) diff --git a/src/pymax/config.py b/src/pymax/config.py index 458e69b..2a004be 100644 --- a/src/pymax/config.py +++ b/src/pymax/config.py @@ -57,42 +57,48 @@ # ("26.9.1", 6643), ) ANDROID_DEVICES: tuple[tuple[str, str, str, str], ...] = ( - ("Samsung SM-A525F", "Android 13", "405dpi 405dpi 1080x2400", "arm64-v8a"), - ("Samsung SM-A536B", "Android 14", "405dpi 405dpi 1080x2400", "arm64-v8a"), - ("Samsung SM-A546E", "Android 14", "405dpi 405dpi 1080x2340", "arm64-v8a"), - ("Samsung SM-G991B", "Android 14", "421dpi 421dpi 1080x2400", "arm64-v8a"), - ("Samsung SM-G998B", "Android 13", "515dpi 515dpi 1440x3200", "arm64-v8a"), - ("Samsung SM-S901B", "Android 14", "425dpi 425dpi 1080x2340", "arm64-v8a"), - ("Samsung SM-S911B", "Android 14", "425dpi 425dpi 1080x2340", "arm64-v8a"), - ("Xiaomi 2109119DG", "Android 13", "395dpi 395dpi 1080x2400", "arm64-v8a"), - ("Xiaomi 2201117TG", "Android 13", "395dpi 395dpi 1080x2400", "arm64-v8a"), - ("Xiaomi 2201123G", "Android 14", "526dpi 526dpi 1440x3200", "arm64-v8a"), - ("Xiaomi 2210132G", "Android 14", "446dpi 446dpi 1220x2712", "arm64-v8a"), ( - "Xiaomi 23049PCD8G", + "Google Pixel 6a", + "Android 13", + "420dpi 420dpi 1080x2400", + "arm64-v8a", + ), + ( + "Google Pixel 7", + "Android 13", + "420dpi 420dpi 1080x2400", + "arm64-v8a", + ), + ( + "Google Pixel 7 Pro", + "Android 13", + "560dpi 560dpi 1440x3120", + "arm64-v8a", + ), + ( + "Google Pixel 8", "Android 14", - "446dpi 446dpi 1220x2712", + "420dpi 420dpi 1080x2400", + "arm64-v8a", + ), + ( + "samsung SM-G991B", + "Android 14", + "xxhdpi 480dpi 1080x2400", + "arm64-v8a", + ), + ( + "samsung SM-S911B", + "Android 15", + "xxhdpi 480dpi 1080x2340", + "arm64-v8a", + ), + ( + "Xiaomi 2201117TG", + "Android 13", + "440dpi 440dpi 1080x2400", "arm64-v8a", ), - ("Redmi 2201116TG", "Android 13", "395dpi 395dpi 1080x2400", "arm64-v8a"), - ("Redmi 22101316G", "Android 13", "395dpi 395dpi 1080x2400", "arm64-v8a"), - ("Redmi 23021RAA2Y", "Android 14", "395dpi 395dpi 1080x2400", "arm64-v8a"), - ("POCO 22011211G", "Android 13", "395dpi 395dpi 1080x2400", "arm64-v8a"), - ("POCO 23049PCD8G", "Android 14", "446dpi 446dpi 1220x2712", "arm64-v8a"), - ("Pixel 6", "Android 14", "411dpi 411dpi 1080x2400", "arm64-v8a"), - ("Pixel 6a", "Android 14", "429dpi 429dpi 1080x2400", "arm64-v8a"), - ("Pixel 7", "Android 14", "416dpi 416dpi 1080x2400", "arm64-v8a"), - ("Pixel 7 Pro", "Android 14", "512dpi 512dpi 1440x3120", "arm64-v8a"), - ("Pixel 8", "Android 14", "428dpi 428dpi 1080x2400", "arm64-v8a"), - ("OnePlus NE2213", "Android 14", "525dpi 525dpi 1440x3216", "arm64-v8a"), - ("OnePlus CPH2449", "Android 14", "451dpi 451dpi 1240x2772", "arm64-v8a"), - ("realme RMX3085", "Android 13", "409dpi 409dpi 1080x2400", "arm64-v8a"), - ("realme RMX3370", "Android 13", "409dpi 409dpi 1080x2400", "arm64-v8a"), - ("realme RMX3630", "Android 13", "400dpi 400dpi 1080x2412", "arm64-v8a"), - ("HUAWEI ELS-NX9", "Android 12", "441dpi 441dpi 1080x2340", "arm64-v8a"), - ("HUAWEI VOG-L29", "Android 12", "398dpi 398dpi 1080x2340", "arm64-v8a"), - ("HONOR RMO-NX1", "Android 13", "391dpi 391dpi 1080x2388", "arm64-v8a"), - ("HONOR REA-NX9", "Android 13", "435dpi 435dpi 1200x2664", "arm64-v8a"), ) LOCALE_TIMEZONES: tuple[tuple[str, str], ...] = ( ("ru", "Europe/Moscow"), From 9cab675435fe4fcee717fac03bee9c2fc8a8fba3 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:04:06 +0300 Subject: [PATCH 13/31] chore: clean up model examples and typing annotations --- src/pymax/api/auth/service.py | 1 + src/pymax/api/auth/types.py | 3 +++ src/pymax/api/response.py | 2 +- src/pymax/client.py | 1 - src/pymax/types/domain/message.py | 18 ------------------ 5 files changed, 5 insertions(+), 20 deletions(-) diff --git a/src/pymax/api/auth/service.py b/src/pymax/api/auth/service.py index 24f5996..c838a6e 100644 --- a/src/pymax/api/auth/service.py +++ b/src/pymax/api/auth/service.py @@ -97,6 +97,7 @@ async def request_code(self, phone: str) -> StartAuthResponse: "sms code request accepted payload_keys=%s", payload_keys(response), ) + return require_payload_model(response, StartAuthResponse) async def send_code(self, token: str, verify_code: str) -> CheckCodeResponse: diff --git a/src/pymax/api/auth/types.py b/src/pymax/api/auth/types.py index cd98cc2..af6b902 100644 --- a/src/pymax/api/auth/types.py +++ b/src/pymax/api/auth/types.py @@ -1,9 +1,12 @@ from typing import Final, TypeAlias +from typing_extensions import override + class MissingType: __slots__ = () + @override def __repr__(self) -> str: return "MISSING" diff --git a/src/pymax/api/response.py b/src/pymax/api/response.py index 1440746..cc6aac7 100644 --- a/src/pymax/api/response.py +++ b/src/pymax/api/response.py @@ -60,7 +60,7 @@ def payload_item( if validation_type is None: return data - return cast(Any, validation_type)(data) + return cast("Any", validation_type)(data) def require_payload_item( diff --git a/src/pymax/client.py b/src/pymax/client.py index 80a641d..bbf703a 100644 --- a/src/pymax/client.py +++ b/src/pymax/client.py @@ -63,7 +63,6 @@ def __init__( # noqa: PLR0913 app_version: str = VersionCatalog.RECOMMENDED_APP_VERSION, catalog: VersionCatalog | None = None, ) -> None: - self.phone: str = phone self.extra_config: ExtraConfig = extra_config or ExtraConfig() self.session_name: str = session_name diff --git a/src/pymax/types/domain/message.py b/src/pymax/types/domain/message.py index c5b22f8..8ad3a80 100644 --- a/src/pymax/types/domain/message.py +++ b/src/pymax/types/domain/message.py @@ -139,24 +139,6 @@ class ForwardLink(MessageLink): chat_icon_url: str | None = None -""" - "link": { - "type": "FORWARD", - "message": { - "id": "116641336752745888", - "time": 1779805553478, - "type": "CHANNEL", - "text": "Добро пожаловать на наше шоу!", - "attaches": [] - }, - "chatId": -75183661482741, - "chatName": "Max Bounty Test", - "chatLink": "https://max.ru/join/htlT5aTtlpAgcno_hc93lLM44Dxe45HvOEBqx22lKms", - "chatAccessType": "PRIVATE" - } -""" - - class Message(CamelModel): """Сообщение Max с методами для действий над ним. From aaf6f9f674a09d72f5fb3877ee72e0f74302f35c Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:04:11 +0300 Subject: [PATCH 14/31] fix: read photo upload ids from photos URL parameter --- src/pymax/api/uploads/service.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pymax/api/uploads/service.py b/src/pymax/api/uploads/service.py index 24cdb54..5a08345 100644 --- a/src/pymax/api/uploads/service.py +++ b/src/pymax/api/uploads/service.py @@ -82,11 +82,11 @@ async def upload_photo(self, photo: Photo, profile: bool = False) -> AttachPhoto try: parsed_url = urlparse(url) - photo_id = str(parse_qs(parsed_url.query)["photoIds"][0]) + photo_id = str(parse_qs(parsed_url.query)["photos"][0]) # TODO: enum maybe? except (KeyError, IndexError) as e: - logger.exception("Photo upload URL does not contain photoIds") + logger.exception("Photo upload URL does not contain photos") logger.debug("Invalid photo upload URL=%s", url) - raise UploadError("Photo upload URL does not contain photoIds") from e + raise UploadError("Photo upload URL does not contain photos") from e except Exception as e: logger.exception("Failed to parse photo id from upload URL") logger.debug("Invalid photo upload URL=%s", url) From 10d6c93651d2d8ae13bc161900e594f6a0cc41d2 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:04:16 +0300 Subject: [PATCH 15/31] refactor: use integer ids for read_message --- src/pymax/api/messages/payloads.py | 2 +- src/pymax/api/messages/service.py | 2 +- src/pymax/infra/message.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pymax/api/messages/payloads.py b/src/pymax/api/messages/payloads.py index dca658b..a364a2d 100644 --- a/src/pymax/api/messages/payloads.py +++ b/src/pymax/api/messages/payloads.py @@ -150,7 +150,7 @@ class RemoveReactionPayload(CamelModel): class ReadMessagesPayload(CamelModel): type: ReadAction chat_id: int - message_id: str | int # Сокет просит int а вс str + message_id: int mark: int diff --git a/src/pymax/api/messages/service.py b/src/pymax/api/messages/service.py index 0a79aab..1bc923d 100644 --- a/src/pymax/api/messages/service.py +++ b/src/pymax/api/messages/service.py @@ -612,7 +612,7 @@ async def remove_reaction( return None - 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: logger.info( "marking message as read chat_id=%s message_id=%s", chat_id, diff --git a/src/pymax/infra/message.py b/src/pymax/infra/message.py index 9701f15..0654221 100644 --- a/src/pymax/infra/message.py +++ b/src/pymax/infra/message.py @@ -337,7 +337,7 @@ async def remove_reaction( 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`` для отметки прочтения: From 192a8e76d1c203230c061692974941ad0953ebb5 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Fri, 23 Oct 2026 22:18:56 +0300 Subject: [PATCH 16/31] fix: accept full LZ4 compression factor range --- src/pymax/protocol/tcp/payload.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/pymax/protocol/tcp/payload.py b/src/pymax/protocol/tcp/payload.py index 175d1aa..aac6060 100644 --- a/src/pymax/protocol/tcp/payload.py +++ b/src/pymax/protocol/tcp/payload.py @@ -128,8 +128,6 @@ def decode(self, payload_bytes: bytes, flags: int = 0) -> dict[str, Any]: 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") From 9008f8884a1cdfe3c5d5a531b6145dfd37a2a5ff Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Fri, 23 Oct 2026 22:19:08 +0300 Subject: [PATCH 17/31] fix: support photo upload URL variants --- src/pymax/api/uploads/service.py | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/pymax/api/uploads/service.py b/src/pymax/api/uploads/service.py index 5a08345..1122f67 100644 --- a/src/pymax/api/uploads/service.py +++ b/src/pymax/api/uploads/service.py @@ -82,11 +82,9 @@ async def upload_photo(self, photo: Photo, profile: bool = False) -> AttachPhoto try: parsed_url = urlparse(url) - photo_id = str(parse_qs(parsed_url.query)["photos"][0]) # TODO: enum maybe? - except (KeyError, IndexError) as e: - logger.exception("Photo upload URL does not contain photos") - logger.debug("Invalid photo upload URL=%s", url) - raise UploadError("Photo upload URL does not contain photos") from e + query = parse_qs(parsed_url.query) + photo_ids = query.get("photos") or query.get("photoIds") + photo_id = str(photo_ids[0]) if photo_ids else None except Exception as e: logger.exception("Failed to parse photo id from upload URL") logger.debug("Invalid photo upload URL=%s", url) @@ -165,6 +163,12 @@ async def upload_photo(self, photo: Photo, profile: bool = False) -> AttachPhoto logger.debug("Invalid photo upload response=%r", result) raise UploadError("Invalid photo upload response model") from e + if photo_id is None: + if len(model.photos) != 1: + logger.error("Expected one photo in upload response without a photo id") + raise UploadError("Expected one photo in upload response without a photo id") + photo_id = next(iter(model.photos)) + try: token = model.photos[photo_id].token except KeyError as e: From c0b8f671157a25d60bc2d4adf7d52d15db7bda0d Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Fri, 23 Oct 2026 22:20:10 +0300 Subject: [PATCH 18/31] fix: stop repeated authentication after token revocation --- src/pymax/base.py | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/src/pymax/base.py b/src/pymax/base.py index b4e92dc..8061e0a 100644 --- a/src/pymax/base.py +++ b/src/pymax/base.py @@ -189,13 +189,18 @@ async def connect(self: ClientT) -> None: # noqa: PYI019 self.extra_config.reconnect_delay, ) raise + except Exception: + await self.close() + raise async def start(self: ClientT) -> None: # noqa: PYI019 """Запускает клиента и слушает события до закрытия соединения. При сетевых ошибках повторяет подключение, если ``reconnect=True``. Отозванный login token автоматически сбрасывается при ``relogin=True``. + Если новый token тоже отклонен, ошибка передается вызывающему коду. """ + relogin_attempted = False while True: try: await self._ensure_runtime() @@ -204,19 +209,24 @@ async def start(self: ClientT) -> None: # noqa: PYI019 await self.close() return + relogin_attempted = False await self._app.dispatcher.emit_start(self) await self._connection.wait_closed() except asyncio.CancelledError: await self.close() raise except ApiError as e: - if not self._app._is_invalid_login_token_error(e): + if ( + not self._app._is_invalid_login_token_error(e) + or not self.extra_config.relogin + or relogin_attempted + ): await self.close() raise logger.warning("login token was revoked; starting authentication again") - if self.extra_config.relogin: - await self.relogin(start=False) + relogin_attempted = True + await self.relogin(start=False) except ( ConnectionError, EOFError, From d818071cc7111c150e80a8494201e5cfea67ea5b Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Fri, 23 Oct 2026 22:21:34 +0300 Subject: [PATCH 19/31] feat: expose client middleware registration and execution chain --- docs/router.rst | 34 ++++++++++++++++++ src/pymax/base.py | 13 ++++++- src/pymax/dispatch/__init__.py | 5 +++ src/pymax/dispatch/dispatcher.py | 62 +++++++++++++++++++++++++++++--- src/pymax/dispatch/mapping.py | 15 +++++++- src/pymax/dispatch/middleware.py | 23 ++++++++++++ src/pymax/dispatch/router.py | 2 ++ 7 files changed, 147 insertions(+), 7 deletions(-) create mode 100644 src/pymax/dispatch/middleware.py diff --git a/docs/router.rst b/docs/router.rst index 34492ec..40eb45b 100644 --- a/docs/router.rst +++ b/docs/router.rst @@ -128,6 +128,40 @@ Root router Все фильтры должны вернуть ``True``. Если хотя бы один фильтр вернул ``False``, handler не вызывается. +Middleware +---------- + +``client.add_middleware()`` добавляет middleware в общую цепочку обработчиков +клиента, включая подключенные роутеры. Регистрировать middleware можно до +``connect()`` или ``start()``; регистрация сохраняется при reconnect. + +.. code-block:: python + + from typing import Any + + from pymax import Client + from pymax.dispatch import DispatchEvent, MiddlewareNext + + client = Client(phone="+79990000000") + + + async def log_event( + client: Client, + event: DispatchEvent, + call_next: MiddlewareNext, + ) -> Any: + print(type(event).__name__) + return await call_next(event) + + + client.add_middleware(log_event) + +Middleware выполняются после фильтров, перед подходящим handler-ом. Первое +зарегистрированное middleware входит первым, а выходит последним. Чтобы +продолжить цепочку, вызовите ``await call_next(event)``. Внутренние обработчики +готовности загрузок выполняются отдельно и через пользовательскую цепочку +не проходят. + Почему handler принимает event и client --------------------------------------- diff --git a/src/pymax/base.py b/src/pymax/base.py index 8061e0a..ae62ed7 100644 --- a/src/pymax/base.py +++ b/src/pymax/base.py @@ -4,7 +4,7 @@ from abc import ABC, abstractmethod from typing import TYPE_CHECKING, Any, Generic, TypeVar -from pymax.dispatch import ErrorScope, Router +from pymax.dispatch import ErrorScope, Middleware, Router from pymax.dispatch.router import DisconnectDecorator, ErrorDecorator from pymax.exceptions import ApiError from pymax.filters import Filter @@ -353,6 +353,17 @@ def include_router(self, router: Router[ClientT]) -> None: """Подключает дочерний router к root router клиента.""" self._router.include_router(router) + def add_middleware(self, middleware: Middleware[ClientT]) -> None: + """Добавляет middleware в цепочку обработчиков клиента. + + Middleware вызываются в порядке регистрации после проверки фильтров. + Регистрация доступна до запуска клиента и сохраняется при reconnect. + """ + if middleware not in self._router.middlewares: + self._router.middlewares.append(middleware) + else: + logger.warning(f"Middleware {middleware.__class__.__name__} is already registered") + async def relogin(self: ClientT, drop_config_token: bool = True, start: bool = True) -> None: # noqa: PYI019 """Удаляет текущую локальную сессию и запускает авторизацию заново. diff --git a/src/pymax/dispatch/__init__.py b/src/pymax/dispatch/__init__.py index 3628ae9..373f10a 100644 --- a/src/pymax/dispatch/__init__.py +++ b/src/pymax/dispatch/__init__.py @@ -1,5 +1,7 @@ from .dispatcher import Dispatcher from .enums import EventType +from .mapping import DispatchEvent +from .middleware import Middleware, MiddlewareNext from .router import ( ClientRouter, DisconnectCallback, @@ -13,9 +15,12 @@ "ClientRouter", "DisconnectCallback", "DisconnectDecorator", + "DispatchEvent", "Dispatcher", "ErrorContext", "ErrorScope", "EventType", + "Middleware", + "MiddlewareNext", "Router", ) diff --git a/src/pymax/dispatch/dispatcher.py b/src/pymax/dispatch/dispatcher.py index 8a17b48..0ad6f0a 100644 --- a/src/pymax/dispatch/dispatcher.py +++ b/src/pymax/dispatch/dispatcher.py @@ -18,7 +18,8 @@ ) from .enums import EventType -from .mapping import EventMapper, EventResolver +from .mapping import DispatchEvent, EventMapper, EventResolver +from .middleware import Middleware, MiddlewareNext from .router import ( DisconnectCallback, DisconnectDecorator, @@ -51,6 +52,7 @@ class Dispatcher(Generic[ClientT]): def __init__(self, app: App, root_router: Router[ClientT] | None = None) -> None: self.root_router: Router[ClientT] = root_router or Router() + self.middlewares: list[Middleware[ClientT]] = self.root_router.middlewares self.internal_router: Router[ClientT] = Router() self.resolver = EventResolver() self.mapper = EventMapper(app) @@ -68,6 +70,12 @@ def include_router(self, router: Router[ClientT]) -> None: len(router.children), ) + def add_middleware(self, middleware: Middleware) -> None: + if middleware not in self.middlewares: # TODO: make better comparison or just remove it + self.middlewares.append(middleware) + else: + logger.warning(f"Middleware {middleware.__class__.__name__} is already registered") + def on_internal( self, event: EventType, @@ -241,7 +249,9 @@ async def dispatch(self, frame: InboundFrame) -> None: if event_type is not None: logger.debug("dispatching event type=%s", event_type) event = self.mapper.map(event_type, frame) - await self._dispatch_to_router(self.internal_router, event_type, event) + await self._dispatch_to_router( + self.internal_router, event_type, event, apply_middleware=False + ) await self._dispatch_to_router(self.root_router, event_type, event) else: logger.debug( @@ -256,7 +266,9 @@ async def _dispatch_to_router( self, router: Router[ClientT], event_type: EventType, - event: Any, + event: DispatchEvent, + *, + apply_middleware: bool = True, ) -> None: for entry in router.handlers.get(event_type, []): try: @@ -266,14 +278,54 @@ async def _dispatch_to_router( event_type, _callback_name(entry.callback), ) - await self._call(entry.callback, event) + if apply_middleware: + await self._call_with_middleware(entry.callback, event) + else: + await self._call(entry.callback, event) except Exception as e: # noqa: PERF203 handled = await self.emit_error(e, event_type, event, router, entry) if not handled: raise for child in router.children: - await self._dispatch_to_router(child, event_type, event) + await self._dispatch_to_router( + child, + event_type, + event, + apply_middleware=apply_middleware, + ) + + async def _call_with_middleware( + self, + callback: HandlerCallback[DispatchEvent, ClientT], + event: DispatchEvent, + ) -> Any: + + async def call_handler(event: DispatchEvent) -> Any: + return await self._call(callback, event) + + call_next: MiddlewareNext = call_handler + + for middleware in reversed(self.middlewares): + next_ = call_next + + async def wrapped( + event: DispatchEvent, + middleware: Middleware[ClientT] = middleware, + next_: MiddlewareNext = next_, + ) -> Any: + if self.client is None: + raise RuntimeError("client is not bound") + + return await middleware( + self.client, + event, + next_, + ) + + call_next = wrapped + + return await call_next(event) async def _matches( self, diff --git a/src/pymax/dispatch/mapping.py b/src/pymax/dispatch/mapping.py index b35b528..93d4636 100644 --- a/src/pymax/dispatch/mapping.py +++ b/src/pymax/dispatch/mapping.py @@ -1,7 +1,7 @@ from __future__ import annotations from collections.abc import Callable -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, TypeAlias from pymax.api.binding import bind_api_model from pymax.protocol import InboundFrame, Opcode @@ -33,6 +33,19 @@ from pymax.app import App Resolver = Callable[[InboundFrame], EventType | None] +DispatchEvent: TypeAlias = ( + Message + | Chat + | MessageDeleteEvent + | MessageReadEvent + | TypingEvent + | PresenceEvent + | ReactionUpdateEvent + | VideoUploadSignal + | FileUploadSignal + | AudioUploadSignal + | InboundFrame +) EVENT_MAP: dict[Opcode, Resolver] = { Opcode.NOTIF_MESSAGE: resolve_message, diff --git a/src/pymax/dispatch/middleware.py b/src/pymax/dispatch/middleware.py new file mode 100644 index 0000000..c996123 --- /dev/null +++ b/src/pymax/dispatch/middleware.py @@ -0,0 +1,23 @@ +from __future__ import annotations + +from collections.abc import Awaitable, Callable +from typing import TYPE_CHECKING, Any, Generic, Protocol, TypeAlias, TypeVar + +from .mapping import DispatchEvent + +if TYPE_CHECKING: + from pymax.base import BaseClient + + +ClientT_contra = TypeVar("ClientT_contra", bound="BaseClient", contravariant=True) + +MiddlewareNext: TypeAlias = Callable[[DispatchEvent], Awaitable[Any]] + + +class Middleware(Protocol, Generic[ClientT_contra]): + async def __call__( + self, + client: ClientT_contra, + event: DispatchEvent, + call_next: MiddlewareNext, + ) -> Any: ... diff --git a/src/pymax/dispatch/router.py b/src/pymax/dispatch/router.py index 30286f0..385319b 100644 --- a/src/pymax/dispatch/router.py +++ b/src/pymax/dispatch/router.py @@ -14,6 +14,7 @@ if TYPE_CHECKING: from pymax.base import BaseClient from pymax.client import Client + from pymax.dispatch.middleware import Middleware from pymax.protocol import InboundFrame from pymax.types import Chat from pymax.types.domain import Message @@ -133,6 +134,7 @@ def __init__(self) -> None: ] = defaultdict(list) self.children: list[Router[ClientT]] = [] + self.middlewares: list[Middleware[ClientT]] = [] self.on_start_handlers: list[StartCallback[ClientT]] = [] self.error_handlers: list[ErrorEntry[ClientT]] = [] self.disconnect_handlers: list[DisconnectCallback] = [] From 993ea68ac2ec76430704f61bfc90c2e803b6ca76 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:42:33 +0300 Subject: [PATCH 20/31] fix: preserve literal content inside Markdown code --- src/pymax/formatting/markdown.py | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/pymax/formatting/markdown.py b/src/pymax/formatting/markdown.py index f0b12c7..f51896e 100644 --- a/src/pymax/formatting/markdown.py +++ b/src/pymax/formatting/markdown.py @@ -88,6 +88,34 @@ def format_markdown(text: str) -> tuple[str, list[Element]]: while i < len(text): handled = False + for marker in ("```", "`"): + if marker not in active: + continue + + closing_index = text.find(marker, i) + content = text[i:closing_index] + clean_text += content + clean_pos += Formatter._code_units_len(content) + + start = active.pop(marker) + length = clean_pos - start + if length > 0: + entities.append( + Element( + type=Formatter.MARKERS[marker], + from_=start, + length=length, + ) + ) + + i = closing_index + len(marker) + handled = True + break + + if handled: + line_start = False + continue + # LINK: [text](url) parsed_link = Formatter._parse_link(text, i, clean_pos) From de768429d3a8810584280813e970a772544c1ff6 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:42:57 +0300 Subject: [PATCH 21/31] fix: preserve API context for comments and callbacks --- src/pymax/api/bots/service.py | 3 +- src/pymax/types/domain/message.py | 86 ++++++++++++++++++++++++++++++- 2 files changed, 86 insertions(+), 3 deletions(-) diff --git a/src/pymax/api/bots/service.py b/src/pymax/api/bots/service.py index 24ccd90..9a3239f 100644 --- a/src/pymax/api/bots/service.py +++ b/src/pymax/api/bots/service.py @@ -3,6 +3,7 @@ import time from typing import TYPE_CHECKING +from pymax.api.binding import bind_api_model from pymax.api.response import require_payload_model from pymax.logging import get_logger from pymax.protocol import Opcode @@ -39,4 +40,4 @@ async def send_callback( callback_id=callback_id, type=type, payload=payload, timestamp=int(time.time() * 1000) ) response = await self.app.invoke(Opcode.MSG_SEND_CALLBACK, frame.to_payload()) - return require_payload_model(response, CallbackResponse) + return bind_api_model(self.app, require_payload_model(response, CallbackResponse)) diff --git a/src/pymax/types/domain/message.py b/src/pymax/types/domain/message.py index 8ad3a80..cd758bc 100644 --- a/src/pymax/types/domain/message.py +++ b/src/pymax/types/domain/message.py @@ -168,6 +168,8 @@ async def on_message(message: Message, client: Client) -> None: :vartype id: int :ivar chat_id: ID чата, если он есть в данных сообщения. :vartype chat_id: int | None + :ivar post_id: ID поста канала, если сообщение является комментарием. + :vartype post_id: int | None :ivar sender: ID отправителя. :vartype sender: int | None :ivar text: Текст сообщения. @@ -209,6 +211,7 @@ async def on_message(message: Message, client: Client) -> None: id: int chat_id: int | None = None + post_id: int | None = None sender: int | None = None text: str = "" time: int @@ -248,7 +251,7 @@ async def reply( notify: bool = True, send_at: DateTimeUnion | None = None, ) -> Message: - """Отправляет ответ на это сообщение в тот же чат. + """Отправляет ответ в тот же чат или ветку комментариев. :param text: Текст сообщения. :type text: str | None @@ -263,9 +266,29 @@ async def reply( :rtype: Message :raises RuntimeError: Если сообщение не привязано к сервису или не содержит ``chat_id``. + :raises ValueError: Если для комментария задана отложенная отправка. """ actions, chat_id = self._bound() + if self.post_id is not None: + if send_at: + raise ValueError("Scheduled comments are not supported") + + message = await actions.send_comment( + chat_id=chat_id, + post_id=self.post_id, + text=text, + reply_to=self.id, + attachments=attachments, + notify=notify, + ) + if message.chat_id is None: + message.chat_id = chat_id + if message.post_id is None: + message.post_id = self.post_id + + return message + return await actions.send_message( chat_id=chat_id, text=text, @@ -284,7 +307,7 @@ async def answer( notify: bool = True, send_at: DateTimeUnion | None = None, ) -> Message: - """Отправляет сообщение в тот же чат. + """Отправляет сообщение в тот же чат или ветку комментариев. :param text: Текст сообщения. :type text: str | None @@ -301,9 +324,29 @@ async def answer( :rtype: Message :raises RuntimeError: Если сообщение не привязано к сервису или не содержит ``chat_id``. + :raises ValueError: Если для комментария задана отложенная отправка. """ actions, chat_id = self._bound() + if self.post_id is not None: + if send_at: + raise ValueError("Scheduled comments are not supported") + + message = await actions.send_comment( + chat_id=chat_id, + post_id=self.post_id, + text=text, + reply_to=reply_to, + attachments=attachments, + notify=notify, + ) + if message.chat_id is None: + message.chat_id = chat_id + if message.post_id is None: + message.post_id = self.post_id + + return message + return await actions.send_message( chat_id=chat_id, text=text, @@ -375,6 +418,21 @@ async def edit( """ actions, chat_id = self._bound() + if self.post_id is not None: + message = await actions.edit_comment( + chat_id=chat_id, + post_id=self.post_id, + message_id=self.id, + text=text, + attachments=attachments, + ) + if message.chat_id is None: + message.chat_id = chat_id + if message.post_id is None: + message.post_id = self.post_id + + return message + return await actions.edit_message( chat_id=chat_id, message_id=self.id, @@ -394,6 +452,14 @@ async def delete(self, for_me: bool = False) -> bool: """ actions, chat_id = self._bound() + if self.post_id is not None: + return await actions.delete_comment( + chat_id=chat_id, + post_id=self.post_id, + message_ids=[self.id], + for_me=for_me, + ) + return await actions.delete_message( chat_id=chat_id, message_ids=[self.id], @@ -427,6 +493,14 @@ async def react(self, reaction: str) -> ReactionInfo | None: """ actions, chat_id = self._bound() + if self.post_id is not None: + return await actions.add_comment_reaction( + chat_id=chat_id, + post_id=self.post_id, + message_id=self.id, + reaction=reaction, + ) + return await actions.add_reaction( chat_id=chat_id, message_id=self.id, @@ -443,6 +517,13 @@ async def unreact(self) -> ReactionInfo | None: """ actions, chat_id = self._bound() + if self.post_id is not None: + return await actions.remove_comment_reaction( + chat_id=chat_id, + post_id=self.post_id, + message_id=self.id, + ) + return await actions.remove_reaction( chat_id=chat_id, message_id=self.id, @@ -494,6 +575,7 @@ def _unwrap_message_event(cls, value: Any) -> Any: return { **message, "chatId": value.get("chatId"), + "postId": value.get("postId"), "prevMessageId": value.get("prevMessageId"), "ttl": value.get("ttl"), "unread": value.get("unread"), From c43ea8d81068281997506447a6ec7f243c50b6f0 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:43:30 +0300 Subject: [PATCH 22/31] fix: respect QR two-factor password attempt limits --- src/pymax/auth/qr.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/pymax/auth/qr.py b/src/pymax/auth/qr.py index d4afcfb..7e42201 100644 --- a/src/pymax/auth/qr.py +++ b/src/pymax/auth/qr.py @@ -5,6 +5,7 @@ from typing import TYPE_CHECKING from pymax.auth.base import AuthFlow +from pymax.auth.exceptions import PasswordAttemptsExceededError from pymax.exceptions import ApiError from pymax.logging import get_logger @@ -107,7 +108,10 @@ async def _authenticate_with_password( hint: str | None, ) -> str: logger.info("starting 2fa password authentication") - while True: + attempt = 0 + while ( + app.config.password_max_attempts is None or app.config.password_max_attempts > attempt + ): password = await self.password_provider.get_password(hint) logger.debug( "2fa password provider returned password_set=%s", @@ -115,16 +119,19 @@ async def _authenticate_with_password( ) if not password: logger.warning("2fa password is empty; retrying") + attempt += 1 continue try: response = await app.api.auth.check_password(track_id, password) except ApiError as e: logger.error("2fa password check failed: %s", e) + attempt += 1 continue if response.error: logger.error("2fa password check failed error=%s", response.error) + attempt += 1 continue if response.login_token: @@ -132,3 +139,6 @@ async def _authenticate_with_password( return response.login_token logger.error("2fa password response did not contain login token; retrying") + attempt += 1 + + raise PasswordAttemptsExceededError From bb2f4c9742fb9d2877335daf23ef651c344b7a0f Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:44:14 +0300 Subject: [PATCH 23/31] feat: add FSM and handler dependency injection Add in-memory FSM storage, per-context message isolation and optional Dishka integration. Preserve application services and state across reconnects while resetting the active connection and relogin session. --- pyproject.toml | 4 + src/pymax/app.py | 20 +++- src/pymax/base.py | 30 ++++-- src/pymax/di/__init__.py | 2 + src/pymax/di/context.py | 18 ++++ src/pymax/di/resolver.py | 38 ++++++++ src/pymax/dispatch/__init__.py | 2 + src/pymax/dispatch/dispatcher.py | 65 ++++++++++--- src/pymax/dispatch/middleware.py | 9 ++ src/pymax/dispatch/router.py | 76 +++++++++++---- src/pymax/filters/base.py | 8 ++ src/pymax/filters/presets.py | 21 ++++ src/pymax/fsm/__init__.py | 3 + src/pymax/fsm/context.py | 30 ++++++ src/pymax/fsm/protocol.py | 14 +++ src/pymax/fsm/state.py | 70 +++++++++++++ src/pymax/fsm/storage.py | 151 +++++++++++++++++++++++++++++ src/pymax/integrations/__init__.py | 0 src/pymax/integrations/dishka.py | 109 +++++++++++++++++++++ tests/app/test_app_runtime.py | 8 +- tests/conftest.py | 2 + uv.lock | 18 +++- 22 files changed, 654 insertions(+), 44 deletions(-) create mode 100644 src/pymax/di/__init__.py create mode 100644 src/pymax/di/context.py create mode 100644 src/pymax/di/resolver.py create mode 100644 src/pymax/fsm/__init__.py create mode 100644 src/pymax/fsm/context.py create mode 100644 src/pymax/fsm/protocol.py create mode 100644 src/pymax/fsm/state.py create mode 100644 src/pymax/fsm/storage.py create mode 100644 src/pymax/integrations/__init__.py create mode 100644 src/pymax/integrations/dishka.py diff --git a/pyproject.toml b/pyproject.toml index bb87b1f..3101069 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -88,6 +88,10 @@ dev = [ video = [ "tinytag>=2.2.1", ] +dishka = [ + "dishka>=1.10.1", +] + [tool.uv] package = true diff --git a/src/pymax/app.py b/src/pymax/app.py index b30cf44..7e44e03 100644 --- a/src/pymax/app.py +++ b/src/pymax/app.py @@ -9,6 +9,7 @@ from pymax.dispatch.router import EventType, Router from pymax.exceptions import ApiError from pymax.fingerprint import FingerprintGenerator +from pymax.fsm import InMemoryFSMStorage from pymax.logging import get_logger from pymax.protocol import Command, InboundFrame, OutboundFrame from pymax.protocol.enums import Opcode @@ -43,6 +44,7 @@ def __init__( if self.config.persist_session else InMemoryStore() ) + self.fsm_storage: InMemoryFSMStorage = InMemoryFSMStorage() self.auth_flow = auth_flow self.fingerprint_generator: FingerprintGenerator | None = ( FingerprintGenerator(self.config.fingering) if self.config.fingering else None @@ -57,7 +59,7 @@ def __init__( self.session: SessionInfo | None = None self.handshake_response: HandshakeResponse | None = None - self.started = False + self.started: bool = False self._ping_task: asyncio.Task[None] | None = None self._telemetry = TelemetryService(self) if config.telemetry else None @@ -186,7 +188,7 @@ async def start(self) -> None: if not handled: raise - await self.close() + await self.disconnect() return if login_response.token is not None and login_response.token != self.session.token: @@ -208,6 +210,7 @@ async def start(self) -> None: self.messages = login_response.messages self.started = True + logger.info( "client started profile=%s chats=%s", self.me.contact.id, @@ -249,7 +252,7 @@ async def handshake(self, device_id: str) -> HandshakeResponse: logger.debug("handshake completed device_id=%s", device_id) return response - async def close(self) -> None: + async def disconnect(self) -> None: if self._telemetry: await self._telemetry.stop() @@ -258,6 +261,7 @@ async def close(self) -> None: self._ping_task = None if not task.done(): task.cancel() + try: await task except asyncio.CancelledError: @@ -267,10 +271,13 @@ async def close(self) -> None: await self.dispatcher.stop_startup_tasks() await self.connection.close() - await self.store.close() self.started = False + async def close(self): + await self.disconnect() + await self.store.close() + async def invoke( self, opcode: int, @@ -374,6 +381,11 @@ def _build_api_error(self, response: InboundFrame) -> ApiError: ) return exc + def bind_connection(self, connection: ConnectionManager) -> None: + self.connection = connection + self.connection.on_event = self.on_event + self.connection.on_close = self.on_connection_lost + async def on_event(self, frame: InboundFrame) -> None: logger.debug( "event received opcode=%s cmd=%s seq=%s", diff --git a/src/pymax/base.py b/src/pymax/base.py index ae62ed7..6478813 100644 --- a/src/pymax/base.py +++ b/src/pymax/base.py @@ -125,7 +125,6 @@ def _build_config( @abstractmethod def _build_connection(self) -> ConnectionManager: - raise NotImplementedError @abstractmethod @@ -140,7 +139,10 @@ async def _ensure_runtime(self: ClientT) -> None: # noqa: PYI019 return self._connection = self._build_connection() - self._app = self._build_app() + if self.__app is not None: + self._app.bind_connection(self._connection) + else: + self._app = self._build_app() def _init_runtime(self: ClientT, *, auth_flow: AuthFlow) -> None: # noqa: PYI019 self._connection = self._build_connection() @@ -158,14 +160,16 @@ def _build_app(self: ClientT) -> App[ClientT]: # noqa: PYI019 app.dispatcher.bind_client(self) return app - def _reset_runtime(self: ClientT) -> None: # noqa: PYI019 + def _reset_connection(self: ClientT) -> None: # noqa: PYI019 self._connection = self._build_connection() - self._app = self._build_app() + self._app.bind_connection(self._connection) + # self._app = self._build_app() async def connect(self: ClientT) -> None: # noqa: PYI019 - """Подключает клиента один раз и возвращается после ``on_start``. + """Подключает клиента один раз и запускает ``on_start``-обработчики. - После возврата соединение остается открытым. В отличие от + Обработчики старта выполняются в отдельных задачах; метод не ждет + их завершения. После возврата соединение остается открытым. В отличие от :meth:`start`, метод не ожидает закрытия соединения и не запускает reconnect loop; завершите работу через :meth:`stop` или :meth:`close`. """ @@ -181,6 +185,9 @@ async def connect(self: ClientT) -> None: # noqa: PYI019 await self.close() raise except (ConnectionError, EOFError, OSError, TimeoutError, ApiError) as e: + if self.__app is None: + raise + await self.close() await self._app.dispatcher.emit_disconnect( @@ -233,6 +240,9 @@ async def start(self: ClientT) -> None: # noqa: PYI019 OSError, TimeoutError, ) as e: + if self.__app is None: + raise + await self.close() await self._app.dispatcher.emit_disconnect( e, @@ -249,7 +259,7 @@ async def start(self: ClientT) -> None: # noqa: PYI019 exc_info=True, ) await asyncio.sleep(self.extra_config.reconnect_delay) - self._reset_runtime() + self._reset_connection() except Exception: await self.close() raise @@ -369,7 +379,7 @@ async def relogin(self: ClientT, drop_config_token: bool = True, start: bool = T Args: drop_config_token: Сбросить token, переданный через ``ExtraConfig``. - start: Сразу запустить клиента после сброса runtime. + start: Сразу запустить клиента после сброса сессии. """ store = self._app.store session = self._app.session @@ -384,7 +394,9 @@ async def relogin(self: ClientT, drop_config_token: bool = True, start: bool = T self.extra_config.token = None self._config.token = None - self._reset_runtime() + self._reset_connection() + + self._app.session = None if start: await self.start() diff --git a/src/pymax/di/__init__.py b/src/pymax/di/__init__.py new file mode 100644 index 0000000..18ba01d --- /dev/null +++ b/src/pymax/di/__init__.py @@ -0,0 +1,2 @@ +from .context import DiContext +from .resolver import DiResolver diff --git a/src/pymax/di/context.py b/src/pymax/di/context.py new file mode 100644 index 0000000..11efea6 --- /dev/null +++ b/src/pymax/di/context.py @@ -0,0 +1,18 @@ +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Generic, TypeVar + +if TYPE_CHECKING: + from pymax.app import App + from pymax.base import BaseClient + from pymax.dispatch.mapping import DispatchEvent + +ClientT = TypeVar("ClientT", bound="BaseClient") + + +@dataclass(slots=True) +class DiContext(Generic[ClientT]): + app: App[ClientT] + event: DispatchEvent + client: ClientT diff --git a/src/pymax/di/resolver.py b/src/pymax/di/resolver.py new file mode 100644 index 0000000..6a448af --- /dev/null +++ b/src/pymax/di/resolver.py @@ -0,0 +1,38 @@ +from __future__ import annotations + +from collections.abc import Awaitable, Callable +from logging import getLogger +from typing import Any, TypeAlias + +from pymax.fsm import FSMContext +from pymax.types import Message + +from .context import DiContext + +logger = getLogger() + + +async def resolve_fsm(ctx: DiContext) -> FSMContext | None: + if not isinstance(ctx.event, Message): + raise ValueError("Fsm is not currently working for non-message handlers.") + + if not ctx.event.chat_id or not ctx.event.sender: + logger.warning("Not enough data in message event. Skipping fsm") + return None + + return ctx.app.fsm_storage.get_context(ctx.client, ctx.event) + + +Resolver: TypeAlias = Callable[[DiContext], Awaitable[Any]] + +DI_MAP: dict[type, Resolver] = {FSMContext: resolve_fsm} + + +class DiResolver: + async def resolve(self, annotation: Any, ctx: DiContext) -> None | Any: + resolver = DI_MAP.get(annotation) + + if resolver is None: + return None + + return await resolver(ctx) diff --git a/src/pymax/dispatch/__init__.py b/src/pymax/dispatch/__init__.py index 373f10a..9d332b0 100644 --- a/src/pymax/dispatch/__init__.py +++ b/src/pymax/dispatch/__init__.py @@ -8,6 +8,7 @@ DisconnectDecorator, ErrorContext, ErrorScope, + HandlerCallback, Router, ) @@ -20,6 +21,7 @@ "ErrorContext", "ErrorScope", "EventType", + "HandlerCallback", "Middleware", "MiddlewareNext", "Router", diff --git a/src/pymax/dispatch/dispatcher.py b/src/pymax/dispatch/dispatcher.py index 0ad6f0a..74baace 100644 --- a/src/pymax/dispatch/dispatcher.py +++ b/src/pymax/dispatch/dispatcher.py @@ -3,8 +3,11 @@ import asyncio import inspect from contextlib import suppress -from typing import TYPE_CHECKING, Any, Generic, TypeVar +from typing import TYPE_CHECKING, Any, Generic, TypeVar, get_type_hints +from pydantic import BaseModel + +from pymax.di import DiContext, DiResolver from pymax.filters import Filter from pymax.logging import get_logger from pymax.protocol import InboundFrame @@ -46,11 +49,11 @@ logger = get_logger(__name__) ClientT = TypeVar("ClientT", bound="BaseClient") -EventT = TypeVar("EventT") +EventT = TypeVar("EventT", bound=BaseModel) class Dispatcher(Generic[ClientT]): - def __init__(self, app: App, root_router: Router[ClientT] | None = None) -> None: + def __init__(self, app: App[ClientT], root_router: Router[ClientT] | None = None) -> None: self.root_router: Router[ClientT] = root_router or Router() self.middlewares: list[Middleware[ClientT]] = self.root_router.middlewares self.internal_router: Router[ClientT] = Router() @@ -58,6 +61,8 @@ def __init__(self, app: App, root_router: Router[ClientT] | None = None) -> None self.mapper = EventMapper(app) self.startup_tasks: list[asyncio.Task[Any]] = [] self.client: ClientT | None = None + self.app = app + self.di_resolver = DiResolver() def bind_client(self, client: ClientT) -> None: self.client = client @@ -249,10 +254,19 @@ async def dispatch(self, frame: InboundFrame) -> None: if event_type is not None: logger.debug("dispatching event type=%s", event_type) event = self.mapper.map(event_type, frame) - await self._dispatch_to_router( - self.internal_router, event_type, event, apply_middleware=False - ) - await self._dispatch_to_router(self.root_router, event_type, event) + + if event: + await self._dispatch_to_router( + self.internal_router, + event_type, + event, + apply_middleware=False, + ) + if self.client: + async with self.app.fsm_storage.isolate(self.client, event): + await self._dispatch_to_router(self.root_router, event_type, event) + else: + await self._dispatch_to_router(self.root_router, event_type, event) else: logger.debug( "dispatching raw event only opcode=%s cmd=%s", @@ -282,7 +296,8 @@ async def _dispatch_to_router( await self._call_with_middleware(entry.callback, event) else: await self._call(entry.callback, event) - except Exception as e: # noqa: PERF203 + break + except Exception as e: handled = await self.emit_error(e, event_type, event, router, entry) if not handled: raise @@ -329,8 +344,8 @@ async def wrapped( async def _matches( self, - entry: HandlerEntry[Any, ClientT], - event: Any, + entry: HandlerEntry[DispatchEvent, ClientT], + event: DispatchEvent, ) -> bool: for flt in entry.filters: if not self.client: @@ -346,11 +361,37 @@ async def _matches( return False return True - async def _call(self, callback: HandlerCallback[Any, ClientT], event: Any) -> Any: + async def _call( + self, callback: HandlerCallback[DispatchEvent, ClientT], event: DispatchEvent + ) -> Any: if self.client is None: raise RuntimeError("client is not bound") - result = callback(event, self.client) + signature = inspect.signature(callback) + bound = signature.bind_partial(event, self.client) + bound.apply_defaults() + + missing_parameters = [ + (name, parameter) + for name, parameter in signature.parameters.items() + if name not in bound.arguments + ] + + if missing_parameters: + hints = get_type_hints(callback, include_extras=True) + + for name, parameter in missing_parameters: + annotation = hints.get(name, parameter.annotation) + + ctx = DiContext(self.app, event, self.client) + result = await self.di_resolver.resolve(annotation, ctx) + + if result is None: + raise ValueError(f"No resolver was found for parameter: `{parameter}`") + + bound.arguments[name] = result + + result = callback(*bound.args, **bound.kwargs) if inspect.isawaitable(result): return await result diff --git a/src/pymax/dispatch/middleware.py b/src/pymax/dispatch/middleware.py index c996123..ddd1e9d 100644 --- a/src/pymax/dispatch/middleware.py +++ b/src/pymax/dispatch/middleware.py @@ -12,9 +12,18 @@ ClientT_contra = TypeVar("ClientT_contra", bound="BaseClient", contravariant=True) MiddlewareNext: TypeAlias = Callable[[DispatchEvent], Awaitable[Any]] +"""Следующий шаг middleware-цепочки, вызываемый как ``await call_next(event)``.""" class Middleware(Protocol, Generic[ClientT_contra]): + """Асинхронная обертка выбранного обработчика события. + + Реализуйте ``async __call__(client, event, call_next)`` и зарегистрируйте + экземпляр через ``client.add_middleware()``. Middleware запускаются после + фильтров в порядке регистрации для обработчиков всех подключенных роутеров. + Вызов ``await call_next(event)`` продолжает цепочку и возвращает ее результат. + """ + async def __call__( self, client: ClientT_contra, diff --git a/src/pymax/dispatch/router.py b/src/pymax/dispatch/router.py index 385319b..21d8ba3 100644 --- a/src/pymax/dispatch/router.py +++ b/src/pymax/dispatch/router.py @@ -4,7 +4,16 @@ from collections.abc import Awaitable, Callable from dataclasses import dataclass from enum import Enum -from typing import TYPE_CHECKING, Any, Generic, TypeAlias, TypeVar +from typing import ( + TYPE_CHECKING, + Any, + Concatenate, + Generic, + ParamSpec, + Protocol, + TypeAlias, + TypeVar, +) from pymax.filters import Filter from pymax.types import MessageDeleteEvent @@ -35,16 +44,33 @@ class ErrorScope(str, Enum): _EventT = TypeVar("_EventT") ClientT = TypeVar("ClientT", bound="BaseClient") - +_P = ParamSpec("_P") HandlerCallback: TypeAlias = Callable[ [_EventT, ClientT], Awaitable[Any] | Any, ] -HandlerDecorator: TypeAlias = Callable[ - [HandlerCallback[_EventT, ClientT]], - HandlerCallback[_EventT, ClientT], -] +# HandlerDecorator: TypeAlias = Callable[ +# [HandlerCallback[_EventT, ClientT]], +# HandlerCallback[_EventT, ClientT], +# ] + +HandlerResult: TypeAlias = Awaitable[Any] | Any + + +class HandlerDecorator(Protocol, Generic[_EventT, ClientT]): + def __call__( + self, + handler: Callable[ + Concatenate[_EventT, ClientT, _P], + HandlerResult, + ], + ) -> Callable[ + Concatenate[_EventT, ClientT, _P], + HandlerResult, + ]: ... + + StartCallback: TypeAlias = Callable[ [ClientT], Awaitable[Any] | Any, @@ -106,20 +132,20 @@ class Router(Generic[ClientT]): """Контейнер обработчиков событий PyMax. Роутер хранит обработчики и фильтры. Когда приходит событие, dispatcher - проходит по root router и его дочерним роутерам, проверяет фильтры и - вызывает подходящие callbacks как ``handler(event, client)``. + проверяет обработчики в порядке регистрации и вызывает первый подходящий + в каждом роутере, затем обходит его дочерние роутеры. Первые два аргумента + обработчика — ``event`` и ``client``; дополнительные обязательные параметры + разрешаются по аннотациям типов через DI. Example: .. code-block:: python from pymax import Client, Message, Router + from pymax.filters import Command router = Router[Client]() - def is_start(message: Message) -> bool: - return message.text == "/start" - - @router.on_message(is_start) + @router.on_message(Command("start")) async def start(message: Message, client: Client) -> None: await message.answer("Привет") @@ -147,6 +173,8 @@ def on_error( ``GLOBAL``-handler видит ошибки всего дерева подключенных router-ов. ``LOCAL``-handler видит только ошибки своего router-а. + Callback получает ``handler(exception, context)``. При обработке + событий сюда передаются ошибки фильтров, middleware и handler-ов. """ scope = ErrorScope(scope) @@ -179,7 +207,9 @@ def on( Args: event: Тип события. - *filters: Фильтры, которые получают событие и возвращают bool. + *filters: Экземпляры ``Filter``, вызываемые как + ``filter(event, client)``. Все фильтры должны вернуть ``True``; + async-результаты ожидаются автоматически. Returns: Декоратор для ``handler(event, client)``. @@ -187,7 +217,7 @@ def on( Example: .. code-block:: python - from pymax import Client + from pymax import Client, EventType from pymax.protocol import InboundFrame @router.on(EventType.RAW) @@ -196,8 +226,14 @@ async def raw(frame: InboundFrame, client: Client) -> None: """ def decorator( - handler: HandlerCallback[_EventT, ClientT], - ) -> HandlerCallback[_EventT, ClientT]: + handler: Callable[ + Concatenate[_EventT, ClientT, _P], + HandlerResult, + ], + ) -> Callable[ + Concatenate[_EventT, ClientT, _P], + HandlerResult, + ]: self.handlers[event].append( HandlerEntry( callback=handler, @@ -299,7 +335,10 @@ def on_reaction_update( self, *filters: Filter[ReactionUpdateEvent, ClientT], ) -> HandlerDecorator[ReactionUpdateEvent, ClientT]: - """Регистрирует обработчик обновления реакций сообщения.""" + """Регистрирует обработчик ``ReactionUpdateEvent``. + + Получает обновления счетчиков реакций и реакции текущего пользователя. + """ return self.on(EventType.REACTION_UPDATE, *filters) def on_chat_update( @@ -322,6 +361,9 @@ def on_raw( ) -> HandlerDecorator[InboundFrame, ClientT]: """Регистрирует обработчик исходных frame-ов. + Вызывается после типизированной обработки, даже если тип события + неизвестен или его обработка завершилась ошибкой. + Args: *filters: Фильтры для ``InboundFrame``. diff --git a/src/pymax/filters/base.py b/src/pymax/filters/base.py index fece961..585c0de 100644 --- a/src/pymax/filters/base.py +++ b/src/pymax/filters/base.py @@ -17,6 +17,14 @@ class Filter(ABC, Generic[EventT, ClientT]): + """Базовый класс фильтра событий. + + Реализуйте ``__call__(event, client)`` с результатом ``bool`` или + ``Awaitable[bool]`` и передайте экземпляр в декоратор роутера. Фильтры + объединяются через ``&``, ``|`` и ``~``; составной фильтр при ручном вызове + нужно ожидать через ``await``. + """ + @abstractmethod def __call__( self, diff --git a/src/pymax/filters/presets.py b/src/pymax/filters/presets.py index a0848f5..dbcbacf 100644 --- a/src/pymax/filters/presets.py +++ b/src/pymax/filters/presets.py @@ -12,6 +12,15 @@ class Command(Filter[Message, "BaseClient"]): + """Проверяет команду в первом слове текста сообщения. + + Args: + command: Имя команды, например ``"start"`` для ``/start``. + prefix: Префикс команды или кортеж допустимых префиксов. + + Аргументы после команды не влияют на совпадение. + """ + def __init__(self, command: str, prefix: str | tuple[str, ...] = "/") -> None: self.prefixes = (prefix,) if isinstance(prefix, str) else prefix @@ -32,6 +41,8 @@ def __call__(self, message: Message, _: BaseClient) -> bool: class Reply(Filter[Message, "BaseClient"]): + """Проверяет, является ли сообщение ответом на другое сообщение.""" + def __call__(self, message: Message, _: BaseClient) -> bool: if not message.link: return False @@ -40,6 +51,8 @@ def __call__(self, message: Message, _: BaseClient) -> bool: class Forwarded(Filter[Message, "BaseClient"]): + """Проверяет, является ли сообщение пересланным.""" + def __call__(self, message: Message, _: BaseClient) -> bool: if not message.link: return False @@ -48,6 +61,8 @@ def __call__(self, message: Message, _: BaseClient) -> bool: class FromMe(Filter[Message, "BaseClient"]): + """Проверяет, отправлено ли сообщение текущим пользователем клиента.""" + def __call__(self, message: Message, client: BaseClient) -> bool: if not message.sender or not client.me: return False @@ -56,6 +71,12 @@ def __call__(self, message: Message, client: BaseClient) -> bool: class HasAttachment(Filter[Message, "BaseClient"]): + """Проверяет наличие хотя бы одного вложения указанных типов. + + Передавайте классы входящих вложений из ``pymax.types``, например + ``PhotoAttachment``, а не классы файлов для отправки. + """ + def __init__(self, *attachment_types: type[Attachment]) -> None: self.expected_types = attachment_types diff --git a/src/pymax/fsm/__init__.py b/src/pymax/fsm/__init__.py new file mode 100644 index 0000000..b547ffe --- /dev/null +++ b/src/pymax/fsm/__init__.py @@ -0,0 +1,3 @@ +from .context import FSMContext +from .state import FsmGroup, State +from .storage import InMemoryFSM, InMemoryFSMStorage diff --git a/src/pymax/fsm/context.py b/src/pymax/fsm/context.py new file mode 100644 index 0000000..cf97f17 --- /dev/null +++ b/src/pymax/fsm/context.py @@ -0,0 +1,30 @@ +from dataclasses import dataclass + +from .protocol import FSMStorage + + +@dataclass(frozen=True, slots=True) +class FSMKey: + client_id: int + user_id: int + chat_id: int + + +class FSMContext: + """Контекст состояния пользователя в текущем чате. + + PyMax передает его в обязательный параметр обработчика сообщения + с аннотацией ``FSMContext``. Состояние и данные доступны через ``storage``. + + Attributes: + storage: Хранилище состояния и данных текущего контекста. + key: Ключ контекста для текущих клиента, пользователя и чата. + """ + + def __init__( + self, + storage: FSMStorage, + key: FSMKey, + ) -> None: + self.storage = storage + self.key = key diff --git a/src/pymax/fsm/protocol.py b/src/pymax/fsm/protocol.py new file mode 100644 index 0000000..76f61cb --- /dev/null +++ b/src/pymax/fsm/protocol.py @@ -0,0 +1,14 @@ +from typing import Any, Protocol + +from .state import State + + +class FSMStorage(Protocol): + async def get_state(self) -> str | None: ... + async def set_state(self, state: str | State | None, ttl: int | None = None) -> None: ... + + async def get_data(self) -> dict[str, Any]: ... + async def set_data(self, key: str, value: Any) -> None: ... + async def update_data(self, **data: Any) -> None: ... + + async def clear(self) -> None: ... diff --git a/src/pymax/fsm/state.py b/src/pymax/fsm/state.py new file mode 100644 index 0000000..ce2dcc2 --- /dev/null +++ b/src/pymax/fsm/state.py @@ -0,0 +1,70 @@ +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from pymax.base import BaseClient + +from pymax.filters import Filter +from pymax.types import Message + + +class State(Filter[Message, "BaseClient"]): + """Состояние FSM и фильтр сообщений по этому состоянию. + + Объявляйте экземпляры атрибутами ``FsmGroup``. Один и тот же экземпляр + можно передать в ``ctx.storage.set_state()`` и ``router.on_message()``. + """ + + owner: type + name: str + + def __set_name__(self, owner: type, name: str) -> None: + self.owner = owner + self.name = name + + @property + def full_name(self) -> str: + """Возвращает полное имя состояния из имени модуля, группы и атрибута.""" + return f"{self.owner.__module__}.{self.owner.__qualname__}:{self.name}" + + def __str__(self) -> str: + return self.full_name + + async def __call__( + self, + event: Message, + client: BaseClient, + ) -> bool: + if event.chat_id is None or event.sender is None: + return False + + fsm_key = client._app.fsm_storage.resolve_key(client, event) + + if not fsm_key: + return False + + record = client._app.fsm_storage.records.get(fsm_key) + + if record is None: + return False + + return await record.get_state() == self.full_name + + +class FsmGroup: + """Группа состояний, объявленных атрибутами класса через ``State()``.""" + + __states__: dict[str, State] = {} + + def __init_subclass__(cls) -> None: + super().__init_subclass__() + + inherited: dict[str, State] = {} + + for base in cls.__bases__: + inherited.update(getattr(base, "__states__", {})) + + own = {name: value for name, value in vars(cls).items() if isinstance(value, State)} + + cls.__states__ = inherited | own diff --git a/src/pymax/fsm/storage.py b/src/pymax/fsm/storage.py new file mode 100644 index 0000000..f919cc2 --- /dev/null +++ b/src/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() diff --git a/src/pymax/integrations/__init__.py b/src/pymax/integrations/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/src/pymax/integrations/dishka.py b/src/pymax/integrations/dishka.py new file mode 100644 index 0000000..f47694d --- /dev/null +++ b/src/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) diff --git a/tests/app/test_app_runtime.py b/tests/app/test_app_runtime.py index 60bce6b..46f993a 100644 --- a/tests/app/test_app_runtime.py +++ b/tests/app/test_app_runtime.py @@ -404,6 +404,10 @@ async def on_error(exc, ctx): assert str(seen[0]) == "Login response does not contain profile" assert app.started is False assert connection.closed is True + assert store.closed is False + + await app.close() + assert store.closed is True @@ -455,10 +459,12 @@ async def on_error(exc, ctx): assert ctx.handler is None assert app.started is False assert connection.closed is True - assert store.closed is True + assert store.closed is False await app.close() + assert store.closed is True + @pytest.mark.asyncio async def test_client_start_does_not_emit_on_start_after_handled_login_error( diff --git a/tests/conftest.py b/tests/conftest.py index 1769c67..c9167a4 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -22,6 +22,7 @@ from pymax.api.users.service import UserService from pymax.config import ClientConfig, DeviceConfig from pymax.fingerprint.fingerprint import FingerprintGenerator +from pymax.fsm import InMemoryFSMStorage from pymax.protocol import Command, InboundFrame from pymax.session.models import SessionInfo from pymax.types.domain import AttachmentType, HandshakeResponse @@ -161,6 +162,7 @@ def __init__( self.calls: list[InvokeCall] = [] self.config = make_config(device_type) self.store = FakeStore() + self.fsm_storage = InMemoryFSMStorage() self.dispatcher = FakeDispatcher() self.connection = SimpleNamespace(is_open=True) diff --git a/uv.lock b/uv.lock index b1066cd..7d17d95 100644 --- a/uv.lock +++ b/uv.lock @@ -589,6 +589,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b4/e1/48cedb2fe63626e91ded1edad159e2a4fb8b6906c4425eb7749673077ce7/cryptography-48.0.0-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:4defde8685ae324a9eb9d818717e93b4638ef67070ac9bc15b8ca85f63048355", size = 4666800, upload-time = "2026-05-04T22:59:27.474Z" }, ] +[[package]] +name = "dishka" +version = "1.10.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "exceptiongroup", marker = "python_full_version < '3.11'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/97/da/b75b5fe665d16725e1d46e291c8dd4b0ed1731c7964f41087fda92f03d40/dishka-1.10.1.tar.gz", hash = "sha256:51fb624b9acc948b90f57128460061d1f3a1780121fe1c7d14c565e8bbff2083", size = 282008, upload-time = "2026-04-25T12:07:57.587Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2c/08/dd3259a319ba45c48d975caf237c830c7873a203288cb4ab186cc5bef585/dishka-1.10.1-py3-none-any.whl", hash = "sha256:84f40c1115eb391ce3fb558fd7946c5bcaf6361c35b77b7a185b7697a5720ec7", size = 120062, upload-time = "2026-04-25T12:07:59.153Z" }, +] + [[package]] name = "distlib" version = "0.4.0" @@ -1032,6 +1044,9 @@ dependencies = [ ] [package.optional-dependencies] +dishka = [ + { name = "dishka" }, +] video = [ { name = "tinytag" }, ] @@ -1071,6 +1086,7 @@ requires-dist = [ { name = "aiofiles", specifier = ">=25.1.0" }, { name = "aiohttp", specifier = ">=3.13.5" }, { name = "aiosqlite", specifier = ">=0.22.1" }, + { name = "dishka", marker = "extra == 'dishka'", specifier = ">=1.10.1" }, { name = "msgpack", specifier = ">=1.1.2" }, { name = "pydantic", specifier = ">=2.10.0" }, { name = "python-socks", extras = ["asyncio"], specifier = ">=2.8.1" }, @@ -1079,7 +1095,7 @@ requires-dist = [ { name = "websockets", specifier = ">=16.0" }, { name = "zstandard", specifier = ">=0.25.0" }, ] -provides-extras = ["video"] +provides-extras = ["video", "dishka"] [package.metadata.requires-dev] dev = [ From f4bb7180bfd6c18dfed85f59543d48c6daa87e61 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:44:33 +0300 Subject: [PATCH 24/31] feat: add stories API and update notifications Support publishing, feed pagination, owner stories, detailed statistics, reads, settings and reactions. Add story media uploads, public models and preview update handlers, and use the bundled CA for upload requests. --- src/pymax/__init__.py | 4 + src/pymax/api/facade.py | 2 + src/pymax/api/stories/__init__.py | 2 + src/pymax/api/stories/enums.py | 19 +++ src/pymax/api/stories/payloads.py | 64 +++++++++ src/pymax/api/stories/service.py | 198 ++++++++++++++++++++++++++++ src/pymax/api/uploads/payloads.py | 11 +- src/pymax/api/uploads/service.py | 87 +++++++++++- src/pymax/base.py | 8 ++ src/pymax/dispatch/dispatcher.py | 8 +- src/pymax/dispatch/enums.py | 1 + src/pymax/dispatch/mapping.py | 10 +- src/pymax/dispatch/resolvers.py | 4 + src/pymax/dispatch/router.py | 12 +- src/pymax/infra/base.py | 2 + src/pymax/infra/stories.py | 205 +++++++++++++++++++++++++++++ src/pymax/types/domain/__init__.py | 12 ++ src/pymax/types/domain/story.py | 126 ++++++++++++++++++ 18 files changed, 768 insertions(+), 7 deletions(-) create mode 100644 src/pymax/api/stories/__init__.py create mode 100644 src/pymax/api/stories/enums.py create mode 100644 src/pymax/api/stories/payloads.py create mode 100644 src/pymax/api/stories/service.py create mode 100644 src/pymax/infra/stories.py create mode 100644 src/pymax/types/domain/story.py diff --git a/src/pymax/__init__.py b/src/pymax/__init__.py index 2cc50dd..b24c818 100644 --- a/src/pymax/__init__.py +++ b/src/pymax/__init__.py @@ -30,6 +30,8 @@ PresenceEvent, Profile, ReactionUpdateEvent, + Story, + StoryPreview, TypingEvent, User, ) @@ -65,6 +67,8 @@ "Router", "SmsAuthFlow", "SmsCodeProvider", + "Story", + "StoryPreview", "SyncOverrides", "SyncState", "TypingEvent", diff --git a/src/pymax/api/facade.py b/src/pymax/api/facade.py index 24f25cf..977fcc1 100644 --- a/src/pymax/api/facade.py +++ b/src/pymax/api/facade.py @@ -10,6 +10,7 @@ from .messages import MessageService from .self import SelfService from .session import SessionService +from .stories import StoriesService from .uploads import UploadService from .users import UserService @@ -31,4 +32,5 @@ def __init__(self, app: App) -> None: self.session = SessionService(app) self.auth = AuthService(app) self.uploads = UploadService(app) + self.stories = StoriesService(app) logger.debug("api facade initialized") diff --git a/src/pymax/api/stories/__init__.py b/src/pymax/api/stories/__init__.py new file mode 100644 index 0000000..079cc89 --- /dev/null +++ b/src/pymax/api/stories/__init__.py @@ -0,0 +1,2 @@ +from .enums import StoryStatsFilter +from .service import StoriesService diff --git a/src/pymax/api/stories/enums.py b/src/pymax/api/stories/enums.py new file mode 100644 index 0000000..31be582 --- /dev/null +++ b/src/pymax/api/stories/enums.py @@ -0,0 +1,19 @@ +from enum import Enum + + +class StoryStatsFilter(int, Enum): + """Фильтр подробной статистики: просмотры (``0``) или реакции (``1``).""" + + VIEWS = 0 + REACTIONS = 1 + + +class StoryPayloadKey(str, Enum): + STORIES = "stories" + PEER_STORIES = "peerStories" + STORY = "story" + STORIES_PREVIEWS = "storiesPreviews" + CURSOR = "cursor" + STORY_DETAILED_STATS = "storyDetailedStats" + MARKER = "marker" + SUCCESS = "success" diff --git a/src/pymax/api/stories/payloads.py b/src/pymax/api/stories/payloads.py new file mode 100644 index 0000000..a1cd002 --- /dev/null +++ b/src/pymax/api/stories/payloads.py @@ -0,0 +1,64 @@ +from pydantic import Field + +from pymax.api.models import CamelModel +from pymax.api.uploads.payloads import AttachPhotoPayload, StoryVideoAttachPayload +from pymax.types.domain.story import StoryLayer, StoryOwner + +from .enums import StoryStatsFilter + + +class SendStoryPayloadStory(CamelModel): + cid: int + media: AttachPhotoPayload | StoryVideoAttachPayload + settings: int = 1 + expiration: int = 172_800_000 + layers: list[StoryLayer] = Field(default_factory=list) + + +class SendStoryPayload(CamelModel): + stories: list[SendStoryPayloadStory] + + +class GetStoriesPayload(CamelModel): + owners: list[StoryOwner] + + +class DeleteStoryPayload(CamelModel): + story_ids: list[int] + + +class StoriesListPayload(CamelModel): + cursor: str = "0" + count: int = 15 + + +class GetStoriesByIdPayload(CamelModel): + owner: StoryOwner + story_ids: list[int] + + +class GetStoryDetailedStatsPayload(CamelModel): + story_id: int + marker: int = 0 + filter: StoryStatsFilter + + +class MarkStoryPayload(CamelModel): + owner: StoryOwner + story_id: int + + +class EditStoryPayload(CamelModel): + story_id: int + settings: int + + +class StoryReactionPayload(CamelModel): + reaction_type: int = 0 + id: str + + +class ReactStoryPayload(CamelModel): + owner: StoryOwner + story_id: int + reaction: StoryReactionPayload | None = None diff --git a/src/pymax/api/stories/service.py b/src/pymax/api/stories/service.py new file mode 100644 index 0000000..a66035c --- /dev/null +++ b/src/pymax/api/stories/service.py @@ -0,0 +1,198 @@ +from __future__ import annotations + +import time +from typing import TYPE_CHECKING + +from pymax.api.response import parse_payload_list, payload_item, require_payload_item_model +from pymax.api.uploads.payloads import AttachPhotoPayload, StoryVideoAttachPayload +from pymax.exceptions import PyMaxError +from pymax.files import Photo, Video +from pymax.logging import get_logger +from pymax.protocol import Opcode +from pymax.types.domain.story import ( + Story, + StoryClickableLink, + StoryCoordinates, + StoryDetailedStats, + StoryLayer, + StoryOwner, + StoryPreview, +) + +from .enums import StoryPayloadKey, StoryStatsFilter +from .payloads import ( + DeleteStoryPayload, + EditStoryPayload, + GetStoriesByIdPayload, + GetStoriesPayload, + GetStoryDetailedStatsPayload, + MarkStoryPayload, + ReactStoryPayload, + SendStoryPayload, + SendStoryPayloadStory, + StoriesListPayload, + StoryReactionPayload, +) + +if TYPE_CHECKING: + from pymax.app import App + + +logger = get_logger(__name__) + + +class StoriesService: + def __init__(self, app: App) -> None: + self.app = app + self._prev = int(time.time() * 1000) + + def _next_cid(self) -> int: + now = int(time.time() * 1000) + cid = max(now, self._prev + 1) + self._prev = cid + return cid + + async def send_story( + self, + media: Photo | Video, + *, + duration: int | None = None, + link: str | None = None, + ) -> Story: + logger.info("sending story media_type=%s", type(media).__name__) + + attachment: AttachPhotoPayload | StoryVideoAttachPayload + if isinstance(media, Photo): + attachment = await self.app.api.uploads.upload_photo(media, upload_type=1) + elif isinstance(media, Video): + if duration is None or duration <= 0: + raise ValueError("Video story duration must be greater than zero") + attachment = await self.app.api.uploads.upload_story_video(media, duration) + else: + raise TypeError("Story media must be Photo or Video") + + layers: list[StoryLayer] = [] + if link is not None: + layers.append( + StoryLayer( + coordinates=StoryCoordinates(x=0.5, y=0.9, w=0.78, h=0.055), + clickable_link=StoryClickableLink(url=link), + ) + ) + + frame = SendStoryPayload( + stories=[ + SendStoryPayloadStory( + cid=self._next_cid(), + media=attachment, + layers=layers, + ) + ] + ) + response = await self.app.invoke(Opcode.STORIES_SEND, frame.to_payload()) + stories = parse_payload_list(response, StoryPayloadKey.STORIES, Story) + if not stories: + raise PyMaxError("Story response does not contain a story") + return stories[0] + + async def get_stories(self, owner_id: int, owner_type: int = 0) -> list[Story]: + logger.info("getting stories owner_id=%s", owner_id) + frame = GetStoriesPayload(owners=[StoryOwner(owner_id=owner_id, type=owner_type)]) + response = await self.app.invoke(Opcode.STORIES_GET_BY_OWNER_ID, frame.to_payload()) + peers = payload_item(response, StoryPayloadKey.PEER_STORIES) or [] + return [ + Story.model_validate(story) for peer in peers for story in peer.get("stories") or [] + ] + + async def delete_story(self, story_id: int) -> bool: + logger.info("deleting story story_id=%s", story_id) + frame = DeleteStoryPayload(story_ids=[story_id]) + await self.app.invoke(Opcode.STORIES_DELETE, frame.to_payload()) + return True + + async def get_stories_feed( + self, + cursor: str = "0", + count: int = 15, + ) -> tuple[list[StoryPreview], str]: + logger.info("getting stories feed cursor=%s count=%s", cursor, count) + frame = StoriesListPayload(cursor=cursor, count=count) + response = await self.app.invoke(Opcode.STORIES_LIST, frame.to_payload()) + previews = parse_payload_list(response, StoryPayloadKey.STORIES_PREVIEWS, StoryPreview) + next_cursor = payload_item(response, StoryPayloadKey.CURSOR, str) or "" + return previews, next_cursor + + async def get_stories_by_id( + self, + owner_id: int, + story_ids: list[int], + owner_type: int = 0, + ) -> list[Story]: + logger.info("getting stories by id owner_id=%s count=%s", owner_id, len(story_ids)) + frame = GetStoriesByIdPayload( + owner=StoryOwner(owner_id=owner_id, type=owner_type), + story_ids=story_ids, + ) + response = await self.app.invoke(Opcode.STORIES_GET_BY_STORY_ID, frame.to_payload()) + return parse_payload_list(response, StoryPayloadKey.STORIES, Story) + + async def get_story_detailed_stats( + self, + story_id: int, + filter: StoryStatsFilter, + marker: int = 0, + ) -> tuple[list[StoryDetailedStats], int]: + logger.info("getting story detailed stats story_id=%s marker=%s", story_id, marker) + frame = GetStoryDetailedStatsPayload(story_id=story_id, filter=filter, marker=marker) + response = await self.app.invoke(Opcode.STORIES_GET_DETAILED_STATS, frame.to_payload()) + stats = parse_payload_list( + response, StoryPayloadKey.STORY_DETAILED_STATS, StoryDetailedStats + ) + next_marker = payload_item(response, StoryPayloadKey.MARKER, int) or 0 + return stats, next_marker + + async def read_story(self, story_id: int, owner_id: int, owner_type: int = 0) -> bool: + logger.info("marking story as read story_id=%s owner_id=%s", story_id, owner_id) + frame = MarkStoryPayload( + owner=StoryOwner(owner_id=owner_id, type=owner_type), + story_id=story_id, + ) + await self.app.invoke(Opcode.STORIES_MARK, frame.to_payload()) + return True + + async def edit_story(self, story_id: int, settings: int) -> Story: + logger.info("editing story settings story_id=%s", story_id) + frame = EditStoryPayload(story_id=story_id, settings=settings) + response = await self.app.invoke(Opcode.STORIES_EDIT, frame.to_payload()) + return require_payload_item_model(response, StoryPayloadKey.STORY, Story) + + async def add_story_reaction( + self, + owner_id: int, + story_id: int, + reaction: str, + reaction_type: int = 0, + owner_type: int = 0, + ) -> bool: + logger.info("adding story reaction owner_id=%s story_id=%s", owner_id, story_id) + frame = ReactStoryPayload( + owner=StoryOwner(owner_id=owner_id, type=owner_type), + story_id=story_id, + reaction=StoryReactionPayload(reaction_type=reaction_type, id=reaction), + ) + response = await self.app.invoke(Opcode.STORIES_REACT, frame.to_payload()) + return bool(payload_item(response, StoryPayloadKey.SUCCESS, bool)) + + async def remove_story_reaction( + self, + owner_id: int, + story_id: int, + owner_type: int = 0, + ) -> bool: + logger.info("removing story reaction owner_id=%s story_id=%s", owner_id, story_id) + frame = ReactStoryPayload( + owner=StoryOwner(owner_id=owner_id, type=owner_type), + story_id=story_id, + ) + response = await self.app.invoke(Opcode.STORIES_REACT, frame.to_payload()) + return bool(payload_item(response, StoryPayloadKey.SUCCESS, bool)) diff --git a/src/pymax/api/uploads/payloads.py b/src/pymax/api/uploads/payloads.py index 216288d..3b1040f 100644 --- a/src/pymax/api/uploads/payloads.py +++ b/src/pymax/api/uploads/payloads.py @@ -1,4 +1,4 @@ -from typing import Any +from typing import Any, Literal from pydantic import Field, SerializerFunctionWrapHandler, model_serializer @@ -11,6 +11,15 @@ class AttachPhotoPayload(CamelModel): photo_token: str +class StoryVideoAttachPayload(CamelModel): + type: Literal[AttachmentType.VIDEO] = Field( + default=AttachmentType.VIDEO, serialization_alias="_type" + ) + video_type: Literal[2] = 2 + duration: int + token: str + + class VideoAttachPayload(CamelModel): type: AttachmentType = Field(default=AttachmentType.VIDEO, serialization_alias="_type") video_id: int diff --git a/src/pymax/api/uploads/service.py b/src/pymax/api/uploads/service.py index 1122f67..d73f518 100644 --- a/src/pymax/api/uploads/service.py +++ b/src/pymax/api/uploads/service.py @@ -2,7 +2,9 @@ import asyncio import base64 +import ssl from http import HTTPStatus +from importlib import resources from typing import TYPE_CHECKING from urllib.parse import parse_qs, quote, urlparse @@ -25,6 +27,7 @@ from .payloads import ( AttachFilePayload, AttachPhotoPayload, + StoryVideoAttachPayload, UploadPayload, VideoAttachPayload, VideoNoteAttachPayload, @@ -49,11 +52,22 @@ def __init__(self, app: App) -> None: self.app.dispatcher.on_internal(EventType.FILE_READY)(self.on_file_attach) self.app.dispatcher.on_internal(EventType.VOICE_READY)(self.on_voice_attach) - async def upload_photo(self, photo: Photo, profile: bool = False) -> AttachPhotoPayload: + self.ssl_ctx = ssl.create_default_context() + self.ssl_ctx.load_verify_locations( + str(resources.files("pymax._data") / "rootca_ssl_rsa2022.crt") + ) + + async def upload_photo( + self, + photo: Photo, + profile: bool = False, + *, + upload_type: int = 0, + ) -> AttachPhotoPayload: logger.info("Uploading photo") logger.debug("Preparing photo upload payload") - payload = UploadPayload(profile=profile).to_payload() + payload = UploadPayload(profile=profile, type=upload_type).to_payload() try: data = await self.app.invoke( @@ -130,6 +144,7 @@ async def upload_photo(self, photo: Photo, profile: bool = False) -> AttachPhoto session.post( url=url, data=form, + ssl=self.ssl_ctx, ) as response, ): logger.debug("Photo upload HTTP response status=%s", response.status) @@ -274,6 +289,7 @@ async def upload_voice(self, voice: Voice) -> VoiceAttachPayload: url=upload_info.url, headers=headers, data=voice.iter_chunks(1024 * 1024), + ssl=self.ssl_ctx, ) as response: logger.debug( "Voice upload HTTP response status=%s voice_id=%s", @@ -420,6 +436,7 @@ async def upload_video( url=upload_info.url, headers=headers, data=uploadable_video.iter_chunks(1024 * 1024), + ssl=self.ssl_ctx, ) as response: logger.debug( "Video upload HTTP response status=%s video_id=%s", @@ -493,6 +510,71 @@ async def upload_video( self.video_upload_waiters.pop(video_id, None) logger.debug("Video upload waiter removed video_id=%s", video_id) + async def upload_story_video(self, video: Video, duration: int) -> StoryVideoAttachPayload: + logger.info("Uploading story video") + payload = UploadPayload(type=3).to_payload() + + try: + data = await self.app.invoke(Opcode.VIDEO_UPLOAD, payload=payload) + except Exception as e: + logger.exception("Failed to request story video upload URL") + raise UploadError("Failed to request story video upload URL") from e + + try: + upload_info = VideoUploadResponse.model_validate(data.payload).info[0] + except (ValidationError, IndexError) as e: + logger.exception("Invalid story video upload response") + raise UploadError("Invalid story video upload response") from e + + try: + file_size = await video.size() + except Exception as e: + logger.exception("Failed to get story video size") + raise UploadError("Failed to get story video size") from e + + headers = { + "Content-Type": "application/octet-stream", + "Content-Disposition": f"attachment; filename={quote(str(video.name))}", + "Content-Range": f"bytes 0-{file_size - 1}/{file_size}", + "Content-Length": str(file_size), + } + timeout = aiohttp.ClientTimeout(total=self.app.config.upload_timeout, sock_read=60) + + try: + async with ( + aiohttp.ClientSession(timeout=timeout, proxy=self.app.config.proxy) as session, + session.post( + url=upload_info.url, + headers=headers, + data=video.iter_chunks(1024 * 1024), + ssl=self.ssl_ctx, + ) as response, + ): + logger.debug("Story video upload HTTP response status=%s", response.status) + if response.status != HTTPStatus.OK: + raise UploadError(f"Story video upload failed with status {response.status}") + + result = await response.json(content_type=None) + attachment = StoryVideoAttachPayload( + duration=duration, + token=result[0]["token"], + ) + + except UploadError: + raise + except aiohttp.ClientError as e: + logger.exception("HTTP error during story video upload") + raise UploadError("HTTP error during story video upload") from e + except asyncio.TimeoutError as e: + logger.exception("Timed out during story video upload") + raise UploadError("Timed out during story video upload") from e + except Exception as e: + logger.exception("Unexpected error during story video upload") + raise UploadError("Unexpected error during story video upload") from e + + logger.debug("Story video upload complete video_id=%s", upload_info.video_id) + return attachment + async def upload_file(self, file: File) -> AttachFilePayload: logger.info("Uploading file") @@ -563,6 +645,7 @@ async def upload_file(self, file: File) -> AttachFilePayload: url=upload_info.url, headers=headers, data=file.iter_chunks(1024 * 1024), + ssl=self.ssl_ctx, ) as response, ): logger.debug( diff --git a/src/pymax/base.py b/src/pymax/base.py index 6478813..efcea89 100644 --- a/src/pymax/base.py +++ b/src/pymax/base.py @@ -30,6 +30,7 @@ MessageReadEvent, PresenceEvent, ReactionUpdateEvent, + StoryPreview, TypingEvent, User, ) @@ -344,6 +345,13 @@ def on_chat_update( """Регистрирует обработчик обновления чата.""" return self._router.on_chat_update(*filters) + def on_story_update( + self, + *filters: Filter[StoryPreview, ClientT], + ) -> HandlerDecorator[StoryPreview, ClientT]: + """Регистрирует обработчик обновления превью сторис владельца.""" + return self._router.on_story_update(*filters) + def on_raw( self, *filters: Filter[InboundFrame, ClientT], diff --git a/src/pymax/dispatch/dispatcher.py b/src/pymax/dispatch/dispatcher.py index 74baace..31d1e9a 100644 --- a/src/pymax/dispatch/dispatcher.py +++ b/src/pymax/dispatch/dispatcher.py @@ -11,7 +11,7 @@ from pymax.filters import Filter from pymax.logging import get_logger from pymax.protocol import InboundFrame -from pymax.types import Chat, MessageDeleteEvent +from pymax.types import Chat, MessageDeleteEvent, StoryPreview from pymax.types.domain import Message from pymax.types.events import ( MessageReadEvent, @@ -158,6 +158,12 @@ def on_chat_update( ) -> HandlerDecorator[Chat, ClientT]: return self.root_router.on_chat_update(*filters) + def on_story_update( + self, + *filters: Filter[StoryPreview, ClientT], + ) -> HandlerDecorator[StoryPreview, ClientT]: + return self.root_router.on_story_update(*filters) + def on_raw( self, *filters: Filter[InboundFrame, ClientT], diff --git a/src/pymax/dispatch/enums.py b/src/pymax/dispatch/enums.py index da7dc96..2d410f5 100644 --- a/src/pymax/dispatch/enums.py +++ b/src/pymax/dispatch/enums.py @@ -10,6 +10,7 @@ class EventType(str, Enum): PRESENCE = "presence" REACTION_UPDATE = "reaction_update" CHAT_UPDATE = "chat_update" + STORY_UPDATE = "story_update" USER_UPDATE = "user_update" VIDEO_READY = "video_ready" FILE_READY = "file_ready" diff --git a/src/pymax/dispatch/mapping.py b/src/pymax/dispatch/mapping.py index 93d4636..5816ea7 100644 --- a/src/pymax/dispatch/mapping.py +++ b/src/pymax/dispatch/mapping.py @@ -7,7 +7,7 @@ from pymax.protocol import InboundFrame, Opcode from pymax.protocol.enums import Command from pymax.types import AudioUploadSignal, Chat, MessageDeleteEvent -from pymax.types.domain import Message +from pymax.types.domain import Message, StoryPreview from pymax.types.events import ( FileUploadSignal, MessageReadEvent, @@ -26,6 +26,7 @@ resolve_message_read, resolve_presence, resolve_reaction_update, + resolve_story_update, resolve_typing, ) @@ -41,12 +42,14 @@ | TypingEvent | PresenceEvent | ReactionUpdateEvent + | StoryPreview | VideoUploadSignal | FileUploadSignal | AudioUploadSignal | InboundFrame ) + EVENT_MAP: dict[Opcode, Resolver] = { Opcode.NOTIF_MESSAGE: resolve_message, Opcode.MSG_EDIT: resolve_message, @@ -58,6 +61,7 @@ Opcode.NOTIF_PRESENCE: resolve_presence, Opcode.NOTIF_MSG_REACTIONS_CHANGED: resolve_reaction_update, Opcode.NOTIF_MSG_YOU_REACTED: resolve_reaction_update, + Opcode.NOTIF_STORIES_UPDATE: resolve_story_update, } @@ -82,7 +86,7 @@ class EventMapper: def __init__(self, app: App) -> None: self.app = app - def map(self, event_type: EventType, frame: InboundFrame): + def map(self, event_type: EventType, frame: InboundFrame) -> DispatchEvent | None: if frame.cmd != Command.REQUEST: return None @@ -110,6 +114,8 @@ def map(self, event_type: EventType, frame: InboundFrame): return PresenceEvent.model_validate(frame.payload) elif event_type == EventType.REACTION_UPDATE: return ReactionUpdateEvent.model_validate(frame.payload) + elif event_type == EventType.STORY_UPDATE: + return StoryPreview.model_validate(frame.payload["storiesPreview"]) elif event_type == EventType.VIDEO_READY: return VideoUploadSignal.model_validate(frame.payload) elif event_type == EventType.FILE_READY: diff --git a/src/pymax/dispatch/resolvers.py b/src/pymax/dispatch/resolvers.py index bf4fb70..a422df6 100644 --- a/src/pymax/dispatch/resolvers.py +++ b/src/pymax/dispatch/resolvers.py @@ -36,6 +36,10 @@ def resolve_reaction_update(_: InboundFrame) -> EventType | None: return EventType.REACTION_UPDATE +def resolve_story_update(_: InboundFrame) -> EventType | None: + return EventType.STORY_UPDATE + + def resolve_attach(frame: InboundFrame) -> EventType | None: try: FileUploadSignal.model_validate(frame.payload) diff --git a/src/pymax/dispatch/router.py b/src/pymax/dispatch/router.py index 21d8ba3..cea6257 100644 --- a/src/pymax/dispatch/router.py +++ b/src/pymax/dispatch/router.py @@ -25,7 +25,7 @@ from pymax.client import Client from pymax.dispatch.middleware import Middleware from pymax.protocol import InboundFrame - from pymax.types import Chat + from pymax.types import Chat, StoryPreview from pymax.types.domain import Message from pymax.types.events import ( MessageReadEvent, @@ -355,6 +355,16 @@ def on_chat_update( """ return self.on(EventType.CHAT_UPDATE, *filters) + def on_story_update( + self, + *filters: Filter[StoryPreview, ClientT], + ) -> HandlerDecorator[StoryPreview, ClientT]: + """Регистрирует обработчик обновления ``StoryPreview`` владельца. + + Первый аргумент handler-а содержит сводное превью, а не ``Story``. + """ + return self.on(EventType.STORY_UPDATE, *filters) + def on_raw( self, *filters: Filter[InboundFrame, ClientT], diff --git a/src/pymax/infra/base.py b/src/pymax/infra/base.py index 4551d01..3639eb0 100644 --- a/src/pymax/infra/base.py +++ b/src/pymax/infra/base.py @@ -3,6 +3,7 @@ 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-методы клиента.""" diff --git a/src/pymax/infra/stories.py b/src/pymax/infra/stories.py new file mode 100644 index 0000000..da6307a --- /dev/null +++ b/src/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, + ) diff --git a/src/pymax/types/domain/__init__.py b/src/pymax/types/domain/__init__.py index 27a813f..467d426 100644 --- a/src/pymax/types/domain/__init__.py +++ b/src/pymax/types/domain/__init__.py @@ -21,5 +21,17 @@ 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 diff --git a/src/pymax/types/domain/story.py b/src/pymax/types/domain/story.py new file mode 100644 index 0000000..4af9732 --- /dev/null +++ b/src/pymax/types/domain/story.py @@ -0,0 +1,126 @@ +from typing import Annotated, Literal, TypeAlias + +from pydantic import Field + +from .attachments.enums import AttachmentType +from .base import CamelModel + + +class StoryCoordinates(CamelModel): + """Положение слоя сторис в долях ширины и высоты кадра.""" + + x: float + y: float + w: float + h: float + rotation: float = 0 + + +class StoryClickableLink(CamelModel): + """Ссылка слоя сторис и результат ее проверки сервером.""" + + url: str + check_result: int | None = None + + +class StoryLayer(CamelModel): + """Слой сторис со ссылкой и координатами.""" + + type: int = 0 + coordinates: StoryCoordinates + clickable_link: StoryClickableLink + + +class StoryPhotoMedia(CamelModel): + """Фото сторис, полученное от Max, без обязательного токена загрузки.""" + + base_url: str + height: int + width: int + photo_id: int + preview_data: bytes | None = None + type: Literal[AttachmentType.PHOTO] = Field(alias="_type") + + +class StoryVideoMedia(CamelModel): + """Видео сторис, полученное от Max. + + В отличие от ``VideoAttachment``, не требует токен загрузки и + ``video_type``, которые используются при публикации. + """ + + height: int + width: int + video_id: int + duration: int | None = None + preview_data: bytes | None = None + type: Literal[AttachmentType.VIDEO] = Field(alias="_type") + thumbnail: str + + +StoryMedia: TypeAlias = Annotated[ + StoryPhotoMedia | StoryVideoMedia, + Field(discriminator="type"), +] + + +class Story(CamelModel): + """Сторис, возвращенная после публикации или при чтении. + + :ivar id: ID сторис. + :ivar cid: Идентификатор публикации, сформированный клиентом. + :ivar media: Фото или видео сторис. + :ivar layers: Слои поверх кадра. + :ivar settings: Настройки сторис в формате Max. + :ivar expiration: Время жизни сторис в миллисекундах. + """ + + id: int + cid: int | None = None + media: StoryMedia + layers: list[StoryLayer] = Field(default_factory=list) + settings: int + expiration: int + + +class StoryOwner(CamelModel): + """Владелец сторис. + + :ivar owner_id: ID владельца, а не отдельной сторис. + :ivar type: Числовой тип владельца из Max. ``0`` — пользователь. + """ + + owner_id: int + type: int = 0 + + +class StoryPreview(CamelModel): + """Сводная информация о сторис владельца в ленте и обновлениях. + + ID отдельных сторис в превью нет. Для их получения передайте + ``owner.owner_id`` и ``owner.type`` в ``client.get_stories()``. + + :ivar owner: Владелец сторис. + :ivar total_count: Общее количество сторис владельца. + :ivar read_count: Количество просмотренных сторис владельца. + """ + + owner: StoryOwner + total_count: int = 0 + read_count: int = 0 + last_story_expiration_time: int = 0 + settings: int = 0 + update_time: int = 0 + + +class StoryDetailedStats(CamelModel): + """Запись подробной статистики просмотра или реакции на сторис. + + Типизировано только ``user_id``. Дополнительные поля доступны в + ``model_extra`` с исходными именами ответа Max, без преобразования + camelCase. Поле ``reaction``, если оно пришло, остается словарем. + + :ivar user_id: ID пользователя. + """ + + user_id: int From 846fce8e739dcc9b2063593e8bca0e9f46f153a8 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:44:43 +0300 Subject: [PATCH 25/31] chore: update Android fingerprints and default to 26.37.1 --- src/pymax/_data/apk_fingerprints.json | 272 ++++++++++++++++++++++++++ src/pymax/versions/catalog.py | 2 +- 2 files changed, 273 insertions(+), 1 deletion(-) diff --git a/src/pymax/_data/apk_fingerprints.json b/src/pymax/_data/apk_fingerprints.json index 0c63fc9..77747fb 100644 --- a/src/pymax/_data/apk_fingerprints.json +++ b/src/pymax/_data/apk_fingerprints.json @@ -747,6 +747,278 @@ }, "build_number": 6804 }, + "26.29.0": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "4e8c23ff85bc3926ada1a577942f6fd7cda673276cd9f6d1edba20a08e03dbcb", + "so_meta_sha256_arm64_v8a": "9a7d6c3f2d3d01ca5e8692f254be92306d37fadb074692479bdf961943675f7a", + "so_meta_sha256": { + "arm64-v8a": "9a7d6c3f2d3d01ca5e8692f254be92306d37fadb074692479bdf961943675f7a", + "armeabi-v7a": "bfc5ac5df34357fa817c4a8ce4696cd95b2c34f903d91ef15ea86463c600befa", + "x86": "918eacab4fa4e04d90a7fa666bc39633ae47fbba70b6817b5dfd1f62233fab8e", + "x86_64": "ae38786d2c0541c4d2c3050265e30bde68df16302aebc5302432813ff20f858c" + }, + "build_number": 6807 + }, + "26.29.1": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "5f794a4cf36dde2a49e10dd7d803ad837eaeb021a28e41321ce345c73cd5e275", + "so_meta_sha256_arm64_v8a": "9a7d6c3f2d3d01ca5e8692f254be92306d37fadb074692479bdf961943675f7a", + "so_meta_sha256": { + "arm64-v8a": "9a7d6c3f2d3d01ca5e8692f254be92306d37fadb074692479bdf961943675f7a", + "armeabi-v7a": "bfc5ac5df34357fa817c4a8ce4696cd95b2c34f903d91ef15ea86463c600befa", + "x86": "918eacab4fa4e04d90a7fa666bc39633ae47fbba70b6817b5dfd1f62233fab8e", + "x86_64": "ae38786d2c0541c4d2c3050265e30bde68df16302aebc5302432813ff20f858c" + }, + "build_number": 6808 + }, + "26.30.0": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "d13689c99becd8d94d5b9a57418b792928915064e6192731763a96625157ec01", + "so_meta_sha256_arm64_v8a": "9a7d6c3f2d3d01ca5e8692f254be92306d37fadb074692479bdf961943675f7a", + "so_meta_sha256": { + "arm64-v8a": "9a7d6c3f2d3d01ca5e8692f254be92306d37fadb074692479bdf961943675f7a", + "armeabi-v7a": "bfc5ac5df34357fa817c4a8ce4696cd95b2c34f903d91ef15ea86463c600befa", + "x86": "918eacab4fa4e04d90a7fa666bc39633ae47fbba70b6817b5dfd1f62233fab8e", + "x86_64": "ae38786d2c0541c4d2c3050265e30bde68df16302aebc5302432813ff20f858c" + }, + "build_number": 6810 + }, + "26.30.1": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "f0478d38a9d9172a7bf055f7a3bbf5a878ea9e4df8196a1c9e788ad3c35e95b7", + "so_meta_sha256_arm64_v8a": "9a7d6c3f2d3d01ca5e8692f254be92306d37fadb074692479bdf961943675f7a", + "so_meta_sha256": { + "arm64-v8a": "9a7d6c3f2d3d01ca5e8692f254be92306d37fadb074692479bdf961943675f7a", + "armeabi-v7a": "bfc5ac5df34357fa817c4a8ce4696cd95b2c34f903d91ef15ea86463c600befa", + "x86": "918eacab4fa4e04d90a7fa666bc39633ae47fbba70b6817b5dfd1f62233fab8e", + "x86_64": "ae38786d2c0541c4d2c3050265e30bde68df16302aebc5302432813ff20f858c" + }, + "build_number": 6819 + }, + "26.31.0": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "9affa687874d88ea80b298949f826bcf8c1bba36f24d48c44b8f54cdbf01c96f", + "so_meta_sha256_arm64_v8a": "38e2e5de3d4a9010ea1053eb28573593683c5b2bb16b09914a8822476c8aab8c", + "so_meta_sha256": { + "arm64-v8a": "38e2e5de3d4a9010ea1053eb28573593683c5b2bb16b09914a8822476c8aab8c", + "armeabi-v7a": "f60cb2576885e0af5350c98fe88355a2f26008a372c998c193b6222f717e274f", + "x86": "80bd04964e7d0492740113047ff20ebdf88ba6e6eb48d8765cbd5fe678283065", + "x86_64": "96173e7c2d9449c1ab4474265b410f37ce45f560b0974460a75c7c6000ca22fd" + }, + "build_number": 6822 + }, + "26.32.0": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "3a2ca283856d80fc435fc138c5491e5b577288abb8fbad3b76119b9c602b5f8e", + "so_meta_sha256_arm64_v8a": "3727957b95dcadea914b43fceacaa0c48f688f4f2517e223e548b525df6c5897", + "so_meta_sha256": { + "arm64-v8a": "3727957b95dcadea914b43fceacaa0c48f688f4f2517e223e548b525df6c5897", + "armeabi-v7a": "4704107fd3816b7e1a7046b700c0a726840d0af25d7beb1f391f5b7cbe93d073", + "x86": "7d120871e1561d53ba0b952a57bdfee7792e2bb4d36d75411a15d7256c5cf548", + "x86_64": "a5fd0a3d40bbfcf038f53e96fcabdee8ea21eafe68ec46a9efb095e326e204ae" + }, + "build_number": 6828 + }, + "26.32.1": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "97da66ad31ca8adcd22b8e181bbd95d17ecba6d7b005745934faa1b90307beab", + "so_meta_sha256_arm64_v8a": "3727957b95dcadea914b43fceacaa0c48f688f4f2517e223e548b525df6c5897", + "so_meta_sha256": { + "arm64-v8a": "3727957b95dcadea914b43fceacaa0c48f688f4f2517e223e548b525df6c5897", + "armeabi-v7a": "4704107fd3816b7e1a7046b700c0a726840d0af25d7beb1f391f5b7cbe93d073", + "x86": "7d120871e1561d53ba0b952a57bdfee7792e2bb4d36d75411a15d7256c5cf548", + "x86_64": "a5fd0a3d40bbfcf038f53e96fcabdee8ea21eafe68ec46a9efb095e326e204ae" + }, + "build_number": 6831 + }, + "26.33.0": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "771ac6fa7aac04f7388d2354f33f22b9f9c4c8ec26126b556192e5d918986142", + "so_meta_sha256_arm64_v8a": "980eb6d9c6c4c04573bf73fbbb2c385be97cbb1d9ec733ce53574612c9730edf", + "so_meta_sha256": { + "arm64-v8a": "980eb6d9c6c4c04573bf73fbbb2c385be97cbb1d9ec733ce53574612c9730edf", + "armeabi-v7a": "2350dd69aa0765371acbc94a5a02487eab29288def1a38f113d0d98b5c60ce81", + "x86": "9b07a1a0a6730c0d0dd230a90ee4dc3df8f3fe890e790f57c183e0fe0b3f981b", + "x86_64": "94999ef1d35c3952773a85ef394a1e44037fa61b562656af15330f9d3e29b871" + }, + "build_number": 6835 + }, + "26.33.1": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "fb3e23aff9bc5956f7f35a6b489c6ee98824be485068ffdba56a24e8437246ac", + "so_meta_sha256_arm64_v8a": "980eb6d9c6c4c04573bf73fbbb2c385be97cbb1d9ec733ce53574612c9730edf", + "so_meta_sha256": { + "arm64-v8a": "980eb6d9c6c4c04573bf73fbbb2c385be97cbb1d9ec733ce53574612c9730edf", + "armeabi-v7a": "2350dd69aa0765371acbc94a5a02487eab29288def1a38f113d0d98b5c60ce81", + "x86": "9b07a1a0a6730c0d0dd230a90ee4dc3df8f3fe890e790f57c183e0fe0b3f981b", + "x86_64": "94999ef1d35c3952773a85ef394a1e44037fa61b562656af15330f9d3e29b871" + }, + "build_number": 6840 + }, + "26.34.0": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "8795ddda6dac6af71d85af784098cef89b76d0433f94d64fcc15539a96efa797", + "so_meta_sha256_arm64_v8a": "a8736be0de244537f21098389c7a6976acda3f0c18b1c197f94e10fb017ef280", + "so_meta_sha256": { + "arm64-v8a": "a8736be0de244537f21098389c7a6976acda3f0c18b1c197f94e10fb017ef280", + "armeabi-v7a": "cf39e98e49b421e67bbf32fb4e869d7445108db35a0e3eac8e68af4294b6354f", + "x86": "07f695a1bc4c2ed9c8fb7b69685ad87364604849b821e8e3bfc7d90b83dc6049", + "x86_64": "8a2d74ac0aa6f9056864a03e9b62cc8ad7554ba25496e73c3d7637ff98adec60" + }, + "build_number": 6850 + }, + "26.34.1": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "89e1f591ba2da77028b567a1c2b41cf572d99dd9827fed5be798b7487696de2e", + "so_meta_sha256_arm64_v8a": "a8736be0de244537f21098389c7a6976acda3f0c18b1c197f94e10fb017ef280", + "so_meta_sha256": { + "arm64-v8a": "a8736be0de244537f21098389c7a6976acda3f0c18b1c197f94e10fb017ef280", + "armeabi-v7a": "cf39e98e49b421e67bbf32fb4e869d7445108db35a0e3eac8e68af4294b6354f", + "x86": "07f695a1bc4c2ed9c8fb7b69685ad87364604849b821e8e3bfc7d90b83dc6049", + "x86_64": "8a2d74ac0aa6f9056864a03e9b62cc8ad7554ba25496e73c3d7637ff98adec60" + }, + "build_number": 6856 + }, + "26.35.0": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "4650b42a1fb52fdd43e8f2bab6117d5eb966fe085bf426e8a8e908e36635984e", + "so_meta_sha256_arm64_v8a": "fdaf7841b16e6ddc64092d188a6202a37a525c0d77d6b773d63f9be6e0ac2529", + "so_meta_sha256": { + "arm64-v8a": "fdaf7841b16e6ddc64092d188a6202a37a525c0d77d6b773d63f9be6e0ac2529", + "armeabi-v7a": "dfa9e6141ec1b96f2addf6900538b992db47b1acc33f1a22adc9378b98f104e8", + "x86": "b4892273ee29c8882e81182bd961c240c5376426ae81919495c16b6ed620ec14", + "x86_64": "c1e2afc2171243a694c25db6694f664540a3e146dcdeb2b1baba090ebcdee289" + }, + "build_number": 6861 + }, + "26.35.1": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "58593332e67b8f80fe708f139f43ad65d654ebeea768adf2ea2b1611a54f19b5", + "so_meta_sha256_arm64_v8a": "fdaf7841b16e6ddc64092d188a6202a37a525c0d77d6b773d63f9be6e0ac2529", + "so_meta_sha256": { + "arm64-v8a": "fdaf7841b16e6ddc64092d188a6202a37a525c0d77d6b773d63f9be6e0ac2529", + "armeabi-v7a": "dfa9e6141ec1b96f2addf6900538b992db47b1acc33f1a22adc9378b98f104e8", + "x86": "b4892273ee29c8882e81182bd961c240c5376426ae81919495c16b6ed620ec14", + "x86_64": "c1e2afc2171243a694c25db6694f664540a3e146dcdeb2b1baba090ebcdee289" + }, + "build_number": 6867 + }, + "26.36.2": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "3d960099bcd1b97bc21bf7826f87689a44ce0d29de5534d24ea9e0c1efc78a7f", + "so_meta_sha256_arm64_v8a": "85ba5340d5a9e031623d938d7180ab4ad5ba1e6ed596215bd3278f71f280fa46", + "so_meta_sha256": { + "arm64-v8a": "85ba5340d5a9e031623d938d7180ab4ad5ba1e6ed596215bd3278f71f280fa46", + "armeabi-v7a": "722f9e5254e247576d99f7f3c46382151bcdbdc4ef1a58d432d612d400cc7720", + "x86": "e22fd336b2a4bb00bdefde00f5618ae385dc73a49040aa5167b1b23f5b6fb188", + "x86_64": "00a641e017691534957f2b0775f4768c5f3ad2334c6c2d6c7a7b1b723ade8031" + }, + "build_number": 6879 + }, + "26.37.0": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "9d941aea70a93c825d979111d518c4cc5061db9ecec530407205c289f0b06f2b", + "so_meta_sha256_arm64_v8a": "09d48edd1d5de5ff00f8dab591b69a5f2bea41d74747a8bbede13a682d3a9aa7", + "so_meta_sha256": { + "arm64-v8a": "09d48edd1d5de5ff00f8dab591b69a5f2bea41d74747a8bbede13a682d3a9aa7", + "armeabi-v7a": "61930b6f9dcb7f1b26b38493917957bd028584ab4927edff8264a85cf7f16303", + "x86": "1a676b7e2885cdb4270d97ad121cd07b463c28295602910df8d8ea406ab55403", + "x86_64": "7eafe59f98f49642cc786bbf9532148d2bdb20f7fe3738f2fa7b77b096a395b3" + }, + "build_number": 6886 + }, + "26.37.1": { + "signature_scheme": "v3", + "certificate_count": 1, + "certificate_meta_sha256": "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93", + "certificate_sha256": [ + "1684414033eb263e2c615f8b7df5ed8793850a07656304997fbf07e9e21e1e93" + ], + "dex_meta_sha256": "dfa98ab26b96aed92da79424d30b71d265a51d8df4d2278c1a53e78a877f647b", + "so_meta_sha256_arm64_v8a": "09d48edd1d5de5ff00f8dab591b69a5f2bea41d74747a8bbede13a682d3a9aa7", + "so_meta_sha256": { + "arm64-v8a": "09d48edd1d5de5ff00f8dab591b69a5f2bea41d74747a8bbede13a682d3a9aa7", + "armeabi-v7a": "61930b6f9dcb7f1b26b38493917957bd028584ab4927edff8264a85cf7f16303", + "x86": "1a676b7e2885cdb4270d97ad121cd07b463c28295602910df8d8ea406ab55403", + "x86_64": "7eafe59f98f49642cc786bbf9532148d2bdb20f7fe3738f2fa7b77b096a395b3" + }, + "build_number": 6900 + }, "26.9.1": { "signature_scheme": "v3", "certificate_count": 1, diff --git a/src/pymax/versions/catalog.py b/src/pymax/versions/catalog.py index dddb6bc..5fc6857 100644 --- a/src/pymax/versions/catalog.py +++ b/src/pymax/versions/catalog.py @@ -21,7 +21,7 @@ class VersionCatalog: remote: Загружать ли удаленные версии при :meth:`load`. """ - RECOMMENDED_APP_VERSION: str = "26.25.0" + RECOMMENDED_APP_VERSION: str = "26.37.1" DEFAULT_REMOTE_URL: str = "https://hashes.pymax.org/versions.json" def __init__(self, remote: bool = False) -> None: From b73aa387bf457a6ddf7cc857c7c40efab412e785 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:45:13 +0300 Subject: [PATCH 26/31] test: align expectations with current message and event models --- tests/api/test_message_service.py | 5 ----- tests/dispatch/test_dispatcher.py | 4 ++-- tests/filters/test_magic.py | 2 +- 3 files changed, 3 insertions(+), 8 deletions(-) diff --git a/tests/api/test_message_service.py b/tests/api/test_message_service.py index 7611889..759a77b 100644 --- a/tests/api/test_message_service.py +++ b/tests/api/test_message_service.py @@ -317,27 +317,22 @@ async def test_delete_pin_and_read_message_send_expected_opcodes( frame({}), frame({}), frame({"unread": 0, "mark": 3000000}), - frame({"unread": 0, "mark": 3000000}), ] ) assert await app.api.messages.delete_message(100, [1, 2], for_me=True) is True assert await app.api.messages.pin_message(100, 2, notify_pin=False) is True read_state = await app.api.messages.read_message(2, 100) - web_read_state = await app.api.messages.read_message("3", 100) assert read_state.mark == 3000000 - assert web_read_state.mark == 3000000 assert [call.opcode for call in app.calls] == [ Opcode.MSG_DELETE, Opcode.CHAT_UPDATE, Opcode.CHAT_MARK, - Opcode.CHAT_MARK, ] assert app.calls[0].payload["forMe"] is True assert app.calls[1].payload["pinMessageId"] == 2 assert app.calls[2].payload["messageId"] == 2 - assert app.calls[3].payload["messageId"] == "3" @pytest.mark.asyncio diff --git a/tests/dispatch/test_dispatcher.py b/tests/dispatch/test_dispatcher.py index 305174d..133e904 100644 --- a/tests/dispatch/test_dispatcher.py +++ b/tests/dispatch/test_dispatcher.py @@ -219,7 +219,7 @@ async def test_dispatcher_maps_reaction_update_event() -> None: router: Router[str] = Router() dispatcher: Dispatcher[str] = Dispatcher(app, router) dispatcher.bind_client("client") - seen: list[tuple[str, int, int, int, str]] = [] + seen: list[tuple[int, int, int, int, str]] = [] @router.on_reaction_update() async def on_reaction_update(event, _client): @@ -246,7 +246,7 @@ async def on_reaction_update(event, _client): ) ) - assert seen == [("116739131144745294", 239067070, 1, 1, "👍")] + assert seen == [(116739131144745294, 239067070, 1, 1, "👍")] @pytest.mark.asyncio diff --git a/tests/filters/test_magic.py b/tests/filters/test_magic.py index 207141c..4ce59b1 100644 --- a/tests/filters/test_magic.py +++ b/tests/filters/test_magic.py @@ -47,7 +47,7 @@ def make_photo() -> PhotoAttachment: def test_message_container_exposes_supported_message_fields() -> None: fields = {name for name, value in vars(type(F.message)).items() if isinstance(value, property)} - assert fields == set(Message.model_fields) - {"link"} + assert fields == set(Message.model_fields) - {"link", "delayed_attributes"} def test_chat_container_exposes_all_chat_fields() -> None: From dd3b717a6d841c09692a602604972f01b1ad1c84 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:46:05 +0300 Subject: [PATCH 27/31] docs: document 2.5.0 public APIs and migration Add FSM, dependency injection, stories and callback guides, release notes, and focused public API docstrings. Update routing, lifecycle, comments, formatting and media examples. --- README.md | 22 +- docs/api/router.rst | 25 +++ docs/client.rst | 32 ++- docs/di.rst | 144 +++++++++++++ docs/examples.rst | 17 +- docs/faq.rst | 2 + docs/files.rst | 9 + docs/formatting.rst | 11 +- docs/fsm.rst | 160 ++++++++++++++ docs/getting-started.rst | 15 +- docs/index.rst | 4 + docs/messages.rst | 109 +++++++++- docs/release-2-5-0.rst | 181 ++++++++++++++++ docs/router.rst | 198 +++++++++++++---- docs/stories.rst | 203 ++++++++++++++++++ docs/troubleshooting.rst | 7 +- docs/types/callback_response.rst | 9 + docs/types/index.rst | 8 + docs/types/story.rst | 62 ++++++ src/pymax/infra/bots.py | 11 + src/pymax/infra/message.py | 30 ++- .../domain/attachments/keyboards/inline.py | 6 +- src/pymax/types/domain/callback.py | 7 + src/pymax/types/domain/comment.py | 4 +- src/pymax/types/events/reaction.py | 4 +- 25 files changed, 1175 insertions(+), 105 deletions(-) create mode 100644 docs/di.rst create mode 100644 docs/fsm.rst create mode 100644 docs/release-2-5-0.rst create mode 100644 docs/stories.rst create mode 100644 docs/types/callback_response.rst create mode 100644 docs/types/story.rst diff --git a/README.md b/README.md index ffeec0c..9e915d5 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,11 @@ WebSocket. - Авторизация по телефону и SMS-коду через `Client`. - QR-авторизация web-клиента через `WebClient`. -- Роутеры, фильтры, `on_start`, raw-события и typed events. +- Роутеры, составные фильтры, middleware, `on_start`, raw-события и typed events. +- FSM для диалогов и необязательная интеграция с Dishka. - Сообщения: отправка и планирование, ответы, реакции, pin, read, delete и история. +- Комментарии к постам каналов и нажатия inline-кнопок ботов. +- Сторис: фото и видео, лента, реакции и статистика просмотров. - Чаты, группы, участники, invite-ссылки и настройки групп. - Пользователи, контакты, профиль, папки, активные сессии и 2FA. - Вложения: `Photo`, `File`, `Video`, `Voice`, `VideoNote`. @@ -62,6 +65,7 @@ pip install git+https://github.com/MaxApiTeam/PyMax.git import asyncio from pymax import Client, Message +from pymax.filters import Command client = Client( phone="+79990000000", @@ -76,7 +80,7 @@ async def on_start(client: Client) -> None: print("Ваш ID:", client.me.contact.id if client.me else "unknown") -@client.on_message() +@client.on_message(Command("start")) async def on_message(message: Message, client: Client) -> None: print(message.chat_id, message.sender, message.text) @@ -92,6 +96,8 @@ if __name__ == "__main__": asyncio.run(main()) ``` +Отправьте `/start`, чтобы вызвать обработчик. + ## WebClient `WebClient` использует WebSocket и QR-авторизацию: @@ -119,15 +125,12 @@ Handler всегда принимает событие и клиента: `(even ```python from pymax import Client, ClientRouter, Message +from pymax.filters import Command router = ClientRouter() -def is_start(message: Message) -> bool: - return message.text == "/start" - - -@router.on_message(is_start) +@router.on_message(Command("start")) async def start(message: Message, client: Client) -> None: await message.answer("Готово") @@ -140,8 +143,11 @@ client.include_router(router) - [Getting Started](docs/getting-started.rst) - первый запуск и сессии. - [Client](docs/client.rst) - жизненный цикл клиента, reconnect и sync-state. -- [Router](docs/router.rst) - роутеры, фильтры и raw events. +- [Router](docs/router.rst) - роутеры, фильтры, middleware и raw events. +- [FSM](docs/fsm.rst) - состояния и данные диалога. +- [DI и Dishka](docs/di.rst) - зависимости обработчиков. - [Messages](docs/messages.rst) - сообщения, реакции, история и вложения. +- [Stories](docs/stories.rst) - публикация и чтение сторис. - [Files](docs/files.rst) - отправка и скачивание файлов. - [FAQ](docs/faq.rst) и [Troubleshooting](docs/troubleshooting.rst) - частые проблемы. diff --git a/docs/api/router.rst b/docs/api/router.rst index b686580..0017a87 100644 --- a/docs/api/router.rst +++ b/docs/api/router.rst @@ -14,3 +14,28 @@ Router API .. autodata:: pymax.ClientRouter .. autodata:: pymax.WebRouter + +Фильтры +------- + +Примеры регистрации и объединения фильтров приведены в :doc:`/router`. + +.. autoclass:: pymax.filters.Filter + :exclude-members: resolve_filter_result + +.. autoclass:: pymax.filters.Command + +.. autoclass:: pymax.filters.Reply + +.. autoclass:: pymax.filters.Forwarded + +.. autoclass:: pymax.filters.FromMe + +.. autoclass:: pymax.filters.HasAttachment + +Middleware +---------- + +.. autoclass:: pymax.dispatch.Middleware + +.. autodata:: pymax.dispatch.MiddlewareNext diff --git a/docs/client.rst b/docs/client.rst index d91ab51..7873a8a 100644 --- a/docs/client.rst +++ b/docs/client.rst @@ -36,10 +36,11 @@ Client ``start()`` - long-running режим с автоматическим reconnect. Метод не возвращается, пока соединение не закрыто штатно или задача не отменена. -``connect()`` выполняет один цикл подключения, login и ``on_start``, после -чего возвращается, оставляя соединение открытым. Он не запускает reconnect -loop: приложение само выполняет работу и затем вызывает ``stop()`` или -``close()``. +``connect()`` выполняет один цикл подключения и login, запускает +``on_start``-обработчики и возвращается, оставляя соединение открытым. +Обработчики выполняются в отдельных задачах: возврат из ``connect()`` не +означает, что они уже завершились. Приложение само выполняет работу и затем +вызывает ``stop()`` или ``close()``; reconnect loop этот метод не запускает. .. code-block:: python @@ -361,7 +362,7 @@ number всегда берутся из конфигурации текущег await client.relogin() -``relogin()`` удаляет загруженную сессию из store, закрывает текущий runtime и +``relogin()`` удаляет загруженную локальную сессию, закрывает соединение и по умолчанию сразу запускает клиента снова. Если token был передан через ``ExtraConfig(token=...)``, он тоже сбрасывается; это можно отключить через ``drop_config_token=False``. @@ -370,16 +371,17 @@ Reconnect --------- По умолчанию reconnect включен. Если соединение падает из-за сетевой ошибки, -клиент закрывает текущий runtime, ждет ``reconnect_delay`` секунд, заново -создает соединение и app, затем снова выполняет start/login. +``start()`` закрывает соединение, ждет ``reconnect_delay`` секунд и повторяет +подключение с login. -Роутеры после reconnect не теряются: корневой ``Router`` хранится на клиенте, -а новый ``App`` снова получает тот же root router. ``on_start`` вызывается -после каждого успешного reconnect. +Регистрации обработчиков и middleware, а также данные FSM в памяти +сохраняются при reconnect того же клиента. ``on_start`` вызывается после +каждого успешного подключения. Завершение процесса очищает FSM в памяти. Если сервер отозвал login token, ``ExtraConfig(relogin=True)`` по умолчанию сбрасывает текущую сессию и запускает авторизацию заново. Значение ``False`` -отключает этот автоматический сброс. +отключает этот автоматический сброс. Если новый token тоже отклонен, ошибка +передается вызывающему коду без повторного автоматического запроса авторизации. Перед повторным подключением можно зарегистрировать ``on_disconnect``: @@ -428,6 +430,14 @@ Debug-логи показывают handshake, login, входящие собы ``delete_message()``, ``pin_message()``, ``read_message()``, реакции и получение URL для входящих файлов/видео. +Комментарии + ``send_comment()``, ``fetch_comments()``, редактирование, удаление, + реакции и подписка на ветку поста. Подробнее: :doc:`messages`. + +Сторис + ``send_story()``, ``get_stories_feed()``, ``get_stories()``, просмотр, + реакции и подробная статистика. Подробнее: :doc:`stories`. + Чаты ``get_chat()``, ``fetch_chats()``, создание групп, invite-ссылки, участники, назначение администраторов, настройки групп, удаление чатов и diff --git a/docs/di.rst b/docs/di.rst new file mode 100644 index 0000000..2c15f20 --- /dev/null +++ b/docs/di.rst @@ -0,0 +1,144 @@ +Внедрение зависимостей +====================== + +Встроенная передача ``FSMContext`` описана в разделе :doc:`fsm` и работает без +дополнительных пакетов. Для собственных сервисов и других зависимостей +можно подключить Dishka. + +Установка +--------- + +.. code-block:: bash + + pip install -U 'maxapi-python[dishka]' + +или через uv: + +.. code-block:: bash + + uv add 'maxapi-python[dishka]' + +Подключение Dishka +------------------ + +Создайте ``AsyncContainer`` и свяжите его с клиентом через +``setup_dishka(container, client)``. Параметры, которые должен заполнить +контейнер, помечаются ``FromDishka[T]``. Событие и клиент остаются первыми +двумя аргументами обработчика. + +.. code-block:: python + + import asyncio + + from dishka import FromDishka, Provider, Scope, make_async_container, provide + + from pymax import Client, ClientRouter, Message + from pymax.filters import Command + from pymax.integrations.dishka import inject, setup_dishka + + + class GreetingService: + def text(self) -> str: + return "Привет от сервиса!" + + + class AppProvider(Provider): + @provide(scope=Scope.APP) + def greetings(self) -> GreetingService: + return GreetingService() + + + router = ClientRouter() + + + @router.on_message(Command("hello")) + @inject + async def hello( + message: Message, + client: Client, + greetings: FromDishka[GreetingService], + ) -> None: + await message.answer(greetings.text()) + + + async def main() -> None: + container = make_async_container(AppProvider()) + client = Client(phone="+79990000000", work_dir="cache") + client.include_router(router) + setup_dishka(container, client) + + try: + await client.start() + finally: + await container.close() + + + if __name__ == "__main__": + asyncio.run(main()) + +``@inject`` находится под ``@router.on_message(...)``: сначала создается +обертка Dishka, затем роутер регистрирует ее. Одна аннотация +``GreetingService`` без ``FromDishka`` не включает внедрение зависимости. + +В примере сервис имеет ``Scope.APP`` и повторно используется в пределах +созданного контейнера. Контейнер привязан к конкретному экземпляру клиента. +Если один роутер подключен к нескольким клиентам, вызовите ``setup_dishka`` +для каждого из них с нужным контейнером. + +Автоматическое оборачивание обработчиков +---------------------------------------- + +Вместо ``@inject`` у каждого обработчика можно включить ``auto_inject``: + +.. code-block:: python + + client.include_router(router) + setup_dishka(container, client, auto_inject=True) + +Сначала зарегистрируйте обработчики и подключите роутеры, затем вызовите +``setup_dishka``. Интеграция обойдет текущее дерево роутеров клиента и обернет +уже зарегистрированные обработчики событий. Обработчики, у которых уже есть +``@inject``, повторно не оборачиваются. + +Если нужно обернуть только отдельный роутер и его детей, используйте +``inject_router``: + +.. code-block:: python + + from pymax.integrations.dishka import inject_router + + inject_router(router) + +Этот вызов не заменяет ``setup_dishka``: контейнер по-прежнему нужно связать +с клиентом. Оба способа оборачивают только существующие регистрации; новые +обработчики и позже подключенные роутеры автоматически не обрабатываются. +Для них используйте ``@inject`` или повторите оборачивание после регистрации. + +Автоматическое оборачивание относится к обработчикам событий, например +``on_message`` и ``on_raw``. Оно не затрагивает ``on_start``, ``on_error`` +и ``on_disconnect``. + +Scope и завершение работы +------------------------- + +Интеграция получает зависимости непосредственно из контейнера, переданного +в ``setup_dishka``. Отдельный ``Scope.REQUEST`` для каждого события не +открывается. При обычном контейнере со ``Scope.APP`` зависимости уровня +``Scope.REQUEST`` автоматически недоступны. + +PyMax также не добавляет ``Message``, ``Client`` или ``FSMContext`` в контекст +Dishka. Событие и клиент передаются самим PyMax, а ``FSMContext`` можно +добавить отдельным обязательным параметром с этой аннотацией. + +Созданием, выбором scope и закрытием контейнера управляет приложение. +``client.close()`` не закрывает контейнер Dishka. В примере это делает +``await container.close()`` в ``finally`` после завершения работы клиента. + +API reference +------------- + +.. autofunction:: pymax.integrations.dishka.inject + +.. autofunction:: pymax.integrations.dishka.inject_router + +.. autofunction:: pymax.integrations.dishka.setup_dishka diff --git a/docs/examples.rst b/docs/examples.rst index 45e65ea..102affb 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -9,11 +9,12 @@ Examples import asyncio from pymax import Client, Message + from pymax.filters import FromMe client = Client(phone="+79990000000", work_dir="cache") - @client.on_message() + @client.on_message(~FromMe()) async def echo(message: Message, client: Client) -> None: if message.chat_id is None or not message.text: return @@ -28,26 +29,18 @@ Examples .. code-block:: python - from collections.abc import Callable - from pymax import Client, ClientRouter, Message + from pymax.filters import Command router = ClientRouter() - def command(name: str) -> Callable[[Message], bool]: - def filter_message(message: Message) -> bool: - return message.text == f"/{name}" - - return filter_message - - - @router.on_message(command("start")) + @router.on_message(Command("start")) async def start(message: Message, client: Client) -> None: await message.answer("Привет") - @router.on_message(command("me")) + @router.on_message(Command("me")) async def me(message: Message, client: Client) -> None: if client.me: await message.answer(f"Ваш ID: {client.me.contact.id}") diff --git a/docs/faq.rst b/docs/faq.rst index d56a16d..be7b0a6 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -26,6 +26,8 @@ FAQ ``@client.on_message()``; * handler принимает один аргумент вместо ``(event, client)``; * фильтр вернул ``False`` или упал с ошибкой; +* вместо экземпляра ``Filter`` передана обычная функция; +* более ранний обработчик этого роутера уже подошел под событие; * событие другого типа; * payload не прошел Pydantic-валидацию. diff --git a/docs/files.rst b/docs/files.rst index ac83e7a..52634a9 100644 --- a/docs/files.rst +++ b/docs/files.rst @@ -95,6 +95,15 @@ Files или другого аудиофайла в ``.ogg`` недостаточно: PyMax загружает исходные байты без перекодирования. +Пример подготовки Ogg/Opus из видео или аудиофайла: + +.. code-block:: console + + ffmpeg -i input.mp4 -vn -c:a libopus -ac 1 -ar 48000 -b:a 32k -f ogg voice.ogg + +Команда создает монофайл Opus с частотой 48 кГц. PyMax загружает уже +подготовленный файл; FFmpeg не требуется во время отправки. + ``VideoNote`` также не перекодирует видео. Для совместимости с официальным клиентом 26.21.1 рекомендуется следующий формат: diff --git a/docs/formatting.rst b/docs/formatting.rst index 8c4da59..da74bd5 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -2,7 +2,8 @@ Text Formatting =============== PyMax поддерживает базовое Markdown-подобное форматирование при отправке -сообщений. Форматирование применяется автоматически в ``send_message()``, +сообщений. Форматирование применяется автоматически при отправке и +редактировании сообщений и комментариев, в том числе через ``Message.answer()``, ``Message.reply()`` и ``Chat.answer()``: библиотека удаляет служебные маркеры из текста и передает Max список ``Element``. @@ -67,6 +68,10 @@ PyMax поддерживает базовое Markdown-подобное форм Этот фрагмент будет отправлен как текст ``print("hello")`` с элементом ``CODE``. +Содержимое inline-кода и блоков кода передается буквально: звёздочки, +подчёркивания, ссылки, заголовки и цитаты внутри них не разбираются как +дополнительная разметка. + Ограничения ----------- @@ -79,3 +84,7 @@ PyMax поддерживает базовое Markdown-подобное форм Экранирование служебных символов обратным слешем пока не обрабатывается. +Одиночное подчёркивание между буквами или цифрами сохраняется, поэтому +``snake_case_name`` и URL с такими подчёркиваниями остаются целыми. +Для звёздочки это правило не действует: ``foo*bar*baz`` содержит выделение. + diff --git a/docs/fsm.rst b/docs/fsm.rst new file mode 100644 index 0000000..a0f59b1 --- /dev/null +++ b/docs/fsm.rst @@ -0,0 +1,160 @@ +FSM +=== + +FSM хранит состояние диалога и данные между сообщениями. Например, можно +сначала спросить имя, затем город и обработать каждый ответ своим handler-ом. +Состояние и данные разделены по клиенту, пользователю и чату: один пользователь +может независимо проходить сценарий в разных чатах. + +Состояния и контекст +-------------------- + +Импортируйте ``FSMContext``, ``FsmGroup`` и ``State`` из ``pymax.fsm``. +Состояния объявляются атрибутами класса ``FsmGroup``. Экземпляр ``State`` +используется и для установки состояния, и как фильтр обработчика. + +Добавьте после ``message`` и ``client`` обязательный параметр с аннотацией +``FSMContext``. PyMax подставит контекст автоматически; имя параметра может +быть любым. Для этого не нужна установка Dishka. + +``ctx.storage`` + Хранилище состояния и данных текущего контекста. Все операции выполняются + через него: например, ``await ctx.storage.set_state(Form.name)``. + +``ctx.key`` + Ключ текущего контекста, связывающий клиента, пользователя и чат. + +Аннотация параметра должна быть ``FSMContext`` без значения по умолчанию. +Автоматическая передача контекста доступна для событий ``Message``, когда +известны отправитель и чат; для других типов событий FSM не поддерживается. + +Пример диалога +-------------- + +.. code-block:: python + + import asyncio + + from pymax import Client, ClientRouter, Message + from pymax.filters import Command + from pymax.fsm import FSMContext, FsmGroup, State + + router = ClientRouter() + + + class Form(FsmGroup): + name = State() + city = State() + + + @router.on_message(Command("form")) + async def begin(message: Message, client: Client, ctx: FSMContext) -> None: + await ctx.storage.clear() + await ctx.storage.set_state(Form.name, ttl=300) + await message.answer("Как вас зовут?") + + + @router.on_message(Form.name) + async def save_name(message: Message, client: Client, ctx: FSMContext) -> None: + if not message.text: + await message.answer("Отправьте имя текстом") + return + + await ctx.storage.set_data("name", message.text) + await ctx.storage.set_state(Form.city, ttl=300) + await message.answer("Из какого вы города?") + + + @router.on_message(Form.city) + async def save_city(message: Message, client: Client, ctx: FSMContext) -> None: + if not message.text: + await message.answer("Отправьте город текстом") + return + + await ctx.storage.update_data(city=message.text) + data = await ctx.storage.get_data() + await ctx.storage.clear() + await message.answer(f"{data['name']}, город: {data['city']}") + + + client = Client(phone="+79990000000", work_dir="cache") + client.include_router(router) + + + async def main() -> None: + await client.start() + + + if __name__ == "__main__": + asyncio.run(main()) + +Отправьте ``/form``, затем имя и город. Повторная команда ``/form`` очищает +предыдущие данные и начинает диалог заново. В примере каждый шаг действует +пять минут с момента перехода в него. + +Порядок обработчиков +-------------------- + +В одном роутере вызывается первый обработчик, у которого совпали все фильтры. +Поэтому команда начала диалога зарегистрирована перед обработчиками состояний, +а общий обработчик без фильтров следует размещать после них. + +После первого совпадения PyMax продолжает обход дочерних роутеров. Если +обработчик родителя изменил состояние, фильтр дочернего роутера уже увидит +новое значение на том же сообщении. В примере все шаги находятся в одном +роутере, поэтому сообщение с командой не обрабатывается сразу как имя. + +Операции с состоянием и данными +------------------------------- + +Все методы ``ctx.storage`` асинхронные: + +``get_state()`` + Возвращает строковое имя состояния или ``None``. Для ``State`` используется + полное имя из модуля, класса группы и имени атрибута. + +``set_state(state, ttl=None)`` + Принимает ``State``, строку или ``None``. ``None`` сбрасывает состояние. + ``ttl`` задается в секундах; без него состояние действует до следующего + изменения. Переход и сброс состояния сохраняют данные. + +``get_data()`` + Возвращает поверхностную копию словаря. Изменение ключей этой копии + не меняет хранилище, но вложенные изменяемые значения остаются общими. + +``set_data(key, value)`` + Записывает одно значение по ключу, сохраняя остальные данные. + +``update_data(**data)`` + Добавляет или перезаписывает несколько ключей, сохраняя остальные данные. + +``clear()`` + Сбрасывает состояние и удаляет все данные текущего контекста. + +Хранение и TTL +-------------- + +Сейчас используется ``InMemoryFSM``: состояние и данные живут в памяти +процесса. Они сохраняются при reconnect того же экземпляра клиента и теряются +после перезапуска процесса. У нового экземпляра клиента отдельное хранилище. + +TTL проверяется при чтении состояния, в том числе фильтром ``State``. +Истечение срока сбрасывает только состояние, без удаления данных и без +вызова отдельного обработчика. Для полного сброса используйте ``clear()``. + +Фильтры и обычные обработчики ``Message`` для одного клиента, пользователя и +чата выполняются последовательно, включая переходы состояния. + +API reference +------------- + +.. autoclass:: pymax.fsm.FSMContext + +.. autoclass:: pymax.fsm.State + :members: full_name + :exclude-members: owner, name + +.. autoclass:: pymax.fsm.FsmGroup + +.. autoclass:: pymax.fsm.InMemoryFSM + :members: get_state, set_state, get_data, set_data, update_data, clear diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 8ad80fa..cffb481 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -35,6 +35,7 @@ PyMax спросит код в консоли и сохранит сессию import asyncio from pymax import Client, Message + from pymax.filters import Command client = Client( phone="+79990000000", @@ -49,11 +50,12 @@ PyMax спросит код в консоли и сохранит сессию print("Чатов в первом sync:", len(client.chats or [])) - @client.on_message() + @client.on_message(Command("start")) async def on_message(message: Message, client: Client) -> None: print(message.chat_id, message.sender, message.text) - await message.answer("Привет от PyMax") + if message.chat_id is not None: + await message.answer("Привет от PyMax") async def main() -> None: @@ -63,12 +65,15 @@ PyMax спросит код в консоли и сохранит сессию if __name__ == "__main__": asyncio.run(main()) +Отправьте ``/start``, чтобы вызвать обработчик. О собственных фильтрах и +объединении условий читайте в :doc:`router`. + Что происходит при запуске -------------------------- -1. ``Client`` открывает TCP-соединение с Max. -2. Выполняется handshake с ``device_id``. -3. PyMax ищет сохраненную сессию в ``work_dir/session_name``. +1. PyMax подготавливает конфигурацию и загружает сохраненную сессию. +2. ``Client`` открывает TCP-соединение с Max. +3. Выполняется handshake с ``device_id`` из сессии или конфигурации. 4. Если сессии нет, запускается авторизация. 5. Клиент делает login и получает профиль, список чатов и sync-state. 6. Вызываются ``on_start``-обработчики. diff --git a/docs/index.rst b/docs/index.rst index 67df008..1f77c67 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,6 +22,7 @@ PyMax - асинхронная Python-библиотека для Max API. Он :maxdepth: 1 :caption: Новости + release-2-5-0 release-2-4-1 release-2-4-0 release-2-3-1 @@ -40,7 +41,10 @@ PyMax - асинхронная Python-библиотека для Max API. Он client auth router + fsm + di messages + stories formatting chats users diff --git a/docs/messages.rst b/docs/messages.rst index febbded..9cb4796 100644 --- a/docs/messages.rst +++ b/docs/messages.rst @@ -204,12 +204,8 @@ Reply и forward во входящем сообщении elif message.text == "/delete": await message.delete(for_me=False) -.. note:: - - У низкоуровневого ``client.read_message(...)`` есть особенность Max: - для отметки прочтения TCP-клиент ожидает ``message_id`` как ``int``, а - WebSocket-клиент - как ``str``. Если вызываете метод напрямую, выбирайте - тип по клиенту. +``client.read_message(message_id, chat_id)`` принимает оба ID как ``int`` +для ``Client`` и ``WebClient``. Методы ``add_reaction()``, ``get_reactions()`` и ``remove_reaction()`` принимают ID сообщений только как ``int``. При этом ``get_reactions()`` @@ -261,13 +257,110 @@ Reply и forward во входящем сообщении сообщения; для отложенных сообщений передайте ``ItemType.DELAYED`` из ``pymax.api.messages.enums``. +Комментарии к постам каналов +---------------------------- + +Для комментария нужны два разных ID: ``chat_id`` канала и ``post_id`` поста +в этом канале. ID самого комментария передается как ``message_id``. + +.. code-block:: python + + comment = await client.send_comment( + chat_id=-123456, + post_id=987654, + text="Комментарий к посту", + ) + await client.send_comment( + chat_id=-123456, + post_id=987654, + reply_to=comment.id, + text="Ответ на комментарий", + ) + comments = await client.fetch_comments( + chat_id=-123456, + post_id=987654, + backward=30, + ) + +Для получения конкретных комментариев доступны ``get_comment()`` и +``get_comments()``. Редактирование, удаление и реакции также принимают +контекст поста: + +.. code-block:: python + + await client.edit_comment( + chat_id=-123456, + post_id=987654, + message_id=comment.id, + text="Обновленный комментарий", + ) + await client.add_comment_reaction( + chat_id=-123456, + post_id=987654, + message_id=comment.id, + reaction="👍", + ) + await client.delete_comment( + chat_id=-123456, + post_id=987654, + message_ids=[comment.id], + ) + +``subscribe_comments(chat_id, post_id)`` подписывает клиента на события ветки. +Для отмены передайте ``subscribe=False``. Счетчики комментариев можно запросить +через ``get_comments_info(chat_id, post_ids)``; ``delete_user_comments()`` +удаляет комментарии указанного автора в ветке поста. + +Если у ``Message`` заполнены ``chat_id`` и ``post_id``, методы ``answer()``, +``reply()``, ``edit()``, ``delete()``, ``react()`` и ``unreact()`` используют +контекст комментария. Отправка и редактирование через эти методы сохраняют +контекст в возвращенном ``Message``. Если ``post_id`` не пришел в объекте, +используйте явные методы клиента с известным ID поста. + +Отложенная отправка комментариев не поддерживается: ``send_comment()`` не +принимает ``send_at``, а ``Message.answer()`` и ``Message.reply()`` с +``post_id`` и ненулевым ``send_at`` вызывают ``ValueError``. + +Inline-кнопки ботов +------------------- + +``InlineKeyboardAttachment.keyboard.buttons`` — список строк кнопок. +``callback_id`` находится во вложении клавиатуры, а тип и ``payload`` — +в конкретной кнопке. Для callback-кнопки можно передать их в +``client.send_callback()``: + +.. code-block:: python + + from pymax import Client, Message + from pymax.types import ButtonType, InlineKeyboardAttachment + + + async def press_first_callback(message: Message, client: Client) -> None: + for attach in message.attaches: + if not isinstance(attach, InlineKeyboardAttachment): + continue + + for row in attach.keyboard.buttons: + for button in row: + if button.type == ButtonType.CALLBACK: + result = await client.send_callback( + callback_id=attach.callback_id, + type=button.type, + payload=button.payload, + ) + print(result.success) + return + +Результат — :doc:`types/callback_response`. Поля ``message`` и ``chat`` +могут отсутствовать; если Max их вернул, у них доступны методы действий. + Почему поля бывают None ----------------------- Max присылает разные формы событий. Некоторые payload-ы содержат полный объект сообщения, а некоторые - только часть данных. Поэтому ``Message.chat_id``, -``sender``, ``attaches``, ``reaction_info``, ``status`` и другие поля могут -быть пустыми. +``sender``, ``reaction_info``, ``status`` и другие поля могут быть ``None``. +Отсутствующие вложения представлены пустым списком ``attaches``. Практическое правило: перед действиями, которым нужен чат, проверяйте ``message.chat_id``. diff --git a/docs/release-2-5-0.rst b/docs/release-2-5-0.rst new file mode 100644 index 0000000..14f1ab7 --- /dev/null +++ b/docs/release-2-5-0.rst @@ -0,0 +1,181 @@ +PyMax 2.5.0 +=========== + +Версия 2.5.0 добавляет FSM для диалогов, внедрение зависимостей, middleware и +составные фильтры. Расширены возможности работы с комментариями каналов, +inline-кнопками ботов и сторис. Исправлены загрузка фотографий, обработка +реакций, повторная авторизация и сохранность текста при форматировании. + +Ниже перечислены пользовательские изменения относительно ``2.4.1``. + +Новый публичный API +------------------- + +* Добавлен FSM: ``FsmGroup`` и ``State`` объявляют шаги диалога, + ``FSMContext`` предоставляет состояние и данные текущего пользователя в + текущем чате. Операции доступны через ``ctx.storage``: ``get_state()``, + ``set_state()``, ``get_data()``, ``set_data()``, ``update_data()`` и + ``clear()``. Состояние можно ограничить TTL в секундах. Хранилище работает + в памяти; перезапуск процесса очищает состояние и данные. + Пример диалога: :doc:`fsm`. +* Обработчики событий могут получать дополнительные обязательные параметры + по аннотации типа. Встроенный ``FSMContext`` автоматически передается в + обработчик ``Message`` при наличии ID чата и отправителя. Для собственных + зависимостей добавлена необязательная интеграция с Dishka: + ``maxapi-python[dishka]``, ``inject()``, ``inject_router()`` и + ``setup_dishka()``. ``auto_inject=True`` оборачивает уже зарегистрированные + обработчики подключенных роутеров. Контейнером и его закрытием управляет + приложение; отдельный request scope для события автоматически не создается. + Подробнее: :doc:`di`. +* Добавлены фильтры ``Command``, ``Reply``, ``Forwarded``, ``FromMe`` и + ``HasAttachment`` из ``pymax.filters``. Условия можно объединять операторами + ``&``, ``|`` и ``~``. ``F.message`` и ``F.chat`` предоставляют проверки + полей: сравнения, ``contains()``, ``startswith()``, ``endswith()``, + ``between()``, ``is_none()`` и ``is_empty()``. Собственные фильтры наследуются + от ``Filter`` и могут быть синхронными или асинхронными. +* ``client.add_middleware()`` регистрирует middleware для обработчиков клиента + и подключенных роутеров. Middleware принимает ``client``, ``event`` и + ``call_next``, выполняется после фильтров и продолжает цепочку через + ``await call_next(event)``. Порядок входа соответствует порядку регистрации. + Фильтры и middleware описаны в :doc:`router`. +* Для комментариев к постам каналов добавлены ``send_comment()``, + ``fetch_comments()``, ``get_comment()``, ``get_comments()``, + ``edit_comment()``, ``delete_comment()``, ``add_comment_reaction()`` и + ``remove_comment_reaction()``. Методы принимают отдельно ``chat_id`` канала + и ``post_id`` поста; ID комментария передается как ``message_id``. +* ``subscribe_comments()`` управляет подпиской на события ветки, + ``get_comments_info()`` возвращает счетчики постов, а + ``delete_user_comments()`` удаляет комментарии автора в ветке. + ``set_channel_comments()`` включает или выключает комментарии канала, + ``block_comment_author()`` блокирует авторов комментариев. +* ``Message.post_id`` сохраняет ID поста из входящего события. При наличии + этого поля методы ``answer()``, ``reply()``, ``edit()``, ``delete()``, + ``react()`` и ``unreact()`` работают с комментарием соответствующего поста. + Возвращаемые из этих методов сообщения сохраняют контекст канала и поста. + Отложенная отправка комментариев не поддерживается. + Подробнее: :doc:`messages`. +* ``send_callback(callback_id, type, payload)`` передает нажатие inline-кнопки + бота и возвращает ``CallbackResponse``. Результат содержит ``success`` и + дополнительные ``message``/``chat``, если Max их прислал. Эти объекты + поддерживают методы действий. ``ButtonType`` и ``CallbackResponse`` + доступны из ``pymax.types``. +* Inline-клавиатуры получили типизированные модели кнопок. Поле + ``InlineKeyboardAttachment.keyboard.buttons`` содержит список строк, а + ``callback_id`` самого вложения используется при нажатии кнопки. Данные + конкретной кнопки доступны через ее поля: ``text``, ``type``, ``payload``, + ``url`` и другие в зависимости от типа. +* Добавлена публикация сторис: ``send_story()`` принимает ``Photo`` или + ``Video``, необязательную ссылку ``link`` и возвращает ``Story`` с ID. + История публикуется на 48 часов. Для видео нужно передать положительную + ``duration`` в миллисекундах; длительность автоматически не определяется. +* ``get_stories_feed()`` возвращает страницу превью владельцев и следующий + курсор. ``get_stories()`` получает истории владельца, а + ``get_stories_by_id()`` — конкретные истории по их ID. + ``StoryPreview`` содержит владельца и счетчики; ID отдельных историй + находятся в ``Story``. Для просмотра, изменения настроек и удаления + доступны ``read_story()``, ``edit_story()`` и ``delete_story()``. +* ``add_story_reaction()`` и ``remove_story_reaction()`` управляют своей + реакцией на историю. ``get_story_detailed_stats()`` возвращает страницу + пользователей и следующий маркер. ``StoryStatsFilter.VIEWS`` выбирает + просмотры, ``StoryStatsFilter.REACTIONS`` — реакции. Фильтр импортируется + из ``pymax.api.stories``. Новый ``on_story_update()`` передает + ``StoryPreview`` обновившегося владельца. Подробнее: :doc:`stories`. + +Изменения поведения +------------------- + +* Встроенный ``VersionCatalog`` расширен: добавлены fingerprints 16 + Android-версий Max от ``26.29.0`` до ``26.37.1`` (build ``6900``). + Их можно выбрать через ``Client(app_version=...)`` без загрузки удаленного + каталога. Подробнее о выборе версии: :doc:`client`. +* В каждом роутере выполняется первый подходящий обработчик данного типа + события. После этого обход дочерних роутеров продолжается. Порядок + регистрации теперь определяет, какой обработчик получит событие внутри + одного роутера. +* Фильтры и обработчики сообщений одного клиента, пользователя и чата + выполняются последовательно. Проверка состояния FSM и переход внутри + обработчика входят в эту последовательность; сообщения с разными ключами + могут обрабатываться параллельно. +* При reconnect того же экземпляра клиента сохраняются регистрации + обработчиков, middleware и данные FSM. Ранее полученные ``Message``, + ``Chat`` и ``User`` продолжают использовать текущее соединение. + Сессия в ``InMemoryStore`` также сохраняется между reconnect, но теряется + после завершения процесса. +* При отозванном login token автоматическая повторная авторизация выполняется + один раз. Если новый token тоже отклонен, ``start()`` передает ошибку + вызывающему коду. ``ExtraConfig(relogin=False)`` отключает автоматическую + повторную авторизацию. +* Пользовательские middleware оборачивают выбранные обработчики событий. + Внутренние уведомления о готовности файлов обрабатываются отдельно: + пользовательская цепочка не задерживает завершение загрузки вложения. + +Исправления +----------- + +* Исправлен разбор сильно сжатых TCP-ответов. Корректные LZ4-ответы с + коэффициентом сжатия больше 127 больше не отклоняются с ошибкой + ``invalid TCP compression factor`` и не обрывают соединение. Это затрагивало, + в частности, загрузку страниц истории сообщений. +* Загрузка фотографий поддерживает ссылки с параметрами ``photos``, + ``photoIds`` и ссылки без ID фотографии. В последнем случае token берется + из единственной записи ответа загрузки; пустой или неоднозначный ответ + вызывает ``UploadError``. +* ``ReactionUpdateEvent`` принимает числовой ``message_id`` и разбирает + счетчики из вложенного ``reactionInfo``. Поле ``your_reaction`` сохраняет + собственную реакцию пользователя. Уведомления об изменении собственной + реакции также направляются в ``on_reaction_update()``. +* ``on_raw`` вызывается и при ошибках распознавания, валидации или обработки + типизированного события. Исходный frame остается доступен для диагностики. +* Markdown-форматтер сохраняет одиночные подчёркивания между буквами и + цифрами: ссылки и идентификаторы вроде ``snake_case_name`` больше не теряют + символы. Внутри inline-кода и блоков кода разметка, ссылки, заголовки и + цитаты передаются буквально. +* ``CommentsInfoUpdate`` допускает ``comments_info=None`` в ответах Max. +* QR-авторизация учитывает ``ExtraConfig.password_max_attempts`` при проверке + пароля 2FA. Пустой пароль, ошибка проверки и ответ без token учитываются + в лимите; при его исчерпании вызывается ``PasswordAttemptsExceededError``. +* Ошибки подготовки конфигурации до создания runtime сохраняют исходный тип + и больше не заменяются ошибкой ``Client runtime is not initialized``. + При ошибках запуска закрываются соединение и фоновые задачи клиента. + +Breaking changes и migration notes +------------------------------------ + +* Обычные функции и lambda больше не принимаются как фильтры роутера. + Используйте готовые фильтры или наследуйтесь от ``Filter``. Метод + ``__call__`` получает два аргумента — событие и клиента — и возвращает + ``bool`` либо awaitable с результатом ``bool``. Например, прежнюю проверку + команды можно заменить на ``@router.on_message(Command("start"))``: + + .. code-block:: python + + from pymax import Client, Message + from pymax.filters import Filter + + client = Client(phone="+79990000000") + + + class HasText(Filter[Message, Client]): + def __call__(self, message: Message, client: Client) -> bool: + return bool(message.text) + + + @client.on_message(HasText()) + async def handle(message: Message, client: Client) -> None: + await message.answer("Текст получен") + +* Если несколько обработчиков одного роутера должны были срабатывать на + одно событие, пересмотрите их регистрацию с учетом первого совпадения. + Общие обработчики без фильтров размещайте после более конкретных. +* ``read_message()`` теперь принимает ``message_id`` как ``int`` для + ``Client`` и ``WebClient``. Разделять тип ID по транспорту больше не нужно. + ``ReactionUpdateEvent.message_id`` также имеет тип ``int``; учитывайте это + в сравнениях и при передаче ID в собственное хранилище. +* ``InlineKeyboardAttachment.keyboard`` теперь объект ``InlineKeyboard``. + Замените обращения вида ``attach.keyboard["buttons"]`` на + ``attach.keyboard.buttons`` и обходите сначала строки, затем кнопки. + Поля кнопок также доступны через атрибуты, а не ключи словаря. +* ``Message.answer()`` и ``Message.reply()`` с заполненным ``post_id`` + отправляют комментарий в соответствующую ветку. Ненулевой ``send_at`` + в этом случае вызывает ``ValueError``: планирование комментариев + не поддерживается. diff --git a/docs/router.rst b/docs/router.rst index 40eb45b..1ed5f0f 100644 --- a/docs/router.rst +++ b/docs/router.rst @@ -28,15 +28,12 @@ Router .. code-block:: python from pymax import Client, ClientRouter, Message + from pymax.filters import Command router = ClientRouter() - def is_start(message: Message) -> bool: - return message.text == "/start" - - - @router.on_message(is_start) + @router.on_message(Command("start")) async def start_command(message: Message, client: Client) -> None: await message.answer("Готово") @@ -100,33 +97,102 @@ Root router Router, подключенный к другому router через ``router.include_router(child)``. Dispatch проходит по root router, затем по подключенным роутерам и их детям. +В каждом роутере обработчики одного типа события проверяются в порядке +регистрации. После первого подходящего обработчика остальные обработчики +этого типа в том же роутере пропускаются. Затем событие передается дочерним +роутерам: обработчик в родительском роутере не останавливает их обход. +Обработчик без фильтров подходит всегда, поэтому общий fallback регистрируйте +после более конкретных обработчиков. + Фильтры ------- -Фильтр - это функция, которая получает событие и возвращает ``True`` или -``False``. Фильтры могут быть async. +Фильтры наследуются от ``pymax.filters.Filter``. Их ``__call__`` получает +``event`` и ``client`` и возвращает ``bool`` или awaitable с результатом +``bool``. Для обычных проверок доступны готовые фильтры: + +* ``Command("start")`` — команда ``/start``, в том числе с аргументами; +* ``Reply()`` и ``Forwarded()`` — ответ и пересланное сообщение; +* ``FromMe()`` — сообщение текущего пользователя; +* ``HasAttachment(PhotoAttachment)`` — наличие вложения указанного типа + из ``pymax.types``. Можно передать несколько типов. + +У ``Command`` можно задать другой префикс, например +``Command("start", prefix="!")`` или ``prefix=("/", "!")``. + +Свой фильтр: .. code-block:: python from pymax import Client, ClientRouter, Message + from pymax.filters import Filter router = ClientRouter() - def only_text(message: Message) -> bool: - return bool(message.text) - + class HasText(Filter[Message, Client]): + def __call__(self, message: Message, client: Client) -> bool: + return bool(message.text) - async def only_private(message: Message) -> bool: - return message.chat_id is not None and message.chat_id > 0 - - @router.on_message(only_text, only_private) + @router.on_message(HasText()) async def handle(message: Message, client: Client) -> None: await message.answer("Текст получил") -Все фильтры должны вернуть ``True``. Если хотя бы один фильтр вернул ``False``, -handler не вызывается. +Метод ``__call__`` также может быть ``async def``. Обычную функцию вместо +экземпляра ``Filter`` передавать не нужно. + +Несколько фильтров в декораторе работают как AND: все должны вернуть ``True``. +При первом ``False`` проверка этого обработчика прекращается. Фильтры можно +объединять операторами ``&`` (AND), ``|`` (OR) и ``~`` (NOT): + +.. code-block:: python + + from pymax.filters import Command, FromMe, Reply + + @router.on_message((Command("start") | Command("help")) & ~FromMe(), Reply()) + async def command_reply(message: Message, client: Client) -> None: + await message.answer("Команда в ответе") + +Magic-фильтры +~~~~~~~~~~~~~ + +``F`` из ``pymax.filters`` строит проверки полей ``Message`` и ``Chat``: + +.. code-block:: python + + from pymax.filters import F + + @router.on_message((F.message.sender == 123456) & F.message.text.contains("привет")) + async def greeting(message: Message, client: Client) -> None: + await message.answer("Привет") + +Сравнения при объединении берите в скобки. Используйте ``&``, ``|`` и ``~``, +а не Python-операторы ``and``, ``or`` и ``not``. + +Ссылка на поле без сравнения проверяет его истинность, например +``F.message.text`` — непустой текст. Для текстовых полей доступны +``contains()``, ``startswith()`` и ``endswith()`` с параметром +``ignore_case=True``; для числовых — сравнения и ``between(minimum, maximum)``. +``is_none()`` проверяет ``None``, ``is_empty()`` — пустой список: + +.. code-block:: python + + no_attachments = F.message.attaches.is_empty() + unknown_sender = F.message.sender.is_none() + private_chat = F.chat.type == "DIALOG" + +Фильтр проверяет и тип события: ``F.message`` применяется к ``Message``, +``F.chat`` — к ``Chat``. Например, ``F.chat.last_message.text`` проверяет +текст последнего сообщения чата. + +Dispatcher сам ожидает async-результат. При ручном вызове составного фильтра +тоже нужен ``await``: + +.. code-block:: python + + text_from_sender = (F.message.sender == 123456) & F.message.text + matched = await text_from_sender(message, client) Middleware ---------- @@ -140,21 +206,23 @@ Middleware from typing import Any from pymax import Client - from pymax.dispatch import DispatchEvent, MiddlewareNext + from pymax.dispatch import DispatchEvent, Middleware, MiddlewareNext client = Client(phone="+79990000000") - async def log_event( - client: Client, - event: DispatchEvent, - call_next: MiddlewareNext, - ) -> Any: - print(type(event).__name__) - return await call_next(event) + class LoggingMiddleware(Middleware[Client]): + async def __call__( + self, + client: Client, + event: DispatchEvent, + call_next: MiddlewareNext, + ) -> Any: + print(type(event).__name__) + return await call_next(event) - client.add_middleware(log_event) + client.add_middleware(LoggingMiddleware()) Middleware выполняются после фильтров, перед подходящим handler-ом. Первое зарегистрированное middleware входит первым, а выходит последним. Чтобы @@ -162,10 +230,15 @@ Middleware выполняются после фильтров, перед под готовности загрузок выполняются отдельно и через пользовательскую цепочку не проходят. +Middleware оборачивает каждый выбранный обработчик. Если событие подходит +обработчикам в нескольких роутерах, цепочка вызывается для каждого из них. +Если middleware не вызывает ``call_next``, оставшаяся цепочка и выбранный +обработчик не запускаются. + Почему handler принимает event и client --------------------------------------- -Handler всегда вызывается как ``handler(event, client)``. Это сделано, чтобы +Первые два аргумента handler-а всегда ``event`` и ``client``. Это сделано, чтобы один и тот же router можно было подключить к разным клиентам, а внутри handler всегда был доступ к API-методам клиента. @@ -177,6 +250,11 @@ Handler всегда вызывается как ``handler(event, client)``. Э async def on_message(message: Message, client: Client) -> None: await message.answer("ok") +Handler может быть синхронным или асинхронным. Дополнительные обязательные +параметры разрешаются по аннотации типа: встроенный ``FSMContext`` описан +в :doc:`fsm`, подключение зависимостей через Dishka — в :doc:`di`. +У ``on_start``, ``on_error`` и ``on_disconnect`` свои сигнатуры, показанные ниже. + ``on_start`` ------------ @@ -198,12 +276,13 @@ Handler всегда вызывается как ``handler(event, client)``. Э Ошибки handler-ов ----------------- -``on_error`` перехватывает ошибки из фильтров, handler-ов, ``on_start`` и login -на этапе запуска. +``on_error`` получает ошибки из фильтров, middleware, обработчиков событий +и ``on_start``. Ошибки распознавания и преобразования входящего frame-а +в типизированное событие возникают до этой границы обработки. .. code-block:: python - from pymax import ApiError, Client, ClientRouter + from pymax import Client, ClientRouter from pymax.dispatch import ErrorContext, ErrorScope client = Client(phone="+79990000000", work_dir="cache") @@ -211,8 +290,7 @@ Handler всегда вызывается как ``handler(event, client)``. Э @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() + print(ctx.event_type, ctx.router, e) router = ClientRouter() @@ -222,12 +300,17 @@ Handler всегда вызывается как ``handler(event, client)``. Э async def router_error(e: Exception, ctx: ErrorContext[Client]) -> None: print("router failed:", e) + + client.include_router(router) + ``ErrorScope.GLOBAL`` получает ошибки из всего дерева подключенных роутеров. ``ErrorScope.LOCAL`` получает только ошибки того router-а, на котором зарегистрирован error-handler. -Если error-handler успешно отработал, исходная ошибка считается обработанной. -Если упал сам error-handler, исходная ошибка продолжит распространяться. +PyMax вызывает все подходящие error-handler-ы в порядке обхода роутеров. +Если они завершились успешно, исходная ошибка считается обработанной. +Если ни одного error-handler-а нет или один из них сам упал, исходная ошибка +продолжит распространяться. Отключение ---------- @@ -244,8 +327,10 @@ Handler всегда вызывается как ``handler(event, client)``. Э Raw events ---------- -Если PyMax не смог распознать событие или вам нужны исходные данные, используйте -``on_raw``. +``on_raw`` получает исходный ``InboundFrame`` для каждого входящего frame-а, +переданного в dispatch. Он вызывается после типизированной обработки, в том +числе когда тип события неизвестен или его распознавание, преобразование либо +обработка завершились ошибкой. .. code-block:: python @@ -259,14 +344,38 @@ Raw events Другие события -------------- -Кроме новых и измененных сообщений, доступны специализированные декораторы: - -* ``on_message_delete()`` и ``on_message_read()``; -* ``on_typing()`` и ``on_presence()``; -* ``on_reaction_update()`` и ``on_chat_update()``. - -Все они поддерживают те же sync/async-фильтры и сигнатуру -``handler(event, client)``. +Декоратор определяет тип первого аргумента handler-а: + +.. list-table:: + :header-rows: 1 + :widths: 45 55 + + * - Декоратор + - Событие + * - ``on_message()``, ``on_message_edit()`` + - ``Message`` + * - ``on_message_delete()`` + - ``MessageDeleteEvent`` + * - ``on_message_read()`` + - ``MessageReadEvent`` + * - ``on_typing()`` + - ``TypingEvent`` + * - ``on_presence()`` + - ``PresenceEvent`` + * - ``on_reaction_update()`` + - ``ReactionUpdateEvent`` + * - ``on_chat_update()`` + - ``Chat`` + * - ``on_story_update()`` + - ``StoryPreview`` + * - ``on_raw()`` + - ``InboundFrame`` + +Все они принимают экземпляры ``Filter`` и используют первые два аргумента +``handler(event, client)``. ``on_reaction_update()`` получает как обновления +счетчиков реакций, так и уведомления о реакции текущего пользователя +(opcode 155 и 156). ``on_story_update()`` получает сводное превью сторис +владельца, а не отдельную ``Story``. Частые ошибки ------------- @@ -278,4 +387,5 @@ Handler принимает один аргумент Используйте ``async def handler(message: Message, client: Client) -> None: ...``. Фильтр падает с ошибкой - Handler не будет вызван, а ошибка попадет в логи dispatch. + Handler не будет вызван. Ошибка передается подходящим ``on_error``; + без них она продолжает распространяться. diff --git a/docs/stories.rst b/docs/stories.rst new file mode 100644 index 0000000..dcc8a97 --- /dev/null +++ b/docs/stories.rst @@ -0,0 +1,203 @@ +Stories +======= + +Что это +------- + +Методы сторис доступны у ``Client`` и ``WebClient``: публикация фото и видео, +лента владельцев, получение отдельных историй, отметка просмотра, реакции и +подробная статистика. Полная история представлена моделью ``Story``, а элемент +ленты и событие обновления — моделью ``StoryPreview``. + +Примеры ниже выполняются после запуска клиента, например в ``on_start()``. +Описание моделей находится на странице :doc:`types/story`. + +Опубликовать фото или видео +--------------------------- + +.. code-block:: python + + from pymax import Photo, Video + + photo_story = await client.send_story( + Photo(path="image.jpg"), + link="https://example.com/", + ) + video_story = await client.send_story( + Video(path="clip.mp4"), + duration=12_000, + ) + print(photo_story.id, video_story.id) + +``send_story()`` публикует одну историю на 48 часов и возвращает ``Story``. +``link`` необязателен: при его передаче PyMax добавляет ссылку в нижней части +кадра. Настроить срок публикации или положение ссылки через этот метод нельзя. + +Для ``Video`` обязательно передайте в ``send_story()`` отдельный аргумент +``duration`` — положительную длительность в миллисекундах. Автоматического +определения длительности для сторис нет; установка extra ``video`` этого не +меняет. Без ``duration`` или при значении ``0`` и меньше метод поднимет +``ValueError`` до загрузки видео. + +``Photo`` и ``Video`` принимают ``path``, ``url`` или ``raw``. Для байтов +нужно указать ``name``. Подробнее об источниках данных: :doc:`files`. + +Лента и получение историй +------------------------- + +``get_stories_feed()`` возвращает пару ``(previews, next_cursor)``. +По умолчанию запрашивается первая страница с ``cursor="0"`` и ``count=15``. +Каждый ``StoryPreview`` описывает владельца и количество его историй, но +не содержит ID отдельных историй. Получите их через ``get_stories()``: + +.. code-block:: python + + cursor = "0" + while True: + previews, cursor = await client.get_stories_feed(cursor=cursor, count=15) + for preview in previews: + owner = preview.owner + stories = await client.get_stories( + owner_id=owner.owner_id, + owner_type=owner.type, + ) + for story in stories: + print(owner.owner_id, story.id, story.media) + + if not cursor: + break + +Передавайте возвращенный курсор в следующий запрос. Пустая строка означает +конец ленты. ``owner_id`` — ID владельца, а ``story.id`` — ID конкретной +истории: это разные аргументы API. + +``owner_type=0`` означает пользователя и используется по умолчанию. Для +владельца из ленты передавайте ``preview.owner.type`` без изменения. + +Если ID историй уже известны, используйте ``get_stories_by_id()``. Ему также +нужны ID и тип владельца: + +.. code-block:: python + + stories = await client.get_stories(owner_id=123) + if stories: + selected = await client.get_stories_by_id( + owner_id=123, + story_ids=[stories[0].id], + owner_type=0, + ) + +Оба метода получения возвращают ``list[Story]``. Если подходящих историй нет, +список пустой. + +Отметка просмотра и реакции +--------------------------- + +Получение истории само по себе не вызывает ``read_story()``. Чтобы отправить +отметку просмотра, передайте ID истории и ее владельца: + +.. code-block:: python + + stories = await client.get_stories(owner_id=123) + if stories: + story_id = stories[0].id + await client.read_story(story_id=story_id, owner_id=123) + added = await client.add_story_reaction( + owner_id=123, + story_id=story_id, + reaction="👍", + ) + removed = await client.remove_story_reaction( + owner_id=123, + story_id=story_id, + ) + +``add_story_reaction()`` добавляет или заменяет свою реакцию. По умолчанию +``reaction_type=0`` означает эмодзи; для строкового ID реакции передайте +``reaction_type=1``. ``remove_story_reaction()`` снимает свою реакцию. +Оба метода возвращают булево значение ``success`` из ответа Max. + +Для владельца из ленты во все три метода передавайте также +``owner_type=preview.owner.type``. ``read_story()`` возвращает ``True``, если +запрос завершился без API-ошибки; отдельного подтверждения изменения состояния +на сервере метод не проверяет. + +Изменить настройки и удалить +---------------------------- + +``edit_story(story_id, settings)`` меняет настройки опубликованной истории +и возвращает обновленную ``Story``. ``settings`` — числовая битовая маска +в формате Max; именованных флагов для нее в публичном API нет. Метод не +меняет медиа или ссылку. + +Удаление принимает ID истории: + +.. code-block:: python + + await client.delete_story(story_id=photo_story.id) + +``delete_story()`` возвращает ``True``, если запрос завершился без API-ошибки. + +Подробная статистика +-------------------- + +``get_story_detailed_stats()`` возвращает пару ``(stats, next_marker)``. +Выберите фильтр из ``pymax.api.stories``: + +* ``StoryStatsFilter.VIEWS`` (``0``) — просмотры; +* ``StoryStatsFilter.REACTIONS`` (``1``) — реакции. + +Первая страница запрашивается с ``marker=0``. Возвращенный ненулевой маркер +передайте в следующий запрос; ``0`` означает конец списка: + +.. code-block:: python + + from pymax.api.stories import StoryStatsFilter + + marker = 0 + while True: + stats, marker = await client.get_story_detailed_stats( + story_id=photo_story.id, + filter=StoryStatsFilter.VIEWS, + marker=marker, + ) + for stat in stats: + print(stat.user_id, stat.model_extra) + + if marker == 0: + break + +В ``StoryDetailedStats`` типизировано только поле ``user_id``. Дополнительные +поля ответа доступны в ``model_extra`` с исходными именами Max, включая +camelCase. Например, ``reaction``, если оно пришло, сохраняется как исходный +словарь, а не отдельная типизированная модель. Аналогично счетчики просмотров +и реакций не объявлены полями ``Story``: проверяйте дополнительные данные +конкретного ответа, если они нужны. + +Обновления сторис +----------------- + +``on_story_update()`` передает в обработчик ``StoryPreview`` владельца, +а не отдельную ``Story``. Чтобы получить сами истории после обновления, +запросите их по ``preview.owner``: + +.. code-block:: python + + from pymax import Client, StoryPreview + + @client.on_story_update() + async def on_story_update(preview: StoryPreview, client: Client) -> None: + owner = preview.owner + stories = await client.get_stories( + owner_id=owner.owner_id, + owner_type=owner.type, + ) + print(owner.owner_id, [story.id for story in stories]) + +Такой же декоратор доступен у ``Router``. + +Методы клиента +-------------- + +Полные сигнатуры методов доступны в API reference для +:doc:`api/client-client` и :doc:`api/client-web`. diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index aac3a7b..5784ae8 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -54,6 +54,7 @@ Handlers * handler зарегистрирован до ``await client.start()``; * декоратор вызван со скобками; * функция принимает ``event`` и ``client``; +* собственный фильтр наследует ``Filter`` и принимает ``event`` и ``client``; * фильтры временно отключены или точно возвращают ``True``; * нужное событие видно через ``on_raw``; * в debug-логах нет ошибки валидации payload. @@ -99,9 +100,9 @@ UploadError Reconnect --------- -При reconnect PyMax создает новый runtime, но оставляет тот же root router. -Обработчики остаются зарегистрированными, а ``on_start`` вызывается заново -после успешного login. +При reconnect того же клиента сохраняются обработчики, middleware и FSM в +памяти. ``on_start`` вызывается заново после успешного login. Этот механизм +работает при ``start()``; ``connect()`` самостоятельно не переподключается. 2FA --- diff --git a/docs/types/callback_response.rst b/docs/types/callback_response.rst new file mode 100644 index 0000000..95318fc --- /dev/null +++ b/docs/types/callback_response.rst @@ -0,0 +1,9 @@ +CallbackResponse +================ + +Возвращается из ``client.send_callback()``. Пример нажатия кнопки приведен +в разделе :doc:`../messages`. + +.. autoclass:: pymax.types.CallbackResponse + :members: + :show-inheritance: diff --git a/docs/types/index.rst b/docs/types/index.rst index 5352eb7..590fc72 100644 --- a/docs/types/index.rst +++ b/docs/types/index.rst @@ -40,6 +40,12 @@ Types ``ContactInfo`` Контакт телефонной книги для ``import_contacts()``. +``Story`` и ``StoryPreview`` + Отдельная сторис с ID и сводная информация о сторис владельца в ленте. + +``CallbackResponse`` + Результат нажатия inline-кнопки через ``send_callback()``. + ``PhotoAttachment``, ``VideoAttachment``, ``FileAttachment``, ``PollAttachment`` и другие Входящие вложения в ``message.attaches``. @@ -88,6 +94,8 @@ API reference chat message + story + callback_response message_delete_event message_read_event typing_event diff --git a/docs/types/story.rst b/docs/types/story.rst new file mode 100644 index 0000000..b162a68 --- /dev/null +++ b/docs/types/story.rst @@ -0,0 +1,62 @@ +Story +===== + +``Story`` содержит отдельную историю. ``StoryPreview`` содержит сводку по +владельцу в ленте или событии ``on_story_update()``; ID отдельных историй +нужно получать через ``get_stories()``. Примеры работы: :doc:`../stories`. + +.. autoclass:: pymax.types.domain.story.Story + :members: + :show-inheritance: + +StoryMedia +---------- + +``StoryMedia`` — объединение ``StoryPhotoMedia`` и ``StoryVideoMedia``. +PyMax выбирает модель по полю ``type``, которому во входящих данных +соответствует ``_type``. Эти модели описывают полученное медиа: поля +``photoToken`` и ``token`` для их создания не обязательны. + +.. autoclass:: pymax.types.domain.story.StoryPhotoMedia + :members: + :show-inheritance: + +.. autoclass:: pymax.types.domain.story.StoryVideoMedia + :members: + :show-inheritance: + +Слои +---- + +.. autoclass:: pymax.types.domain.story.StoryLayer + :members: + :show-inheritance: + +.. autoclass:: pymax.types.domain.story.StoryCoordinates + :members: + :show-inheritance: + +.. autoclass:: pymax.types.domain.story.StoryClickableLink + :members: + :show-inheritance: + +Владелец и превью +----------------- + +.. autoclass:: pymax.types.domain.story.StoryOwner + :members: + :show-inheritance: + +.. autoclass:: pymax.types.domain.story.StoryPreview + :members: + :show-inheritance: + +Статистика +---------- + +.. autoclass:: pymax.types.domain.story.StoryDetailedStats + :members: + :show-inheritance: + +.. autoclass:: pymax.api.stories.StoryStatsFilter + :members: diff --git a/src/pymax/infra/bots.py b/src/pymax/infra/bots.py index 9ea9828..fd68b2b 100644 --- a/src/pymax/infra/bots.py +++ b/src/pymax/infra/bots.py @@ -39,4 +39,15 @@ async def send_callback( 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) diff --git a/src/pymax/infra/message.py b/src/pymax/infra/message.py index 0654221..ed53627 100644 --- a/src/pymax/infra/message.py +++ b/src/pymax/infra/message.py @@ -340,12 +340,8 @@ async def remove_reaction( 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: @@ -393,7 +389,16 @@ async def send_comment( ) -> Message: """Отправляет комментарий к посту канала. - ``reply_to`` задает ID комментария для ответа; текст поддерживает markdown. + 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, @@ -413,7 +418,12 @@ async def fetch_comments( 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, @@ -429,7 +439,11 @@ async def get_comments( post_id: int, message_ids: list[int], ) -> list[Message]: - """Возвращает конкретные комментарии поста по их ID.""" + """Возвращает конкретные комментарии поста по их ID. + + ``chat_id`` задает канал, ``post_id`` — пост, а ``message_ids`` — + ID запрашиваемых комментариев. + """ return await self._app.api.messages.get_comments( chat_id=chat_id, post_id=post_id, diff --git a/src/pymax/types/domain/attachments/keyboards/inline.py b/src/pymax/types/domain/attachments/keyboards/inline.py index 6e3c45f..9d32bce 100644 --- a/src/pymax/types/domain/attachments/keyboards/inline.py +++ b/src/pymax/types/domain/attachments/keyboards/inline.py @@ -69,6 +69,8 @@ class ClipboardButton(BaseButton): class InlineKeyboard(CamelModel): + """Inline-клавиатура со списком строк кнопок в ``buttons``.""" + buttons: list[ButtonRow] @@ -78,7 +80,9 @@ class InlineKeyboardAttachment(CamelModel): :ivar type: Тип вложения. :vartype type: Literal[AttachmentType.INLINE_KEYBOARD] :ivar keyboard: Данные inline-клавиатуры. - :vartype keyboard: dict[str, Any] + :vartype keyboard: InlineKeyboard + :ivar callback_id: ID клавиатуры для ``client.send_callback()``. + :vartype callback_id: str """ type: Literal[AttachmentType.INLINE_KEYBOARD] = Field(alias="_type") diff --git a/src/pymax/types/domain/callback.py b/src/pymax/types/domain/callback.py index d0c5d30..e796046 100644 --- a/src/pymax/types/domain/callback.py +++ b/src/pymax/types/domain/callback.py @@ -4,6 +4,13 @@ class CallbackResponse(CamelModel): + """Результат нажатия inline-кнопки бота. + + ``success`` показывает результат операции. Необязательные ``message`` и + ``chat`` содержат дополнительные данные ответа Max и поддерживают методы + действий, если ответ получен через клиент. + """ + success: bool unread: int mark: int diff --git a/src/pymax/types/domain/comment.py b/src/pymax/types/domain/comment.py index 3fefda9..195d488 100644 --- a/src/pymax/types/domain/comment.py +++ b/src/pymax/types/domain/comment.py @@ -16,8 +16,8 @@ class CommentsInfoUpdate(CamelModel): :ivar post_id: ID поста. :vartype post_id: int - :ivar comments_info: Счетчики комментариев поста. - :vartype comments_info: CommentsInfo + :ivar comments_info: Счетчики комментариев поста, если Max их прислал. + :vartype comments_info: CommentsInfo | None """ post_id: int diff --git a/src/pymax/types/events/reaction.py b/src/pymax/types/events/reaction.py index 719676b..f983ea2 100644 --- a/src/pymax/types/events/reaction.py +++ b/src/pymax/types/events/reaction.py @@ -13,8 +13,8 @@ class ReactionUpdateEvent(CamelModel): :vartype message_id: int :ivar chat_id: ID чата. :vartype chat_id: int - :ivar counters: Счетчики реакций по типам. - :vartype counters: list[ReactionCounter] + :ivar counters: Счетчики реакций по типам, если Max их прислал. + :vartype counters: list[ReactionCounter] | None :ivar total_count: Общее количество реакций. :vartype total_count: int :ivar your_reaction: Реакция текущего пользователя, если она есть. From 91c394d882f8eea83c6d9beb423a1d97a7e3a42d Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:46:28 +0300 Subject: [PATCH 28/31] chore: prepare 2.5.0 release metadata --- TODO.md | 13 +++++++------ pyproject.toml | 2 +- src/pymax/__init__.py | 2 +- uv.lock | 2 +- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/TODO.md b/TODO.md index 40202d3..63e6b5b 100644 --- a/TODO.md +++ b/TODO.md @@ -28,17 +28,18 @@ Format: # Autogenerated TODO. Please, dont touch it - [ ] src/pymax/api/chats/payloads.py:100: ENUMM!!! - [ ] src/pymax/api/chats/payloads.py:123: ENUMM!!! -- [ ] src/pymax/api/messages/payloads.py:32: enum? -- [ ] src/pymax/api/messages/service.py:94: TypeAlias +- [ ] src/pymax/api/messages/payloads.py:40: enum? +- [ ] src/pymax/api/messages/service.py:137: TypeAlias - [ ] src/pymax/api/uploads/service.py:68: ENUM!!!! -- [ ] src/pymax/api/uploads/service.py:286: Error handing (yes, with 200 status 💔) +- [ ] src/pymax/api/uploads/service.py:85: enum maybe? +- [ ] src/pymax/api/uploads/service.py:291: Error handing (yes, with 200 status 💔) - [ ] src/pymax/api/users/service.py:133: maybe also return phone mapping? -- [ ] src/pymax/base.py:226: maybe impl it better way - [ ] src/pymax/config.py:52: delete maybe -- [ ] src/pymax/dispatch/dispatcher.py:190: create iter_on_start_handlers +- [ ] src/pymax/dispatch/dispatcher.py:79: make better comparison or just remove it +- [ ] src/pymax/dispatch/dispatcher.py:204: create iter_on_start_handlers - [ ] src/pymax/protocol/tcp/payload.py:34: deprecate? idk - [ ] src/pymax/transport/websocket.py:28: origin should be configurable - [ ] src/pymax/types/domain/attachments/video.py:70: idk maybe | None = None better - [ ] src/pymax/types/domain/user.py:14: move to another file - [ ] src/pymax/types/events/message.py:49: impl it in the better way maybe -- [ ] src/pymax/versions/catalog.py:56: msg +- [ ] src/pymax/versions/catalog.py:88: msg diff --git a/pyproject.toml b/pyproject.toml index 3101069..2123f6a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "maxapi-python" -version = "2.4.1" +version = "2.5.0" description = "Python wrapper для API мессенджера Max" readme = "README.md" requires-python = ">=3.10" diff --git a/src/pymax/__init__.py b/src/pymax/__init__.py index b24c818..58d6060 100644 --- a/src/pymax/__init__.py +++ b/src/pymax/__init__.py @@ -1,4 +1,4 @@ -__version__ = "2.4.1" +__version__ = "2.5.0" from .api.self import PrivacyAccess, PrivacySettingsUpdate diff --git a/uv.lock b/uv.lock index 7d17d95..9ecaea7 100644 --- a/uv.lock +++ b/uv.lock @@ -1029,7 +1029,7 @@ wheels = [ [[package]] name = "maxapi-python" -version = "2.4.1" +version = "2.5.0" source = { editable = "." } dependencies = [ { name = "aiofiles" }, From 02f167fb043432047bfeee2480c01b33266f962d Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 20:50:44 +0300 Subject: [PATCH 29/31] test: exclude unsupported post_id magic filter selector --- tests/filters/test_magic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/filters/test_magic.py b/tests/filters/test_magic.py index 4ce59b1..c82b65a 100644 --- a/tests/filters/test_magic.py +++ b/tests/filters/test_magic.py @@ -47,7 +47,7 @@ def make_photo() -> PhotoAttachment: def test_message_container_exposes_supported_message_fields() -> None: fields = {name for name, value in vars(type(F.message)).items() if isinstance(value, property)} - assert fields == set(Message.model_fields) - {"link", "delayed_attributes"} + assert fields == set(Message.model_fields) - {"link", "delayed_attributes", "post_id"} def test_chat_container_exposes_all_chat_fields() -> None: From ee75cf9333a83e627f943834cc8dcd03a5d8f299 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 21:24:09 +0300 Subject: [PATCH 30/31] fix: preserve session store during reconnect and relogin --- src/pymax/base.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/pymax/base.py b/src/pymax/base.py index efcea89..6f28c13 100644 --- a/src/pymax/base.py +++ b/src/pymax/base.py @@ -244,7 +244,11 @@ async def start(self: ClientT) -> None: # noqa: PYI019 if self.__app is None: raise - await self.close() + if self.extra_config.reconnect: + await self._app.disconnect() + else: + await self.close() + await self._app.dispatcher.emit_disconnect( e, self.extra_config.reconnect, @@ -396,7 +400,7 @@ async def relogin(self: ClientT, drop_config_token: bool = True, start: bool = T raise RuntimeError("Cannot relogin before session is loaded") await store.delete_session(session.token) - await self.close() + await self._app.disconnect() if drop_config_token: self.extra_config.token = None From ca26c026c5f0a627c4e72a99ae292c1cd4f9a1b1 Mon Sep 17 00:00:00 2001 From: ink-developer <142109011+ink-developer@users.noreply.github.com> Date: Sun, 25 Oct 2026 21:24:18 +0300 Subject: [PATCH 31/31] fix: handle whitespace-only text in Command filter --- src/pymax/filters/presets.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/pymax/filters/presets.py b/src/pymax/filters/presets.py index dbcbacf..41569a4 100644 --- a/src/pymax/filters/presets.py +++ b/src/pymax/filters/presets.py @@ -31,9 +31,13 @@ def __call__(self, message: Message, _: BaseClient) -> bool: if not message.text: return False - for prefix in self.prefixes: - dirty_command = message.text.split(maxsplit=1)[0] + parts = message.text.split(maxsplit=1) + if not parts: + return False + dirty_command = parts[0] + + for prefix in self.prefixes: if message.text.startswith(prefix) and dirty_command[len(prefix) :] == self.command: return True