Merge tag 'v2.2.0' into develop

In this release, we conducted a general cleanup and refactoring across
various modules to enhance code readability and maintainability. We
improved exception handling and reduced code redundancy.

As a result, we achieved a **~2.2x** faster setup in our performance
tests and significantly simplified the callback machinery.

Author: fgmacedo

docs/mixins.md

@@ -25,8 +25,8 @@ Given a state machine definition:
 ...     "A workflow machine"
 ...     draft = State('Draft', initial=True, value=1)
 ...     producing = State('Being produced', value=2)
-...     closed = State('Closed', value=3)
-...     cancelled = State('Cancelled', value=4)
+...     closed = State('Closed', value=3, final=True)
+...     cancelled = State('Cancelled', value=4, final=True)
 ...
 ...     add_job = draft.to.itself() | producing.to.itself()
 ...     produce = draft.to(producing)

docs/processing_model.md

@@ -32,7 +32,7 @@ Consider this state machine:
 >>> class ServerConnection(StateMachine):
 ...     disconnected = State(initial=True)
 ...     connecting = State()
-...     connected = State()
+...     connected = State(final=True)
 ...
 ...     connect = disconnected.to(connecting, after="connection_succeed")
 ...     connection_succeed = connecting.to(connected)

docs/releases/2.2.0.md

@@ -1,6 +1,6 @@
 # StateMachine 2.2.0
 
-*Not released yet*
+*May  6, 2024*
 
 ## What's new in 2.2.0
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-statemachine"
-version = "2.1.2"
+version = "2.2.0"
 description = "Python Finite State Machines made easy."
 authors = ["Fernando Macedo <[email protected]>"]
 maintainers = [

statemachine/__init__.py

@@ -3,6 +3,6 @@
 
 __author__ = """Fernando Macedo"""
 __email__ = "[email protected]"
-__version__ = "2.1.2"
+__version__ = "2.2.0"
 
 __all__ = ["StateMachine", "State"]

statemachine/factory.py

@@ -113,7 +113,7 @@ def _check_trap_states(cls):
             if cls._strict_states:
                 raise InvalidDefinition(message)
             else:
-                warnings.warn(message, UserWarning, stacklevel=1)
+                warnings.warn(message, UserWarning, stacklevel=4)
 
     def _check_reachable_final_states(cls):
         if not any(s.final for s in cls.states):

statemachine/states.py

@@ -15,21 +15,23 @@ class States:
     Helps creating :ref:`StateMachine`'s :ref:`state` definitions from other
     sources, like an ``Enum`` class, using :meth:`States.from_enum`.
 
+    >>> states_def = [('open', {'initial': True}), ('closed', {'final': True})]
+
     >>> from statemachine import StateMachine
     >>> class SM(StateMachine):
     ...
     ...     states = States({
-    ...         name: State(initial=idx == 0) for idx, name in enumerate(["initial", "final"])
+    ...         name: State(**params) for name, params in states_def
     ...     })
     ...
-    ...     finish = states.initial.to(states.final)
+    ...     close = states.open.to(states.closed)
 
     And states can be used as usual.
 
     >>> sm = SM()
-    >>> sm.send("finish")
+    >>> sm.send("close")
     >>> sm.current_state.id
-    'final'
+    'closed'
 
     """
 

tests/test_callbacks.py

@@ -187,8 +187,8 @@ def race_uppercase(race):
     def test_decorate_unbounded_machine_methods(self):
         class MiniHeroJourneyMachine(StateMachine, strict_states=False):
             ordinary_world = State(initial=True)
-            call_to_adventure = State()
-            refusal_of_call = State()
+            call_to_adventure = State(final=True)
+            refusal_of_call = State(final=True)
 
             adventure_called = ordinary_world.to(call_to_adventure)
 

tests/test_statemachine.py

@@ -383,7 +383,7 @@ def test_state_value_is_correct():
 
     class ValueTestModel(StateMachine, strict_states=False):
         new = State(STATE_NEW, value=STATE_NEW, initial=True)
-        draft = State(STATE_DRAFT, value=STATE_DRAFT)
+        draft = State(STATE_DRAFT, value=STATE_DRAFT, final=True)
 
         write = new.to(draft)
 

tests/testcases/issue406.md

@@ -11,7 +11,7 @@ In this example, the event callback must be registered only once.
 
 >>> class ExampleStateMachine(StateMachine, strict_states=False):
 ...     Created = State(initial=True)
-...     Inited = State()
+...     Inited = State(final=True)
 ...
 ...     initialize = Created.to(Inited)
 ...