python-statemachine

What it is and what it does

Python StateMachine is a declarative state machine and statechart library that lets you model complex workflows and control logic as classes with states and transitions. You define states as class attributes, connect them with transition rules, and attach callbacks (guards, entry/exit handlers) that run when events fire or states change. The library handles both synchronous and asynchronous callbacks transparently, automatically detecting async functions and switching to an async engine when needed.

The package supports flat finite state machines for simple workflows, but also hierarchical compound states for breaking complex behavior into nested levels, parallel regions for concurrent sub-machines, history states for remembering previous positions, and conditional transitions guarded by custom predicates. It includes error handling (runtime exceptions become error.execution events), eventless transitions that fire automatically when conditions are met, and introspection methods like checking active states or generating text/graphical representations of the machine. With no external runtime dependencies and support for Python 3.10+, it integrates cleanly into sync and async codebases.

Use it for:

• Model approval workflows with conditional routing: pending → approved or rejected based on score guards.
• Implement document editing pipelines with nested states: editing (draft/review) → published, tracking hierarchical progress.
• Build deployment orchestration with parallel regions: compile and test simultaneously, fire done event only when all regions finish.
• Create traffic light or traffic-control systems with cyclic state transitions and entry/exit side effects.
• Handle async task workflows where callbacks are coroutines and state transitions await completion.
• Implement error recovery: catch runtime exceptions as error.execution events and transition to failure states.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Defines finite state machines and statecharts with a declarative Python API, supporting flat states, compound hierarchies, parallel regions, history states, guards, and both sync and async callbacks.

Yes. The library is production-stable (Development Status 5), actively maintained, has no known vulnerabilities, zero runtime dependencies, and a clean declarative API. Install it if you need to model workflows, control logic, or any system with discrete states and event-driven transitions — from simple state machines to complex statecharts with hierarchy and concurrency. The async support and low friction make it suitable for modern Python projects.

Install

python-statemachine on PyPI

pip install python-statemachine

uv add python-statemachine

poetry add python-statemachine

Installing python-statemachine

Before you install

Low friction: pure Python wheel with no runtime dependencies. Active maintenance with a recent release (13 days old) and 1278 repository stars.

License in practice

MIT License (permissive) — you can use, modify, and distribute this package freely in commercial and open-source projects with minimal restrictions.

Quickstart

from statemachine import StateChart, State

class TrafficLight(StateChart):
    green = State(initial=True)
    yellow = State()
    red = State()
    cycle = green.to(yellow) | yellow.to(red) | red.to(green)

sm = TrafficLight()
sm.send("cycle")
print(sm.green.is_active)

Requires Python 3.10 or later.

Verify before relying

• Whether the library supports pickling or serialization of state machine instances.
• Performance characteristics under high-frequency event dispatch or deeply nested compound states.
• Availability and scope of visualization/diagram generation beyond the basic graph example shown.

Package facts

Evidence: python_statemachine-3.2.1-py3-none-any.whl

Tags

More Libraries packages