State Machine¶
State Machine module¶
This module contains the StateMachine
class.
This StateMachine
class is designed to do 3 specific things:
- Allow only transitions that are valid for the current state (enforced by the
State
object).- Pass events to the
State
and let the state handle them. You can pass both transition events as well as events that should trigger something, which you can define yourself. TheState
class can be extended withhandle_...()
functions that handle these specific events. You should be careful not to name your transitions the same as yourhandle_...()
functions because an exception will be raised if they collide.- Pass actions to the
State
and let the state handle them. TheState
class can be extended withaction_...()
functions that do these specific actions.
The state machine’s __init__()
takes a dict argument that contains
all states the state machine should support.
The states can have ‘on_enter’ and ‘on_leave’ definitions, which are lists
of actions to do when the state is entered or left respectively. These
actions have to be defined in the State
object for this to work.
There should also be a list of ‘allowed_actions’ array defined in each
state definition, this array should contain the action names without the
prefix ‘action_’. The reason the ‘action_’ is not prefixed is that
the prefix string can be changed in a class extension, to e.g.: ‘do_’.
-
class
otrbot.statemachine.statemachine.
StateMachine
(states_object, ctxt)¶ This class in not supposed to be used directly, you should extend this class and add the application specific functions to it.
You will most likely require your own definition of the
State
class as well, to override the definition of theState
class the state machine uses, you will need to override theSTATE_OBJECT
in your state machine class extension.You should also use
super()
to initialise theStateMachine
object, you will need to pass some arguments too, see below.Initialise the
StateMachine
class.Parameters: - states_object (dict) – A dict containing all possible states, its transitions, actions, ‘on_enter’ and ‘on_leave’ actions
- ctxt (SharedContext) – A shared context that contains the current state context data
Raises: StateDoesNotExist – Indicates that the state you chose to be the initial state is not in the states_object
-
STATE_OBJECT
¶ alias of
State
-
action
(action, *args, **kwargs)¶ Run an action using the current state.
Parameters: The action will be handled by the current state which is an instance of
State
. SeeState.action()
for more information.
-
state
¶ Return current state.
Returns State: The instance of the current State
object.
-
handle
(event, *args, **kwargs)¶ Handle an event using the current state.
Parameters: The event will be handled by the current state which is an instance of
State
. SeeState.handle()
for more information.
-
ctxt
¶ Return the current context.
Returns SharedContext: The shared context used by the state machine
State module¶
This module contains the State
class for the
StateMachine
.
You can extend this class to add action_...()
and handle_...()
functions. To let the StateMachine
use your own custom state
class, you need to extend the StateMachine
class and override the
StateMachine.STATE_OBJECT
constant.
-
class
otrbot.statemachine.state.
State
(name, states_object, ctxt)¶ This class in not supposed to be used directly, you should extend this class and add the application specific functions to it.
To override the definition of the
State
classthe state machine uses, you will need to override theSTATE_OBJECT
in your state machine class extension.You should also use
super()
to initialise theState
object, you will need to pass some arguments too, see below.If you want to define different prefixes for the
action_...()
orhandle_...()
functions, e.g.:do_...()
, you can override thePREFIX_ACTION
or thePREFIX_HANDLE
class constants.Initialise the state.
Parameters: - name (str) – The name of the current state
- states_object (dict) – A dict containing all possible states, its transitions, actions, ‘on_enter’ and ‘on_leave’ actions
- ctxt (SharedContext) – A shared context that contains the current state context data
-
on_enter
()¶ When the state is entered the “on_enter” actions will be executed.
-
on_leave
()¶ When the state is left the “on_leave” actions will be executed.
-
action
(action, *args, **kwargs)¶ Run an action that is defined in the
State
and prefixed byPREFIX_ACTION
.Parameters: Raises: - NotImplementedError – If the requested action is not implemented
- ActionNotAllowed – If the action is not allowed within the current state.
-
handle
(event, *args, **kwargs)¶ Handle events passed to the
State
object.There are 2 types of events that can be handled by state objects:
- Transition events, which should cause a transition to another state if the transition is allowed.
- Events that should be handled by the state without transitioning.
Parameters: Raises: CannotHandle – If there is no way to handle the event.
-
possible_actions
¶ Return all actions that are defined in the
State
object.The results of the introspection are cached, if you dynamically modify the object after getting this property the changes will not be reflected by the result.
Returns set: All actions defined in this State
object.
-
ctxt
¶ Return the current context.
Returns SharedContext: The shared context used by the state object
Shared Context module¶
This module contains the SharedContext
class.
This SharedContext
hold all the data that needs to be shared
between the State
and the StateMachine
objects.
A shared context for the state machine and the state.
Parameters: state (str) – The curent StateMachine state