Registry / workflow / automaton

automaton

JSON →
library3.4.0pypypi✓ verified 83d ago

Automaton is a Python library for creating friendly and declarative state machines. It simplifies the definition and management of states, events, and transitions, making it easy to model complex system behaviors. The current version is 3.4.0, and the project is under active development with periodic releases.

pip install automaton
INSTALL
IMPORT
SIG · AUTOMATON
A
automaton
workflowpythonv3.4.0
Install
1.9s avg
Import
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 25.6MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 1.9s · import 0.000s · 26MB
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

StateMachine
import automaton
from automaton import StateMachine

This example demonstrates how to define a simple `LightSwitch` state machine with `off` and `on` states and `turn_on`/`turn_off` events. It shows state initialization, event triggering, and how `automaton` handles invalid transitions by raising an `InvalidTransition` exception.

from automaton import StateMachine, State, Event class LightSwitch(StateMachine): # Define states off = State("off") on = State("on") # Define events and transitions turn_on = Event(source=off, target=on) turn_off = Event(source=on, target=off) # Instantiate the state machine switch = LightSwitch() # Check initial state print(f"Initial state: {switch.current_state}") # Trigger events switch.turn_on() print(f"After turning on: {switch.current_state}") try: switch.turn_on() # This should fail as it's already on except Exception as e: print(f"Attempting to turn on again (expected error): {e}") switch.turn_off() print(f"After turning off: {switch.current_state}")
Debug
Known issues
gotchaEvents defined without a specific `source` state (`source=None` or omitted) can transition from *any* state. This can lead to unexpected behavior if strict, explicit transitions are intended.
fix
Always explicitly define the `source` state for events (e.g., `Event(source=my_state, ...)`) to enforce strict state transitions, unless a 'global' transition from any state is genuinely desired.
affects: All versions
gotchaDirectly manipulating the `_current_state` attribute is discouraged and bypasses important logic. All state changes should occur via defined `Event` objects to ensure hooks, validations, and listeners are properly invoked.
fix
Ensure all state transitions are performed by triggering `Event` objects (e.g., `my_machine.my_event()`) rather than reassigning `my_machine._current_state`.
affects: All versions
gotchaAutomaton requires Python 3.10 or newer. Attempting to install or run the library on older Python versions will result in installation failures or runtime errors.
fix
Ensure your Python environment is 3.10 or newer. Upgrade your Python installation or use a virtual environment configured with a compatible Python version.
affects: <3.10
Upgrade
Version history
3.4.0latest on PyPI · released Mar 24, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
37 hits · last 30 days
node
32
OpenAI (training)
1
Resources
automaton — pip install automaton · libregistry