yasmin.state_machine module

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

Bases: State

Represents a state machine that can manage states and transitions between them, including callbacks for different state 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. _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) → None

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

Parameters:

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) → None

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

Parameters:

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 = None) → None

Adds a new state to the state machine.

Parameters:

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) → None

Adds a callback to be called during state transitions.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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.