fix: symmetric state param for on_exit_state across compound boundaries

docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

docs/behaviour.md

@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

docs/events.md

@@ -131,6 +131,83 @@ delayed events, and cancellation.
 ```
 
 
+(events-as-method-protocol)=
+
+## Events as a method-call protocol
+
+Because every event is a callable method, a state machine can act as a guard
+for the **order** in which your object's methods may be called. Set
+`allow_event_without_transition = False` so that any call that doesn't match an
+enabled transition raises `TransitionNotAllowed` instead of being silently
+ignored. The transitions then describe the legal
+sequence, and the machine enforces it for you:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Connection(StateChart):
+... "A client whose methods can only be called in a valid order."
+... allow_event_without_transition = False # reject any unexpected call
+...
+... disconnected = State(initial=True)
+... connected = State()
+... authenticated = State()
+...
+... connect = disconnected.to(connected)
+... authenticate = connected.to(authenticated)
+... disconnect = connected.to(disconnected) | authenticated.to(disconnected)
+...
+... def on_connect(self):
+... print("socket opened")
+...
+... def on_authenticate(self):
+... print("credentials accepted")
+
+```
+
+Calling the methods in a valid order works:
+
+```py
+>>> conn = Connection()
+>>> conn.connect()
+socket opened
+>>> conn.authenticate()
+credentials accepted
+>>> "authenticated" in conn.configuration_values
+True
+
+```
+
+A call that isn't valid in the current state raises, so an out-of-order method
+call fails loudly instead of doing nothing:
+
+```py
+>>> fresh = Connection()
+
+>>> fresh.authenticate() # must connect first
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't Authenticate when in Disconnected.
+
+```
+
+The same protection applies to unknown event names sent dynamically:
+
+```py
+>>> fresh.send("teleport")
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't teleport when in Disconnected.
+
+```
+
+```{seealso}
+{ref}`behaviour` explains `allow_event_without_transition` and the other
+class-level flags that switch between this strict mode and the tolerant,
+event-driven default.
+```
+
+
 (event-parameter)=
 
 ## The `event` parameter on transitions

docs/releases/3.2.1.md

@@ -0,0 +1,71 @@
+# StateChart 3.2.1
+
+*Not released yet*
+
+## Bug fixes in 3.2.1
+
+### Symmetric `state` for `on_exit_state` across compound boundaries
+
+When exiting a compound state directly (a transition like `child -> outsider`),
+the generic `on_exit_state()` callback reported the transition's `source` for
+**every** exited state. Exiting `child` and its parent `parent` both arrived
+with `state` and `source` bound to `child`, so the parent level was never
+observable and the two exit calls were indistinguishable.
+
+This was asymmetric with `on_enter_state()`, which already binds `state` (and
+`target`) to each individual state being entered. The exit side now matches:
+`state` (and `source`) is bound to the individual state being exited.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class FSM(StateChart):
+... orphan = State(initial=True)
+...
+... class parent(State.Compound):
+... child = State()
+...
+... switch = orphan.to(parent.child) | parent.child.to(orphan)
+...
+... def on_exit_state(self, source, state):
+... print(f"exit {state.id} (source={source.id})")
+
+>>> sm = FSM()
+>>> sm.send("switch")
+exit orphan (source=orphan)
+>>> sm.send("switch")
+exit child (source=child)
+exit parent (source=parent)
+
+```
+
+Before this fix, the last line read `exit child (source=child)`, hiding the
+parent. State-specific callbacks (`on_exit_<state>`) were already correctly
+keyed per state and are unaffected. Flat (non-compound) machines are also
+unaffected, since there the exited state is always the transition's `source`.
+
+[#634](https://github.com/fgmacedo/python-statemachine/issues/634).
+
+### Negative indices in `OrderedSet.__getitem__`
+
+`OrderedSet.__getitem__` raised `ValueError` (leaking from `itertools.islice`)
+when called with a negative index, instead of following the sequence protocol.
+Negative indices now count from the end like any Python sequence, and an index
+that is still out of range after normalisation raises `IndexError`:
+
+```py
+>>> from statemachine.orderedset import OrderedSet
+
+>>> s = OrderedSet([1, 2, 3])
+>>> s[-1]
+3
+>>> s[-3]
+1
+>>> s[-4]
+Traceback (most recent call last):
+ ...
+IndexError: index -4 out of range
+
+```
+
+[#633](https://github.com/fgmacedo/python-statemachine/pull/633).

docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.10+.
 ```{toctree}
 :maxdepth: 2
 
+3.2.1
 3.2.0
 3.1.2
 3.1.1

statemachine/engines/async_.py

@@ -71,17 +71,27 @@ def _reject_pending_futures(self, exc: Exception):
  # --- Callback dispatch overrides (async versions of BaseEngine methods) ---
 
  async def _get_args_kwargs(
- self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: "Transition",
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # See the sync engine for the rationale: bind `state`/`target` to the
+ # entered state and `state`/`source` to the exited state, keeping the
+ # generic enter/exit callbacks symmetric across compound boundaries.
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -173,7 +183,9 @@ async def _exit_states( # type: ignore[override]
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = await self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = await self._get_args_kwargs(
+ info.transition, trigger_data, source=info.state
+ )
 
  if info.state is not None: # pragma: no branch
  self._debug("%s Exiting state: %s", self._log_id, info.state)

statemachine/engines/base.py

@@ -419,19 +419,30 @@ def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
  return result
 
  def _get_args_kwargs(
- self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: Transition,
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
  # Generate a unique key for the cache, the cache is invalidated once per loop
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  # Check the cache for existing results
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # Bind `state`/`target` to the individual state being entered, and
+ # `state`/`source` to the individual state being exited, so the generic
+ # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+ # compound state boundaries (the transition only knows its own endpoints).
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -500,7 +511,7 @@ def _exit_states(
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
 
  # Execute `onexit` handlers — same per-block error isolation as onentry.
  if info.state is not None: # pragma: no branch

tests/test_statechart_compound.py

@@ -123,6 +123,56 @@ def on_enter_outside(self):
  await sm_runner.send(sm, "leave")
  assert log == ["exit_day", "exit_realm", "enter_outside"]
 
+ async def test_generic_enter_exit_state_param_is_symmetric(self, sm_runner):
+ """Generic ``on_enter_state``/``on_exit_state`` bind ``state`` to the
+ individual state being crossed, symmetrically in both directions.
+
+ Regression test for #634: exiting a compound used to report the
+ transition ``source`` for every exited state (``child`` twice), so the
+ parent state was never observable. Entering already reported the
+ individual state, so the two callbacks were asymmetric.
+ """
+ enters: list = []
+ exits: list = []
+
+ class SymmetricCompound(StateChart):
+ orphan = State(initial=True)
+
+ class parent(State.Compound):
+ child = State()
+
+ switch = orphan.to(parent.child) | parent.child.to(orphan)
+
+ def on_enter_state(self, source, target, state):
+ enters.append((source.id, target.id, state.id))
+
+ def on_exit_state(self, source, target, state):
+ exits.append((source.id, target.id, state.id))
+
+ sm = await sm_runner.start(SymmetricCompound)
+ enters.clear()
+ exits.clear()
+
+ # Enter the compound: `state`/`target` track each entered state.
+ await sm_runner.send(sm, "switch")
+ assert enters == [
+ ("orphan", "parent", "parent"),
+ ("orphan", "child", "child"),
+ ]
+ assert exits == [("orphan", "child", "orphan")]
+
+ enters.clear()
+ exits.clear()
+
+ # Exit the compound: `state`/`source` track each exited state, so the
+ # parent is now distinguishable from the child.
+ await sm_runner.send(sm, "switch")
+ assert exits == [
+ ("child", "orphan", "child"),
+ ("parent", "orphan", "parent"),
+ ]
+ assert enters == [("child", "orphan", "orphan")]
+
  async def test_callbacks_inside_compound_class(self, sm_runner):
  """Methods defined inside the State.Compound class body are discovered."""
  log = []

docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

docs/behaviour.md

@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

docs/events.md

@@ -131,6 +131,83 @@ delayed events, and cancellation.
 ```
 
 
+(events-as-method-protocol)=
+
+## Events as a method-call protocol
+
+Because every event is a callable method, a state machine can act as a guard
+for the **order** in which your object's methods may be called. Set
+`allow_event_without_transition = False` so that any call that doesn't match an
+enabled transition raises `TransitionNotAllowed` instead of being silently
+ignored. The transitions then describe the legal
+sequence, and the machine enforces it for you:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Connection(StateChart):
+... "A client whose methods can only be called in a valid order."
+... allow_event_without_transition = False # reject any unexpected call
+...
+... disconnected = State(initial=True)
+... connected = State()
+... authenticated = State()
+...
+... connect = disconnected.to(connected)
+... authenticate = connected.to(authenticated)
+... disconnect = connected.to(disconnected) | authenticated.to(disconnected)
+...
+... def on_connect(self):
+... print("socket opened")
+...
+... def on_authenticate(self):
+... print("credentials accepted")
+
+```
+
+Calling the methods in a valid order works:
+
+```py
+>>> conn = Connection()
+>>> conn.connect()
+socket opened
+>>> conn.authenticate()
+credentials accepted
+>>> "authenticated" in conn.configuration_values
+True
+
+```
+
+A call that isn't valid in the current state raises, so an out-of-order method
+call fails loudly instead of doing nothing:
+
+```py
+>>> fresh = Connection()
+
+>>> fresh.authenticate() # must connect first
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't Authenticate when in Disconnected.
+
+```
+
+The same protection applies to unknown event names sent dynamically:
+
+```py
+>>> fresh.send("teleport")
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't teleport when in Disconnected.
+
+```
+
+```{seealso}
+{ref}`behaviour` explains `allow_event_without_transition` and the other
+class-level flags that switch between this strict mode and the tolerant,
+event-driven default.
+```
+
+
 (event-parameter)=
 
 ## The `event` parameter on transitions

docs/releases/3.2.1.md

@@ -0,0 +1,71 @@
+# StateChart 3.2.1
+
+*Not released yet*
+
+## Bug fixes in 3.2.1
+
+### Symmetric `state` for `on_exit_state` across compound boundaries
+
+When exiting a compound state directly (a transition like `child -> outsider`),
+the generic `on_exit_state()` callback reported the transition's `source` for
+**every** exited state. Exiting `child` and its parent `parent` both arrived
+with `state` and `source` bound to `child`, so the parent level was never
+observable and the two exit calls were indistinguishable.
+
+This was asymmetric with `on_enter_state()`, which already binds `state` (and
+`target`) to each individual state being entered. The exit side now matches:
+`state` (and `source`) is bound to the individual state being exited.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class FSM(StateChart):
+... orphan = State(initial=True)
+...
+... class parent(State.Compound):
+... child = State()
+...
+... switch = orphan.to(parent.child) | parent.child.to(orphan)
+...
+... def on_exit_state(self, source, state):
+... print(f"exit {state.id} (source={source.id})")
+
+>>> sm = FSM()
+>>> sm.send("switch")
+exit orphan (source=orphan)
+>>> sm.send("switch")
+exit child (source=child)
+exit parent (source=parent)
+
+```
+
+Before this fix, the last line read `exit child (source=child)`, hiding the
+parent. State-specific callbacks (`on_exit_<state>`) were already correctly
+keyed per state and are unaffected. Flat (non-compound) machines are also
+unaffected, since there the exited state is always the transition's `source`.
+
+[#634](https://github.com/fgmacedo/python-statemachine/issues/634).
+
+### Negative indices in `OrderedSet.__getitem__`
+
+`OrderedSet.__getitem__` raised `ValueError` (leaking from `itertools.islice`)
+when called with a negative index, instead of following the sequence protocol.
+Negative indices now count from the end like any Python sequence, and an index
+that is still out of range after normalisation raises `IndexError`:
+
+```py
+>>> from statemachine.orderedset import OrderedSet
+
+>>> s = OrderedSet([1, 2, 3])
+>>> s[-1]
+3
+>>> s[-3]
+1
+>>> s[-4]
+Traceback (most recent call last):
+ ...
+IndexError: index -4 out of range
+
+```
+
+[#633](https://github.com/fgmacedo/python-statemachine/pull/633).

docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.10+.
 ```{toctree}
 :maxdepth: 2
 
+3.2.1
 3.2.0
 3.1.2
 3.1.1

statemachine/engines/async_.py

@@ -71,17 +71,27 @@ def _reject_pending_futures(self, exc: Exception):
  # --- Callback dispatch overrides (async versions of BaseEngine methods) ---
 
  async def _get_args_kwargs(
- self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: "Transition",
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # See the sync engine for the rationale: bind `state`/`target` to the
+ # entered state and `state`/`source` to the exited state, keeping the
+ # generic enter/exit callbacks symmetric across compound boundaries.
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -173,7 +183,9 @@ async def _exit_states( # type: ignore[override]
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = await self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = await self._get_args_kwargs(
+ info.transition, trigger_data, source=info.state
+ )
 
  if info.state is not None: # pragma: no branch
  self._debug("%s Exiting state: %s", self._log_id, info.state)

statemachine/engines/base.py

@@ -419,19 +419,30 @@ def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
  return result
 
  def _get_args_kwargs(
- self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: Transition,
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
  # Generate a unique key for the cache, the cache is invalidated once per loop
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  # Check the cache for existing results
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # Bind `state`/`target` to the individual state being entered, and
+ # `state`/`source` to the individual state being exited, so the generic
+ # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+ # compound state boundaries (the transition only knows its own endpoints).
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -500,7 +511,7 @@ def _exit_states(
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
 
  # Execute `onexit` handlers — same per-block error isolation as onentry.
  if info.state is not None: # pragma: no branch

tests/test_statechart_compound.py

@@ -123,6 +123,56 @@ def on_enter_outside(self):
  await sm_runner.send(sm, "leave")
  assert log == ["exit_day", "exit_realm", "enter_outside"]
 
+ async def test_generic_enter_exit_state_param_is_symmetric(self, sm_runner):
+ """Generic ``on_enter_state``/``on_exit_state`` bind ``state`` to the
+ individual state being crossed, symmetrically in both directions.
+
+ Regression test for #634: exiting a compound used to report the
+ transition ``source`` for every exited state (``child`` twice), so the
+ parent state was never observable. Entering already reported the
+ individual state, so the two callbacks were asymmetric.
+ """
+ enters: list = []
+ exits: list = []
+
+ class SymmetricCompound(StateChart):
+ orphan = State(initial=True)
+
+ class parent(State.Compound):
+ child = State()
+
+ switch = orphan.to(parent.child) | parent.child.to(orphan)
+
+ def on_enter_state(self, source, target, state):
+ enters.append((source.id, target.id, state.id))
+
+ def on_exit_state(self, source, target, state):
+ exits.append((source.id, target.id, state.id))
+
+ sm = await sm_runner.start(SymmetricCompound)
+ enters.clear()
+ exits.clear()
+
+ # Enter the compound: `state`/`target` track each entered state.
+ await sm_runner.send(sm, "switch")
+ assert enters == [
+ ("orphan", "parent", "parent"),
+ ("orphan", "child", "child"),
+ ]
+ assert exits == [("orphan", "child", "orphan")]
+
+ enters.clear()
+ exits.clear()
+
+ # Exit the compound: `state`/`source` track each exited state, so the
+ # parent is now distinguishable from the child.
+ await sm_runner.send(sm, "switch")
+ assert exits == [
+ ("child", "orphan", "child"),
+ ("parent", "orphan", "parent"),
+ ]
+ assert enters == [("child", "orphan", "orphan")]
+
  async def test_callbacks_inside_compound_class(self, sm_runner):
  """Methods defined inside the State.Compound class body are discovered."""
  log = []

docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

docs/behaviour.md

@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

docs/events.md

@@ -131,6 +131,83 @@ delayed events, and cancellation.
 ```
 
 
+(events-as-method-protocol)=
+
+## Events as a method-call protocol
+
+Because every event is a callable method, a state machine can act as a guard
+for the **order** in which your object's methods may be called. Set
+`allow_event_without_transition = False` so that any call that doesn't match an
+enabled transition raises `TransitionNotAllowed` instead of being silently
+ignored. The transitions then describe the legal
+sequence, and the machine enforces it for you:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Connection(StateChart):
+... "A client whose methods can only be called in a valid order."
+... allow_event_without_transition = False # reject any unexpected call
+...
+... disconnected = State(initial=True)
+... connected = State()
+... authenticated = State()
+...
+... connect = disconnected.to(connected)
+... authenticate = connected.to(authenticated)
+... disconnect = connected.to(disconnected) | authenticated.to(disconnected)
+...
+... def on_connect(self):
+... print("socket opened")
+...
+... def on_authenticate(self):
+... print("credentials accepted")
+
+```
+
+Calling the methods in a valid order works:
+
+```py
+>>> conn = Connection()
+>>> conn.connect()
+socket opened
+>>> conn.authenticate()
+credentials accepted
+>>> "authenticated" in conn.configuration_values
+True
+
+```
+
+A call that isn't valid in the current state raises, so an out-of-order method
+call fails loudly instead of doing nothing:
+
+```py
+>>> fresh = Connection()
+
+>>> fresh.authenticate() # must connect first
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't Authenticate when in Disconnected.
+
+```
+
+The same protection applies to unknown event names sent dynamically:
+
+```py
+>>> fresh.send("teleport")
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't teleport when in Disconnected.
+
+```
+
+```{seealso}
+{ref}`behaviour` explains `allow_event_without_transition` and the other
+class-level flags that switch between this strict mode and the tolerant,
+event-driven default.
+```
+
+
 (event-parameter)=
 
 ## The `event` parameter on transitions

docs/releases/3.2.1.md

@@ -0,0 +1,71 @@
+# StateChart 3.2.1
+
+*Not released yet*
+
+## Bug fixes in 3.2.1
+
+### Symmetric `state` for `on_exit_state` across compound boundaries
+
+When exiting a compound state directly (a transition like `child -> outsider`),
+the generic `on_exit_state()` callback reported the transition's `source` for
+**every** exited state. Exiting `child` and its parent `parent` both arrived
+with `state` and `source` bound to `child`, so the parent level was never
+observable and the two exit calls were indistinguishable.
+
+This was asymmetric with `on_enter_state()`, which already binds `state` (and
+`target`) to each individual state being entered. The exit side now matches:
+`state` (and `source`) is bound to the individual state being exited.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class FSM(StateChart):
+... orphan = State(initial=True)
+...
+... class parent(State.Compound):
+... child = State()
+...
+... switch = orphan.to(parent.child) | parent.child.to(orphan)
+...
+... def on_exit_state(self, source, state):
+... print(f"exit {state.id} (source={source.id})")
+
+>>> sm = FSM()
+>>> sm.send("switch")
+exit orphan (source=orphan)
+>>> sm.send("switch")
+exit child (source=child)
+exit parent (source=parent)
+
+```
+
+Before this fix, the last line read `exit child (source=child)`, hiding the
+parent. State-specific callbacks (`on_exit_<state>`) were already correctly
+keyed per state and are unaffected. Flat (non-compound) machines are also
+unaffected, since there the exited state is always the transition's `source`.
+
+[#634](https://github.com/fgmacedo/python-statemachine/issues/634).
+
+### Negative indices in `OrderedSet.__getitem__`
+
+`OrderedSet.__getitem__` raised `ValueError` (leaking from `itertools.islice`)
+when called with a negative index, instead of following the sequence protocol.
+Negative indices now count from the end like any Python sequence, and an index
+that is still out of range after normalisation raises `IndexError`:
+
+```py
+>>> from statemachine.orderedset import OrderedSet
+
+>>> s = OrderedSet([1, 2, 3])
+>>> s[-1]
+3
+>>> s[-3]
+1
+>>> s[-4]
+Traceback (most recent call last):
+ ...
+IndexError: index -4 out of range
+
+```
+
+[#633](https://github.com/fgmacedo/python-statemachine/pull/633).

docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.10+.
 ```{toctree}
 :maxdepth: 2
 
+3.2.1
 3.2.0
 3.1.2
 3.1.1

statemachine/engines/async_.py

@@ -71,17 +71,27 @@ def _reject_pending_futures(self, exc: Exception):
  # --- Callback dispatch overrides (async versions of BaseEngine methods) ---
 
  async def _get_args_kwargs(
- self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: "Transition",
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # See the sync engine for the rationale: bind `state`/`target` to the
+ # entered state and `state`/`source` to the exited state, keeping the
+ # generic enter/exit callbacks symmetric across compound boundaries.
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -173,7 +183,9 @@ async def _exit_states( # type: ignore[override]
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = await self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = await self._get_args_kwargs(
+ info.transition, trigger_data, source=info.state
+ )
 
  if info.state is not None: # pragma: no branch
  self._debug("%s Exiting state: %s", self._log_id, info.state)

statemachine/engines/base.py

@@ -419,19 +419,30 @@ def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
  return result
 
  def _get_args_kwargs(
- self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: Transition,
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
  # Generate a unique key for the cache, the cache is invalidated once per loop
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  # Check the cache for existing results
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # Bind `state`/`target` to the individual state being entered, and
+ # `state`/`source` to the individual state being exited, so the generic
+ # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+ # compound state boundaries (the transition only knows its own endpoints).
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -500,7 +511,7 @@ def _exit_states(
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
 
  # Execute `onexit` handlers — same per-block error isolation as onentry.
  if info.state is not None: # pragma: no branch

tests/test_statechart_compound.py

@@ -123,6 +123,56 @@ def on_enter_outside(self):
  await sm_runner.send(sm, "leave")
  assert log == ["exit_day", "exit_realm", "enter_outside"]
 
+ async def test_generic_enter_exit_state_param_is_symmetric(self, sm_runner):
+ """Generic ``on_enter_state``/``on_exit_state`` bind ``state`` to the
+ individual state being crossed, symmetrically in both directions.
+
+ Regression test for #634: exiting a compound used to report the
+ transition ``source`` for every exited state (``child`` twice), so the
+ parent state was never observable. Entering already reported the
+ individual state, so the two callbacks were asymmetric.
+ """
+ enters: list = []
+ exits: list = []
+
+ class SymmetricCompound(StateChart):
+ orphan = State(initial=True)
+
+ class parent(State.Compound):
+ child = State()
+
+ switch = orphan.to(parent.child) | parent.child.to(orphan)
+
+ def on_enter_state(self, source, target, state):
+ enters.append((source.id, target.id, state.id))
+
+ def on_exit_state(self, source, target, state):
+ exits.append((source.id, target.id, state.id))
+
+ sm = await sm_runner.start(SymmetricCompound)
+ enters.clear()
+ exits.clear()
+
+ # Enter the compound: `state`/`target` track each entered state.
+ await sm_runner.send(sm, "switch")
+ assert enters == [
+ ("orphan", "parent", "parent"),
+ ("orphan", "child", "child"),
+ ]
+ assert exits == [("orphan", "child", "orphan")]
+
+ enters.clear()
+ exits.clear()
+
+ # Exit the compound: `state`/`source` track each exited state, so the
+ # parent is now distinguishable from the child.
+ await sm_runner.send(sm, "switch")
+ assert exits == [
+ ("child", "orphan", "child"),
+ ("parent", "orphan", "parent"),
+ ]
+ assert enters == [("child", "orphan", "orphan")]
+
  async def test_callbacks_inside_compound_class(self, sm_runner):
  """Methods defined inside the State.Compound class body are discovered."""
  log = []

docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

docs/behaviour.md

@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

docs/events.md

@@ -131,6 +131,83 @@ delayed events, and cancellation.
 ```
 
 
+(events-as-method-protocol)=
+
+## Events as a method-call protocol
+
+Because every event is a callable method, a state machine can act as a guard
+for the **order** in which your object's methods may be called. Set
+`allow_event_without_transition = False` so that any call that doesn't match an
+enabled transition raises `TransitionNotAllowed` instead of being silently
+ignored. The transitions then describe the legal
+sequence, and the machine enforces it for you:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Connection(StateChart):
+... "A client whose methods can only be called in a valid order."
+... allow_event_without_transition = False # reject any unexpected call
+...
+... disconnected = State(initial=True)
+... connected = State()
+... authenticated = State()
+...
+... connect = disconnected.to(connected)
+... authenticate = connected.to(authenticated)
+... disconnect = connected.to(disconnected) | authenticated.to(disconnected)
+...
+... def on_connect(self):
+... print("socket opened")
+...
+... def on_authenticate(self):
+... print("credentials accepted")
+
+```
+
+Calling the methods in a valid order works:
+
+```py
+>>> conn = Connection()
+>>> conn.connect()
+socket opened
+>>> conn.authenticate()
+credentials accepted
+>>> "authenticated" in conn.configuration_values
+True
+
+```
+
+A call that isn't valid in the current state raises, so an out-of-order method
+call fails loudly instead of doing nothing:
+
+```py
+>>> fresh = Connection()
+
+>>> fresh.authenticate() # must connect first
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't Authenticate when in Disconnected.
+
+```
+
+The same protection applies to unknown event names sent dynamically:
+
+```py
+>>> fresh.send("teleport")
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't teleport when in Disconnected.
+
+```
+
+```{seealso}
+{ref}`behaviour` explains `allow_event_without_transition` and the other
+class-level flags that switch between this strict mode and the tolerant,
+event-driven default.
+```
+
+
 (event-parameter)=
 
 ## The `event` parameter on transitions

docs/releases/3.2.1.md

@@ -0,0 +1,71 @@
+# StateChart 3.2.1
+
+*Not released yet*
+
+## Bug fixes in 3.2.1
+
+### Symmetric `state` for `on_exit_state` across compound boundaries
+
+When exiting a compound state directly (a transition like `child -> outsider`),
+the generic `on_exit_state()` callback reported the transition's `source` for
+**every** exited state. Exiting `child` and its parent `parent` both arrived
+with `state` and `source` bound to `child`, so the parent level was never
+observable and the two exit calls were indistinguishable.
+
+This was asymmetric with `on_enter_state()`, which already binds `state` (and
+`target`) to each individual state being entered. The exit side now matches:
+`state` (and `source`) is bound to the individual state being exited.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class FSM(StateChart):
+... orphan = State(initial=True)
+...
+... class parent(State.Compound):
+... child = State()
+...
+... switch = orphan.to(parent.child) | parent.child.to(orphan)
+...
+... def on_exit_state(self, source, state):
+... print(f"exit {state.id} (source={source.id})")
+
+>>> sm = FSM()
+>>> sm.send("switch")
+exit orphan (source=orphan)
+>>> sm.send("switch")
+exit child (source=child)
+exit parent (source=parent)
+
+```
+
+Before this fix, the last line read `exit child (source=child)`, hiding the
+parent. State-specific callbacks (`on_exit_<state>`) were already correctly
+keyed per state and are unaffected. Flat (non-compound) machines are also
+unaffected, since there the exited state is always the transition's `source`.
+
+[#634](https://github.com/fgmacedo/python-statemachine/issues/634).
+
+### Negative indices in `OrderedSet.__getitem__`
+
+`OrderedSet.__getitem__` raised `ValueError` (leaking from `itertools.islice`)
+when called with a negative index, instead of following the sequence protocol.
+Negative indices now count from the end like any Python sequence, and an index
+that is still out of range after normalisation raises `IndexError`:
+
+```py
+>>> from statemachine.orderedset import OrderedSet
+
+>>> s = OrderedSet([1, 2, 3])
+>>> s[-1]
+3
+>>> s[-3]
+1
+>>> s[-4]
+Traceback (most recent call last):
+ ...
+IndexError: index -4 out of range
+
+```
+
+[#633](https://github.com/fgmacedo/python-statemachine/pull/633).

docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.10+.
 ```{toctree}
 :maxdepth: 2
 
+3.2.1
 3.2.0
 3.1.2
 3.1.1

statemachine/engines/async_.py

@@ -71,17 +71,27 @@ def _reject_pending_futures(self, exc: Exception):
  # --- Callback dispatch overrides (async versions of BaseEngine methods) ---
 
  async def _get_args_kwargs(
- self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: "Transition",
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # See the sync engine for the rationale: bind `state`/`target` to the
+ # entered state and `state`/`source` to the exited state, keeping the
+ # generic enter/exit callbacks symmetric across compound boundaries.
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -173,7 +183,9 @@ async def _exit_states( # type: ignore[override]
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = await self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = await self._get_args_kwargs(
+ info.transition, trigger_data, source=info.state
+ )
 
  if info.state is not None: # pragma: no branch
  self._debug("%s Exiting state: %s", self._log_id, info.state)

statemachine/engines/base.py

@@ -419,19 +419,30 @@ def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
  return result
 
  def _get_args_kwargs(
- self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: Transition,
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
  # Generate a unique key for the cache, the cache is invalidated once per loop
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  # Check the cache for existing results
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # Bind `state`/`target` to the individual state being entered, and
+ # `state`/`source` to the individual state being exited, so the generic
+ # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+ # compound state boundaries (the transition only knows its own endpoints).
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -500,7 +511,7 @@ def _exit_states(
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
 
  # Execute `onexit` handlers — same per-block error isolation as onentry.
  if info.state is not None: # pragma: no branch

tests/test_statechart_compound.py

@@ -123,6 +123,56 @@ def on_enter_outside(self):
  await sm_runner.send(sm, "leave")
  assert log == ["exit_day", "exit_realm", "enter_outside"]
 
+ async def test_generic_enter_exit_state_param_is_symmetric(self, sm_runner):
+ """Generic ``on_enter_state``/``on_exit_state`` bind ``state`` to the
+ individual state being crossed, symmetrically in both directions.
+
+ Regression test for #634: exiting a compound used to report the
+ transition ``source`` for every exited state (``child`` twice), so the
+ parent state was never observable. Entering already reported the
+ individual state, so the two callbacks were asymmetric.
+ """
+ enters: list = []
+ exits: list = []
+
+ class SymmetricCompound(StateChart):
+ orphan = State(initial=True)
+
+ class parent(State.Compound):
+ child = State()
+
+ switch = orphan.to(parent.child) | parent.child.to(orphan)
+
+ def on_enter_state(self, source, target, state):
+ enters.append((source.id, target.id, state.id))
+
+ def on_exit_state(self, source, target, state):
+ exits.append((source.id, target.id, state.id))
+
+ sm = await sm_runner.start(SymmetricCompound)
+ enters.clear()
+ exits.clear()
+
+ # Enter the compound: `state`/`target` track each entered state.
+ await sm_runner.send(sm, "switch")
+ assert enters == [
+ ("orphan", "parent", "parent"),
+ ("orphan", "child", "child"),
+ ]
+ assert exits == [("orphan", "child", "orphan")]
+
+ enters.clear()
+ exits.clear()
+
+ # Exit the compound: `state`/`source` track each exited state, so the
+ # parent is now distinguishable from the child.
+ await sm_runner.send(sm, "switch")
+ assert exits == [
+ ("child", "orphan", "child"),
+ ("parent", "orphan", "parent"),
+ ]
+ assert enters == [("child", "orphan", "orphan")]
+
  async def test_callbacks_inside_compound_class(self, sm_runner):
  """Methods defined inside the State.Compound class body are discovered."""
  log = []

docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

docs/behaviour.md

@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

docs/events.md

@@ -131,6 +131,83 @@ delayed events, and cancellation.
 ```
 
 
+(events-as-method-protocol)=
+
+## Events as a method-call protocol
+
+Because every event is a callable method, a state machine can act as a guard
+for the **order** in which your object's methods may be called. Set
+`allow_event_without_transition = False` so that any call that doesn't match an
+enabled transition raises `TransitionNotAllowed` instead of being silently
+ignored. The transitions then describe the legal
+sequence, and the machine enforces it for you:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Connection(StateChart):
+... "A client whose methods can only be called in a valid order."
+... allow_event_without_transition = False # reject any unexpected call
+...
+... disconnected = State(initial=True)
+... connected = State()
+... authenticated = State()
+...
+... connect = disconnected.to(connected)
+... authenticate = connected.to(authenticated)
+... disconnect = connected.to(disconnected) | authenticated.to(disconnected)
+...
+... def on_connect(self):
+... print("socket opened")
+...
+... def on_authenticate(self):
+... print("credentials accepted")
+
+```
+
+Calling the methods in a valid order works:
+
+```py
+>>> conn = Connection()
+>>> conn.connect()
+socket opened
+>>> conn.authenticate()
+credentials accepted
+>>> "authenticated" in conn.configuration_values
+True
+
+```
+
+A call that isn't valid in the current state raises, so an out-of-order method
+call fails loudly instead of doing nothing:
+
+```py
+>>> fresh = Connection()
+
+>>> fresh.authenticate() # must connect first
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't Authenticate when in Disconnected.
+
+```
+
+The same protection applies to unknown event names sent dynamically:
+
+```py
+>>> fresh.send("teleport")
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't teleport when in Disconnected.
+
+```
+
+```{seealso}
+{ref}`behaviour` explains `allow_event_without_transition` and the other
+class-level flags that switch between this strict mode and the tolerant,
+event-driven default.
+```
+
+
 (event-parameter)=
 
 ## The `event` parameter on transitions

docs/releases/3.2.1.md

@@ -0,0 +1,71 @@
+# StateChart 3.2.1
+
+*Not released yet*
+
+## Bug fixes in 3.2.1
+
+### Symmetric `state` for `on_exit_state` across compound boundaries
+
+When exiting a compound state directly (a transition like `child -> outsider`),
+the generic `on_exit_state()` callback reported the transition's `source` for
+**every** exited state. Exiting `child` and its parent `parent` both arrived
+with `state` and `source` bound to `child`, so the parent level was never
+observable and the two exit calls were indistinguishable.
+
+This was asymmetric with `on_enter_state()`, which already binds `state` (and
+`target`) to each individual state being entered. The exit side now matches:
+`state` (and `source`) is bound to the individual state being exited.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class FSM(StateChart):
+... orphan = State(initial=True)
+...
+... class parent(State.Compound):
+... child = State()
+...
+... switch = orphan.to(parent.child) | parent.child.to(orphan)
+...
+... def on_exit_state(self, source, state):
+... print(f"exit {state.id} (source={source.id})")
+
+>>> sm = FSM()
+>>> sm.send("switch")
+exit orphan (source=orphan)
+>>> sm.send("switch")
+exit child (source=child)
+exit parent (source=parent)
+
+```
+
+Before this fix, the last line read `exit child (source=child)`, hiding the
+parent. State-specific callbacks (`on_exit_<state>`) were already correctly
+keyed per state and are unaffected. Flat (non-compound) machines are also
+unaffected, since there the exited state is always the transition's `source`.
+
+[#634](https://github.com/fgmacedo/python-statemachine/issues/634).
+
+### Negative indices in `OrderedSet.__getitem__`
+
+`OrderedSet.__getitem__` raised `ValueError` (leaking from `itertools.islice`)
+when called with a negative index, instead of following the sequence protocol.
+Negative indices now count from the end like any Python sequence, and an index
+that is still out of range after normalisation raises `IndexError`:
+
+```py
+>>> from statemachine.orderedset import OrderedSet
+
+>>> s = OrderedSet([1, 2, 3])
+>>> s[-1]
+3
+>>> s[-3]
+1
+>>> s[-4]
+Traceback (most recent call last):
+ ...
+IndexError: index -4 out of range
+
+```
+
+[#633](https://github.com/fgmacedo/python-statemachine/pull/633).

docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.10+.
 ```{toctree}
 :maxdepth: 2
 
+3.2.1
 3.2.0
 3.1.2
 3.1.1

statemachine/engines/async_.py

@@ -71,17 +71,27 @@ def _reject_pending_futures(self, exc: Exception):
  # --- Callback dispatch overrides (async versions of BaseEngine methods) ---
 
  async def _get_args_kwargs(
- self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: "Transition",
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # See the sync engine for the rationale: bind `state`/`target` to the
+ # entered state and `state`/`source` to the exited state, keeping the
+ # generic enter/exit callbacks symmetric across compound boundaries.
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -173,7 +183,9 @@ async def _exit_states( # type: ignore[override]
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = await self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = await self._get_args_kwargs(
+ info.transition, trigger_data, source=info.state
+ )
 
  if info.state is not None: # pragma: no branch
  self._debug("%s Exiting state: %s", self._log_id, info.state)

statemachine/engines/base.py

@@ -419,19 +419,30 @@ def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
  return result
 
  def _get_args_kwargs(
- self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: Transition,
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
  # Generate a unique key for the cache, the cache is invalidated once per loop
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  # Check the cache for existing results
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # Bind `state`/`target` to the individual state being entered, and
+ # `state`/`source` to the individual state being exited, so the generic
+ # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+ # compound state boundaries (the transition only knows its own endpoints).
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -500,7 +511,7 @@ def _exit_states(
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
 
  # Execute `onexit` handlers — same per-block error isolation as onentry.
  if info.state is not None: # pragma: no branch

tests/test_statechart_compound.py

@@ -123,6 +123,56 @@ def on_enter_outside(self):
  await sm_runner.send(sm, "leave")
  assert log == ["exit_day", "exit_realm", "enter_outside"]
 
+ async def test_generic_enter_exit_state_param_is_symmetric(self, sm_runner):
+ """Generic ``on_enter_state``/``on_exit_state`` bind ``state`` to the
+ individual state being crossed, symmetrically in both directions.
+
+ Regression test for #634: exiting a compound used to report the
+ transition ``source`` for every exited state (``child`` twice), so the
+ parent state was never observable. Entering already reported the
+ individual state, so the two callbacks were asymmetric.
+ """
+ enters: list = []
+ exits: list = []
+
+ class SymmetricCompound(StateChart):
+ orphan = State(initial=True)
+
+ class parent(State.Compound):
+ child = State()
+
+ switch = orphan.to(parent.child) | parent.child.to(orphan)
+
+ def on_enter_state(self, source, target, state):
+ enters.append((source.id, target.id, state.id))
+
+ def on_exit_state(self, source, target, state):
+ exits.append((source.id, target.id, state.id))
+
+ sm = await sm_runner.start(SymmetricCompound)
+ enters.clear()
+ exits.clear()
+
+ # Enter the compound: `state`/`target` track each entered state.
+ await sm_runner.send(sm, "switch")
+ assert enters == [
+ ("orphan", "parent", "parent"),
+ ("orphan", "child", "child"),
+ ]
+ assert exits == [("orphan", "child", "orphan")]
+
+ enters.clear()
+ exits.clear()
+
+ # Exit the compound: `state`/`source` track each exited state, so the
+ # parent is now distinguishable from the child.
+ await sm_runner.send(sm, "switch")
+ assert exits == [
+ ("child", "orphan", "child"),
+ ("parent", "orphan", "parent"),
+ ]
+ assert enters == [("child", "orphan", "orphan")]
+
  async def test_callbacks_inside_compound_class(self, sm_runner):
  """Methods defined inside the State.Compound class body are discovered."""
  log = []

docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

docs/behaviour.md

@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

docs/events.md

@@ -131,6 +131,83 @@ delayed events, and cancellation.
 ```
 
 
+(events-as-method-protocol)=
+
+## Events as a method-call protocol
+
+Because every event is a callable method, a state machine can act as a guard
+for the **order** in which your object's methods may be called. Set
+`allow_event_without_transition = False` so that any call that doesn't match an
+enabled transition raises `TransitionNotAllowed` instead of being silently
+ignored. The transitions then describe the legal
+sequence, and the machine enforces it for you:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Connection(StateChart):
+... "A client whose methods can only be called in a valid order."
+... allow_event_without_transition = False # reject any unexpected call
+...
+... disconnected = State(initial=True)
+... connected = State()
+... authenticated = State()
+...
+... connect = disconnected.to(connected)
+... authenticate = connected.to(authenticated)
+... disconnect = connected.to(disconnected) | authenticated.to(disconnected)
+...
+... def on_connect(self):
+... print("socket opened")
+...
+... def on_authenticate(self):
+... print("credentials accepted")
+
+```
+
+Calling the methods in a valid order works:
+
+```py
+>>> conn = Connection()
+>>> conn.connect()
+socket opened
+>>> conn.authenticate()
+credentials accepted
+>>> "authenticated" in conn.configuration_values
+True
+
+```
+
+A call that isn't valid in the current state raises, so an out-of-order method
+call fails loudly instead of doing nothing:
+
+```py
+>>> fresh = Connection()
+
+>>> fresh.authenticate() # must connect first
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't Authenticate when in Disconnected.
+
+```
+
+The same protection applies to unknown event names sent dynamically:
+
+```py
+>>> fresh.send("teleport")
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't teleport when in Disconnected.
+
+```
+
+```{seealso}
+{ref}`behaviour` explains `allow_event_without_transition` and the other
+class-level flags that switch between this strict mode and the tolerant,
+event-driven default.
+```
+
+
 (event-parameter)=
 
 ## The `event` parameter on transitions

docs/releases/3.2.1.md

@@ -0,0 +1,71 @@
+# StateChart 3.2.1
+
+*Not released yet*
+
+## Bug fixes in 3.2.1
+
+### Symmetric `state` for `on_exit_state` across compound boundaries
+
+When exiting a compound state directly (a transition like `child -> outsider`),
+the generic `on_exit_state()` callback reported the transition's `source` for
+**every** exited state. Exiting `child` and its parent `parent` both arrived
+with `state` and `source` bound to `child`, so the parent level was never
+observable and the two exit calls were indistinguishable.
+
+This was asymmetric with `on_enter_state()`, which already binds `state` (and
+`target`) to each individual state being entered. The exit side now matches:
+`state` (and `source`) is bound to the individual state being exited.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class FSM(StateChart):
+... orphan = State(initial=True)
+...
+... class parent(State.Compound):
+... child = State()
+...
+... switch = orphan.to(parent.child) | parent.child.to(orphan)
+...
+... def on_exit_state(self, source, state):
+... print(f"exit {state.id} (source={source.id})")
+
+>>> sm = FSM()
+>>> sm.send("switch")
+exit orphan (source=orphan)
+>>> sm.send("switch")
+exit child (source=child)
+exit parent (source=parent)
+
+```
+
+Before this fix, the last line read `exit child (source=child)`, hiding the
+parent. State-specific callbacks (`on_exit_<state>`) were already correctly
+keyed per state and are unaffected. Flat (non-compound) machines are also
+unaffected, since there the exited state is always the transition's `source`.
+
+[#634](https://github.com/fgmacedo/python-statemachine/issues/634).
+
+### Negative indices in `OrderedSet.__getitem__`
+
+`OrderedSet.__getitem__` raised `ValueError` (leaking from `itertools.islice`)
+when called with a negative index, instead of following the sequence protocol.
+Negative indices now count from the end like any Python sequence, and an index
+that is still out of range after normalisation raises `IndexError`:
+
+```py
+>>> from statemachine.orderedset import OrderedSet
+
+>>> s = OrderedSet([1, 2, 3])
+>>> s[-1]
+3
+>>> s[-3]
+1
+>>> s[-4]
+Traceback (most recent call last):
+ ...
+IndexError: index -4 out of range
+
+```
+
+[#633](https://github.com/fgmacedo/python-statemachine/pull/633).

docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.10+.
 ```{toctree}
 :maxdepth: 2
 
+3.2.1
 3.2.0
 3.1.2
 3.1.1

statemachine/engines/async_.py

@@ -71,17 +71,27 @@ def _reject_pending_futures(self, exc: Exception):
  # --- Callback dispatch overrides (async versions of BaseEngine methods) ---
 
  async def _get_args_kwargs(
- self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: "Transition",
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # See the sync engine for the rationale: bind `state`/`target` to the
+ # entered state and `state`/`source` to the exited state, keeping the
+ # generic enter/exit callbacks symmetric across compound boundaries.
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -173,7 +183,9 @@ async def _exit_states( # type: ignore[override]
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = await self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = await self._get_args_kwargs(
+ info.transition, trigger_data, source=info.state
+ )
 
  if info.state is not None: # pragma: no branch
  self._debug("%s Exiting state: %s", self._log_id, info.state)

statemachine/engines/base.py

@@ -419,19 +419,30 @@ def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
  return result
 
  def _get_args_kwargs(
- self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: Transition,
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
  # Generate a unique key for the cache, the cache is invalidated once per loop
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  # Check the cache for existing results
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # Bind `state`/`target` to the individual state being entered, and
+ # `state`/`source` to the individual state being exited, so the generic
+ # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+ # compound state boundaries (the transition only knows its own endpoints).
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -500,7 +511,7 @@ def _exit_states(
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
 
  # Execute `onexit` handlers — same per-block error isolation as onentry.
  if info.state is not None: # pragma: no branch

tests/test_statechart_compound.py

@@ -123,6 +123,56 @@ def on_enter_outside(self):
  await sm_runner.send(sm, "leave")
  assert log == ["exit_day", "exit_realm", "enter_outside"]
 
+ async def test_generic_enter_exit_state_param_is_symmetric(self, sm_runner):
+ """Generic ``on_enter_state``/``on_exit_state`` bind ``state`` to the
+ individual state being crossed, symmetrically in both directions.
+
+ Regression test for #634: exiting a compound used to report the
+ transition ``source`` for every exited state (``child`` twice), so the
+ parent state was never observable. Entering already reported the
+ individual state, so the two callbacks were asymmetric.
+ """
+ enters: list = []
+ exits: list = []
+
+ class SymmetricCompound(StateChart):
+ orphan = State(initial=True)
+
+ class parent(State.Compound):
+ child = State()
+
+ switch = orphan.to(parent.child) | parent.child.to(orphan)
+
+ def on_enter_state(self, source, target, state):
+ enters.append((source.id, target.id, state.id))
+
+ def on_exit_state(self, source, target, state):
+ exits.append((source.id, target.id, state.id))
+
+ sm = await sm_runner.start(SymmetricCompound)
+ enters.clear()
+ exits.clear()
+
+ # Enter the compound: `state`/`target` track each entered state.
+ await sm_runner.send(sm, "switch")
+ assert enters == [
+ ("orphan", "parent", "parent"),
+ ("orphan", "child", "child"),
+ ]
+ assert exits == [("orphan", "child", "orphan")]
+
+ enters.clear()
+ exits.clear()
+
+ # Exit the compound: `state`/`source` track each exited state, so the
+ # parent is now distinguishable from the child.
+ await sm_runner.send(sm, "switch")
+ assert exits == [
+ ("child", "orphan", "child"),
+ ("parent", "orphan", "parent"),
+ ]
+ assert enters == [("child", "orphan", "orphan")]
+
  async def test_callbacks_inside_compound_class(self, sm_runner):
  """Methods defined inside the State.Compound class body are discovered."""
  log = []

docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

docs/behaviour.md

@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

docs/events.md

@@ -131,6 +131,83 @@ delayed events, and cancellation.
 ```
 
 
+(events-as-method-protocol)=
+
+## Events as a method-call protocol
+
+Because every event is a callable method, a state machine can act as a guard
+for the **order** in which your object's methods may be called. Set
+`allow_event_without_transition = False` so that any call that doesn't match an
+enabled transition raises `TransitionNotAllowed` instead of being silently
+ignored. The transitions then describe the legal
+sequence, and the machine enforces it for you:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Connection(StateChart):
+... "A client whose methods can only be called in a valid order."
+... allow_event_without_transition = False # reject any unexpected call
+...
+... disconnected = State(initial=True)
+... connected = State()
+... authenticated = State()
+...
+... connect = disconnected.to(connected)
+... authenticate = connected.to(authenticated)
+... disconnect = connected.to(disconnected) | authenticated.to(disconnected)
+...
+... def on_connect(self):
+... print("socket opened")
+...
+... def on_authenticate(self):
+... print("credentials accepted")
+
+```
+
+Calling the methods in a valid order works:
+
+```py
+>>> conn = Connection()
+>>> conn.connect()
+socket opened
+>>> conn.authenticate()
+credentials accepted
+>>> "authenticated" in conn.configuration_values
+True
+
+```
+
+A call that isn't valid in the current state raises, so an out-of-order method
+call fails loudly instead of doing nothing:
+
+```py
+>>> fresh = Connection()
+
+>>> fresh.authenticate() # must connect first
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't Authenticate when in Disconnected.
+
+```
+
+The same protection applies to unknown event names sent dynamically:
+
+```py
+>>> fresh.send("teleport")
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't teleport when in Disconnected.
+
+```
+
+```{seealso}
+{ref}`behaviour` explains `allow_event_without_transition` and the other
+class-level flags that switch between this strict mode and the tolerant,
+event-driven default.
+```
+
+
 (event-parameter)=
 
 ## The `event` parameter on transitions

docs/releases/3.2.1.md

@@ -0,0 +1,71 @@
+# StateChart 3.2.1
+
+*Not released yet*
+
+## Bug fixes in 3.2.1
+
+### Symmetric `state` for `on_exit_state` across compound boundaries
+
+When exiting a compound state directly (a transition like `child -> outsider`),
+the generic `on_exit_state()` callback reported the transition's `source` for
+**every** exited state. Exiting `child` and its parent `parent` both arrived
+with `state` and `source` bound to `child`, so the parent level was never
+observable and the two exit calls were indistinguishable.
+
+This was asymmetric with `on_enter_state()`, which already binds `state` (and
+`target`) to each individual state being entered. The exit side now matches:
+`state` (and `source`) is bound to the individual state being exited.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class FSM(StateChart):
+... orphan = State(initial=True)
+...
+... class parent(State.Compound):
+... child = State()
+...
+... switch = orphan.to(parent.child) | parent.child.to(orphan)
+...
+... def on_exit_state(self, source, state):
+... print(f"exit {state.id} (source={source.id})")
+
+>>> sm = FSM()
+>>> sm.send("switch")
+exit orphan (source=orphan)
+>>> sm.send("switch")
+exit child (source=child)
+exit parent (source=parent)
+
+```
+
+Before this fix, the last line read `exit child (source=child)`, hiding the
+parent. State-specific callbacks (`on_exit_<state>`) were already correctly
+keyed per state and are unaffected. Flat (non-compound) machines are also
+unaffected, since there the exited state is always the transition's `source`.
+
+[#634](https://github.com/fgmacedo/python-statemachine/issues/634).
+
+### Negative indices in `OrderedSet.__getitem__`
+
+`OrderedSet.__getitem__` raised `ValueError` (leaking from `itertools.islice`)
+when called with a negative index, instead of following the sequence protocol.
+Negative indices now count from the end like any Python sequence, and an index
+that is still out of range after normalisation raises `IndexError`:
+
+```py
+>>> from statemachine.orderedset import OrderedSet
+
+>>> s = OrderedSet([1, 2, 3])
+>>> s[-1]
+3
+>>> s[-3]
+1
+>>> s[-4]
+Traceback (most recent call last):
+ ...
+IndexError: index -4 out of range
+
+```
+
+[#633](https://github.com/fgmacedo/python-statemachine/pull/633).

docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.10+.
 ```{toctree}
 :maxdepth: 2
 
+3.2.1
 3.2.0
 3.1.2
 3.1.1

statemachine/engines/async_.py

@@ -71,17 +71,27 @@ def _reject_pending_futures(self, exc: Exception):
  # --- Callback dispatch overrides (async versions of BaseEngine methods) ---
 
  async def _get_args_kwargs(
- self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: "Transition",
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # See the sync engine for the rationale: bind `state`/`target` to the
+ # entered state and `state`/`source` to the exited state, keeping the
+ # generic enter/exit callbacks symmetric across compound boundaries.
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -173,7 +183,9 @@ async def _exit_states( # type: ignore[override]
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = await self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = await self._get_args_kwargs(
+ info.transition, trigger_data, source=info.state
+ )
 
  if info.state is not None: # pragma: no branch
  self._debug("%s Exiting state: %s", self._log_id, info.state)

statemachine/engines/base.py

@@ -419,19 +419,30 @@ def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
  return result
 
  def _get_args_kwargs(
- self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: Transition,
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
  # Generate a unique key for the cache, the cache is invalidated once per loop
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  # Check the cache for existing results
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # Bind `state`/`target` to the individual state being entered, and
+ # `state`/`source` to the individual state being exited, so the generic
+ # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+ # compound state boundaries (the transition only knows its own endpoints).
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -500,7 +511,7 @@ def _exit_states(
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
 
  # Execute `onexit` handlers — same per-block error isolation as onentry.
  if info.state is not None: # pragma: no branch

tests/test_statechart_compound.py

@@ -123,6 +123,56 @@ def on_enter_outside(self):
  await sm_runner.send(sm, "leave")
  assert log == ["exit_day", "exit_realm", "enter_outside"]
 
+ async def test_generic_enter_exit_state_param_is_symmetric(self, sm_runner):
+ """Generic ``on_enter_state``/``on_exit_state`` bind ``state`` to the
+ individual state being crossed, symmetrically in both directions.
+
+ Regression test for #634: exiting a compound used to report the
+ transition ``source`` for every exited state (``child`` twice), so the
+ parent state was never observable. Entering already reported the
+ individual state, so the two callbacks were asymmetric.
+ """
+ enters: list = []
+ exits: list = []
+
+ class SymmetricCompound(StateChart):
+ orphan = State(initial=True)
+
+ class parent(State.Compound):
+ child = State()
+
+ switch = orphan.to(parent.child) | parent.child.to(orphan)
+
+ def on_enter_state(self, source, target, state):
+ enters.append((source.id, target.id, state.id))
+
+ def on_exit_state(self, source, target, state):
+ exits.append((source.id, target.id, state.id))
+
+ sm = await sm_runner.start(SymmetricCompound)
+ enters.clear()
+ exits.clear()
+
+ # Enter the compound: `state`/`target` track each entered state.
+ await sm_runner.send(sm, "switch")
+ assert enters == [
+ ("orphan", "parent", "parent"),
+ ("orphan", "child", "child"),
+ ]
+ assert exits == [("orphan", "child", "orphan")]
+
+ enters.clear()
+ exits.clear()
+
+ # Exit the compound: `state`/`source` track each exited state, so the
+ # parent is now distinguishable from the child.
+ await sm_runner.send(sm, "switch")
+ assert exits == [
+ ("child", "orphan", "child"),
+ ("parent", "orphan", "parent"),
+ ]
+ assert enters == [("child", "orphan", "orphan")]
+
  async def test_callbacks_inside_compound_class(self, sm_runner):
  """Methods defined inside the State.Compound class body are discovered."""
  log = []

docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

docs/behaviour.md

@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

docs/events.md

@@ -131,6 +131,83 @@ delayed events, and cancellation.
 ```
 
 
+(events-as-method-protocol)=
+
+## Events as a method-call protocol
+
+Because every event is a callable method, a state machine can act as a guard
+for the **order** in which your object's methods may be called. Set
+`allow_event_without_transition = False` so that any call that doesn't match an
+enabled transition raises `TransitionNotAllowed` instead of being silently
+ignored. The transitions then describe the legal
+sequence, and the machine enforces it for you:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Connection(StateChart):
+... "A client whose methods can only be called in a valid order."
+... allow_event_without_transition = False # reject any unexpected call
+...
+... disconnected = State(initial=True)
+... connected = State()
+... authenticated = State()
+...
+... connect = disconnected.to(connected)
+... authenticate = connected.to(authenticated)
+... disconnect = connected.to(disconnected) | authenticated.to(disconnected)
+...
+... def on_connect(self):
+... print("socket opened")
+...
+... def on_authenticate(self):
+... print("credentials accepted")
+
+```
+
+Calling the methods in a valid order works:
+
+```py
+>>> conn = Connection()
+>>> conn.connect()
+socket opened
+>>> conn.authenticate()
+credentials accepted
+>>> "authenticated" in conn.configuration_values
+True
+
+```
+
+A call that isn't valid in the current state raises, so an out-of-order method
+call fails loudly instead of doing nothing:
+
+```py
+>>> fresh = Connection()
+
+>>> fresh.authenticate() # must connect first
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't Authenticate when in Disconnected.
+
+```
+
+The same protection applies to unknown event names sent dynamically:
+
+```py
+>>> fresh.send("teleport")
+Traceback (most recent call last):
+ ...
+statemachine.exceptions.TransitionNotAllowed: Can't teleport when in Disconnected.
+
+```
+
+```{seealso}
+{ref}`behaviour` explains `allow_event_without_transition` and the other
+class-level flags that switch between this strict mode and the tolerant,
+event-driven default.
+```
+
+
 (event-parameter)=
 
 ## The `event` parameter on transitions

docs/releases/3.2.1.md

@@ -0,0 +1,71 @@
+# StateChart 3.2.1
+
+*Not released yet*
+
+## Bug fixes in 3.2.1
+
+### Symmetric `state` for `on_exit_state` across compound boundaries
+
+When exiting a compound state directly (a transition like `child -> outsider`),
+the generic `on_exit_state()` callback reported the transition's `source` for
+**every** exited state. Exiting `child` and its parent `parent` both arrived
+with `state` and `source` bound to `child`, so the parent level was never
+observable and the two exit calls were indistinguishable.
+
+This was asymmetric with `on_enter_state()`, which already binds `state` (and
+`target`) to each individual state being entered. The exit side now matches:
+`state` (and `source`) is bound to the individual state being exited.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class FSM(StateChart):
+... orphan = State(initial=True)
+...
+... class parent(State.Compound):
+... child = State()
+...
+... switch = orphan.to(parent.child) | parent.child.to(orphan)
+...
+... def on_exit_state(self, source, state):
+... print(f"exit {state.id} (source={source.id})")
+
+>>> sm = FSM()
+>>> sm.send("switch")
+exit orphan (source=orphan)
+>>> sm.send("switch")
+exit child (source=child)
+exit parent (source=parent)
+
+```
+
+Before this fix, the last line read `exit child (source=child)`, hiding the
+parent. State-specific callbacks (`on_exit_<state>`) were already correctly
+keyed per state and are unaffected. Flat (non-compound) machines are also
+unaffected, since there the exited state is always the transition's `source`.
+
+[#634](https://github.com/fgmacedo/python-statemachine/issues/634).
+
+### Negative indices in `OrderedSet.__getitem__`
+
+`OrderedSet.__getitem__` raised `ValueError` (leaking from `itertools.islice`)
+when called with a negative index, instead of following the sequence protocol.
+Negative indices now count from the end like any Python sequence, and an index
+that is still out of range after normalisation raises `IndexError`:
+
+```py
+>>> from statemachine.orderedset import OrderedSet
+
+>>> s = OrderedSet([1, 2, 3])
+>>> s[-1]
+3
+>>> s[-3]
+1
+>>> s[-4]
+Traceback (most recent call last):
+ ...
+IndexError: index -4 out of range
+
+```
+
+[#633](https://github.com/fgmacedo/python-statemachine/pull/633).

docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.10+.
 ```{toctree}
 :maxdepth: 2
 
+3.2.1
 3.2.0
 3.1.2
 3.1.1

statemachine/engines/async_.py

@@ -71,17 +71,27 @@ def _reject_pending_futures(self, exc: Exception):
  # --- Callback dispatch overrides (async versions of BaseEngine methods) ---
 
  async def _get_args_kwargs(
- self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: "Transition",
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # See the sync engine for the rationale: bind `state`/`target` to the
+ # entered state and `state`/`source` to the exited state, keeping the
+ # generic enter/exit callbacks symmetric across compound boundaries.
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -173,7 +183,9 @@ async def _exit_states( # type: ignore[override]
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = await self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = await self._get_args_kwargs(
+ info.transition, trigger_data, source=info.state
+ )
 
  if info.state is not None: # pragma: no branch
  self._debug("%s Exiting state: %s", self._log_id, info.state)

statemachine/engines/base.py

@@ -419,19 +419,30 @@ def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
  return result
 
  def _get_args_kwargs(
- self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+ self,
+ transition: Transition,
+ trigger_data: TriggerData,
+ target: "State | None" = None,
+ source: "State | None" = None,
  ):
  # Generate a unique key for the cache, the cache is invalidated once per loop
- cache_key = (id(transition), id(trigger_data), id(target))
+ cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
  # Check the cache for existing results
  if cache_key in self._cache:
  return self._cache[cache_key]
 
  event_data = EventData(trigger_data=trigger_data, transition=transition)
+ # Bind `state`/`target` to the individual state being entered, and
+ # `state`/`source` to the individual state being exited, so the generic
+ # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+ # compound state boundaries (the transition only knows its own endpoints).
  if target:
  event_data.state = target
  event_data.target = target
+ if source:
+ event_data.state = source
+ event_data.source = source
 
  args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -500,7 +511,7 @@ def _exit_states(
  if info.state is not None: # pragma: no branch
  self._invoke_manager.cancel_for_state(info.state)
 
- args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
+ args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
 
  # Execute `onexit` handlers — same per-block error isolation as onentry.
  if info.state is not None: # pragma: no branch

tests/test_statechart_compound.py

@@ -123,6 +123,56 @@ def on_enter_outside(self):
  await sm_runner.send(sm, "leave")
  assert log == ["exit_day", "exit_realm", "enter_outside"]
 
+ async def test_generic_enter_exit_state_param_is_symmetric(self, sm_runner):
+ """Generic ``on_enter_state``/``on_exit_state`` bind ``state`` to the
+ individual state being crossed, symmetrically in both directions.
+
+ Regression test for #634: exiting a compound used to report the
+ transition ``source`` for every exited state (``child`` twice), so the
+ parent state was never observable. Entering already reported the
+ individual state, so the two callbacks were asymmetric.
+ """
+ enters: list = []
+ exits: list = []
+
+ class SymmetricCompound(StateChart):
+ orphan = State(initial=True)
+
+ class parent(State.Compound):
+ child = State()
+
+ switch = orphan.to(parent.child) | parent.child.to(orphan)
+
+ def on_enter_state(self, source, target, state):
+ enters.append((source.id, target.id, state.id))
+
+ def on_exit_state(self, source, target, state):
+ exits.append((source.id, target.id, state.id))
+
+ sm = await sm_runner.start(SymmetricCompound)
+ enters.clear()
+ exits.clear()
+
+ # Enter the compound: `state`/`target` track each entered state.
+ await sm_runner.send(sm, "switch")
+ assert enters == [
+ ("orphan", "parent", "parent"),
+ ("orphan", "child", "child"),
+ ]
+ assert exits == [("orphan", "child", "orphan")]
+
+ enters.clear()
+ exits.clear()
+
+ # Exit the compound: `state`/`source` track each exited state, so the
+ # parent is now distinguishable from the child.
+ await sm_runner.send(sm, "switch")
+ assert exits == [
+ ("child", "orphan", "child"),
+ ("parent", "orphan", "parent"),
+ ]
+ assert enters == [("child", "orphan", "orphan")]
+
  async def test_callbacks_inside_compound_class(self, sm_runner):
  """Methods defined inside the State.Compound class body are discovered."""
  log = []