{"id":9506,"library":"automaton","title":"Automaton","description":"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.","status":"active","version":"3.4.0","language":"en","source_language":"en","source_url":"https://github.com/lycantropos/automaton","tags":["state machine","finite automaton","workflow","declarative","pattern matching"],"install":[{"cmd":"pip install automaton","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"StateMachine","correct":"from automaton import StateMachine"},{"symbol":"State","correct":"from automaton import State"},{"symbol":"Event","correct":"from automaton import Event"}],"quickstart":{"code":"from automaton import StateMachine, State, Event\n\nclass LightSwitch(StateMachine):\n    # Define states\n    off = State(\"off\")\n    on = State(\"on\")\n\n    # Define events and transitions\n    turn_on = Event(source=off, target=on)\n    turn_off = Event(source=on, target=off)\n\n# Instantiate the state machine\nswitch = LightSwitch()\n\n# Check initial state\nprint(f\"Initial state: {switch.current_state}\")\n\n# Trigger events\nswitch.turn_on()\nprint(f\"After turning on: {switch.current_state}\")\n\ntry:\n    switch.turn_on() # This should fail as it's already on\nexcept Exception as e:\n    print(f\"Attempting to turn on again (expected error): {e}\")\n\nswitch.turn_off()\nprint(f\"After turning off: {switch.current_state}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Events 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all state transitions are performed by triggering `Event` objects (e.g., `my_machine.my_event()`) rather than reassigning `my_machine._current_state`.","message":"Directly 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Automaton 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.","severity":"gotcha","affected_versions":"<3.10"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Review your state machine definition and ensure that the `source` state for the triggered event matches the machine's `current_state`. Design your events and state transitions to handle all valid paths.","cause":"Attempting to trigger an `Event` from a state that is not specified as its `source` state in the state machine definition.","error":"automaton.exceptions.InvalidTransition: Event 'event_name' cannot transition from state 'current_state'."},{"fix":"Install the library using `pip install automaton`. If using a virtual environment, ensure it is activated before installation.","cause":"The `automaton` library is not installed in your current Python environment or is not accessible on the Python path.","error":"ModuleNotFoundError: No module named 'automaton'"},{"fix":"Upgrade your Python environment to 3.10 or newer. You can use `pyenv` or `conda` to manage multiple Python versions, or create a virtual environment with a compatible Python version.","cause":"You are attempting to install or run `automaton` on a Python version older than 3.10, which is not supported.","error":"ERROR: Package 'automaton' requires a different Python version: >=3.10"}]}