FG Manager

docs/bg/index.rst

@@ -0,0 +1,106 @@
+Updating from another chat or background
+*********************************************************************
+
+There are several cases when you do not have proper ``dialog_manager`` instance:
+
+* background tasks
+* http/broker handlers
+* handlers for another user/chat
+
+In all these cases you should use so called "background manager" which can be obtained from ``BgManagerFactory`` or another ``dialog_manager`` instance using ``.bg()`` method.
+Note, that you cannot use normal ``dialog_manager`` outside of aiogram dialog handler.
+
+Using BgManager
+------------------------------------------------
+
+Background manager can be used to asynchronously update dialog stack. All these actions are handled in background and you have not access to current state or dialog data.
+
+.. code-block:: python
+
+    await bg_manager.start(state)
+    await bg_manager.done()
+    await bg_manager.switch_to(state)
+    await bg_manager.update(data)
+
+Or you can enter a context to use normal dialog manager accessing all necessary data:
+
+.. code-block:: python
+
+    with bg_manager.fg() as dialog_manager:
+        dialog_manager.dialog_data["key"] = value
+        dialog_manager.update()
+
+
+Obtaining BgManagerFactory
+------------------------------------------------
+
+In aiogram handlers:
+
+.. code-block:: python
+
+    async def handler(update: Any, dialog_bg_factory: BgManagerFactory) -> None: ...
+
+
+In middleware. Works if the middleware is registered after setup_dialogs. In 99% of cases, you won’t need this.
+
+.. code-block:: python
+
+    async def __call__(self, handler, event, data):
+        dialog_bg_factory = data[BG_FACTORY_KEY]
+
+As a result of the setup_dialogs function:
+
+.. code-block:: python
+
+    dialog_bg_factory = setup_dialogs(dispatcher)
+
+In aiogram dialog handlers:
+
+.. code-block:: python
+
+    async def handler(update: Any, widget: Widget, manager: DialogManager) -> None:
+        dialog_bg_factory = manager.middleware_data["dialog_bg_factory"]
+
+Getting a BgManager
+------------------------------------------------
+
+Using ``DialogManager`` (another background manager will work as well):
+
+.. code-block:: python
+
+    bg_manager = dialog_manager.bg(
+        user_id=other_user_id,
+        chat_id=other_chat_id,
+    )
+
+Using ``BgManagerFactory``
+
+.. code-block:: python
+
+    bg_manager = dialog_manager.bg(
+        bot,
+        user_id=other_user_id,
+        chat_id=other_chat_id,
+    )
+
+
+Dealing with middlewares
+------------------------------------------------
+
+Background manager sends custom events using aiogram dispatcher, so you have to your middlewares won't be triggered by default. To fix it register you middleware for dialog events:
+
+.. code-block:: python
+
+    from aiogram_dialog import DIALOG_EVENT_NAME
+
+    dispatcher.observers[DIALOG_EVENT_NAME].middleware(...)
+
+
+Classes and signatures
+------------------------------------------------
+
+.. autoclass:: aiogram_dialog.api.protocols.BaseDialogManager
+   :members: done, start, switch_to, update, bg, fg
+
+.. autoclass:: aiogram_dialog.api.protocols.BgManagerFactory
+   :members: bg

docs/index.rst

@@ -11,6 +11,7 @@ aiogram-dialog
     transitions/index
     how_are_messages_updated/index
     group_business
+    bg/index
     helper_tools/index
     migration
     faq

example/loading.py

@@ -65,9 +65,9 @@ async def background(callback: CallbackQuery, manager: BaseDialogManager):
     count = 10
     for i in range(1, count + 1):
         await asyncio.sleep(1)
-        await manager.update({
-            "progress": i * 100 / count,
-        })
+        async with manager.fg() as m:
+            m.dialog_data["progress"] = i * 100 / count
+            await m.update()
     await asyncio.sleep(1)
     await manager.done()
 

src/aiogram_dialog/__init__.py

@@ -1,5 +1,6 @@
 __all__ = [
     "DEFAULT_STACK_ID",
+    "DIALOG_EVENT_NAME",
     "GROUP_STACK_ID",
     "AccessSettings",
     "BaseDialogManager",
@@ -22,6 +23,7 @@
 
 from .api.entities import (
     DEFAULT_STACK_ID,
+    DIALOG_EVENT_NAME,
     GROUP_STACK_ID,
     AccessSettings,
     ChatEvent,

src/aiogram_dialog/api/entities/update_event.py

@@ -1,3 +1,4 @@
+from asyncio import Future
 from enum import Enum
 from typing import Any
 
@@ -24,6 +25,7 @@ class DialogAction(Enum):
     START = "START"
     UPDATE = "UPDATE"
     SWITCH = "SWITCH"
+    FG = "FG"
 
 
 class DialogUpdateEvent(TelegramObject):
@@ -52,6 +54,11 @@ class DialogSwitchEvent(DialogUpdateEvent):
     new_state: State
 
 
+class DialogFgEvent(DialogUpdateEvent):
+    entered: Future
+    exited: Future
+
+
 class DialogUpdate(Update):
     aiogd_update: DialogUpdateEvent
 

src/aiogram_dialog/api/protocols/manager.py

@@ -1,4 +1,5 @@
 from abc import abstractmethod
+from contextlib import AbstractAsyncContextManager
 from enum import Enum
 from typing import Any, Protocol
 
@@ -27,6 +28,7 @@ async def done(
             result: Any = None,
             show_mode: ShowMode | None = None,
     ) -> None:
+        """Close current dialog and show underlying dialog in the stack"""
         raise NotImplementedError
 
     @abstractmethod
@@ -38,6 +40,7 @@ async def start(
             show_mode: ShowMode | None = None,
             access_settings: AccessSettings | None = None,
     ) -> None:
+        """Add new dialog to the stack and show it"""
         raise NotImplementedError
 
     @abstractmethod
@@ -46,14 +49,16 @@ async def switch_to(
             state: State,
             show_mode: ShowMode | None = None,
     ) -> None:
+        """Switch active window in the current dialog"""
         raise NotImplementedError
 
     @abstractmethod
     async def update(
             self,
-            data: dict,
+            data: dict | None = None,
             show_mode: ShowMode | None = None,
     ) -> None:
+        """Update dialog data and dredraw current window."""
         raise NotImplementedError
 
     @abstractmethod
@@ -66,6 +71,12 @@ def bg(
             business_connection_id: str | UnsetId | None = UnsetId.UNSET,
             load: bool = False,  # load chat and user
     ) -> "BaseDialogManager":
+        """Get background manager for specified chat"""
+        raise NotImplementedError
+
+    @abstractmethod
+    def fg(self) -> AbstractAsyncContextManager["DialogManager"]:
+        """Get full-featured dialog manager"""
         raise NotImplementedError
 
 
@@ -81,6 +92,7 @@ def bg(
             business_connection_id: str | None = None,
             load: bool = False,  # load chat and user
     ) -> "BaseDialogManager":
+        """Get background manager for specified chat"""
         raise NotImplementedError
 
 

src/aiogram_dialog/manager/bg_manager.py

@@ -1,3 +1,6 @@
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from logging import getLogger
 from typing import Any
 
@@ -18,13 +21,15 @@
     ShowMode,
     StartMode,
 )
+from aiogram_dialog.api.entities.update_event import DialogFgEvent
 from aiogram_dialog.api.internal import (
     FakeChat,
     FakeUser,
 )
 from aiogram_dialog.api.protocols import (
     BaseDialogManager,
     BgManagerFactory,
+    DialogManager,
     UnsetId,
 )
 from aiogram_dialog.manager.updater import Updater
@@ -244,17 +249,41 @@ async def switch_to(
 
     async def update(
             self,
-            data: dict,
+            data: dict | None = None,
             show_mode: ShowMode | None = None,
     ) -> None:
         await self._load()
         await self._notify(
             DialogUpdateEvent(
-                action=DialogAction.UPDATE, data=data, show_mode=show_mode,
+                action=DialogAction.UPDATE,
+                data=data or {},
+                show_mode=show_mode,
                 **self._base_event_params(),
             ),
         )
 
+    @asynccontextmanager
+    async def fg(self) -> AsyncIterator[DialogManager]:
+        event = DialogFgEvent(
+            data=None,
+            action=DialogAction.FG,
+            entered=asyncio.get_running_loop().create_future(),
+            exited=asyncio.get_running_loop().create_future(),
+            **self._base_event_params(),
+        )
+        bot = self._event_context.bot
+        update = DialogUpdate(aiogd_update=event.as_(bot)).as_(bot)
+        task = self._updater.notify_task(bot=bot, update=update)
+        manager = await event.entered
+        try:
+            yield manager
+        except Exception as e:
+            event.exited.set_exception(e)
+            raise e
+        else:
+            event.exited.set_result(None)
+        await task
+
 
 class BgManagerFactoryImpl(BgManagerFactory):
     def __init__(self, router: Router):

src/aiogram_dialog/manager/manager.py

@@ -1,4 +1,6 @@
 import sys
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from copy import deepcopy
 from logging import getLogger
 from typing import Any, cast
@@ -518,10 +520,11 @@ def _calc_show_mode(self) -> ShowMode:  # noqa: PLR0911
 
     async def update(
             self,
-            data: dict,
+            data: dict | None = None,
             show_mode: ShowMode | None = None,
     ) -> None:
-        self.current_context().dialog_data.update(data)
+        if data:
+            self.current_context().dialog_data.update(data)
         await self.show(show_mode)
 
     def find(self, widget_id) -> Any | None:
@@ -603,6 +606,10 @@ def bg(
             load=load,
         )
 
+    @asynccontextmanager
+    async def fg(self) -> AsyncIterator[DialogManager]:
+        yield self
+
     async def close_manager(self) -> None:
         self.check_disabled()
         self.disabled = True

src/aiogram_dialog/manager/sub_manager.py

@@ -1,4 +1,6 @@
 import dataclasses
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from typing import Any
 
 from aiogram.fsm.state import State
@@ -139,10 +141,11 @@ async def switch_to(
 
     async def update(
             self,
-            data: dict,
+            data: dict | None = None,
             show_mode: ShowMode | None = None,
     ) -> None:
-        self.current_context().dialog_data.update(data)
+        if data:
+            self.current_context().dialog_data.update(data)
         await self.show(show_mode)
 
     def bg(
@@ -162,3 +165,7 @@ def bg(
             business_connection_id=business_connection_id,
             load=load,
         )
+
+    @asynccontextmanager
+    async def fg(self) -> AsyncIterator[DialogManager]:
+        yield self

src/aiogram_dialog/manager/update_handler.py

@@ -7,6 +7,7 @@
     DialogUpdateEvent,
     ShowMode,
 )
+from aiogram_dialog.api.entities.update_event import DialogFgEvent
 from aiogram_dialog.api.protocols import DialogManager
 
 logger = getLogger(__name__)
@@ -27,6 +28,9 @@ async def handle_update(
     elif isinstance(event, DialogSwitchEvent):
         await dialog_manager.switch_to(state=event.new_state)
         await dialog_manager.show()
+    elif isinstance(event, DialogFgEvent):
+        event.entered.set_result(dialog_manager)
+        await event.exited
     elif event.action is DialogAction.UPDATE:
         if not dialog_manager.has_context():
             logger.warning("No context found")

src/aiogram_dialog/manager/updater.py

@@ -1,4 +1,5 @@
 import asyncio
+from asyncio import Task
 from contextvars import copy_context
 
 from aiogram import Bot, Dispatcher, Router
@@ -22,6 +23,10 @@ def callback():
 
         asyncio.get_running_loop().call_soon(callback, context=copy_context())
 
+    def notify_task(self, bot: Bot, update: DialogUpdate) -> Task:
+        ctx = copy_context()
+        return ctx.run(asyncio.create_task, self._process_update(bot, update))
+
     async def _process_update(self, bot: Bot, update: DialogUpdate) -> None:
         event = update.event
         await self.dp.propagate_event(