OrderedStateMachine provides facilities to implement a state machine. Besides storing the state, it provides coroutines which allow to wait for a specific state.
The state machine uses initial_state as initial state. States used by OrderedStateMachine must be ordered; a sanity check is performed by checking if the initial_state is less than itself. If that check fails, TypeError is raised.
Reading and manipulating the state:
The current state of the state machine. Writing to this attribute advances the state of the state machine.
Attempting to change the state to a state which is less than the current state will result in a ValueError exception; an OrderedStateMachine can only move forwards.
Any coroutines waiting for a specific state to be reached will be woken up appropriately, see the specific methods for details.
Rewind can be used as an exceptional way to roll back the state of a OrderedStateMachine.
Rewinding is not the usual use case for an OrderedStateMachine. Usually, if the current state A is greater than any given state B, it is assumed that state B cannot be reached anymore (which makes wait_for() raise).
It may make sense to go backwards though, and in cases where the ability to go backwards is sensible even if routines which previously attempted to wait for the state you are going backwards to failed, using a OrderedStateMachine is still a good idea.
Waiting for specific states:
Wait for an exact state new_state to be reached by the state machine.
If the state is skipped, that is, if a state which is greater than new_state is written to state, the coroutine raises OrderedStateSkipped exception as it is not possible anymore that it can return successfully (see state).
This exception signals that a state has been skipped in a OrderedStateMachine and cannot be waited for anymore.
The state which a routine attempted to wait for and which cannot be reached by the state machine anymore.