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

trueconf/dispatcher/dispatcher.py

@@ -1,63 +1,149 @@
 from __future__ import annotations
-from typing import List
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List
 from trueconf.filters.base import Event
 from trueconf.dispatcher.router import Router
 
+MiddlewareHandler = Callable[[Event, Dict[str, Any]], Awaitable[None]]
 
-class Dispatcher:
-    """
-        Central event dispatcher for processing and routing incoming events.
+if TYPE_CHECKING:
+    from trueconf.fsm.key_builder import KeyBuilder
+    from trueconf.fsm.manager import FSMManager
+    from trueconf.fsm.storage.base import BaseStorage
+    from trueconf.fsm.strategy import FSMStrategy
 
-        The `Dispatcher` aggregates one or more `Router` instances and feeds each
-        incoming event through them. The routers are traversed recursively via their
-        `subrouters` (using `_iter_all()`), and each event is passed to `_feed()` of
-        each router in order until it is handled.
 
-        Typical usage includes registering routers with handlers and then calling
-        `feed_update()` with incoming events.
+class Dispatcher(Router):
+    """Central dispatcher for routing incoming events.
 
-        Examples:
-            >>> dispatcher = Dispatcher()
-            >>> dispatcher.include_router(my_router)
+    The dispatcher is the root router of an application. It receives incoming
+    events, applies its own outer middleware chain, and then passes each event
+    to the included root routers in order. Processing stops when a router handles
+    the event, unless that router allows propagation to its child routers.
 
-        Attributes:
-            routers (List[Router]): List of root routers included in the dispatcher.
+    `Dispatcher` inherits from `Router`, so it supports the same handler,
+    middleware, and subrouter registration APIs.
 
-        """
+    Example:
+        ```python
+        dispatcher = Dispatcher()
+        dispatcher.include_router(router)
+        ```
+
+    FSM example:
+        ```python
+        from trueconf.fsm.storage.memory import MemoryStorage
+
+        storage = MemoryStorage()
+        dp = Dispatcher(storage=storage)
+        ```
+
+    Args:
+        storage: Storage backend used to create an FSM manager. Cannot be used
+            together with `fsm_manager`.
+        fsm_manager: Existing FSM manager instance. Cannot be used together
+            with `storage`.
+        key_builder: Key builder used when creating an FSM manager from
+            `storage`. Ignored when `fsm_manager` is passed.
+        strategy: FSM strategy used when creating an FSM manager from `storage`.
+            Ignored when `fsm_manager` is passed.
 
-    def __init__(self):
-        """Initializes an empty dispatcher with no routers."""
+    Attributes:
+        routers: Root routers included in the dispatcher.
+        fsm: FSM manager configured for the dispatcher, or `None` if FSM support
+            has not been enabled.
+    """
+
+    def __init__(
+        self,
+        *,
+        storage: BaseStorage | None = None,
+        fsm_manager: FSMManager | None = None,
+        key_builder: KeyBuilder | None = None,
+        strategy: FSMStrategy | None = None,
+    ):
+        super().__init__(name="dispatcher")
         self.routers: List[Router] = []
+        self.fsm: FSMManager | None = None
 
-    def include_router(self, router: Router):
-        """
-            Includes a router to be used by the dispatcher.
+        if fsm_manager is not None and storage is not None:
+            raise ValueError("Pass either fsm_manager or storage, not both")
+
+        if fsm_manager is not None:
+            self.setup_fsm(fsm_manager=fsm_manager)
+        elif storage is not None:
+            self.setup_fsm(storage=storage, key_builder=key_builder, strategy=strategy)
 
-            Args:
-                router (Router): A `Router` instance to include.
+    def setup_fsm(
+        self,
+        *,
+        fsm_manager: FSMManager | None = None,
+        storage: BaseStorage | None = None,
+        key_builder: KeyBuilder | None = None,
+        strategy: FSMStrategy | None = None,
+    ) -> FSMManager:
+        from trueconf.fsm.key_builder import DefaultKeyBuilder
+        from trueconf.fsm.manager import FSMManager
+        from trueconf.fsm.middleware import FSMMiddleware
+        from trueconf.fsm.storage.memory import MemoryStorage
+        from trueconf.fsm.strategy import FSMStrategy
+
+        if self.fsm is not None:
+            raise RuntimeError(
+                "FSM is already configured for this Dispatcher. "
+                "Call setup_fsm() only once, or create a new Dispatcher."
+            )
+
+        if fsm_manager is None:
+            fsm_manager = FSMManager(
+                storage=storage or MemoryStorage(),
+                key_builder=key_builder or DefaultKeyBuilder(),
+                strategy=strategy or FSMStrategy.USER_IN_CHAT,
+            )
+
+        self.fsm = fsm_manager
+        self._outer_middlewares.insert(0, FSMMiddleware(fsm_manager))
+        return fsm_manager
+
+    def include_router(self, router: "Router") -> None:
+        """Include a root router in the dispatcher.
+
+        The dispatcher's own middleware is applied in ``_feed_update`` before
+        the event reaches child routers. Therefore we do NOT set ``_parent`` —
+        child routers should not inherit the dispatcher's middleware through
+        the ancestor chain.
         """
         self.routers.append(router)
 
-    async def _feed_update(self, event: Event):
+    async def _feed_update(self, event: Event, data: Dict[str, Any]) -> None:
         """
-            Feeds an event to all routers and subrouters in order,
+            Feeds an event to all child routers in order,
             stopping at the first one that handles it.
 
-            Args:
-                event (Event): The event to be processed.
+            The event first passes through the dispatcher's own middleware chain
+            (outer middlewares from dispatcher ancestors → dispatcher), then is
+            fed to each child router.
 
-            Returns:
-                None
+        Args:
+            event (Event): The event to be processed.
+            data (Dict[str, Any]): Context data passed through the middleware pipeline.
         """
 
-        async def progress_router(router, count = 0):
-            handled = await router._feed(event)
-            if count < 0 or count >= len(router._subrouters):
-                return
-            if (not handled) or (handled and router.allow_child_on_event):
-                subrouter = router._subrouters[count]
-                return await progress_router(subrouter, count=len(router._subrouters) - 1)
-            return
-
-        for router in self.routers:
-            await progress_router(router)
+        async def _feed_children(evt: Event, ctx: Dict[str, Any]) -> None:
+            async def progress_router(router: Router, count: int = 0) -> None:
+                handled = await router._feed(evt, ctx)
+                if count < 0 or count >= len(router._subrouters):
+                    return
+                if (not handled) or (handled and router.allow_child_on_event):
+                    subrouter = router._subrouters[count]
+                    await progress_router(subrouter, count=len(router._subrouters) - 1)
+
+            for router in self.routers:
+                await progress_router(router)
+
+        # Build outer middleware chain: dispatcher outer_mw → feed_children
+        chain: MiddlewareHandler = _feed_children
+        for mw in reversed(self._collect_middlewares("_outer_middlewares")):
+            nxt = chain
+            chain = Router._wrap_middleware(mw, nxt)
+
+        await chain(event, data)

trueconf/dispatcher/router.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 import asyncio
 import logging
 import inspect
-from typing import Callable, Awaitable, List, Tuple, Any, Union
+from typing import TYPE_CHECKING, Callable, Awaitable, Dict, List, Tuple, Any, Union
 from magic_filter import MagicFilter
 from trueconf.filters.base import Event
 from trueconf.filters.base import Filter
@@ -25,6 +25,9 @@ from trueconf.types.requests.removed_chat_participant import RemovedChatParticip
 from trueconf.types.requests.removed_message import RemovedMessage
 from trueconf.types.requests.uploading_progress import UploadingProgress
 
+if TYPE_CHECKING:
+    from trueconf.middleware import BaseMiddleware
+
 logger = logging.getLogger("chat_bot")
 
 Handler = Callable[..., Awaitable[None]]
@@ -62,12 +65,19 @@ class Router:
         If you have multiple routers, use `.include_router()` to add them to a parent router.
         """
 
-    def __init__(self, name: str | None = None, allow_child_on_event: bool = False):
-
+    def __init__(
+        self,
+        name: str | None = None,
+        allow_child_on_event: bool = False,
+        _parent: "Router | None" = None,
+    ):
         self.name = name or hex(id(self))
         self.allow_child_on_event = allow_child_on_event
+        self._parent: Router | None = _parent
         self._handlers: List[Tuple[Tuple[FilterLike, ...], Handler]] = []
         self._subrouters: List["Router"] = []
+        self._outer_middlewares: List["BaseMiddleware"] = []
+        self._inner_middlewares: List["BaseMiddleware"] = []
 
     def _iter_all(self) -> List["Router"]:
         """Return a list of this router and all nested subrouters recursively."""
@@ -76,8 +86,42 @@ class Router:
             out.extend(child._iter_all())
         return out
 
+    def _ancestors_with_self(self) -> List["Router"]:
+        """Return routers from root ancestor down to self."""
+        chain: list[Router] = []
+        current: Router | None = self
+        while current is not None:
+            chain.append(current)
+            current = current._parent
+        chain.reverse()
+        return chain
+
+    def _collect_middlewares(
+        self, attr: str
+    ) -> List["BaseMiddleware"]:
+        """Collect middlewares from ancestors → self."""
+        result: list[BaseMiddleware] = []
+        for router in self._ancestors_with_self():
+            result.extend(getattr(router, attr, []))
+        return result
+
+    def outer_middleware(self, middleware: "BaseMiddleware") -> None:
+        """Register outer middleware (runs before filter/handler matching)."""
+        self._outer_middlewares.append(middleware)
+
+    def inner_middleware(self, middleware: "BaseMiddleware") -> None:
+        """Register inner middleware (runs after filter match, before handler)."""
+        self._inner_middlewares.append(middleware)
+
     def _register(self, filters: Tuple[FilterLike, ...]):
         """Internal decorator for registering handlers with filters."""
+        # Sugar: State instances are auto-wrapped with StateFilter
+        from trueconf.fsm.filters import StateFilter
+        from trueconf.fsm.state import State
+        filters = tuple(
+            StateFilter(f) if isinstance(f, State) else f
+            for f in filters
+        )
 
         def decorator(func: Handler):
             async def async_wrapper(evt: Event, **kwargs: Any):
@@ -91,41 +135,96 @@ class Router:
 
         return decorator
 
-    async def _feed(self, event: Event) -> bool:
-        """Feed an incoming event to the router and invoke the first matching handler."""
-        logger.info(f"📥 Incoming event: {event}")
-        for flts, handler in self._handlers:
+    async def _feed(self, event: Event, data: Dict[str, Any]) -> bool:
+        """Feed an incoming event to the router and invoke the first matching handler.
 
-            if not flts:
-                self._spawn(handler, event, "<none>")
-                return True
+        Pipeline:
+            outer_middleware → filter match → inner_middleware → handler
 
-            matched = True
-            for f in flts:
-                try:
-                    if not await self._apply_filter(f, event):
-                        matched = False
-                        break
-                except Exception as e:
-                    logger.exception(f"Filter {type(f).__name__} error: {e}")
-                    matched = False
-                    break
+        Returns:
+            True  — event was handled or blocked by outer middleware.
+            False — no handler matched and outer middleware did not block;
+                    the dispatcher may try the next router.
+        """
+        logger.info("📥 Incoming event: %s", event)
 
-            if matched:
-                filters_str = ", ".join(
-                    getattr(f, "__name__", type(f).__name__) if callable(f) else type(f).__name__
-                    for f in flts
-                )
+        outer_passed = False
+        handler_found = False
 
+        async def _core(evt: Event, ctx: Dict[str, Any]) -> None:
+            nonlocal outer_passed, handler_found
+            outer_passed = True
+
+            # --- filter search ---
+            for flts, handler in self._handlers:
+                if not flts:
+                    handler_found = True
+                    self._spawn(handler, evt, "<none>")
+                    return
+
+                matched = True
                 kwargs: dict[str, Any] = {}
                 for f in flts:
-                    result = await self._apply_filter(f, event)
+                    try:
+                        result = await self._apply_filter(f, evt, ctx)
+                    except Exception as e:
+                        logger.exception("Filter %s error: %s", type(f).__name__, e)
+                        matched = False
+                        break
+
+                    if not result:
+                        matched = False
+                        break
+
                     if isinstance(result, dict):
                         kwargs.update(result)
 
-                self._spawn(handler, event, filters_str, **kwargs)
-                return True
-        return False
+                if matched:
+                    handler_found = True
+                    filters_str = ", ".join(
+                        getattr(f, "__name__", type(f).__name__) if callable(f) else type(f).__name__
+                        for f in flts
+                    )
+
+                    # Merge data dict (bot, state, etc.) with filter-returned kwargs
+                    all_kwargs: dict[str, Any] = {**ctx, **kwargs}
+
+                    # --- build inner chain: inner_mw → handler ---
+                    async def _inner_base(ievt: Event, ictx: Dict[str, Any]) -> None:
+                        self._spawn(handler, ievt, filters_str, **all_kwargs)
+
+                    inner_chain: Callable[[Event, Dict[str, Any]], Awaitable[None]] = _inner_base
+                    for mw in reversed(self._collect_middlewares("_inner_middlewares")):
+                        nxt = inner_chain
+                        inner_chain = self._wrap_middleware(mw, nxt)
+
+                    await inner_chain(evt, ctx)
+                    return
+
+        # --- wrap with outer middlewares ---
+        chain: Callable[[Event, Dict[str, Any]], Awaitable[None]] = _core
+        for mw in reversed(self._collect_middlewares("_outer_middlewares")):
+            nxt = chain
+            chain = self._wrap_middleware(mw, nxt)
+
+        await chain(event, data)
+
+        if not outer_passed:
+            # Outer middleware blocked — event consumed
+            return True
+        if not handler_found:
+            # No handler matched — try next router
+            return False
+        return True
+
+    @staticmethod
+    def _wrap_middleware(
+        mw: "BaseMiddleware",
+        nxt: Callable[[Event, Dict[str, Any]], Awaitable[None]],
+    ) -> Callable[[Event, Dict[str, Any]], Awaitable[None]]:
+        async def wrapped(evt: Event, ctx: Dict[str, Any]) -> None:
+            await mw(nxt, evt, ctx)
+        return wrapped
 
     def _spawn(self, handler: Handler, event: Event, filters_str: str, **kwargs: dict[str, Any]):
         """Internal method to spawn a task for executing the matched handler."""
@@ -140,24 +239,42 @@ class Router:
 
         asyncio.create_task(_run())
 
-    async def _apply_filter(self, f: Filter | Any, event: Event) -> bool:
-        """Evaluate a filter (sync or async) against the event."""
+    async def _apply_filter(self, f: Filter | Any, event: Event, data: dict[str, Any] | None = None) -> bool:
+        """Evaluate a filter against the event, passing matching kwargs from data."""
+        data = data or {}
+
         if isinstance(f, MagicFilter):
             try:
                 return bool(f.resolve(event))
             except Exception:
                 return False
 
+        # Resolve which kwargs from data the filter accepts
+        kwargs: dict[str, Any] = {}
+        has_var_kwargs = False
         try:
-            res = f(event)
-        except Exception:
-            return False
+            sig = inspect.signature(f)
+            for name, param in sig.parameters.items():
+                if param.kind == inspect.Parameter.VAR_KEYWORD:
+                    has_var_kwargs = True
+                    continue
+                if name in data and param.kind in (
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    inspect.Parameter.KEYWORD_ONLY,
+                ):
+                    kwargs[name] = data[name]
+        except (ValueError, TypeError):
+            pass
+
+        # If filter accepts **kwargs, pass all remaining data
+        if has_var_kwargs:
+            kwargs.update({k: v for k, v in data.items() if k not in kwargs})
+
+        # Regular filters: let exceptions propagate (config errors must be explicit)
+        res = f(event, **kwargs) if kwargs else f(event)
 
         if inspect.isawaitable(res):
-            try:
-                res = await res
-            except Exception:
-                return False
+            res = await res
 
         if isinstance(res, (bool, dict)):
             return res
@@ -165,6 +282,7 @@ class Router:
 
     def include_router(self, router: "Router") -> None:
         """Include a child router for hierarchical event routing."""
+        router._parent = self
         self._subrouters.append(router)
 
     def event(self, method: str, *filters: FilterLike):

trueconf/exceptions.py

@@ -1,19 +1,41 @@
-
-
-
 class TrueConfChatBotError(Exception):
     """
     Base exception for all TrueConf ChatBot Connector errors.
+
+    All custom exceptions raised by the library inherit from this class.
+    You can catch this exception to handle any library-specific error in a
+    single place.
     """
 
 class TokenValidationError(TrueConfChatBotError):
+    """
+    Raised when the bot token fails local validation.
+
+    This error indicates that the token value has an invalid format or
+    cannot be used by the connector before the authorization request is sent.
+    """
     pass
 
 class InvalidGrantError(TrueConfChatBotError):
+    """
+    Raised when the server rejects the provided authorization grant.
+
+    This usually means that the token or credentials are invalid, expired,
+    revoked, or cannot be used to authorize the bot.
+    """
     pass
 
 class LimitExceededError(TrueConfChatBotError):
-    """Base exception for all limit-related errors (length, size, etc.)."""
+    """
+    Base exception for all limit-related errors.
+
+    This class is used for errors related to text length, title length,
+    file size, and other numeric limits.
+
+    Attributes:
+        actual_value: Actual value that exceeded the limit.
+        limit: Maximum allowed value.
+    """
     def __init__(self, message: str, actual_value: int, limit: int):
         super().__init__(message)
         self.actual_value = actual_value
@@ -21,7 +43,17 @@ class LimitExceededError(TrueConfChatBotError):
 
 
 class TextMessageTooLongError(LimitExceededError):
-    """Raised when the message text exceeds TrueConf's allowed length."""
+    """
+    Raised when a text message exceeds the maximum allowed length.
+
+    The default text message limit is 4096 visible characters. For long texts,
+    such as LLM-generated responses, use `safe_split_text` from `trueconf.utils`
+    and send the returned chunks one by one.
+
+    Attributes:
+        actual_value: Actual visible length of the message text.
+        limit: Maximum allowed message length.
+    """
     def __init__(self, actual_length: int, limit: int = 4096):
         message = (
             f"Bad Request: text message is too long. "
@@ -31,7 +63,17 @@ class TextMessageTooLongError(LimitExceededError):
         super().__init__(message, actual_length, limit)
 
 class FileCaptionTooLongError(LimitExceededError):
-    """Raised when the caption exceeds TrueConf's allowed length."""
+    """
+    Raised when a file caption exceeds the maximum allowed length.
+
+    The default caption limit is 4096 visible characters. For long captions,
+    use `safe_split_text` from `trueconf.utils` and send the returned chunks
+    separately when appropriate.
+
+    Attributes:
+        actual_value: Actual visible length of the caption.
+        limit: Maximum allowed caption length.
+    """
     def __init__(self, actual_length: int, limit: int = 4096):
         message = (
             f"Bad Request: caption is too long. "
@@ -41,11 +83,22 @@ class FileCaptionTooLongError(LimitExceededError):
         super().__init__(message, actual_length, limit)
 
 class ChatTitleTooLongError(LimitExceededError):
-    """Base error for long chat titles."""
+    """
+    Base exception for chat title length errors.
+
+    This class is inherited by more specific exceptions for group and channel
+    title length validation.
+    """
     pass
 
 class GroupTitleTooLongError(ChatTitleTooLongError):
-    """Raised when the group title exceeds allowed length."""
+    """
+    Raised when a group title exceeds the maximum allowed length.
+
+    Attributes:
+        actual_value: Actual length of the group title.
+        limit: Maximum allowed group title length.
+    """
     def __init__(self, actual_length: int, limit: int = 256):
         message = (
             f"Bad Request: group title is too long. "
@@ -54,7 +107,13 @@ class GroupTitleTooLongError(ChatTitleTooLongError):
         super().__init__(message, actual_length, limit)
 
 class ChannelTitleTooLongError(ChatTitleTooLongError):
-    """Raised when the channel title exceeds allowed length."""
+    """
+    Raised when a channel title exceeds the maximum allowed length.
+
+    Attributes:
+        actual_value: Actual length of the channel title.
+        limit: Maximum allowed channel title length.
+    """
     def __init__(self, actual_length: int, limit: int = 256):
         message = (
             f"Bad Request: channel title is too long. "
@@ -63,10 +122,25 @@ class ChannelTitleTooLongError(ChatTitleTooLongError):
         super().__init__(message, actual_length, limit)
 
 class FileValidationError(TrueConfChatBotError):
-    """Общий класс для всех ошибок валидации файлов."""
+    """
+    Base exception for file validation errors.
+
+    This class is used for errors related to file size limits, extension filters,
+    and other file validation rules received from TrueConf Server.
+    """
     pass
 
 class FileSizeTooLargeError(FileValidationError, LimitExceededError):
+    """
+    Raised when a file exceeds the maximum size allowed by the server.
+
+    File size limits are configured by the TrueConf Server administrator and
+    are checked by the bot before sending a file.
+
+    Attributes:
+        actual_value: Actual file size in bytes.
+        limit: Maximum allowed file size in bytes.
+    """
     def __init__(self, actual_size: int, limit: int):
         actual_mb = round(actual_size / (1024 * 1024), 2)
         limit_mb = round(limit / (1024 * 1024), 2)
@@ -78,6 +152,18 @@ class FileSizeTooLargeError(FileValidationError, LimitExceededError):
 
 
 class InvalidFileExtensionError(FileValidationError):
+    """
+    Raised when a file extension does not satisfy the server extension filter.
+
+    File extension rules are configured by the TrueConf Server administrator.
+    Depending on the filter mode, the extension list can work either as an
+    allow list or as a block list.
+
+    Attributes:
+        extension: File extension that failed validation.
+        extensions: Set of extensions used for validation.
+        mode: Extension filter mode.
+    """
     def __init__(self, extension: str, extensions: set[str] | None = None, mode: str = "allow"):
         self.extension = extension
         self.extensions = extensions or set()
@@ -106,6 +192,17 @@ class InvalidFileExtensionError(FileValidationError):
         super().__init__(message)
 
 class ApiErrorException(TrueConfChatBotError):
+    """
+    Raised when TrueConf Server returns an API error response.
+
+    This exception stores the server error code, human-readable detail, and
+    optional response payload for additional context.
+
+    Attributes:
+        code: Error code returned by the server.
+        detail: Human-readable error description.
+        payload: Raw error payload returned by the server, or an empty dict.
+    """
     def __init__(self, code: int, detail: str, payload: dict | None = None):
         super().__init__(f"[{code}] {detail}")
         self.code = code

trueconf/fsm/__init__.py

@@ -0,0 +1,20 @@
+from trueconf.fsm.context import FSMContext
+from trueconf.fsm.filters import StateFilter
+from trueconf.fsm.key_builder import DefaultKeyBuilder, KeyBuilder, StorageKey
+from trueconf.fsm.manager import FSMManager
+from trueconf.fsm.state import State, StatesGroup, any_state, default_state
+from trueconf.fsm.strategy import FSMStrategy
+
+__all__ = (
+    "FSMContext",
+    "FSMManager",
+    "FSMStrategy",
+    "State",
+    "StateFilter",
+    "StatesGroup",
+    "StorageKey",
+    "KeyBuilder",
+    "DefaultKeyBuilder",
+    "any_state",
+    "default_state",
+)