Merge branch 'release/2.3.2'

Author: fgmacedo

.pre-commit-config.yaml

@@ -21,7 +21,7 @@ repos:
   hooks:
   - id: mypy
     name: Mypy
-    entry: poetry run mypy statemachine/ tests/
+    entry: poetry run mypy --namespace-packages --explicit-package-bases statemachine/ tests/
     types: [python]
     language: system
     pass_filenames: false

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}"
 ```

conftest.py

@@ -1,3 +1,5 @@
+import sys
+
 import pytest
 
 
@@ -21,3 +23,11 @@ def __init__(self):
     doctest_namespace["State"] = State
     doctest_namespace["StateMachine"] = StateMachine
     doctest_namespace["asyncio"] = ContribAsyncio()
+
+
+def pytest_ignore_collect(collection_path, path, config):
+    if sys.version_info >= (3, 10):  # noqa: UP036
+        return None
+
+    if "django_project" in str(path):
+        return True

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/images/order_control_machine_initial.png

@@ -12,7 +12,7 @@ transitions
 actions
 guards
 models
-observers
+listeners
 async
 mixins
 integrations

docs/index.md

@@ -0,0 +1,107 @@
+
+(observers)=
+# Listeners
+
+Listeners are a way to generically add behavior to a state machine without
+changing its internal implementation.
+
+One possible use case is to add a listener that prints a log message when the SM runs a
+transition or enters a new state.
+
+Giving the {ref}`sphx_glr_auto_examples_traffic_light_machine.py` as example:
+
+
+```py
+>>> from tests.examples.traffic_light_machine import TrafficLightMachine
+
+>>> class LogListener(object):
+...     def __init__(self, name):
+...         self.name = name
+...
+...     def after_transition(self, event, source, target):
+...         print(f"{self.name} after: {source.id}--({event})-->{target.id}")
+...
+...     def on_enter_state(self, target, event):
+...         print(f"{self.name} enter: {target.id} from {event}")
+
+
+>>> sm = TrafficLightMachine(listeners=[LogListener("Paulista Avenue")])
+Paulista Avenue enter: green from __initial__
+
+>>> sm.cycle()
+Paulista Avenue enter: yellow from cycle
+Paulista Avenue after: green--(cycle)-->yellow
+'Running cycle from green to yellow'
+
+```
+
+## Adding listeners to an instance
+
+Attach listeners to an already running state machine instance using `add_listener`.
+
+Exploring our example, imagine that you can implement the LED panel as a listener, that
+reacts to state changes and turn on/off automatically.
+
+
+``` py
+>>> class LedPanel:
+...
+...     def __init__(self, color: str):
+...         self.color = color
+...
+...     def on_enter_state(self, target: State):
+...         if target.id == self.color:
+...             print(f"{self.color} turning on")
+...
+...     def on_exit_state(self, source: State):
+...         if source.id == self.color:
+...             print(f"{self.color} turning off")
+
+```
+
+Adding a listener for each traffic light indicator
+
+```
+>>> sm.add_listener(LedPanel("green"), LedPanel("yellow"), LedPanel("red"))  # doctest: +ELLIPSIS
+TrafficLightMachine...
+
+```
+
+Now each "LED panel" reacts to changes in state from the state machine:
+
+```py
+>>> sm.cycle()
+yellow turning off
+Paulista Avenue enter: red from cycle
+red turning on
+Don't move.
+Paulista Avenue after: yellow--(cycle)-->red
+'Running cycle from yellow to red'
+
+>>> sm.cycle()
+red turning off
+Go ahead!
+Paulista Avenue enter: green from cycle
+green turning on
+Paulista Avenue after: red--(cycle)-->green
+'Running cycle from red to green'
+
+```
+
+
+```{hint}
+The `StateMachine` itself is registered as a listener, so by using `listeners` an
+external object can have the same level of functionalities provided to the built-in class.
+```
+
+```{tip}
+{ref}`domain models` are also registered as a listener.
+```
+
+
+```{seealso}
+See {ref}`actions`, {ref}`validators and guards` for a list of possible callbacks.
+
+And also {ref}`dynamic-dispatch` to know more about how the lib calls methods to match
+their signature.
+```

docs/listeners.md

@@ -44,6 +44,7 @@ class.
 ...     state_machine_name = '__main__.CampaignMachineWithKeys'
 ...     state_machine_attr = 'sm'
 ...     state_field_name = 'workflow_step'
+...     bind_events_as_methods = True
 ...
 ...     workflow_step = 1
 ...
@@ -65,7 +66,11 @@ True
 >>> model.sm.current_state == model.sm.draft
 True
 
->>> model.sm.cancel()
+>>> model.produce()  # `bind_events_as_methods = True` adds triggers to events in the mixin instance
+>>> model.workflow_step
+2
+
+>>> model.sm.cancel()  # You can still call the SM directly
 
 >>> model.workflow_step
 4

docs/mixins.md

@@ -20,7 +20,7 @@ domain object to hold attributes and methods to be used on the `StateMachine` de
 ```
 
 ```{hint}
-Domain models are registered as {ref}`observers`, so you can have the same level of functionalities
+Domain models are registered as {ref}`listeners`, so you can have the same level of functionalities
 provided to the built-in {ref}`StateMachine`, such as implementing all {ref}`actions` and
 {ref}`guards` on your domain model and keeping only the definition of {ref}`states` and
 {ref}`transitions` on the {ref}`StateMachine`.