fysom

2.1.6 verified Fri May 01 auth: no python

A simple Python finite state machine (FSM) for state management in applications. Current version: 2.1.6. Release cadence is irregular, with maintenance updates as needed.

pip install fysom

Common errors

error ImportError: No module named fysom ↓

cause The package is not installed or pip install failed due to old setuptools.

fix

Upgrade pip and setuptools: pip install --upgrade pip setuptools && pip install fysom

error TypeError: __init__() got an unexpected keyword argument 'src' ↓

cause Using version 1.x style event definitions with separate arguments instead of a dictionary.

fix

In v2.x, events must be defined as a list of dictionaries, each with keys 'name', 'src', 'dst'. Example: events=[{'name': 'wake', 'src': 'asleep', 'dst': 'awake'}]

error AttributeError: 'Fysom' object has no attribute 'wakeup' ↓

cause The event name is misspelled or the event was defined with a different name.

fix

Check the event definition; the method name is exactly the 'name' field of the event dictionary. Ensure it is lowercase and matches.

Warnings

breaking In version 2.0.0, the API changed significantly. The old 'FysomGlobal' and event callback signatures are deprecated. Upgrade scripts may break. ↓

fix Use the new Fysom class with dictionary-based event definitions. Callbacks now receive the event object instead of state names as separate arguments.

deprecated The 'final' state support in event definitions (from v1.0.13) is deprecated; use the separate 'final' property in Fysom constructor instead. ↓

fix In v2.x, set 'final' as a top-level key in the constructor dict: Fysom({'initial': 's1', 'final': 's5', 'events': [...]})

gotcha Event names must not conflict with method names on the Fysom object (e.g., 'current', 'is_finished'). Doing so will silently override or cause AttributeError. ↓

fix Avoid naming events 'current', 'is_finished', or any reserved attribute.

Imports

Fysom
wrong
```
old.fysom.Fysom
```
correct
```
from fysom import Fysom
```
In previous versions, the import path included 'old' package. Use 'from fysom import Fysom' in 2.x.

Quickstart

Create a simple state machine with two states and two events.

from fysom import Fysom

fsm = Fysom({
    'initial': 'asleep',
    'events': [
        {'name': 'wakeup', 'src': 'asleep', 'dst': 'awake'},
        {'name': 'sleep', 'src': 'awake', 'dst': 'asleep'},
    ]
})

print(fsm.current)  # 'asleep'
fsm.wakeup()
print(fsm.current)  # 'awake'
fsm.sleep()
print(fsm.current)  # 'asleep'