# Welcome to state_machine’s documentation!

## state_machine (State Machine)

Author:

- Dirk Alders <sudo-dirk@mount-mockery.de>

Description:

> This Module helps implementing state machines.

Submodules:

- `state_machine.state_machine`

Unittest:

> See also the `unittest` documentation.

Module Documentation:

class `state_machine.``state_machine`(default_state, log_lvl, **kwargs)

  Parameters:

  - default_state – The default state which is set on initialisation.
  - log_lvl – The log level, this Module logs to (see Loging-Levels of Module `logging`)

  Note

  Additional keyword parameters well be stored as varibles of the instance (e.g. to give variables or methods for transition condition calculation).

  A state machine class can be created by deriving it from this class. The transitions are defined by overriding the variable TRANSITIONS. This Variable is a dictionary, where the key is the start-state and the content is a tuple or list of transitions. Each transition is a tuple or list including the following information: (condition-method (str), transition-time (number), target_state (str)).

  Note

  The condition-method needs to be implemented as part of the new class.

  Note

  It is usefull to define the states as variables of this class.

  Example:

      #!/usr/bin/env python
      # -*- coding: UTF-8 -*-

      import sys
      sys.path.append('../..')
      import logging
      import os

      import report
      import state_machine

      logger = logging.getLogger('root')
      report.stdoutLoggingConfigure(log_name_lvl=[('root', 'DEBUG'), ])

      class trafic_lights(state_machine.state_machine):
          LOG_PREFIX = 'TraficLights:'

          STATE_RED = 'state_red'
          STATE_GREEN = 'state_green'

          CONDITION_TRUE = 'condition_true'
          CONDITION_PEDASTRIAN_REQUEST = 'condition_pedastrian_request'

          TRANSITIONS = {
              STATE_RED: (
                  (CONDITION_PEDASTRIAN_REQUEST, 1, STATE_GREEN),
              ),
              STATE_GREEN: (
                  (CONDITION_TRUE, 3, STATE_RED),
              )
          }

          def condition_true(self):
              return True

          def set_padestrian_request(self):
              logger.log(self.__log_lvl__, '%s Pedestrian gave state change request.', self.LOG_PREFIX)
              self.pedastrian_request = True

          def condition_pedastrian_request(self):
              return self.pedastrian_request

      sm = trafic_lights(trafic_lights.STATE_RED, logging.INFO, pedastrian_request=False)
      sm.register_state_change_callback(sm.STATE_GREEN, sm.CONDITION_PEDASTRIAN_REQUEST, logger.info, 'Callback information: Traffic light had been changed to green caused by pedastrian request')
      while not sm.previous_state_was(sm.STATE_GREEN):
          if sm.this_state_is(sm.STATE_RED) and sm.this_state_duration() > 0.2 and not sm.condition_pedastrian_request():
              sm.set_padestrian_request()
          sm.work()

      2021-01-07 01:36:29,619: root.state_machine - INFO - TraficLights: State change ('__init__'): None -> 'state_red'
      2021-01-07 01:36:29,819: root - INFO - TraficLights: Pedestrian gave state change request.
      2021-01-07 01:36:30,819: root.state_machine - INFO - TraficLights: State change ('condition_pedastrian_request'): 'state_red' -> 'state_green'
      2021-01-07 01:36:30,819: root.state_machine - DEBUG - Executing callback 0 - logging.info
      2021-01-07 01:36:30,819: root - INFO - Callback information: Traffic light had been changed to green caused by pedastrian request
      2021-01-07 01:36:33,819: root.state_machine - INFO - TraficLights: State change ('condition_true'): 'state_green' -> 'state_red'

  `last_transition_condition`()

    Returns: | The last transition condition.
    Return type: | str

    This method returns the last transition condition.

  `last_transition_condition_was`(condition)

    Parameters: | condition (str) – The condition to be checked
    Returns: | True if the given condition was the last transition condition, else False.
    Return type: | bool

    This methods returns the boolean information if the last transition condition is equivalent to the given condition.

  `previous_state`()

    Returns: | The previous state.
    Return type: | str

    This method returns the previous state of the state machine.

  `previous_state_duration`()

    Returns: | The time how long the previous state was active.
    Return type: | float

    This method returns the time how long the previous state was active.

  `previous_state_was`(state)

    Parameters: | state (str) – The state to be checked
    Returns: | True if the given state was previously active, else False.
    Return type: | bool

    This methods returns the boolean information if the state machine was previously in the given state.

  `register_state_change_callback`(state, condition, callback, *args, **kwargs)

    Parameters:

    - state (str) – The target state. The callback will be executed, if the state machine changes to this state. None means all states.
    - condition (str) – The transition condition. The callback will be executed, if this condition is responsible for the state change. None means all conditions.
    - callback – The callback to be executed.

    Note

    Additional arguments and keyword parameters are supported. These arguments and parameters will be used as arguments and parameters for the callback execution.

    This methods allows to register callbacks which will be executed on state changes.

  `this_state`()

    Returns: | The current state.

    This method returns the current state of the state machine.

  `this_state_duration`()

    Returns: | The time how long the current state is active.
    Return type: | float

    This method returns the time how long the current state is active.

  `this_state_is`(state)

    Parameters: | state (str) – The state to be checked
    Returns: | True if the given state is currently active, else False.
    Return type: | bool

    This methods returns the boolean information if the state machine is currently in the given state.

  `work`()

    This Method needs to be executed cyclicly to enable the state machine.

# Indices and tables

- Index
- Module Index
- Search Page