Automat Finite State Machines

25.4.16 · active · verified Thu Apr 09

Automat provides a declarative, self-service API for defining finite-state machines directly within your Python classes. It helps manage complex state transitions and actions in a structured, testable way. The current version is 25.4.16, and it maintains a relatively stable release cadence with minor updates and bug fixes.

Warnings

gotcha Failing to call `_machine.initial(self, self.initial_state)` in your class's `__init__` method will result in an uninitialized state machine, preventing any transitions.
Fix: Always ensure your class's `__init__` explicitly calls `self._machine.initial(self, self.your_initial_state)` to set the starting state.
gotcha When defining transitions with `state.upon(input, ...)` if `enter` is omitted, the machine will remain in the *current* state by default. This can be unexpected if you intended a state change.
Fix: Always explicitly specify the `enter` argument in `state.upon` if you intend for the machine to transition to a new state. If you mean to stay in the current state, `enter=self.current_state` (or omitting `enter`) is correct.
gotcha Output methods (decorated with `@_machine.output()`) are instance methods and receive `self` as their first argument. They are called in the context of the instance, allowing them to access and modify instance attributes.
Fix: Design your output methods to accept `self` and use it to interact with the object's internal state or perform side effects directly related to the object.
gotcha Automat discourages directly modifying the machine's state outside of defined inputs and transitions. Attempting to do so breaks the FSM's contract and can lead to unpredictable behavior.
Fix: Always drive state changes through the defined `@_machine.input()` methods. If you need to expose internal state, do so via read-only properties or specific queries, not direct manipulation.

Install

pip install automat Install stable version

Imports

MethodicalMachine
```
from automat import MethodicalMachine
```

Quickstart

This quickstart demonstrates how to define a simple state machine for a door with 'closed' and 'open' states, and 'open_door'/'close_door' inputs. It also shows how to associate outputs (actions) with state transitions and how to initialize and interact with the machine.

from automat import MethodicalMachine

class Door(object):
    _machine = MethodicalMachine()

    @_machine.state()
    def closed(self):
        "The door is closed."

    @_machine.state()
    def open(self):
        "The door is open."

    @_machine.input()
    def open_door(self):
        "Open the door."

    @_machine.input()
    def close_door(self):
        "Close the door."

    @_machine.output()
    def _actuallyOpen(self):
        print("The door opens.")

    @_machine.output()
    def _actuallyClose(self):
        print("The door closes.")

    closed.upon(open_door, enter=open, outputs=[_actuallyOpen])
    open.upon(close_door, enter=closed, outputs=[_actuallyClose])

    def __init__(self):
        # Crucial: Initialize the machine with an initial state
        self._machine.initial(self, self.closed)

# Example usage:
d = Door()
print(f"Initial state: {d._machine.current_state(d)._name}")
d.open_door()
print(f"After open_door: {d._machine.current_state(d)._name}")
d.close_door()
print(f"After close_door: {d._machine.current_state(d)._name}")

view raw JSON →