feat: Support for native coroutines (asyncio) (#435)

* tests: New air conditioner example using asyncio

* fix: Custom error if the model is initialized with an invalid current state

Author: fgmacedo

README.md

@@ -65,7 +65,7 @@ Define your state machine:
 ...         | red.to(green)
 ...     )
 ...
-...     def before_cycle(self, event: str, source: State, target: State, message: str = ""):
+...     async 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}"
 ...
@@ -240,6 +240,34 @@ and in diagrams:
 
 ```
 
+## Async 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.
+
+
+```py
+>>> class AsyncStateMachine(StateMachine):
+...     initial = State('Initial', initial=True)
+...     final = State('Final', final=True)
+...
+...     advance = initial.to(final)
+...
+...     async def on_advance(self):
+...         return 42
+
+>>> async def run_sm():
+...     sm = AsyncStateMachine()
+...     result = await sm.advance()
+...     print(f"Result is {result}")
+...     print(sm.current_state)
+
+>>> asyncio.run(run_sm())
+Result is 42
+Final
+
+```
+
 ## A more useful example
 
 A simple didactic state machine for controlling an `Order`:

conftest.py

@@ -0,0 +1,23 @@
+import pytest
+
+
+@pytest.fixture(autouse=True, scope="session")
+def add_doctest_context(doctest_namespace):  # noqa: PT004
+    from statemachine import State
+    from statemachine import StateMachine
+    from statemachine.utils import run_async_from_sync
+
+    class ContribAsyncio:
+        """
+        Using `run_async_from_sync` to be injected in the doctests to better integration with an
+        already running loop, as all of our examples are also automated executed as doctests.
+
+        On real life code you should use standard `import asyncio; asyncio.run(main())`.
+        """
+
+        def __init__(self):
+            self.run = run_async_from_sync
+
+    doctest_namespace["State"] = State
+    doctest_namespace["StateMachine"] = StateMachine
+    doctest_namespace["asyncio"] = ContribAsyncio()

docs/actions.md

@@ -5,7 +5,7 @@ outside world, and indeed they are the main reason why they exist at all.
 
 The main point of introducing a state machine is for the
 actions to be invoked at the right times, depending on the sequence of events
-and the state of the guards.
+and the state of the {ref}`conditions`.
 
 Actions are most commonly performed on entry or exit of a state, although
 it is possible to add them before/after a transition.
@@ -79,7 +79,7 @@ After 'go', on the 'final' state.
 
 
 ```{seealso}
-All actions and {ref}`guards` support multiple method signatures. They follow the
+All actions and {ref}`conditions` support multiple method signatures. They follow the
 {ref}`dynamic-dispatch` method calling implemented on this library.
 ```
 
@@ -298,7 +298,7 @@ On loop
 In addition to {ref}`actions`, you can specify {ref}`validators and guards` that are checked before a transition is started. They are meant to stop a transition to occur.
 
 ```{seealso}
-See {ref}`guards` and {ref}`validators`.
+See {ref}`conditions` and {ref}`validators`.
 ```
 
 
@@ -377,21 +377,20 @@ For {ref}`RTC model`, only the main event will get its value list, while the cha
 
 
 (dynamic-dispatch)=
-## Dynamic dispatch
+(dynamic dispatch)=
+## Dependency injection
 
-{ref}`statemachine` implements a custom dispatch mechanism on all those available Actions and
-Guards. This means that you can declare an arbitrary number of `*args` and `**kwargs`, and the
-library will match your method signature of what's expected to receive with the provided arguments.
+{ref}`statemachine` implements a dependency injection mechanism on all available {ref}`Actions` and
+{ref}`Conditions` that automatically inspects and matches the expected callback params with those available by the library in conjunction with any values informed when calling an event using `*args` and `**kwargs`.
 
-This means that if on your `on_enter_<state.id>()` or `on_<event>()` method, you need to know
-the `source` ({ref}`state`), or the `event` ({ref}`event`), or access a keyword
-argument passed with the trigger, just add this parameter to the method and It will be passed
-by the dispatch mechanics.
+The library ensures that your method signatures match the expected arguments.
+
+For example, if you need to access the source (state), the event (event), or any keyword arguments passed with the trigger in any method, simply include these parameters in the method. They will be automatically passed by the dependency injection dispatch mechanics.
 
 In other words, if you implement a method to handle an event and don't declare any parameter,
 you'll be fine, if you declare an expected parameter, you'll also be covered.
 
-For your convenience, all these parameters are available for you on any Action or Guard:
+For your convenience, all these parameters are available for you on any callback:
 
 
 `*args`

docs/async.md

@@ -0,0 +1,85 @@
+# Async
+
+```{versionadded} 2.3.0
+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.
+
+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.
+```
+
+## 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.
+
+
+```{seealso}
+See {ref}`sphx_glr_auto_examples_air_conditioner_machine.py` for an example of
+async code with a state machine.
+```
+
+
+```py
+>>> class AsyncStateMachine(StateMachine):
+...     initial = State('Initial', initial=True)
+...     final = State('Final', final=True)
+...
+...     advance = initial.to(final)
+...
+...     async def on_advance(self):
+...         return 42
+
+>>> async def run_sm():
+...     sm = AsyncStateMachine()
+...     result = await sm.advance()
+...     print(f"Result is {result}")
+...     print(sm.current_state)
+
+>>> asyncio.run(run_sm())
+Result is 42
+Final
+
+```
+
+## Sync codebase with async handlers
+
+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()
+>>> result = sm.advance()
+>>> print(f"Result is {result}")
+Result is 42
+>>> print(sm.current_state)
+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.
+
+```py
+>>> async def initialize_sm():
+...     sm = AsyncStateMachine()
+...     await sm.activate_initial_state()
+...     return sm
+
+>>> sm = asyncio.run(initialize_sm())
+>>> print(sm.current_state)
+Initial
+
+```

docs/conf.py

@@ -15,6 +15,7 @@
 import sys
 
 import sphinx_rtd_theme
+from sphinx_gallery import gen_gallery
 
 # If extensions (or modules to document with autodoc) are in another
 # directory, add these directories to sys.path here. If the directory is
@@ -271,3 +272,11 @@
     "image_scrapers": (MachineScraper(project_root),),
     "reset_modules": [],
 }
+
+
+def dummy_write_computation_times(gallery_conf, target_dir, costs):
+    "patch gen_gallery to disable write_computation_times"
+    pass
+
+
+gen_gallery.write_computation_times = dummy_write_computation_times

docs/guards.md

@@ -1,34 +1,32 @@
 (validators-and-guards)=
-# Validators and guards
+(validators and guards)=
+# Conditions and Validators
 
-Validations and Guards are checked before a transition is started. They are meant to stop a
+Conditions and Validations are checked before a transition is started. They are meant to prevent or stop a
 transition to occur.
 
-The main difference is that {ref}`validators` raise exceptions to stop the flow, and {ref}`guards`
+The main difference is that {ref}`validators` raise exceptions to stop the flow, and {ref}`conditions`
 act like predicates that shall resolve to a ``boolean`` value.
 
 ```{seealso}
 Please see {ref}`dynamic-dispatch` to know more about how this lib supports multiple signatures
 for all the available callbacks, being validators and guards or {ref}`actions`.
 ```
 
-## Guards
+(guards)=
+## Conditions
 
-Also known as **Conditional transition**.
+This feature is also known as a **Conditional Transition**.
 
-A guard is a condition that may be checked when a {ref}`statemachine` wants to handle
-an {ref}`event`. A guard is declared on the {ref}`transition`, and when that {ref}`transition`
-would trigger, then the guard (if any) is checked. If the guard is `True`
-then the transition does happen. If the guard is `False`, the transition
-is ignored.
+A conditional transition occurs only if specific conditions or criteria are met. In addition to checking if there is a transition handling the event in the current state, you can register callbacks that are evaluated based on other factors or inputs at runtime.
 
-When {ref}`transitions` have guards, then it's possible to define two or more
-transitions for the same {ref}`event` from the same {ref}`state`. When the {ref}`event` happens, then
-the guarded transitions are checked, one by one, and the first transition
-whose guard is true will be used, and the others will be ignored.
+When a transition is conditional, it includes a condition (also known as a _guard_) that must be satisfied for the transition to take place. If the condition is not met, the transition does not occur, and the state machine remains in its current state or follows an alternative path.
 
-A guard is generally a boolean function or boolean variable and must not have any side effects.
-Side effects are reserved for {ref}`actions`.
+This feature allows for multiple transitions on the same {ref}`event`, with each {ref}`transition` checked in the order they are declared. A condition acts like a predicate (a function that evaluates to true/false) and is checked when a {ref}`statemachine` handles an {ref}`event` with a transition from the current state bound to this event. The first transition that meets the conditions (if any) is executed. If none of the transitions meet the conditions, the state machine either raises an exception or does nothing (see the `allow_event_without_transition` parameter of {ref}`StateMachine`).
+
+When {ref}`transitions` have guards, it is possible to define two or more transitions for the same {ref}`event` from the same {ref}`state`. When the {ref}`event` occurs, the guarded transitions are checked one by one, and the first transition whose guard is true will be executed, while the others will be ignored.
+
+A condition is generally a boolean function, property, or attribute, and must not have any side effects. Side effects are reserved for {ref}`actions`.
 
 There are two variations of Guard clauses available:
 
@@ -44,6 +42,11 @@ unless
 * Single condition: `unless="condition"`
 * Multiple conditions: `unless=["condition1", "condition2"]`
 
+```{seealso}
+See {ref}`sphx_glr_auto_examples_air_conditioner_machine.py` for an example of
+combining multiple transitions to the same event.
+```
+
 ```{hint}
 In Python, a boolean value is either `True` or `False`. However, there are also specific values that
 are considered "**falsy**" and will evaluate as `False` when used in a boolean context.

docs/index.md

@@ -13,6 +13,7 @@ actions
 guards
 models
 observers
+async
 mixins
 integrations
 diagram

docs/releases/2.3.0.md

@@ -0,0 +1,59 @@
+# StateMachine 2.3.0
+
+*Not released yet*
+
+## What's new in 2.3.0
+
+In this release, we conducted a significant update focusing on adding asynchronous support, and enhancing overall functionality. In fact, the approach we took was to go all the way down changing the internals of the library to be fully async, keeping only the current external API as a thin sync wrapper.
+
+Here are the major changes and new features:
+
+### Asynchronous Support in 2.3.0
+
+This release introduces native coroutine support using asyncio, enabling seamless integration with asynchronous code.
+
+Now you can send and await for events, and also write async {ref}`Actions`, {ref}`Conditions` and {ref}`Validators`.
+
+
+```{seealso}
+See {ref}`sphx_glr_auto_examples_air_conditioner_machine.py` for an example of
+async code with a state machine.
+```
+
+
+```py
+>>> class AsyncStateMachine(StateMachine):
+...     initial = State('Initial', initial=True)
+...     final = State('Final', final=True)
+...
+...     advance = initial.to(final)
+
+>>> async def run_sm():
+...     sm = AsyncStateMachine()
+...     await sm.advance()
+...     print(sm.current_state)
+
+>>> asyncio.run(run_sm())
+Final
+
+```
+
+
+### Manual Initial State Activation for Async Code
+
+When working with asynchronous state machines from async code, users must manually activate
+the initial 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.
+
+```py
+>>> async def initialize_sm():
+...     sm = AsyncStateMachine()
+...     await sm.activate_initial_state()
+...     return sm
+
+>>> sm = asyncio.run(initialize_sm())
+>>> print(sm.current_state)
+Initial
+
+```

docs/releases/index.md

@@ -15,6 +15,7 @@ Below are release notes through StateMachine and its patch releases.
 ```{toctree}
 :maxdepth: 2
 
+2.3.0
 2.2.0
 2.1.2
 2.1.1