Machine Class Reference

Inheritance diagram for Machine:

Public Member Functions
	__init__ (self, states=None, initial_state="default_initial")
	add_state (self, state, enter=None, exit=None)
	initial_state (self)
	initial_state (self, state)
	state (self)
	state (self, state)
	add_transition (self, trigger, source, dest, conditions=None, before=None, after=None)
	__getattr__ (self, name, **kwargs)
	get_transitions (self, source)
	get_transition_dict (self, state, transition)
	save_graph (self, filename, graphname)

Static Public Member Functions
	default_condition (**kwargs)

Public Attributes
dict	states = {}
	Valid states for this machine.
	initial_state = initial_state
	Pointless docstring since it's a property.
	transitions = defaultdict(list)
	Allowed transitions between states.
	state = dest
	Current State of machine.

Protected Member Functions
	_trigger (self, transition_name, transition_dict, **kwargs)

Static Protected Member Functions
	_callback (func, **kwargs)

Protected Attributes
dict	_initial_state = State(initial_state)
	Actual attribute holding initial state for this machine.
dict	_state = self.initial_state
	Actual attribute holding the Current state.

Detailed Description

Parameters:
  states (list[str]): A list of possible states of the machine.
  initial_state (str):

Base class for a final state machine wrapper.
Implements the framework that a more complex machine can inherit from.

The `transitions` attribute is a dictionary of trigger name keys, each value of
which is another dictionary of 'source' states, 'dest' states, and 'conditions'
methods. 'conditions' should be a list of callables or a single one. A transition is
valid if it goes from an allowed state to an allowed state.
Conditions are optional but must be a callable that returns True or False based
on some state of the machine. They cannot have input arguments currently.

Every condition/before/after callback function MUST take ``**kwargs`` as the only
argument (except ``self`` if it's a class method). This is because it's basically
impossible to determine which arguments to pass to which functions for a transition.
Therefore this machine just enforces that every function should simply take ``**kwargs``
and use the dictionary of arguments (even if it doesn't need any arguments).

This also means that if you call a trigger with arguments e.g. ``machine.walk(speed=5)``
you MUST use the keyword arguments rather than positional ones. So ``machine.walk(5)``
will *not* work.

Definition at line 144 of file state_machines.py.

Constructor & Destructor Documentation

__init__()

__init__	(		self,
			states = None,
			initial_state = "default_initial" )

Basic Setup of states and initial_state.

Definition at line 171 of file state_machines.py.

    def __init__(self, states=None, initial_state="default_initial"):
        """
        Basic Setup of states and initial_state.
        """
        
        self.states = {}
        if states:
            for state in states:
                self.add_state(state)
        if initial_state != "default_initial":
            
            self.initial_state = initial_state
        else:
            self.add_state(initial_state)
            
            self._initial_state = State(initial_state)
 
        
        self._state = self.initial_state
        
        self.transitions = defaultdict(list)
 

Member Function Documentation

__getattr__()

__getattr__	(		self,
			name,
		**	kwargs )

Allows us to create a new method for each trigger on the fly.
If there is no trigger name in the machine to match, then the normal
AttributeError is called.

Definition at line 306 of file state_machines.py.

    def __getattr__(self, name, **kwargs):
        """
        Allows us to create a new method for each trigger on the fly.
        If there is no trigger name in the machine to match, then the normal
        AttributeError is called.
        """
        possible_transitions = self.get_transitions(self.state)
        if name not in possible_transitions:
            raise AttributeError(f"{name} does not exist in transitions for state {self.state}.")
        transition_dict = self.get_transition_dict(self.state, name)
        # \cond silence doxygen warning about _trigger
        return partial(self._trigger, name, transition_dict, **kwargs)
        # \endcond
 

_callback()

_callback ( func, ** kwargs )

staticprotected

Calls a condition/before/after.. function using arguments passed (or not).

Definition at line 344 of file state_machines.py.

    def _callback(func, **kwargs):
        """
        Calls a condition/before/after.. function using arguments passed (or not).
        """
        return func(**kwargs)
 

_trigger()

_trigger ( self, transition_name, transition_dict, ** kwargs )

protected

Runs the transition logic. Callbacks are evaluated in the order:
conditions -> before -> <new state set here> -> after.

Definition at line 320 of file state_machines.py.

    def _trigger(self, transition_name, transition_dict, **kwargs):
        """
        Runs the transition logic. Callbacks are evaluated in the order:
        conditions -> before -> <new state set here> -> after.
        """
        dest, conditions, before_callbacks, after_callbacks = (
            transition_dict["dest"],
            transition_dict["conditions"],
            transition_dict["before"],
            transition_dict["after"]
        )
        # Returns True only if every condition returns True when called
        if all(map(lambda condition: self._callback(condition, **kwargs), conditions)):
            for before_func in before_callbacks:
                self._callback(before_func, **kwargs)
            
            self.state = dest
            for after_func in after_callbacks:
                self._callback(after_func, **kwargs)
        else:
            raise ConditionError(f"Transition '{transition_name}' called for but one or more conditions "
                                 "evaluated False")
 

add_state()

add_state	(		self,
			state,
			enter = None,
			exit = None )

Adds a single state to the list of possible ones.
Should be a unique string or a State object with a unique name.

Definition at line 193 of file state_machines.py.

    def add_state(self, state, enter=None, exit=None):
        """
        Adds a single state to the list of possible ones.
        Should be a unique string or a State object with a unique name.
        """
        if isinstance(state, str):
            self.add_state(State(state, enter, exit))
        elif isinstance(state, State):
            if state.name not in self.states.keys():
                self.states[state.name] = state
            else:
                B2WARNING(f"You asked to add a state {state} but it was already in the machine states.")
        else:
            B2WARNING(f"You asked to add a state {state} but it wasn't a State or str object")
 

add_transition()

add_transition	(		self,
			trigger,
			source,
			dest,
			conditions = None,
			before = None,
			after = None )

Adds a single transition to the dictionary of possible ones.
Trigger is the method name that begins the transition between the
source state and the destination state.

The condition is an optional function that returns True or False
depending on the current state/input.

Definition at line 264 of file state_machines.py.

    def add_transition(self, trigger, source, dest, conditions=None, before=None, after=None):
        """
        Adds a single transition to the dictionary of possible ones.
        Trigger is the method name that begins the transition between the
        source state and the destination state.
 
        The condition is an optional function that returns True or False
        depending on the current state/input.
        """
        transition_dict = {}
        try:
            source = self.states[source]
            dest = self.states[dest]
            transition_dict["source"] = source
            transition_dict["dest"] = dest
        except KeyError as err:
            B2WARNING("Tried to add a transition where the source or dest isn't in the list of states")
            raise err
        if conditions:
            if isinstance(conditions, (list, tuple, set)):
                transition_dict["conditions"] = list(conditions)
            else:
                transition_dict["conditions"] = [conditions]
        else:
            transition_dict["conditions"] = [Machine.default_condition]
 
        if not before:
            before = []
        if isinstance(before, (list, tuple, set)):
            transition_dict["before"] = list(before)
        else:
            transition_dict["before"] = [before]
 
        if not after:
            after = []
        if isinstance(after, (list, tuple, set)):
            transition_dict["after"] = list(after)
        else:
            transition_dict["after"] = [after]
 
        self.transitions[trigger].append(transition_dict)
 

default_condition()

default_condition ( ** kwargs )

static

Method to always return True.

Definition at line 258 of file state_machines.py.

    def default_condition(**kwargs):
        """
        Method to always return True.
        """
        return True
 

get_transition_dict()

get_transition_dict	(		self,
			state,
			transition )

Returns the transition dictionary for a state and transition out of it.

Definition at line 361 of file state_machines.py.

    def get_transition_dict(self, state, transition):
        """
        Returns the transition dictionary for a state and transition out of it.
        """
        transition_dicts = self.transitions[transition]
        for transition_dict in transition_dicts:
            if transition_dict["source"] == state:
                return transition_dict
        else:
            raise KeyError(f"No transition from state {state} with the name {transition}.")
 

get_transitions()

get_transitions	(		self,
			source )

Returns allowed transitions from a given state.

Definition at line 350 of file state_machines.py.

    def get_transitions(self, source):
        """
        Returns allowed transitions from a given state.
        """
        possible_transitions = []
        for transition, transition_dicts in self.transitions.items():
            for transition_dict in transition_dicts:
                if transition_dict["source"] == source:
                    possible_transitions.append(transition)
        return possible_transitions
 

initial_state() [1/2]

initial_state

(

self

)

The initial state of the machine. Needs a special property to prevent trying to run on_enter callbacks when set.

Definition at line 209 of file state_machines.py.

    def initial_state(self):
        """
        The initial state of the machine. Needs a special property to prevent trying to run on_enter callbacks when set.
        """
        return self._initial_state
 

initial_state() [2/2]

initial_state	(		self,
			state )

Definition at line 216 of file state_machines.py.

    def initial_state(self, state):
        """
        """
        if state in self.states.keys():
            self._initial_state = self.states[state]
            
            self._state = self.states[state]
        else:
            raise KeyError(f"Attempted to set state to '{state}' which is not in the 'states' attribute!")
 

save_graph()

save_graph	(		self,
			filename,
			graphname )

Does a simple dot file creation to visualise states and transiitons.

Definition at line 372 of file state_machines.py.

    def save_graph(self, filename, graphname):
        """
        Does a simple dot file creation to visualise states and transiitons.
        """
        with open(filename, "w") as dotfile:
            dotfile.write("digraph " + graphname + " {\n")
            for state in self.states.keys():
                dotfile.write('"' + state + '" [shape=ellipse, color=black]\n')
            for trigger, transition_dicts in self.transitions.items():
                for transition in transition_dicts:
                    dotfile.write('"' + transition["source"].name + '" -> "' +
                                  transition["dest"].name + '" [label="' + trigger + '"]\n')
            dotfile.write("}\n")
 
 

state() [1/2]

state

(

self

)

        The current state of the machine. Actually a `property` decorator. It will call the exit method of the
        current state and enter method of the new one. To get around the behaviour e.g. for setting initial states,
        either use the `initial_state` property or directly set the _state attribute itself (at your own risk!).

Definition at line 227 of file state_machines.py.

    def state(self):
        """
                The current state of the machine. Actually a `property` decorator. It will call the exit method of the
                current state and enter method of the new one. To get around the behaviour e.g. for setting initial states,
                either use the `initial_state` property or directly set the _state attribute itself (at your own risk!).
        """
        return self._state
 

state() [2/2]

state	(		self,
			state )

Definition at line 236 of file state_machines.py.

    def state(self, state):
        """
        """
        if isinstance(state, str):
            state_name = state
        else:
            state_name = state.name
 
        try:
            state = self.states[state_name]
            # Run exit callbacks of current state
            for callback in self.state.on_exit:
                callback(prior_state=self.state, new_state=state)
            # Run enter callbacks of new state
            for callback in state.on_enter:
                callback(prior_state=self.state, new_state=state)
            # Set the state
            self._state = state
        except KeyError:
            raise MachineError(f"Attempted to set state to '{state}' which not in the 'states' attribute!")
 

Member Data Documentation

_initial_state

dict _initial_state = State(initial_state)

protected

Actual attribute holding initial state for this machine.

Definition at line 186 of file state_machines.py.

_state

dict _state = self.initial_state

protected

Actual attribute holding the Current state.

Definition at line 189 of file state_machines.py.

initial_state

initial_state = initial_state

Pointless docstring since it's a property.

Definition at line 182 of file state_machines.py.

state

state = dest

Current State of machine.

Definition at line 336 of file state_machines.py.

states

dict states = {}

Valid states for this machine.

Definition at line 176 of file state_machines.py.

transitions

transitions = defaultdict(list)

Allowed transitions between states.

Definition at line 191 of file state_machines.py.

---

The documentation for this class was generated from the following file:

• calibration/scripts/caf/state_machines.py