on_exit_state and on_enter_state should be symmetrical when exiting compound states

[danhorner]

I think this is a known issue but I'm confused by the behavior of on_enter_state and on_exit_state when directly exiting compound states. That is with a direct transition CHILD -> OUTSIDER. The result is that the on_exit() hook isn't symmetrical with on_enter(). If I'm tracking states, I get two exits from the nested state and none from the parent.

stateDiagram-v2
 Done
 state Parent {
 A --> B
 }
A --> Done : on_exit_state(state=A)<br>on_exit_state(state=A !!!)

Loading

There is a note in the documentation that sort of acknowledges this:

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.

Q: Even if source doesn't match, is there any way to detect the parent in my handler? Even though the note says to check event_data, the two calls to on_exit_state() look identical in their parameters.

Toy example

import statemachine
from statemachine import StateChart, State, Event

class FSM(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):
 print(f" On Enter: -> {target}")

 def on_exit_state(self, source, target):
 print(f" On exit: {source} -> ")


if __name__ == "__main__":
 print(f"1. Start [version:{statemachine.__version__}]")
 fsm = FSM()
 print("2. Switch")
 fsm.SWITCH()
 print("3. Switch")
 fsm.SWITCH()

Sample output shows problem:

1. Start [version:3.2.0]
 On Enter: -> Orphan
2. Switch
 On exit: Orphan ->
 On Enter: -> Parent
 On Enter: -> Child
3. Switch
 On exit: Child ->
 On exit: Child -> ### I expected this to be PARENT
 On Enter: -> Orphan

[danhorner]

For anybody with a similar request, this is my workaround:

A:
I want this because I'm writing a Listener that dispatches from on_exit_state based on the state being exited. I solved it for my case by dynamically writing on_exit_<state>() handlers during setup, but it would be nice if the library worked this way:

# Listener creates named on_exit_<state> handlers for each state
class Listener():
 def setup(self, sm, **kwargs):
 for state in sm.states_map.values():
 self._create_exit_handler(state)

 def _create_exit_handler(self, state):
 def exit_handler(**kwargs):
 kwargs["state"] = state # Patch state
 kwargs["source"] = state 
 return self._on_exit_state__fixup(**kwargs)
 setattr(self, f"on_exit_{state.value}", exit_handler)

 def on_enter_state(self, source, target):
 print(f" Listener on enter: -> {target}")

 def _on_exit_state__fixup(self, source, target, **kwargs):
 print(f" Listener on exit: {source} -> ")

1. Start [version:3.2.0]
 Listener on enter: -> Orphan
2. Switch
 Listener on exit: Orphan ->
 Listener on enter: -> Parent
 Listener on enter: -> Child
3. Switch
 Listener on exit: Child ->
 Listener on exit: Parent -> ### YAY! 
 Listener on enter: -> Orphan

[fgmacedo]

Hi @danhorner, thanks for the detailed report and the minimal toy example, it made the investigation really easy.

You're right, this is a genuine asymmetry and the bug is on our side, not in your understanding. Here's what's happening under the hood.

When the engine enters a set of states, it binds the generic on_enter_state callback's state/target parameters to each individual state being entered (Parent, then Child). But when it exits a set of states, on_exit_state keeps state/source pinned to the transition's source for every exited state, so you get Child twice and Parent never shows up.

The root cause is in engines/base.py: _enter_states passes the individual state down into _get_args_kwargs (which sets event_data.state/event_data.target), while _exit_states doesn't pass anything, so the individual info.state is only used to key the state-specific on_exit_<state> callback and never reaches the generic callback's parameters.

Two consequences worth calling out:

1. To answer your question directly: today there is no way to detect the parent from the handler, the two exit calls are truly identical in state, source, target, and event_data. So the only reliable option right now is the state-specific on_exit_<state> callbacks, which are correctly keyed per state.
2. Our documentation note is also wrong, it claims state is bound to the transition's source/target for both enter and exit, but enter already binds to the individual state. The note only describes the (buggy) exit side.

The fix is to make exit symmetric with enter: bind state (and source) to the individual state being exited, so you'd get:

On exit: source=Child target=Orphan state=Child
On exit: source=Parent target=Orphan state=Parent

We'll get this fixed and update the docs note accordingly. Thanks again for the clear repro and for pushing on the symmetry, it's the right expectation.