chore: Add internal engine abstraction (strategy pattern) for sync vs hybrid sync/async (#456)

* chore: Add internal Sync and Async engines

Author: fgmacedo

README.md

@@ -77,7 +77,7 @@ Define your state machine:
 ...         | red.to(green)
 ...     )
 ...
-...     async def before_cycle(self, event: str, source: State, target: State, message: str = ""):
+...     def before_cycle(self, event: str, source: State, target: State, message: str = ""):
 ...         message = ". " + message if message else ""
 ...         return f"Running {event} from {source.id} to {target.id}{message}"
 ...
@@ -120,26 +120,6 @@ Then start sending events to your new state machine:
 
 ```
 
-You can use the exactly same state machine from an async codebase:
-
-
-```py
->>> async def run_sm():
-...    asm = TrafficLightMachine()
-...    results = []
-...    for _i in range(4):
-...        result = await asm.send("cycle")
-...        results.append(result)
-...    return results
-
->>> asyncio.run(run_sm())
-Don't move.
-Go ahead!
-['Running cycle from green to yellow', 'Running cycle from yellow to red', ...
-
-```
-
-
 **That's it.** This is all an external object needs to know about your state machine: How to send events.
 Ideally, all states, transitions, and actions should be kept internally and not checked externally to avoid unnecessary coupling.
 
@@ -227,7 +207,7 @@ callback method.
 Note how `before_cycle` was declared:
 
 ```py
-async def before_cycle(self, event: str, source: State, target: State, message: str = ""):
+def before_cycle(self, event: str, source: State, target: State, message: str = ""):
     message = ". " + message if message else ""
     return f"Running {event} from {source.id} to {target.id}{message}"
 ```

docs/async.md

@@ -4,21 +4,61 @@
 Support for async code was added!
 ```
 
-The {ref}`StateMachine` has full async suport. You can write async {ref}`actions`, {ref}`guards` and {ref}`event` triggers.
+The {ref}`StateMachine` fully supports asynchronous code. You can write async {ref}`actions`, {ref}`guards`, and {ref}`event` triggers, while maintaining the same external API for both synchronous and asynchronous codebases.
+
+This is achieved through a new concept called "engine," an internal strategy pattern abstraction that manages transitions and callbacks.
+
+There are two engines:
+
+SyncEngine
+: Activated if there are no async callbacks. All code runs exactly as it did before version 2.3.0.
+
+AsyncEngine
+: Activated if there is at least one async callback. The code runs asynchronously and requires a running event loop, which it will create if none exists.
+
+These engines are internal and are activated automatically by inspecting the registered callbacks in the following scenarios:
+
+
+```{list-table} Sync vs async engines
+:widths: 15 10 25 10 10
+:header-rows: 1
+
+*   - Outer scope
+    - Async callbacks?
+    - Engine
+    - Creates internal loop
+    - Reuses external loop
+*   - Sync
+    - No
+    - Sync
+    - No
+    - No
+*   - Sync
+    - Yes
+    - Async
+    - Yes
+    - No
+*   - Async
+    - No
+    - Sync
+    - No
+    - No
+*   - Async
+    - Yes
+    - Async
+    - No
+    - Yes
+
+```
 
-Keeping the same external API do interact both on sync or async codebases.
 
 ```{note}
-All the handlers will run on the same thread they're called. So it's not recommended to mix sync with async code unless
-you know what you're doing.
+All handlers will run on the same thread they are called. Therefore, mixing synchronous and asynchronous code is not recommended unless you are confident in your implementation.
 ```
 
 ## Asynchronous Support
 
-We support native coroutine using asyncio, enabling seamless integration with asynchronous code.
-There's no change on the public API of the library to work on async codebases.
-
-One requirement is that when running on an async code, you must manually await for the {ref}`initial state activation` to be able to check the current state.
+We support native coroutine callbacks using asyncio, enabling seamless integration with asynchronous code. There is no change in the public API of the library to work with asynchronous codebases.
 
 
 ```{seealso}
@@ -49,10 +89,10 @@ Final
 
 ```
 
-## Sync codebase with async handlers
+## Sync codebase with async callbacks
+
+The same state machine can be executed in a synchronous codebase, even if it contains async callbacks. The callbacks will be awaited using `asyncio.get_event_loop()` if needed.
 
-The same state machine can be executed on a sync codebase, even if it contains async handlers. The handlers will be
-awaited on an `asyncio.get_event_loop()` if needed.
 
 ```py
 >>> sm = AsyncStateMachine()
@@ -68,9 +108,12 @@ Final
 (initial state activation)=
 ## Initial State Activation for Async Code
 
-When working with asynchronous state machines from async code, users must manually [activate initial state](statemachine.StateMachine.activate_initial_state) to be able to check the current state. This change ensures proper state initialization and
-execution flow given that Python don't allow awaiting at class initalization time and the initial state activation
-may contain async callbacks that must be awaited.
+
+If you perform checks against the `current_state`, like a loop `while sm.current_state.is_final:`, then on async code you must manually
+await for the  [activate initial state](statemachine.StateMachine.activate_initial_state) to be able to check the current state.
+
+If you don't do any check for current state externally, just ignore this as the initial state is activated automatically before the first event trigger is handled.
+
 
 ```py
 >>> async def initialize_sm():
@@ -83,3 +126,7 @@ may contain async callbacks that must be awaited.
 Initial
 
 ```
+
+```{hint}
+This manual initial state activation on async is because Python don't allow awaiting at class initalization time and the initial state activation may contain async callbacks that must be awaited.
+```

docs/releases/2.3.0.md

@@ -32,13 +32,18 @@ async code with a state machine.
 ...     final = State('Final', final=True)
 ...
 ...     advance = initial.to(final)
+...
+...     async def on_advance(self):
+...         return 42
+
+
 
 >>> async def run_sm():
 ...     sm = AsyncStateMachine()
-...     await sm.advance()
-...     print(sm.current_state)
+...     res = await sm.advance()
+...     return (42, sm.current_state.name)
 
 >>> asyncio.run(run_sm())
-Final
+(42, 'Final')
 
 ```

docs/releases/2.3.2.md

@@ -7,6 +7,29 @@
 Observers are now rebranded to {ref}`listeners`. With expanted support for adding listeners when
 instantiating a state machine. This allows covering more use cases.
 
+### Improved async support
+
+Since version 2.3.0, we have added async support. However, we encountered use cases, such as the [async safety on Django ORM](https://docs.djangoproject.com/en/5.0/topics/async/#async-safety), which expects no running event loop and blocks if it detects one on the current thread.
+
+To address this issue, we developed a solution that maintains a unified API for both synchronous and asynchronous operations while effectively handling these scenarios.
+
+This is achieved through a new concept called "engine," an internal strategy pattern abstraction that manages transitions and callbacks.
+
+There are two engines:
+
+SyncEngine
+: Activated if there are no async callbacks. All code runs exactly as it did before version 2.3.0.
+
+AsyncEngine
+: Activated if there is at least one async callback. The code runs asynchronously and requires a running event loop, which it will create if none exists.
+
+These engines are internal and are activated automatically by inspecting the registered callbacks in the following scenarios:
+
+```{seealso}
+See {ref}`async` for more details.
+```
+
+
 ### Listeners at class initialization
 
 Listeners are a way to generically add behavior to a state machine without changing its internal implementation.

statemachine/callbacks.py

@@ -1,8 +1,12 @@
+import asyncio
 from bisect import insort
+from collections import Counter
 from collections import defaultdict
 from collections import deque
 from enum import IntEnum
 from enum import auto
+from inspect import isawaitable
+from inspect import iscoroutinefunction
 from typing import Callable
 from typing import Dict
 from typing import Generator
@@ -42,7 +46,7 @@ def build_key(self, specs: "CallbackSpecList") -> str:
         return f"{self.name}@{id(specs)}"
 
 
-async def allways_true(*args, **kwargs):
+def allways_true(*args, **kwargs):
     return True
 
 
@@ -86,7 +90,10 @@ def __repr__(self):
         return f"{type(self).__name__}({self.func!r}, is_convention={self.is_convention!r})"
 
     def __str__(self):
-        return getattr(self.func, "__name__", self.func)
+        name = getattr(self.func, "__name__", self.func)
+        if self.expected_value is False:
+            name = f"!{name}"
+        return name
 
     def __eq__(self, other):
         return self.func == other.func and self.group == other.group
@@ -99,9 +106,6 @@ def _update_func(self, func: Callable, attr_name: str):
         self.reference = SpecReference.CALLABLE
         self.attr_name = attr_name
 
-    def _wrap_callable(self, func, _expected_value):
-        return func
-
     def build(self, resolver) -> Generator["CallbackWrapper", None, None]:
         """
         Resolves the `func` into a usable callable.
@@ -111,53 +115,15 @@ def build(self, resolver) -> Generator["CallbackWrapper", None, None]:
                 can receive arbitrary parameters like `*args, **kwargs`.
         """
         for callback in resolver.search(self):
-            condition = (
-                next(resolver.search(CallbackSpec(self.cond, CallbackGroup.COND)))
-                if self.cond is not None
-                else allways_true
-            )
+            condition = self.cond if self.cond is not None else allways_true
             yield CallbackWrapper(
-                callback=self._wrap_callable(callback, self.expected_value),
+                callback=callback,
                 condition=condition,
                 meta=self,
                 unique_key=callback.unique_key,
             )
 
 
-class BoolCallbackSpec(CallbackSpec):
-    """A thin wrapper that register info about actions and guards.
-
-    At first, `func` can be a string or a callable, and even if it's already
-    a callable, his signature can mismatch.
-
-    After instantiation, `.setup(resolver)` must be called before any real
-    call is performed, to allow the proper callback resolution.
-    """
-
-    def __init__(
-        self,
-        func,
-        group: CallbackGroup,
-        is_convention=False,
-        cond=None,
-        priority: CallbackPriority = CallbackPriority.NAMING,
-        expected_value=True,
-    ):
-        super().__init__(
-            func, group, is_convention, cond, priority=priority, expected_value=expected_value
-        )
-
-    def __str__(self):
-        name = super().__str__()
-        return name if self.expected_value else f"!{name}"
-
-    def _wrap_callable(self, func, expected_value):
-        async def bool_wrapper(*args, **kwargs):
-            return bool(await func(*args, **kwargs)) == expected_value
-
-        return bool_wrapper
-
-
 class SpecListGrouper:
     def __init__(
         self, list: "CallbackSpecList", group: CallbackGroup, factory=CallbackSpec
@@ -275,9 +241,11 @@ def __init__(
         unique_key: str,
     ) -> None:
         self._callback = callback
+        self._iscoro = iscoroutinefunction(callback)
         self.condition = condition
         self.meta = meta
         self.unique_key = unique_key
+        self.expected_value = self.meta.expected_value
 
     def __repr__(self):
         return f"{type(self).__name__}({self.unique_key})"
@@ -289,7 +257,19 @@ def __lt__(self, other):
         return self.meta.priority < other.meta.priority
 
     async def __call__(self, *args, **kwargs):
-        return await self._callback(*args, **kwargs)
+        value = self._callback(*args, **kwargs)
+        if isawaitable(value):
+            value = await value
+
+        if self.expected_value is not None:
+            return bool(value) == self.expected_value
+        return value
+
+    def call(self, *args, **kwargs):
+        value = self._callback(*args, **kwargs)
+        if self.expected_value is not None:
+            return bool(value) == self.expected_value
+        return value
 
 
 class CallbacksExecutor:
@@ -322,23 +302,40 @@ def add(self, items: Iterable[CallbackSpec], resolver: Callable):
             self._add(item, resolver)
         return self
 
-    async def call(self, *args, **kwargs):
+    async def async_call(self, *args, **kwargs):
+        return await asyncio.gather(
+            *(
+                callback(*args, **kwargs)
+                for callback in self
+                if callback.condition(*args, **kwargs)
+            )
+        )
+
+    async def async_all(self, *args, **kwargs):
+        coros = [condition(*args, **kwargs) for condition in self]
+        for coro in asyncio.as_completed(coros):
+            if not await coro:
+                return False
+        return True
+
+    def call(self, *args, **kwargs):
         return [
-            await callback(*args, **kwargs)
+            callback.call(*args, **kwargs)
             for callback in self
-            if await callback.condition(*args, **kwargs)
+            if callback.condition(*args, **kwargs)
         ]
 
-    async def all(self, *args, **kwargs):
+    def all(self, *args, **kwargs):
         for condition in self:
-            if not await condition(*args, **kwargs):
+            if not condition.call(*args, **kwargs):
                 return False
         return True
 
 
 class CallbacksRegistry:
     def __init__(self) -> None:
         self._registry: Dict[str, CallbacksExecutor] = defaultdict(CallbacksExecutor)
+        self._method_types: Counter = Counter()
 
     def clear(self):
         self._registry.clear()
@@ -358,3 +355,8 @@ def check(self, specs: CallbackSpecList):
             raise AttrNotFound(
                 _("Did not found name '{}' from model or statemachine").format(meta.func)
             )
+
+    def async_or_sync(self):
+        self._method_types.update(
+            callback._iscoro for executor in self._registry.values() for callback in executor
+        )