init to got straight into a sub-state?

[MiMiMeowMeow]

Hello, i'm wondering something like the attached is possible now.

I tried to code it up but it doesn't seem possible to define the init of one state to go into a sub-state. For example d2-init will go right into d211 state. Or d-init will go right into d11 state.

Just for reference this was from Practical UML Statecharts in C/C++, 2nd Ed
https://www.state-machine.com/doc/PSiCC2.pdf

[fgmacedo]

Hi @MiMiMeowMeow, this is absolutely possible with v3! The key is that compound states cascade their initial transitions automatically — when the engine enters a compound state, it recursively enters the initial child at each level until it reaches an atomic state.

So for your diagram, when d2 is entered, the engine automatically goes: d2 → d21 (initial child) → d211 (initial child of d21). No special setup needed — just mark the initial states and the cascading happens.

Here's a working reproduction of the full structure from the PSiCC2 diagram:

from statemachine import State, StateChart


class PSiCC2(StateChart):
    """HSM example from Practical UML Statecharts in C/C++, 2nd Ed."""

    # State hierarchy:
    # d (compound, top-level)
    #   d1 (compound, initial of d)
    #     d11 (atomic, initial of d1)
    #   d2 (compound)
    #     d21 (compound, initial of d2)
    #       d211 (atomic, initial of d21)

    class d(State.Compound):
        class d1(State.Compound):
            d11 = State(initial=True)

        class d2(State.Compound):
            class d21(State.Compound):
                d211 = State(initial=True)

    terminate = State(final=True)

    # Instance variable used in guards
    foo: bool = False

    def is_foo(self):
        return self.foo

    def not_foo(self):
        return not self.foo

    def set_foo(self):
        self.foo = True

    def clear_foo(self):
        self.foo = False

    # --- Transitions ---

    # A: d1 self-transition; d21 self-transition
    A = d.d1.to(d.d1) | d.d2.d21.to(d.d2.d21)

    # B: d1 → d11; d21 → d211
    B = d.d1.to(d.d1.d11) | d.d2.d21.to(d.d2.d21.d211)

    # C: d1 ↔ d2
    C = d.d1.to(d.d2) | d.d2.to(d.d1)

    # D: d1 [!foo] → d / set_foo; d11 [foo] → d1 / clear_foo; d211 → d21
    D = (
        d.d1.to(d, cond="not_foo", on="set_foo")
        | d.d1.d11.to(d.d1, cond="is_foo", on="clear_foo")
        | d.d2.d21.d211.to(d.d2.d21)
    )

    # E: d → d11
    E = d.to(d.d1.d11)

    # F: d1 → d211; d2 → d11
    F = d.d1.to(d.d2.d21.d211) | d.d2.to(d.d1.d11)

    # G: d11 → d21; d21 → d1
    G = d.d1.d11.to(d.d2.d21) | d.d2.d21.to(d.d1)

    # H: d11 → d; d211 → d
    H = d.d1.d11.to(d) | d.d2.d21.d211.to(d)

    # I: d1 internal; d2 [!foo] self / set_foo; d [foo] self / clear_foo
    I = (
        d.d1.to.itself(internal=True)
        | d.d2.to(d.d2, cond="not_foo", on="set_foo")
        | d.to(d, cond="is_foo", on="clear_foo")
    )

    # TERMINATE: d → final state
    TERMINATE = d.to(terminate)

    # d2's initial transition action: foo = False
    def on_enter_d2(self):
        self.foo = False

And here's how the cascading init works:

>>> sm = PSiCC2()

>>> sorted(sm.configuration_values)
['d', 'd1', 'd11']
# d-init cascades: d → d1 (initial) → d11 (initial) ✓

>>> sm.send("C")  # d1 → d2
>>> sorted(sm.configuration_values)
['d', 'd2', 'd21', 'd211']
# d2-init cascades: d2 → d21 (initial) → d211 (initial) ✓

>>> sm.send("H")  # d211 → d (re-enters d, cascades back to d1/d11)
>>> sorted(sm.configuration_values)
['d', 'd1', 'd11']

How it works: at each compound level, if no explicit initial=True is set, the first child in document order becomes the initial state. The engine creates initial transitions automatically, and when entering a compound state, it follows these transitions recursively until it reaches an atomic state. You can access deeply nested states using dot notation (d.d2.d21.d211) for defining transitions, and use the | operator to combine multiple transitions under a single event name.

[MiMiMeowMeow]

@fgmacedo Thank you for looking into this and for your great work on this package!

Is there a way to mimic the concept of the "top" state entering the whole state machine? When starting it should have preformed the foo = 0 and the d-entry and then go to d2.
top-INIT;d-ENTRY;d2-ENTRY;d2-INIT;d21-ENTRY;d211-ENTRY;

Right now when I start the program, it skips that part and follows the d-init into d11.

I was playing around with adding a lisenter that will trace the path and I noticed that the Exit source remains the same (d11) as it is finding the lowest common state. However the entries looks like it's following the targets okay.

import logging

from rich.console import Console
from rich.text import Text

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)

class TraceListener:
    def __init__(self, name: str, use_logger: bool = False) -> None:
        self.name = name
        self.use_logger = use_logger
        self.console = Console()
        self.transition_buffer = []

    def _log(self, message: str):
        if self.use_logger:
            logger.debug(message, extra={"markup": True})
        else:
            self.console.print(Text(message))

    def before_transition(self, event, source, target):
        # Start buffering the transition sequence
        self.transition_buffer = [f"{source.id}-{event}"]

    def on_exit_state(self, source, event):
        # Append exiting state to buffer
        state_name = str(source).lower() if source else "unknown"
        self.transition_buffer.append(f"{state_name}-EXIT")

    def on_transition(self, event, source, target):
        # Could be used if needed, but not part of the output format
        pass

    def on_enter_state(self, target, event):
        # Append entering state to buffer
        state_name = str(target).lower() if target else "unknown"
        self.transition_buffer.append(f"{state_name}-ENTRY")

    def after_transition(self, event, source, target):
        # Finalize and print the accumulated transition string
        if self.transition_buffer:
            output = ";".join(self.transition_buffer) + ";"
            self._log(f"[bold green]{output}[/bold green]")
        self.transition_buffer = []

[fgmacedo]

Great follow-up! You're touching on an important distinction between UML Statecharts (as in Samek's QP framework / PSiCC2) and W3C SCXML, which is the spec that python-statemachine v3 follows.

The "init" concept: UML vs SCXML

In UML/QP, composite states have two separate signals: Q_ENTRY_SIG (entry action) and Q_INIT_SIG (initial transition action). These are distinct hooks — entry fires every time the state is entered, while init fires only when the state's initial transition is followed (and is skipped when a transition targets a substate directly).

SCXML doesn't have a separate "init" hook on states. Instead, it models the same behavior as executable content on the <initial> transition — the action lives on the transition, not on the state. The execution order is the same: parent onentry → initial transition content → child onentry.

What works today

For controlling which substate the initial transition targets, you just need to set initial=True on the desired child. In your diagram, to make "top-INIT" go to d2 instead of d1:

class d(State.Compound):
    class d1(State.Compound):
        d11 = State(initial=True)

    class d2(State.Compound, initial=True):  # ← d2 is now the initial child of d
        class d21(State.Compound):
            d211 = State(initial=True)

For the action on the initial transition (foo = 0), right now you'd use on_enter_d2() as a workaround — but as you noticed, that runs on every entry, not just the initial one.

What's planned

The engine already supports executing actions on initial transitions internally (it's how we handle SCXML <initial> elements with executable content, validated by W3C test412). What's missing is a Python-facing API to attach actions to initial transitions when defining state machines in code.

I'm considering the best way to expose this — likely through a naming convention like on_init_<state>() that would align with the UML mental model while staying consistent with the existing callback patterns (on_enter_<state>, on_exit_<state>). The semantics would be: runs after on_enter_<state>(), before on_enter_<child>(), and only when the initial transition is followed (not when a transition targets a substate directly).

I'll keep this issue open to track the feature. Thanks for raising it — it's a valid gap between the UML model and what we currently expose in the Python API!

[MiMiMeowMeow]

@fgmacedo

Thanks for explaination! I will contiune playing around and look forward to how the package evolves. I was watching for 3.x all of last year because I use to work with the QP framework in the past. haha