telegrinder 1.0.0rc1__py3-none-any.whl

telegrinder/bot/dispatch/action.py

@@ -0,0 +1,99 @@
+import typing
+
+from kungfu.library import Error, Ok, Result, unwrapping
+from nodnod.error import NodeError
+
+from telegrinder.api.api import API
+from telegrinder.bot.dispatch.context import Context
+from telegrinder.bot.dispatch.handler.func import FuncHandler
+from telegrinder.bot.dispatch.process import check_rule
+from telegrinder.bot.rules.abc import ABCRule, Always, AndRule
+from telegrinder.modules import logger
+from telegrinder.node.compose import compose
+from telegrinder.tools import fullname
+from telegrinder.types.objects import Update
+
+if typing.TYPE_CHECKING:
+    from nodnod.agent.base import Agent
+
+type Handler = typing.Callable[..., typing.Any]
+type ActionFunction = typing.Callable[..., ActionFunctionResult]
+type ActionFunctionResult = typing.Union[
+    typing.AsyncGenerator[typing.Any, typing.Any],
+    typing.Awaitable[typing.Any],
+    typing.Generator[typing.Any, typing.Any, typing.Any],
+    typing.Any,
+]
+
+
+@unwrapping
+async def run_action_function[T: Handler](
+    func_handler: FuncHandler[T],
+    function: ActionFunction,
+    api: API,
+    update: Update,
+    context: Context,
+    agent: type[Agent] | None = None,
+) -> Result[typing.Any, str]:
+    async with compose(
+        function,
+        context,
+        agent_cls=agent,
+    ) as result:
+        match result:
+            case Ok():
+                return await func_handler.run(api, update, context)
+            case Error(error):
+                return Error(
+                    "{}\n".format(
+                        NodeError(f"* failed to compose action function `{fullname(function)}`", from_error=error),
+                    ),
+                )
+
+
+def action(function: ActionFunction, agent: type[Agent] | None = None) -> Action:
+    return Action(function, agent=agent)
+
+
+class Action:
+    _on: ABCRule
+
+    def __init__(self, function: ActionFunction, agent: type[Agent] | None = None) -> None:
+        self.function = function
+        self.agent = agent
+        self._on = Always()
+
+    def on(self, *rules: ABCRule) -> typing.Self:
+        self._on &= AndRule(*rules)
+        return self
+
+    def __call__[T: Handler](self, handler: T) -> T:
+        func_handler = FuncHandler(function=handler, agent=self.agent)
+
+        async def action_wrapper(api: API, update: Update, context: Context) -> typing.Any:
+            if not await check_rule(self._on, context):
+                await logger.adebug("Action rule `{!r}` failed.", self._on)
+                result = await func_handler.run(api, update, context)
+            else:
+                result = await run_action_function(
+                    func_handler,
+                    self.function,
+                    api,
+                    update,
+                    context,
+                    agent=self.agent,
+                )
+
+            match result:
+                case Ok(value):
+                    return value
+                case Error(error):
+                    await logger.adebug(error)
+                    return None
+
+        action_wrapper.__name__ = f"<action for {handler.__name__}>"
+        action_wrapper.__qualname__ = f"<action for {handler.__qualname__}>"
+        return action_wrapper  # type: ignore
+
+
+__all__ = ("Action", "action")

telegrinder/bot/dispatch/context.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import typing
+from reprlib import recursive_repr
+
+from kungfu.library.monad.option import NOTHING, Option, Some
+from nodnod.interface.node_from_function import Externals
+
+if typing.TYPE_CHECKING:
+    from nodnod.scope import Scope
+
+    from telegrinder.api.api import API
+    from telegrinder.bot.cute_types.update import UpdateCute
+    from telegrinder.bot.dispatch.router.base import Router
+    from telegrinder.types.objects import Update
+
+type Key = str
+type AnyValue = typing.Any
+
+
+class Context(Externals):
+    """Low level per event context storage."""
+
+    SELF_CONTEXT_KEYS: typing.Final = frozenset(("context", "ctx"))
+
+    api: API
+    update: Update
+    raw_update: Update
+    update_cute: UpdateCute
+    per_event_scope: Scope
+    exceptions_update: dict[Router, Exception] = {}
+    exception_update: Option[Exception] = NOTHING
+
+    @typing.overload
+    def __init__(self) -> None: ...
+
+    @typing.overload
+    def __init__(self, map: typing.Mapping[Key, AnyValue], /) -> None: ...
+
+    @typing.overload
+    def __init__(self, **kwargs: AnyValue) -> None: ...
+
+    def __init__(
+        self,
+        map: typing.Mapping[Key, AnyValue] | None = None,
+        **kwargs: AnyValue,
+    ) -> None:
+        Externals.__init__(self, map or kwargs)
+
+    @recursive_repr()
+    def __repr__(self) -> str:
+        return "{}({})".format(
+            type(self).__name__,
+            ", ".join(f"{k}={repr(v) if v is not self else '<self>'}" for k, v in self.items()),
+        )
+
+    def __setitem__(self, __key: Key, __value: AnyValue) -> None:
+        Externals.__setitem__(self, __key, __value)
+
+    def __getitem__(self, __key: Key) -> AnyValue:
+        if __key in type(self).SELF_CONTEXT_KEYS:
+            return self
+        return Externals.__getitem__(self, __key)
+
+    def __delitem__(self, __key: Key) -> None:
+        Externals.__delitem__(self, __key)
+
+    def __setattr__(self, __name: str, __value: AnyValue) -> None:
+        self.__setitem__(__name, __value)
+
+    def __getattribute__(self, __name: str) -> AnyValue:
+        if __name in type(self).SELF_CONTEXT_KEYS:
+            return self
+
+        if __name in _CONTEXT_CLASS_ATTRS and not Externals.__contains__(self, __name):
+            return super().__getattribute__(__name)
+
+        return self[__name]
+
+    def __delattr__(self, __name: str) -> None:
+        self.__delitem__(__name)
+
+    def __contains__(self, __key: object) -> bool:
+        if __key in type(self).SELF_CONTEXT_KEYS:
+            return True
+        return Externals.__contains__(self, __key)
+
+    def __or__(self, other: object, /) -> typing.Self:
+        if type(other) is not Context and not isinstance(other, dict):
+            return NotImplemented
+
+        new_context = type(self)(self)
+        new_context |= other
+        return new_context
+
+    def __ior__(self, other: object, /) -> typing.Self:
+        if type(other) is not Context and not isinstance(other, dict):
+            raise TypeError(f"Cannot update `Context` with `{type(other).__name__}`.")
+
+        for key, value in other.items():
+            self[key] = value
+
+        return self
+
+    def as_dict(self) -> dict[Key, AnyValue]:
+        return {key: value for key, value in Externals.items(self)}
+
+    def add_roots(
+        self,
+        api: API,
+        update: Update,
+        per_event_scope: Scope,
+        /,
+    ) -> typing.Self:
+        from telegrinder.bot.cute_types.update import UpdateCute
+
+        for key, value in {
+            "api": api,
+            "raw_update": update,
+            "update": update,
+            "update_cute": UpdateCute.from_update(update, bound_api=api),
+            "per_event_scope": per_event_scope,
+        }.items():
+            self[key] = value
+
+        return self
+
+    def add_exception_update(self, exception_update: Exception, /) -> typing.Self:
+        self.exception_update = Some(exception_update)
+        return self
+
+    def copy(self) -> typing.Self:
+        return type(self)(self)
+
+    def set(self, key: Key, value: AnyValue) -> None:
+        self[key] = value
+
+    @typing.overload
+    def get(self, key: Key) -> AnyValue | None: ...
+
+    @typing.overload
+    def get[T](self, key: Key, default: T) -> T | AnyValue: ...
+
+    @typing.overload
+    def get(self, key: Key, default: None = None) -> AnyValue | None: ...
+
+    def get[T](self, key: Key, default: T | None = None) -> T | AnyValue | None:
+        return dict.get(self, key, default)
+
+    def get_or_set[T](self, key: Key, default: T) -> T:
+        if key not in self:
+            self.set(key, default)
+        return self.get(key, default)
+
+    def delete(self, key: Key) -> None:
+        del self[key]
+
+
+_CONTEXT_CLASS_ATTRS = frozenset(Context.__dict__ | dict.__dict__ | object.__dict__)
+
+
+__all__ = ("Context",)

telegrinder/bot/dispatch/dispatch.py

@@ -0,0 +1,362 @@
+import typing
+from collections import deque
+from functools import cached_property
+
+from nodnod.interface.inject import inject_internals
+
+from telegrinder.api.api import API
+from telegrinder.bot.dispatch.abc import ABCDispatch
+from telegrinder.bot.dispatch.context import Context
+from telegrinder.bot.dispatch.middleware.abc import ABCMiddleware, run_post_middleware, run_pre_middleware
+from telegrinder.bot.dispatch.middleware.box import MiddlewareBox
+from telegrinder.bot.dispatch.router.base import Router
+from telegrinder.bot.dispatch.view.base import ErrorView, View
+from telegrinder.bot.dispatch.view.box import ViewBox
+from telegrinder.modules import logger
+from telegrinder.node.scope import PER_EVENT
+from telegrinder.tools.fullname import fullname
+from telegrinder.tools.global_context import TelegrinderContext
+from telegrinder.types.objects import Update
+
+if typing.TYPE_CHECKING:
+    from vbml.patcher.abc import ABCPatcher
+
+    from telegrinder.bot.dispatch.view.base import EventView, RawEventView, View
+    from telegrinder.bot.dispatch.view.media_group import MediaGroupView
+
+NANOSECONDS_PER_MILLISECOND: typing.Final = 1_000_000_000
+
+
+class ViewGetter:
+    main_router: Router
+
+    def __getattr__(self, name: str, /) -> typing.Any:
+        if name in ViewBox.__dataclass_fields__ or name in ViewBox.__dict__:
+            return getattr(self.main_router, name)
+        return super().__getattribute__(name)
+
+
+class Dispatch[
+    T: MiddlewareBox = MiddlewareBox,
+    ErrorHandler: ErrorView = ErrorView,
+    MessageView: EventView = EventView,
+    EditedMessageView: EventView = EventView,
+    ChannelPostView: EventView = EventView,
+    EditedChannelPostView: EventView = EventView,
+    BusinessConnectionView: EventView = EventView,
+    BusinessMessageView: EventView = EventView,
+    EditedBusinessMessageView: EventView = EventView,
+    DeletedBusinessMessagesView: EventView = EventView,
+    MessageReactionView: EventView = EventView,
+    MessageReactionCountView: EventView = EventView,
+    InlineQueryView: EventView = EventView,
+    ChosenInlineResultView: EventView = EventView,
+    CallbackQueryView: EventView = EventView,
+    ShippingQueryView: EventView = EventView,
+    PreCheckoutQueryView: EventView = EventView,
+    PurchasedPaidMediaView: EventView = EventView,
+    PollView: EventView = EventView,
+    PollAnswerView: EventView = EventView,
+    MyChatMemberView: EventView = EventView,
+    ChatMemberView: EventView = EventView,
+    ChatJoinRequestView: EventView = EventView,
+    ChatBoostView: EventView = EventView,
+    RemovedChatBoostView: EventView = EventView,
+    MediaGroup: View = MediaGroupView,
+    EventError: ErrorView = ErrorView,
+    RawEvent: RawEventView = RawEventView,
+](
+    ABCDispatch,
+    ViewBox[
+        MessageView,
+        EditedMessageView,
+        ChannelPostView,
+        EditedChannelPostView,
+        BusinessConnectionView,
+        BusinessMessageView,
+        EditedBusinessMessageView,
+        DeletedBusinessMessagesView,
+        MessageReactionView,
+        MessageReactionCountView,
+        InlineQueryView,
+        ChosenInlineResultView,
+        CallbackQueryView,
+        ShippingQueryView,
+        PreCheckoutQueryView,
+        PurchasedPaidMediaView,
+        PollView,
+        PollAnswerView,
+        MyChatMemberView,
+        ChatMemberView,
+        ChatJoinRequestView,
+        ChatBoostView,
+        RemovedChatBoostView,
+        MediaGroup,
+        EventError,
+        RawEvent,
+    ]
+    if typing.TYPE_CHECKING
+    else ViewGetter,
+):
+    type MainRouter = Router[
+        MessageView,
+        EditedMessageView,
+        ChannelPostView,
+        EditedChannelPostView,
+        BusinessConnectionView,
+        BusinessMessageView,
+        EditedBusinessMessageView,
+        DeletedBusinessMessagesView,
+        MessageReactionView,
+        MessageReactionCountView,
+        InlineQueryView,
+        ChosenInlineResultView,
+        CallbackQueryView,
+        ShippingQueryView,
+        PreCheckoutQueryView,
+        PurchasedPaidMediaView,
+        PollView,
+        PollAnswerView,
+        MyChatMemberView,
+        ChatMemberView,
+        ChatJoinRequestView,
+        ChatBoostView,
+        RemovedChatBoostView,
+        MediaGroup,
+        EventError,
+        RawEvent,
+    ]
+
+    main_router: MainRouter
+    error_handler: ErrorHandler
+    middlewares: T
+    _routers: deque[Router] | None = None
+
+    @typing.overload
+    def __init__(self) -> None: ...
+
+    @typing.overload
+    def __init__(self, *, router: MainRouter) -> None: ...
+
+    @typing.overload
+    def __init__(self, *, middleware_box: T) -> None: ...
+
+    @typing.overload
+    def __init__(self, *, router: MainRouter, middleware_box: T) -> None: ...
+
+    def __init__(
+        self,
+        *,
+        router: MainRouter | None = None,
+        error_handler: ErrorHandler | None = None,
+        middleware_box: MiddlewareBox | None = None,
+    ) -> None:
+        self.main_router = router or Router()  # type: ignore
+        self.error_handler = error_handler or ErrorView()  # type: ignore
+        self.global_context = TelegrinderContext()
+        self.global_scope = self.global_context.node_global_scope
+        self.loop_wrapper = self.global_context.loop_wrapper
+        self.middlewares = self.global_context.setdefault_value("middleware_box", middleware_box or MiddlewareBox())
+
+    def __setitem__(self, injection_type: typing.Any, injection_value: typing.Any, /) -> None:
+        self.global_scope.inject(injection_type, injection_value)
+
+    @property
+    def routers(self) -> deque[Router]:
+        if self._routers is None:
+            self._routers = deque((self.main_router,) if self.main_router else ())  # type: ignore
+        return self._routers  # type: ignore
+
+    @cached_property
+    def raw_views(self) -> tuple[View, ...]:
+        return tuple(filter(None, (router.raw for router in self.routers)))
+
+    @property
+    def patcher(self) -> ABCPatcher:
+        """Alias `patcher` to get a vbml patcher from the global context."""
+        return self.global_context.vbml_patcher
+
+    @property
+    def register_middleware[Middleware: ABCMiddleware](self) -> typing.Callable[[type[Middleware]], type[Middleware]]:
+        """Decorator to register a custom middleware in the dispatch's middleware box."""
+        return self.middlewares.__call__
+
+    async def _handle_exceptions(
+        self,
+        api: API,
+        update: Update,
+        context: Context,
+        exceptions: tuple[BaseException | BaseExceptionGroup[BaseException], ...],
+    ) -> None:
+        unhandled_exceptions: list[BaseException] = []
+
+        try:
+            async with self.loop_wrapper.create_task_group() as task_group:
+                for exception in exceptions:
+                    if isinstance(exception, BaseExceptionGroup):
+                        task_group.create_task(self._handle_exceptions(api, update, context, exception.exceptions))
+                    elif isinstance(exception, Exception):
+                        task_group.create_task(
+                            self.main_router.route_view(
+                                self.error_handler,
+                                api,
+                                update,
+                                context.copy().add_exception_update(exception),
+                            ),
+                        )
+                    else:
+                        unhandled_exceptions.append(exception)
+        except BaseExceptionGroup as group:
+            raise BaseExceptionGroup(
+                "Unhandled exception groups:",
+                [group, BaseExceptionGroup("Unhandled exceptions:", unhandled_exceptions)],
+            )
+
+        if unhandled_exceptions:
+            raise BaseExceptionGroup("Unhandled exceptions:", unhandled_exceptions)
+
+    async def _process_views(
+        self,
+        views: typing.Iterable[View],
+        api: API,
+        update: Update,
+        context: Context,
+    ) -> bool:
+        async with self.loop_wrapper.create_task_group() as task_group:
+            for view in views:
+                task_group.create_task(self.main_router.route_view(view, api, update, context))
+
+        return any(task_group.results())
+
+    async def _process_update_exceptions(
+        self,
+        api: API,
+        update: Update,
+        context: Context,
+    ) -> None:
+        await logger.adebug(
+            "Processing error views with exceptions [{}] for update (id={}, type={!r})",
+            ", ".join(f"{type(e).__name__}" for e in context.exceptions_update.values()),
+            update.update_id,
+            update.update_type,
+        )
+
+        async with self.loop_wrapper.create_task_group() as task_group:
+            for router, exception in context.exceptions_update.items():
+                await logger.adebug(
+                    "Routing exception update (id={}, type={!r}) to router `{!r}`",
+                    update.update_id,
+                    update.update_type,
+                    router,
+                )
+                task_group.create_task(
+                    router.route_view(
+                        router.event_error,
+                        api,
+                        update,
+                        context.copy().add_exception_update(exception),
+                    ),
+                )
+
+    async def _route_update(self, api: API, update: Update, context: Context) -> bool:
+        async with self.loop_wrapper.create_task_group() as task_group:
+            for router in self.routers:
+                await logger.adebug(
+                    "Routing update (id={}, type={!r}) to router `{!r}`",
+                    update.update_id,
+                    update.update_type,
+                    router,
+                )
+                task_group.create_task(router.route(api, update, context))
+
+        return any(task_group.results())
+
+    async def feed(self, api: API, update: Update) -> None:
+        await logger.ainfo(
+            "New Update(id={}, type={!r}) received by bot (id={})",
+            update.update_id,
+            update.update_type,
+            api.id,
+        )
+
+        per_event_scope = self.global_scope.create_child(detail=PER_EVENT)
+        context = Context().add_roots(api, update, per_event_scope)
+
+        inject_internals(per_event_scope, {API: api, Update: update})
+
+        failed = False
+        middlewares = self.middlewares
+        start_time = self.loop_wrapper.time
+
+        try:
+            for middleware in middlewares:
+                if await run_pre_middleware(middleware, context) is not True:
+                    await logger.ainfo(
+                        "Update(id={}, type={!r}) processed with dispatch's pre-middleware `{}` and raised failure.",
+                        update.update_id,
+                        update.update_type,
+                        fullname(middleware),
+                    )
+                    return
+
+            if not self.routers:
+                await logger.adebug(
+                    "No corresponding routers from dispatch found for update (id={}, type={!r}).",
+                    update.update_id,
+                    update.update_type,
+                )
+            elif not await self._route_update(api, update, context) and self.raw_views:
+                await self._process_views(self.raw_views, api, update, context)
+
+            for middleware in middlewares:
+                await run_post_middleware(middleware, context)
+        except BaseException as exc:
+            failed = True
+
+            if context.exceptions_update:
+                try:
+                    await self._process_update_exceptions(api, update, context)
+                except BaseExceptionGroup as group:
+                    if not self.error_handler:
+                        raise
+
+                    await logger.adebug(
+                        "Dispatch caught unhandled exceptions while processing update (id={}, type={!r}), routing to error handler...",
+                        update.update_id,
+                        update.update_type,
+                    )
+                    await self._handle_exceptions(api, update, context, group.exceptions)
+
+                return
+
+            if isinstance(exc, Exception) and self.error_handler:
+                await logger.adebug(
+                    "Dispatch caught an exception while processing update (id={}, type={!r}), routing to error handler...",
+                    update.update_id,
+                    update.update_type,
+                )
+                await self.main_router.route_view(self.error_handler, api, update, context.add_exception_update(exc))
+                return
+
+            raise
+        finally:
+            await per_event_scope.close()
+
+            if not failed:
+                elapsed_time = self.loop_wrapper.time - start_time
+                elapsed_ms = elapsed_time * 1000
+                await logger.adebug(
+                    "Update (id={}, type={!r}) processed in {} {} by bot (id={})",
+                    update.update_id,
+                    update.update_type,
+                    int(elapsed_time * NANOSECONDS_PER_MILLISECOND) if elapsed_ms < 1 else int(elapsed_ms),
+                    "ns" if elapsed_ms < 1 else "ms",
+                    api.id,
+                )
+
+    def load(self, external: typing.Self) -> None:
+        self.routers.extend(filter(None, external.routers))
+        self.error_handler.load(external.error_handler)
+
+
+__all__ = ("Dispatch",)

telegrinder/bot/dispatch/handler/__init__.py

@@ -0,0 +1,23 @@
+from telegrinder.bot.dispatch.handler.abc import ABCHandler
+from telegrinder.bot.dispatch.handler.audio_reply import AudioReplyHandler
+from telegrinder.bot.dispatch.handler.base import BaseReplyHandler
+from telegrinder.bot.dispatch.handler.document_reply import DocumentReplyHandler
+from telegrinder.bot.dispatch.handler.func import FuncHandler
+from telegrinder.bot.dispatch.handler.media_group_reply import MediaGroupReplyHandler
+from telegrinder.bot.dispatch.handler.message_reply import MessageReplyHandler
+from telegrinder.bot.dispatch.handler.photo_reply import PhotoReplyHandler
+from telegrinder.bot.dispatch.handler.sticker_reply import StickerReplyHandler
+from telegrinder.bot.dispatch.handler.video_reply import VideoReplyHandler
+
+__all__ = (
+    "ABCHandler",
+    "AudioReplyHandler",
+    "BaseReplyHandler",
+    "DocumentReplyHandler",
+    "FuncHandler",
+    "MediaGroupReplyHandler",
+    "MessageReplyHandler",
+    "PhotoReplyHandler",
+    "StickerReplyHandler",
+    "VideoReplyHandler",
+)

telegrinder/bot/dispatch/handler/abc.py

@@ -0,0 +1,25 @@
+import typing
+from abc import ABC, abstractmethod
+
+from kungfu.library.monad.result import Result
+
+from telegrinder.api import API
+from telegrinder.bot.dispatch.context import Context
+from telegrinder.types.objects import Update
+
+
+class ABCHandler(ABC):
+    final: bool
+
+    @abstractmethod
+    async def run(
+        self,
+        api: API,
+        update: Update,
+        context: Context,
+        check: bool = True,
+    ) -> Result[typing.Any, typing.Any]:
+        pass
+
+
+__all__ = ("ABCHandler",)