Merge branch 'release/2.3.3'

Author: fgmacedo

docs/releases/2.3.3.md

@@ -0,0 +1,20 @@
+# StateMachine 2.3.3
+
+*July 3, 2024*
+
+
+## Bugfixes in 2.3.3
+
+- Fixes [#457](https://github.com/fgmacedo/python-statemachine/issues/457) regression that caused backwards incomplatible changes when using Enums. Thanks [@hperrey](https://github.com/hperrey)!
+
+
+
+## Deprecation notes in 2.3.3
+
+Deprecations that will be removed on the next major release:
+
+- The `States.from_enum(..., use_enum_instance=True)` will be the default.
+
+```{seealso}
+See {ref}`States from Enum types` for more details.
+```

docs/releases/index.md

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

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-statemachine"
-version = "2.3.2"
+version = "2.3.3"
 description = "Python Finite State Machines made easy."
 authors = ["Fernando Macedo <fgmacedo@gmail.com>"]
 maintainers = [

statemachine/__init__.py

@@ -3,6 +3,6 @@
 
 __author__ = """Fernando Macedo"""
 __email__ = "fgmacedo@gmail.com"
-__version__ = "2.3.2"
+__version__ = "2.3.3"
 
 __all__ = ["StateMachine", "State"]

statemachine/callbacks.py

@@ -1,6 +1,5 @@
 import asyncio
 from bisect import insort
-from collections import Counter
 from collections import defaultdict
 from collections import deque
 from enum import IntEnum
@@ -335,7 +334,7 @@ def all(self, *args, **kwargs):
 class CallbacksRegistry:
     def __init__(self) -> None:
         self._registry: Dict[str, CallbacksExecutor] = defaultdict(CallbacksExecutor)
-        self._method_types: Counter = Counter()
+        self.has_async_callbacks: bool = False
 
     def clear(self):
         self._registry.clear()
@@ -357,6 +356,6 @@ def check(self, specs: CallbackSpecList):
             )
 
     def async_or_sync(self):
-        self._method_types.update(
+        self.has_async_callbacks = any(
             callback._iscoro for executor in self._registry.values() for callback in executor
         )

statemachine/engines/async_.py

@@ -31,9 +31,9 @@ async def activate_initial_state(self):
         Given how async works on python, there's no built-in way to activate the initial state that
         may depend on async code from the StateMachine.__init__ method.
         """
-        return await self._processing_loop()
+        return await self.processing_loop()
 
-    async def _processing_loop(self):
+    async def processing_loop(self):
         """Process event triggers.
 
         The simplest implementation is the non-RTC (synchronous),

statemachine/engines/sync.py

@@ -29,9 +29,9 @@ def activate_initial_state(self):
         Given how async works on python, there's no built-in way to activate the initial state that
         may depend on async code from the StateMachine.__init__ method.
         """
-        return self._processing_loop()
+        return self.processing_loop()
 
-    def _processing_loop(self):
+    def processing_loop(self):
         """Process event triggers.
 
         The simplest implementation is the non-RTC (synchronous),

statemachine/statemachine.py

@@ -106,7 +106,7 @@ def __init__(
         self._engine = self._get_engine(rtc)
 
     def _get_engine(self, rtc: bool):
-        if self._callbacks_registry._method_types[True] > 0:
+        if self._callbacks_registry.has_async_callbacks:
             return AsyncEngine(self, rtc=rtc)
         else:
             return SyncEngine(self, rtc=rtc)
@@ -118,7 +118,7 @@ def activate_initial_state(self):
         return run_async_from_sync(result)
 
     def _processing_loop(self):
-        return self._engine._processing_loop()
+        return self._engine.processing_loop()
 
     def __init_subclass__(cls, strict_states: bool = False):
         cls._strict_states = strict_states
@@ -303,9 +303,6 @@ def _put_nonblocking(self, trigger_data: TriggerData):
     def send(self, event: str, *args, **kwargs):
         """Send an :ref:`Event` to the state machine.
 
-        This is a thin wrapper around :meth:`async_send` to allow synchronous
-        code to send events.
-
         .. seealso::
 
             See: :ref:`triggering events`.

statemachine/states.py

@@ -54,7 +54,6 @@ def __eq__(self, other):
         return list(self) == list(other)
 
     def __getattr__(self, name: str):
-        name = name.lower()
         if name in self._states:
             return self._states[name]
         raise AttributeError(f"{name} not found in {self.__class__.__name__}")
@@ -81,7 +80,7 @@ def items(self):
         return self._states.items()
 
     @classmethod
-    def from_enum(cls, enum_type: EnumType, initial, final=None):
+    def from_enum(cls, enum_type: EnumType, initial, final=None, use_enum_instance: bool = False):
         """
         Creates a new instance of the ``States`` class from an enumeration.
 
@@ -125,20 +124,37 @@ def from_enum(cls, enum_type: EnumType, initial, final=None):
         True
 
         >>> sm.current_state_value
+        2
+
+        If you need to use the enum instance as the state value, you can set the
+        ``use_enum_instance=True``:
+
+        >>> states = States.from_enum(Status, initial=Status.pending, use_enum_instance=True)
+        >>> states.completed.value
         <Status.completed: 2>
 
+        .. deprecated:: 2.3.3
+
+            On the next major release, the ``use_enum_instance=True`` will be the default.
+
         Args:
             enum_type: An enumeration containing the states of the machine.
             initial: The initial state of the machine.
             final: A set of final states of the machine.
+            use_enum_instance: If ``True``, the value of the state will be the enum item instance,
+                otherwise the enum item value.
 
         Returns:
             A new instance of the :ref:`States (class)`.
         """
         final_set = set(ensure_iterable(final))
         return cls(
             {
-                e.name.lower(): State(value=e, initial=e is initial, final=e in final_set)
+                e.name: State(
+                    value=(e if use_enum_instance else e.value),
+                    initial=e is initial,
+                    final=e in final_set,
+                )
                 for e in enum_type
             }
         )

tests/django_project/workflow/statemachines.py

@@ -7,8 +7,8 @@
 class WorfklowStateMachine(StateMachine):
     _ = States.from_enum(WorkflowSteps, initial=WorkflowSteps.DRAFT, final=WorkflowSteps.PUBLISHED)
 
-    publish = _.draft.to(_.published, cond="is_active")
-    notify_user = _.draft.to.itself(internal=True, cond="has_user")
+    publish = _.DRAFT.to(_.PUBLISHED, cond="is_active")
+    notify_user = _.DRAFT.to.itself(internal=True, cond="has_user")
 
     def has_user(self):
         return bool(self.model.user)