yasmin.state_machine module

class yasmin.state_machine.StateMachine(outcomes: Set[str])

Bases: State

A class that implements a state machine with a set of states, transitions, and callback mechanisms for state changes.

The StateMachine class inherits from the State class and allows the registration of states with their respective transitions and callbacks for start, transition, and end events.

Attributes:

_states (Dict[str, Dict[str, Any]]): A dictionary mapping state names to their corresponding state objects and transitions. _start_state (str): The name of the initial state of the state machine. __current_state (str): The name of the current state being executed. __current_state_lock (Lock): A threading lock to manage access to the current state. __current_state_event (Event): An event to signal when the current state changes. _validated (bool): A flag indicating whether the state machine has been validated. __start_cbs (List[Tuple[Callable[[Blackboard, str, List[Any]], None], List[Any]]]): A list of callbacks to call when the state machine starts. __transition_cbs (List[Tuple[Callable[[Blackboard, str, List[Any]], None], List[Any]]]): A list of callbacks to call during state transitions. __end_cbs (List[Tuple[Callable[[Blackboard, str, List[Any]], None], List[Any]]]): A list of callbacks to call when the state machine ends.

add_end_cb(cb: Callable, args: List[Any] = None) → None

Adds a callback to be called when the state machine ends.

Args:

cb (Callable): The callback function to execute. args (List[Any], optional): A list of arguments to pass to the callback. Defaults to None.

add_start_cb(cb: Callable, args: List[Any] = None) → None

Adds a callback to be called when the state machine starts.

Args:

cb (Callable): The callback function to execute. args (List[Any], optional): A list of arguments to pass to the callback. Defaults to None.

add_state(name: str, state: State, transitions: Dict[str, str] = None, remappings: Dict[str, Dict[str, str]] = None) → None

Adds a new state to the state machine.

Args:

name (str): The name of the state to add. state (State): The State object to associate with the name. transitions (Dict[str, str], optional): A dictionary mapping source outcomes to target states. Defaults to None.

Raises:

KeyError: If the state name is already registered or is an outcome. ValueError: If transitions contain empty keys or values. KeyError: If transitions reference unregistered outcomes.

add_transition_cb(cb: Callable, args: List[Any] = None) → None

Adds a callback to be called during state transitions.

Args:

cb (Callable): The callback function to execute. args (List[Any], optional): A list of arguments to pass to the callback. Defaults to None.

cancel_state() → None

Cancels the current state and any associated operations.

Overrides the cancel_state method from the parent State class.

execute(blackboard: Blackboard) → str

Executes the state machine starting from the initial state.

Args:

blackboard (Blackboard): The blackboard instance used for sharing state.

Returns:

str: The final outcome of the state machine execution.

Raises:

RuntimeError: If the execution is canceled unexpectedly. KeyError: If an outcome does not belong to a state or the state machine.

get_current_state() → str

Retrieves the name of the current state being executed.

Returns:

str: The name of the current state, or an empty string if none is set.

get_start_state() → str

Retrieves the name of the current starting state.

Returns:

str: The name of the starting state.

get_states() → Dict[str, State | Dict[str, str]]

Retrieves all states in the state machine.

Returns:

Dict[str, Union[State, Dict[str, str]]]: A dictionary of states and their transitions.

set_start_state(state_name: str) → None

Sets the initial state for the state machine.

Args:

state_name (str): The name of the initial state to set.

Raises:

ValueError: If the state name is empty. KeyError: If the state name is not found in the states.

validate(strict_mode: bool = False) → None

Validates the state machine to ensure all states and transitions are correct.

Args:

strict_mode (bool): Whether the validation is strict, which means checking if all state outcomes are used and all state machine outcomes are reached.

Raises:

RuntimeError: If no initial state is set. KeyError: If there are any unregistered outcomes or transitions.