PoC Scenes (#1280)

* Base implementation

* Small refactoring + added possibility to specify post-action on handlers

* Move scene properties to config object

* Revise aiogram/scenes with wizard-based design pattern

Modified files in aiogram/scenes to incorporate the Wizard design pattern. Files affected are _marker.py, _registry.py, _wizard.py and __init__.py. The changes introduced a SceneWizard Class and ScenesManager, both of which aid in controlling navigation between different scenes or states. This helps clarifying the codebase, streamline scene transitions and offer more control over the app flow.

* Added example

* Small optimizations

* Replace ValueError with SceneException in scenes. Added error safety in scene resolver.

* str

* Added possibility to reset context on scene entered and to handle callback query in any state

* Remove inline markup in example

* Small changes

* Docs + example

* Small refactoring

* Remove scene inclusion methods from router

The methods for including scenes as sub-routers have been removed from the router.py file. Instead, the SceneRegistry class is now set to register scenes by default upon initializing. This streamlines the scene management process by removing redundant routers and making registration automatic.

* Init tests

* Small fix in tests

* Add support for State instance in the scene

The aiogram FSM scene now allows the use of State instance as an argument, enabling more customization. Modified the 'as_handler' method to receive **kwargs arguments, allowing passing of attributes to the handler. An additional type check has been also added to ensure the 'scene' is either a subclass of Scene or a string.

* Fixed test

* Expand test coverage for test_fsm module

The commit enhances tests for the test_fsm module to improve code reliability. It includes additional unit tests for the ObserverDecorator and ActionContainer classes and introduces new tests for the SceneHandlerWrapper class. This ensures the correct functionality of the decorator methods, the action container execution, and the handler wrapper.

* Reformat code

* Fixed long line in the example

* Skip some tests on PyPy

* Change mock return_value

* Compatibility...

* Compatibility...

* Compatibility...

* Added base changes description

* Scenes Tests (#1369)

* ADD tests for `SceneRegistry`

* ADD tests for `ScenesManager`

* ADD Changelog

* Revert "ADD Changelog"

This reverts commit 6dd9301.

* Remove `@pytest.mark.asyncio`, Reformat code

* Scenes Tests. Part 2 (#1371)

* ADD tests for `SceneWizard`

* ADD tests for `Scene`

* Refactor ObserverDecorator to use on.message syntax in test_scene.py
Cover `Scene::__init_subclass__::if isinstance(value, ObserverDecorator):`

* Refactor `HistoryManager` in `aiogram/fsm/scene.py`
Removed condition that checked if 'history' is empty before calling 'update_data' in 'Scene'.

* ADD tests for `HistoryManager`

* Small changes in the documentation

* Small changes in the documentation

* Small changes in the documentation

---------

Co-authored-by: Andrew <11490628+andrew000@users.noreply.github.com>

CHANGES/1280.feature.rst

@@ -0,0 +1,2 @@
+Introduced Scenes feature that helps you to simplify user interactions using Finite State Machines.
+Read more about 👉 :ref:`Scenes <Scenes>`.

aiogram/__init__.py

@@ -1,3 +1,4 @@
+import asyncio as _asyncio
 from contextlib import suppress
 
 from aiogram.dispatcher.flags import FlagGenerator
@@ -14,11 +15,9 @@
 from .utils.text_decorations import markdown_decoration as md
 
 with suppress(ImportError):
-    import asyncio
-
     import uvloop as _uvloop
 
-    asyncio.set_event_loop_policy(_uvloop.EventLoopPolicy())
+    _asyncio.set_event_loop_policy(_uvloop.EventLoopPolicy())
 
 
 F = MagicFilter()

aiogram/dispatcher/event/handler.py

@@ -18,7 +18,7 @@
 
 
 @dataclass
-class CallableMixin:
+class CallableObject:
     callback: CallbackType
     awaitable: bool = field(init=False)
     params: Set[str] = field(init=False)
@@ -49,7 +49,7 @@ async def call(self, *args: Any, **kwargs: Any) -> Any:
 
 
 @dataclass
-class FilterObject(CallableMixin):
+class FilterObject(CallableObject):
     magic: Optional[MagicFilter] = None
 
     def __post_init__(self) -> None:
@@ -76,7 +76,7 @@ def __post_init__(self) -> None:
 
 
 @dataclass
-class HandlerObject(CallableMixin):
+class HandlerObject(CallableObject):
     filters: Optional[List[FilterObject]] = None
     flags: Dict[str, Any] = field(default_factory=dict)
 

aiogram/exceptions.py

@@ -37,6 +37,12 @@ class CallbackAnswerException(AiogramError):
     """
 
 
+class SceneException(AiogramError):
+    """
+    Exception for scenes.
+    """
+
+
 class UnsupportedKeywordArgument(DetailedAiogramError):
     """
     Exception raised when a keyword argument is passed as filter.