feat: Support to declare States using Enum. Closes #367 (#375)

Author: fgmacedo

.pre-commit-config.yaml

@@ -9,11 +9,9 @@ repos:
         exclude: docs/auto_examples
 - repo: https://github.com/charliermarsh/ruff-pre-commit
   # Ruff version.
-  rev: 'v0.0.220'
+  rev: 'v0.0.257'
   hooks:
     - id: ruff
-      # Respect `exclude` and `extend-exclude` settings.
-      args: ["--force-exclude"]
 -   repo: https://github.com/psf/black
     rev: 22.10.0
     hooks:

docs/api.md

@@ -20,6 +20,14 @@
     :members:
 ```
 
+## States (class)
+
+```{eval-rst}
+.. autoclass:: statemachine.states.States
+    :noindex:
+    :members:
+```
+
 ## Transition
 
 ```{seealso}

docs/releases/2.0.1.md

@@ -0,0 +1,42 @@
+# StateMachine 2.1.0
+
+*Not released yet*
+
+## What's new in 2.1
+
+### Added support for declaring states using Enum
+
+Given an ``Enum`` type that declares our expected states:
+
+```py
+>>> from enum import Enum
+
+>>> class Status(Enum):
+...     pending = 1
+...     completed = 2
+
+```
+
+A {ref}`StateMachine` can be declared as follows:
+
+```py
+>>> from statemachine import StateMachine
+>>> from statemachine.states import States
+
+>>> class ApprovalMachine(StateMachine):
+...
+...     _ = States.from_enum(Status, initial=Status.pending, final=Status.completed)
+...
+...     finish = _.pending.to(_.completed)
+...
+...     def on_enter_completed(self):
+...         print("Completed!")
+
+```
+
+See {ref}`States from Enum types`.
+
+## Bugfixes
+
+- Fixes [#369](https://github.com/fgmacedo/python-statemachine/issues/369) adding support to wrap
+  methods used as {ref}`Actions` decorated with `functools.partial`.

docs/releases/2.1.0.md

@@ -15,7 +15,7 @@ Below are release notes through StateMachine and its patch releases.
 ```{toctree}
 :maxdepth: 1
 
-2.0.1
+2.1.0
 2.0.0
 
 ```

docs/releases/index.md

@@ -3,6 +3,15 @@
 
 {ref}`State`, as the name says, holds the representation of a state in a {ref}`StateMachine`.
 
+```{eval-rst}
+.. autoclass:: statemachine.state.State
+    :noindex:
+```
+
+```{seealso}
+How to define and attach [](actions.md) to {ref}`States`.
+```
+
 
 ## Initial state
 
@@ -58,6 +67,18 @@ You can retrieve all final states.
 
 ```
 
+## States from Enum types
+
+{ref}`States` can also be declared from standard `Enum` classes.
+
+For this, use {ref}`States (class)` to convert your `Enum` type to a list of {ref}`State` objects.
+
+
+```{eval-rst}
+.. automethod:: statemachine.states.States.from_enum
+  :noindex:
+```
+
 ```{seealso}
-How to define and attach [](actions.md) to {ref}`States`.
+See the example {ref}`sphx_glr_auto_examples_enum_campaign_machine.py`.
 ```

docs/states.md

@@ -40,7 +40,7 @@ pytest = "^7.2.0"
 pytest-cov = "^4.0.0"
 pytest-sugar = "^0.9.6"
 pydot = "^1.4.2"
-ruff = "^0.0.220"
+ruff = "^0.0.257"
 pre-commit = "^2.21.0"
 mypy = "^0.991"
 black = "^22.12.0"
@@ -100,6 +100,8 @@ select = [
 ]
 ignore = [
     "UP006", # `use-pep585-annotation` Requires Python3.9+
+    "UP035", # `use-pep585-annotation` Requires Python3.9+
+    "UP038", # `use-pep585-annotation` Requires Python3.9+
 ]
 
 line-length = 99

poetry.lock

@@ -1,3 +1,7 @@
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Dict
+from typing import Tuple
 from uuid import uuid4
 
 from . import registry
@@ -7,25 +11,35 @@
 from .graph import visit_connected_states
 from .i18n import _
 from .state import State
+from .states import States
 from .transition import Transition
 from .transition_list import TransitionList
 
 
 class StateMachineMetaclass(type):
-    def __init__(cls, name, bases, attrs):
+    def __init__(cls, name: str, bases: Tuple[type], attrs: Dict[str, Any]):
         super().__init__(name, bases, attrs)
         registry.register(cls)
-        cls._abstract = True
         cls.name = cls.__name__
-        cls.states = []
-        cls._events = {}
-        cls.states_map = {}
+        cls.states: States = States()
+        cls.states_map: Dict[Any, State] = {}
+        """Map of ``state.value`` to the corresponding :ref:`state`."""
+
+        cls._abstract = True
+        cls._events: Dict[str, Event] = {}
+
         cls.add_inherited(bases)
         cls.add_from_attributes(attrs)
 
         cls._set_special_states()
         cls._check()
 
+    if TYPE_CHECKING:
+        """Makes mypy happy with dynamic created attributes"""
+
+        def __getattr__(self, attribute: str) -> Any:
+            ...
+
     def _set_special_states(cls):
         if not cls.states:
             return
@@ -95,13 +109,19 @@ def add_inherited(cls, bases):
 
     def add_from_attributes(cls, attrs):
         for key, value in sorted(attrs.items(), key=lambda pair: pair[0]):
+            if isinstance(value, States):
+                cls._add_states_from_dict(value)
             if isinstance(value, State):
                 cls.add_state(key, value)
             elif isinstance(value, (Transition, TransitionList)):
                 cls.add_event(key, value)
             elif getattr(value, "_callbacks_to_update", None):
                 cls._add_unbounded_callback(key, value)
 
+    def _add_states_from_dict(cls, states):
+        for state_id, state in states.items():
+            cls.add_state(state_id, state)
+
     def _add_unbounded_callback(cls, attr_name, func):
         if func._is_event:
             # if func is an event, the `attr_name` will be replaced by an event trigger,
@@ -118,6 +138,8 @@ def add_state(cls, id, state: State):
         state._set_id(id)
         cls.states.append(state)
         cls.states_map[state.value] = state
+        if not hasattr(cls, id):
+            setattr(cls, id, state)
 
         # also register all events associated directly with transitions
         for event in state.transitions.unique_events:

pyproject.toml

@@ -1,6 +1,7 @@
 class Model:
     def __init__(self):
         self.state = None
+        """Holds the current :ref:`state` value of the :ref:`StateMachine`."""
 
     def __repr__(self):
         return f"Model(state={self.state})"