# `statemachine` – Utils for implementing a state machine

class aioxmpp.statemachine.OrderedStateMachine(initial_state, *, loop=None)

  `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:

  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(new_state)

    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:

  async wait_for(new_state)

    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`).

  async wait_for_at_least(new_state)

    Wait for a state to be entered which is greater than or equal to new_state and return.

class aioxmpp.statemachine.OrderedStateSkipped(skipped_state)

  This exception signals that a state has been skipped in a `OrderedStateMachine` and cannot be waited for anymore.

  skipped_state

    The state which a routine attempted to wait for and which cannot be reached by the state machine anymore.