python-trueconf-bot 1.2.3.dev1__py3-none-any.whl → 1.4.0__py3-none-any.whl

trueconf/fsm/context.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, overload
+
+from trueconf.fsm.key_builder import StorageKey
+from trueconf.fsm.state import State
+from trueconf.fsm.storage.base import BaseStorage
+
+
+class FSMContext:
+    def __init__(self, storage: BaseStorage, key: StorageKey) -> None:
+        self._storage = storage
+        self._key = key
+
+    @property
+    def key(self) -> StorageKey:
+        return self._key
+
+    @property
+    def storage(self) -> BaseStorage:
+        return self._storage
+
+    async def get_state(self) -> str | None:
+        return await self._storage.get_state(self._key)
+
+    async def set_state(self, state: State | str | None) -> None:
+        value = str(state) if isinstance(state, State) else state
+        await self._storage.set_state(self._key, value)
+
+    async def get_data(self) -> dict[str, Any]:
+        return await self._storage.get_data(self._key)
+
+    async def set_data(self, data: Mapping[str, Any]) -> None:
+        await self._storage.set_data(self._key, dict(data))
+
+    @overload
+    async def get_value(self, key: str) -> Any | None: ...
+
+    @overload
+    async def get_value(self, key: str, default: Any) -> Any: ...
+
+    async def get_value(self, key: str, default: Any | None = None) -> Any | None:
+        return await self._storage.get_value(self._key, key, default)
+
+    async def update_data(
+        self,
+        data: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        if data:
+            kwargs.update(data)
+        return await self._storage.update_data(self._key, kwargs)
+
+    async def clear(self) -> None:
+        await self.set_state(None)
+        await self.set_data({})

trueconf/fsm/filters.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from trueconf.fsm.context import FSMContext
+from trueconf.fsm.state import State
+
+
+class StateFilter:
+    def __init__(self, *states: State | str | None) -> None:
+        self._states: set[str | None] = {
+            str(s) if isinstance(s, State) else s for s in states
+        }
+        self._wildcard = "*" in self._states
+
+    async def __call__(
+        self,
+        event: Any,
+        *,
+        state: FSMContext | None = None,
+    ) -> bool:
+        if state is None:
+            raise RuntimeError(
+                "StateFilter requires FSMContext in data['state'], but it was not found. "
+                "Make sure FSMMiddleware is registered as outer middleware "
+                "before any StateFilter is evaluated."
+            )
+        if self._wildcard:
+            return True
+        current = await state.get_state()
+        return current in self._states

trueconf/fsm/key_builder.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class StorageKey:
+    bot_id: str | None
+    chat_id: str
+    user_id: str
+    destiny: str = "default"
+
+
+@runtime_checkable
+class KeyBuilder(Protocol):
+    def build(self, bot: Any, event: Any) -> StorageKey: ...
+
+
+class DefaultKeyBuilder:
+    def build(self, bot: Any, event: Any) -> StorageKey:
+        bot_id = getattr(bot, "me_id", None) or getattr(bot, "id", None)
+
+        chat_id = (
+            getattr(event, "chat_id", None)
+            or getattr(getattr(event, "chat", None), "id", None)
+        )
+
+        user = getattr(event, "from_user", None) or getattr(event, "author", None)
+        user_id = getattr(user, "id", None) if user else None
+
+        if chat_id is None or user_id is None:
+            raise RuntimeError(
+                f"Cannot build FSM StorageKey: event of type {type(event).__name__} "
+                f"has no chat_id ({chat_id}) or user_id ({user_id}). "
+                f"Provide a custom KeyBuilder to Dispatcher.setup_fsm()."
+            )
+
+        return StorageKey(bot_id=bot_id, chat_id=str(chat_id), user_id=str(user_id))

trueconf/fsm/manager.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from trueconf.fsm.context import FSMContext
+from trueconf.fsm.key_builder import DefaultKeyBuilder, KeyBuilder, StorageKey
+from trueconf.fsm.storage.base import BaseStorage
+from trueconf.fsm.storage.memory import MemoryStorage
+from trueconf.fsm.strategy import FSMStrategy, apply_strategy
+
+
+class FSMManager:
+    def __init__(
+        self,
+        storage: BaseStorage | None = None,
+        key_builder: KeyBuilder | None = None,
+        strategy: FSMStrategy = FSMStrategy.USER_IN_CHAT,
+    ) -> None:
+        self.storage: BaseStorage = storage or MemoryStorage()
+        self.key_builder: KeyBuilder = key_builder or DefaultKeyBuilder()
+        self.strategy = strategy
+
+    def get_context(self, bot: Any, event: Any) -> FSMContext:
+        key = self.key_builder.build(bot, event)
+        chat_id, user_id = apply_strategy(
+            self.strategy,
+            key.chat_id,
+            key.user_id,
+        )
+        adjusted_key = StorageKey(
+            bot_id=key.bot_id,
+            chat_id=chat_id,
+            user_id=user_id,
+            destiny=key.destiny,
+        )
+        return FSMContext(self.storage, adjusted_key)

trueconf/fsm/middleware.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+from trueconf.fsm.manager import FSMManager
+from trueconf.middleware import BaseMiddleware
+
+
+class FSMMiddleware(BaseMiddleware):
+    def __init__(self, fsm_manager: FSMManager) -> None:
+        self._manager = fsm_manager
+
+    async def __call__(
+        self,
+        handler: Any,
+        event: Any,
+        data: dict[str, Any],
+    ) -> None:
+        bot = data.get("bot")
+        if bot is not None:
+            context = self._manager.get_context(bot, event)
+            data["state"] = context
+            data["raw_state"] = await context.get_state()
+        return await handler(event, data)

trueconf/fsm/state.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+
+class State:
+    def __init__(self, state: str | None = None) -> None:
+        self._custom_state = state
+        self._name: str | None = None
+        self._group: type[StatesGroup] | None = None
+
+    def bind(self, group: type[StatesGroup], name: str) -> None:
+        if self._group is not None or self._name is not None:
+            raise RuntimeError(
+                f"State '{self._name}' is already bound to {self._group}. "
+                f"Cannot rebind to {group.__name__}:{name}."
+            )
+        self._group = group
+        self._name = name
+
+    def __str__(self) -> str:
+        if self._custom_state is not None:
+            return self._custom_state
+        if self._group is None or self._name is None:
+            raise RuntimeError(
+                "State is not bound to a StatesGroup. "
+                "Use State inside a StatesGroup class definition, "
+                "or pass a custom string: State('my:state')."
+            )
+        return f"{self._group.__full_group_name__}:{self._name}"
+
+    def __repr__(self) -> str:
+        return f"State({str(self)!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, State):
+            return str(self) == str(other)
+        if isinstance(other, str):
+            return str(self) == other
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(str(self))
+
+
+class _StatesGroupMeta(type):
+    __parent__: type[StatesGroup] | None
+    __childs__: tuple[type[StatesGroup], ...]
+    __states__: tuple[State, ...]
+    __all_states__: tuple[State, ...]
+    __all_childs__: tuple[type[StatesGroup], ...]
+
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+    ) -> _StatesGroupMeta:
+        cls = super().__new__(mcs, name, bases, namespace)
+
+        states: list[State] = []
+        childs: list[type[StatesGroup]] = []
+
+        for key, value in namespace.items():
+            if isinstance(value, State):
+                value.bind(cls, key)
+                states.append(value)
+            elif (
+                inspect.isclass(value)
+                and issubclass(value, StatesGroup)
+                and value is not StatesGroup
+            ):
+                child = cls._prepare_child(value)
+                childs.append(child)
+
+        cls.__parent__ = None  # type: ignore[attr-defined]
+        cls.__childs__ = tuple(childs)  # type: ignore[attr-defined]
+        cls.__states__ = tuple(states)  # type: ignore[attr-defined]
+        cls.__all_childs__ = cls._get_all_childs()  # type: ignore[attr-defined]
+        cls.__all_states__ = cls._get_all_states()  # type: ignore[attr-defined]
+
+        return cls
+
+    @property
+    def __full_group_name__(cls) -> str:  # type: ignore[override]
+        if cls.__parent__ is not None:
+            return f"{cls.__parent__.__full_group_name__}.{cls.__name__}"
+        return cls.__name__
+
+    def _prepare_child(cls, child: type[StatesGroup]) -> type[StatesGroup]:
+        child.__parent__ = cls  # type: ignore[assignment]
+        return child
+
+    def _get_all_childs(cls) -> tuple[type[StatesGroup], ...]:
+        result: list[type[StatesGroup]] = list(cls.__childs__)
+        for child in cls.__childs__:
+            result.extend(child.__childs__)
+        return tuple(result)
+
+    def _get_all_states(cls) -> tuple[State, ...]:
+        result: list[State] = list(cls.__states__)
+        for child in cls.__childs__:
+            result.extend(child.__all_states__)
+        return tuple(result)
+
+    def __contains__(cls, item: Any) -> bool:
+        if isinstance(item, str):
+            return item in tuple(str(s) for s in cls.__all_states__)
+        if isinstance(item, State):
+            return item in cls.__all_states__
+        if isinstance(item, _StatesGroupMeta):
+            return item in cls.__all_childs__
+        return False
+
+    def __iter__(cls) -> Any:
+        return iter(cls.__all_states__)
+
+
+class StatesGroup(metaclass=_StatesGroupMeta):
+    __parent__: type[StatesGroup] | None = None
+    __childs__: tuple[type[StatesGroup], ...] = ()
+    __states__: tuple[State, ...] = ()
+    __all_states__: tuple[State, ...] = ()
+    __all_childs__: tuple[type[StatesGroup], ...] = ()
+
+    @classmethod
+    def get_root(cls) -> type[StatesGroup]:
+        if cls.__parent__ is None:
+            return cls
+        return cls.__parent__.get_root()
+
+
+any_state = State(state="*")
+default_state = State()

trueconf/fsm/storage/__init__.py

@@ -0,0 +1,4 @@
+from trueconf.fsm.storage.base import BaseStorage
+from trueconf.fsm.storage.memory import MemoryStorage
+
+__all__ = ("BaseStorage", "MemoryStorage")

trueconf/fsm/storage/base.py

@@ -0,0 +1,36 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from trueconf.fsm.key_builder import StorageKey
+
+
+class BaseStorage(ABC):
+    @abstractmethod
+    async def get_state(self, key: StorageKey) -> str | None: ...
+
+    @abstractmethod
+    async def set_state(self, key: StorageKey, state: str | None) -> None: ...
+
+    @abstractmethod
+    async def get_data(self, key: StorageKey) -> dict[str, Any]: ...
+
+    @abstractmethod
+    async def set_data(self, key: StorageKey, data: dict[str, Any]) -> None: ...
+
+    @abstractmethod
+    async def update_data(self, key: StorageKey, updates: dict[str, Any]) -> dict[str, Any]: ...
+
+    @abstractmethod
+    async def clear(self, key: StorageKey) -> None: ...
+
+    async def get_value(
+        self,
+        key: StorageKey,
+        dict_key: str,
+        default: Any | None = None,
+    ) -> Any | None:
+        data = await self.get_data(key)
+        return data.get(dict_key, default)
+
+    async def close(self) -> None:
+        pass

trueconf/fsm/storage/memory.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from copy import copy
+from dataclasses import dataclass, field
+from typing import Any
+
+from trueconf.fsm.key_builder import StorageKey
+from trueconf.fsm.storage.base import BaseStorage
+
+
+@dataclass
+class _Record:
+    state: str | None = None
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+class MemoryStorage(BaseStorage):
+    def __init__(self) -> None:
+        self._records: dict[StorageKey, _Record] = {}
+
+    def _get_or_create(self, key: StorageKey) -> _Record:
+        if key not in self._records:
+            self._records[key] = _Record()
+        return self._records[key]
+
+    async def get_state(self, key: StorageKey) -> str | None:
+        record = self._records.get(key)
+        return record.state if record else None
+
+    async def set_state(self, key: StorageKey, state: str | None) -> None:
+        self._get_or_create(key).state = state
+
+    async def get_data(self, key: StorageKey) -> dict[str, Any]:
+        record = self._records.get(key)
+        return record.data.copy() if record else {}
+
+    async def set_data(self, key: StorageKey, data: dict[str, Any]) -> None:
+        self._get_or_create(key).data = data.copy()
+
+    async def update_data(self, key: StorageKey, updates: dict[str, Any]) -> dict[str, Any]:
+        record = self._get_or_create(key)
+        record.data.update(updates)
+        return record.data.copy()
+
+    async def clear(self, key: StorageKey) -> None:
+        self._records.pop(key, None)
+
+    async def get_value(
+        self,
+        key: StorageKey,
+        dict_key: str,
+        default: Any | None = None,
+    ) -> Any | None:
+        record = self._records.get(key)
+        if record is None:
+            return default
+        return copy(record.data.get(dict_key, default))

trueconf/fsm/strategy.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from enum import Enum, auto
+
+
+class FSMStrategy(Enum):
+    """FSM strategy for storage key generation.
+
+    Determines how chat_id and user_id are combined to form the storage key.
+    """
+
+    USER_IN_CHAT = auto()
+    """State is stored per user per chat. Default behavior."""
+
+    CHAT = auto()
+    """State is stored per chat (all users in a chat share the same state)."""
+
+    GLOBAL_USER = auto()
+    """State is stored per user globally (across all chats)."""
+
+
+def apply_strategy(
+    strategy: FSMStrategy,
+    chat_id: str,
+    user_id: str,
+) -> tuple[str, str]:
+    """Apply FSM strategy to chat_id and user_id.
+
+    Returns (effective_chat_id, effective_user_id) for StorageKey construction.
+    """
+    if strategy == FSMStrategy.CHAT:
+        return chat_id, chat_id
+    if strategy == FSMStrategy.GLOBAL_USER:
+        return user_id, user_id
+    # USER_IN_CHAT (default)
+    return chat_id, user_id

trueconf/middleware.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+import logging
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict
+
+from trueconf.filters.base import Event
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger("chat_bot")
+
+MiddlewareHandler = Callable[[Event, Dict[str, Any]], Awaitable[None]]
+
+
+class BaseMiddleware:
+    """
+    Base middleware class for event processing pipeline.
+
+    Middleware wraps event handlers and can intercept, modify, or block events
+    before they reach the actual handler. To block an event, simply do not call
+    ``await handler(event, data)``.
+
+    Example:
+        >>> class LoggingMiddleware(BaseMiddleware):
+        ...     async def __call__(self, handler, event, data):
+        ...         logger.info(f"Event: {event}")
+        ...         await handler(event, data)
+        ...         logger.info("Done")
+
+        >>> router.outer_middleware(LoggingMiddleware())
+    """
+
+    async def __call__(
+        self,
+        handler: MiddlewareHandler,
+        event: Event,
+        data: Dict[str, Any],
+    ) -> None:
+        await handler(event, data)
+
+
+class SkipSelfMessages(BaseMiddleware):
+    """
+    Middleware that drops messages sent by the bot itself.
+
+    Prevents the bot from reacting to its own messages when multiple bot sessions
+    are running. If the event is a ``Message`` and its ``author.id`` matches
+    ``bot.me_id``, the event is silently dropped.
+
+    Registration:
+        Automatically registered when ``Bot(skip_self_messages=True)`` (default).
+        Alternatively:
+        >>> from trueconf.middleware import SkipSelfMessages
+        >>> dp.outer_middleware(SkipSelfMessages())
+    """
+
+    async def __call__(
+        self,
+        handler: MiddlewareHandler,
+        event: Event,
+        data: Dict[str, Any],
+    ) -> None:
+        bot = data.get("bot")
+        if bot is None:
+            await handler(event, data)
+            return
+
+        from trueconf.types.message import Message
+
+        if isinstance(event, Message) and event.author.id == bot.me_id:
+            logger.debug(
+                "[SkipSelfMessages] dropped message %s from bot self (author=%s)",
+                event.message_id,
+                event.author.id,
+            )
+            return
+
+        await handler(event, data)