{"id":4732,"library":"python-statemachine","title":"Python Statemachine","description":"Python Statemachine is an intuitive and powerful library for implementing finite state machines and statecharts. It offers a clean, pythonic, and declarative API for both synchronous and asynchronous Python codebases, supporting advanced features like compound states, parallel regions, history states, and dynamic diagram generation. The library maintains an active development pace with frequent updates and major releases introducing significant new capabilities.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/fgmacedo/python-statemachine","tags":["state machine","finite state machine","fsm","workflow","statechart","async"],"install":[{"cmd":"pip install python-statemachine","lang":"bash","label":"Default Install"},{"cmd":"pip install python-statemachine[diagrams]","lang":"bash","label":"With Diagramming Support"}],"dependencies":[{"reason":"Required for generating state machine diagrams.","package":"pydot","optional":true}],"imports":[{"note":"Introduced in v3.0, recommended for new projects and statechart features.","symbol":"StateChart","correct":"from statemachine import StateChart, State"},{"note":"Main class in v2.x, preserved in v3.x for backward compatibility. Use StateChart for new features.","symbol":"StateMachine","correct":"from statemachine import StateMachine, State"}],"quickstart":{"code":"from statemachine import StateChart, State\n\nclass TrafficLightMachine(StateChart):\n    \"A traffic light machine\"\n    green = State(initial=True)\n    yellow = State()\n    red = State()\n\n    cycle = (\n        green.to(yellow)\n        | yellow.to(red)\n        | red.to(green)\n    )\n\n    def before_cycle(self, event: str, source: State, target: State):\n        return f\"Running {event} from {source.id} to {target.id}\"\n\n    def on_enter_red(self):\n        print(\"Don't move.\")\n\n    def on_exit_red(self):\n        print(\"Go ahead!\")\n\nsm = TrafficLightMachine()\nprint(f\"Initial state: {sm.current_state.id}\")\nprint(sm.send(\"cycle\"))\nprint(f\"Current state: {sm.current_state.id}\")\nprint(sm.send(\"cycle\"))\nprint(f\"Current state: {sm.current_state.id}\")\nprint(sm.send(\"cycle\"))\nprint(f\"Current state: {sm.current_state.id}\")","lang":"python","description":"This quickstart defines a `TrafficLightMachine` as a `StateChart` with three states: `green`, `yellow`, and `red`. A `cycle` event transitions the light sequentially. It includes `before_cycle`, `on_enter_red`, and `on_exit_red` methods, which are automatically called during transitions and state entries/exits respectively."},"warnings":[{"fix":"For new projects or to use full statechart capabilities, import and inherit from `StateChart` instead of `StateMachine`. Refer to the upgrade guide for migration details from 2.x.","message":"Version 3.0.0 introduces `StateChart` as the new recommended base class for full statechart support (e.g., compound states, parallel regions, history states) and modern defaults. While the older `StateMachine` class is preserved, it maintains 2.x defaults and may not expose all new features. New projects should prefer `StateChart`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace calls to `sm.run('event')` with `sm.send('event')`. Review documentation on the RTC processing model if your state machine relies on specific nested event behaviors.","message":"In version 2.0.0, the `StateMachine.run()` method was removed in favor of `StateMachine.send()` for triggering events. Additionally, the default event processing model changed to 'Run-to-completion (RTC)', which affects how nested events are handled.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update any code referencing `State.identification` to `State.id`. Consider relying on automatic state naming unless an explicit custom name is required.","message":"Version 2.0.0 removed `State.identification`, replacing it with `State.id`. State names also became optional, automatically deriving from the class variable name by default.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `Graphviz` is installed and accessible in your system's PATH (e.g., `sudo apt install graphviz` on Debian/Ubuntu, or follow instructions for other OS).","message":"Diagram generation (using `python-statemachine[diagrams]`) requires the external `Graphviz` command-line tool (`dot`) to be installed on your system, in addition to the Python `pydot` dependency.","severity":"gotcha","affected_versions":"All versions with diagram support"},{"fix":"Ensure all non-final states have at least one outgoing transition. If intentional, you can silence the warning or explicitly set `strict_states=False` on your `StateMachine`/`StateChart` class. Prepare for `strict_states=True` to become the default in future major releases.","message":"From version 2.2.0, the library warns if non-final states do not have outgoing transitions, indicating potential 'trapped' states. This check is currently a warning but will become an exception by default (`strict_states=True`) in the next major release.","severity":"deprecated","affected_versions":">=2.2.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}