hsm.core.Container

class Container(name)

Bases: State

Containers allow for hierarchical nesting of states.

Containers can be used to just group a set of children states. However, the most useful feature of containers is behavior inheritance: Containers can define a common (default) event handling for all its children states. Of course, children still can override this event handling. But if they don’t do and thus don’t handle a specific event, that event is propagated to the parent state, i.e. the container, and handled there. If the parent doesn’t handle the event either, its further propagated to the grand parent and so on.

Methods

add_handler	Add a new event callback.
add_state	Add a state to a state the container.
add_states	Add multiple states to the Container.
add_transition	Add a transition from self to target_state
get_active_states
get_initial_states
is_active
is_substate	Check whether the state is a substate of self.
ros_subscribe
set_initial_state	Set an initial state in a state machine.

Attributes

history_state	Get the history state of this Container.
initial_state	Get the initial state in a state machine.
leaf_state	Get the current leaf state.
root	Get the root state in a states hierarchy.

add_handler(events, func, prepend=False)

Add a new event callback.

Parameters:

• trigger (str) – name of triggering event

• func (callable) – callback function

add_state(state, initial=False)

Add a state to a state the container.

If states are added, one (and only one) of them has to be declared as initial.

Parameters:

• state (State) – State to be added. It may be an another Container

• initial (bool) – Declare a state as initial

add_states(*states)

Add multiple states to the Container.

Parameters:

states – A list of states to be added

add_transition(events, target_state, *args, **kwargs)

Add a transition from self to target_state

All callbacks take two arguments - state and event. See parameters description for details.

It is possible to create conditional if/elif/else-like logic for transitions. To do so, add many same transition rules with different condition callbacks. First met condition will trigger a transition, if no condition is met, no transition is performed.

Parameters:

• target_state (State, None) – Target state. If None, then it’s an internal transition

• events (Iterable of Hashable) – List of events that trigger the transition

• condition (Callable) –

  Condition callback - if returns True transition may be initiated.

  condition callback takes two arguments:

  • state: Leaf state before transition

  • event: Event that triggered the transition

• action (Callable) –

  Action callback that is called during the transition after all states have been left but before the new one is entered.

  action callback takes two arguments:

  • state: Leaf state before transition

  • event: Event that triggered the transition

• before (Callable) –

  Action callback that is called right before the transition.

  before callback takes two arguments:

  • state: Leaf state before transition

  • event: Event that triggered the transition

• after (Callable) –

  Action callback that is called just after the transition

  after callback takes two arguments:

  • state: Leaf state after transition

  • event: Event that triggered the transition

property history_state

Get the history state of this Container.

Returns:

Leaf state in a hierarchical state machine

Return type:

State

property initial_state

Get the initial state in a state machine.

Returns:

Initial state in a state machine

Return type:

State

is_substate(state)

Check whether the state is a substate of self.

Also self is considered a substate of self.

Parameters:

state (State) – State to verify

Returns:

True if state is a substate of self, False otherwise

Return type:

bool

property leaf_state

Get the current leaf state.

The state property gives the current, local state in a state machine. The leaf_state goes to the bottom in a hierarchy of states. In most cases, this is the property that should be used to get the current state in a state machine, even in a flat FSM, to keep the consistency in the code and to avoid confusion.

Returns:

Leaf state in a hierarchical state machine

Return type:

State

property root

Get the root state in a states hierarchy.

Returns:

Root state in the states hierarchy

Return type:

State

set_initial_state(state)

Set an initial state in a state machine.

Parameters:

state (State) – Set this state as initial in a state machine