{"id":2815,"library":"transitions","title":"Transitions","description":"Transitions is a lightweight, object-oriented finite state machine implementation for Python, designed to be easy to use and extend. It supports features like hierarchical states, parallel states, conditional transitions, and callbacks. Currently at version 0.9.3, the library maintains an active development pace with minor releases frequently adding new features, bugfixes, and typing improvements.","status":"active","version":"0.9.3","language":"en","source_language":"en","source_url":"https://github.com/pytransitions/transitions","tags":["state machine","FSM","finite state machine","statechart","workflow"],"install":[{"cmd":"pip install transitions","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Machine","correct":"from transitions import Machine"},{"note":"While `State` might be in `transitions.core`, the public API exposes it directly from `transitions` for easier access.","wrong":"from transitions.core import State","symbol":"State","correct":"from transitions import State"}],"quickstart":{"code":"from transitions import Machine\n\nclass Matter(object):\n    def __init__(self):\n        self.state = None # Machine will manage this\n\n    def make_hissing_noises(self):\n        print(\"HISSSSSSSSSSSSSSSS\")\n\n    def disappear(self):\n        print(\"where'd all the liquid go?\")\n\nstates = ['solid', 'liquid', 'gas', 'plasma']\ntransitions = [\n    { 'trigger': 'melt', 'source': 'solid', 'dest': 'liquid', 'before': 'make_hissing_noises' },\n    { 'trigger': 'evaporate', 'source': 'liquid', 'dest': 'gas', 'after': 'disappear' },\n    { 'trigger': 'sublimate', 'source': 'solid', 'dest': 'gas' },\n    { 'trigger': 'ionize', 'source': 'gas', 'dest': 'plasma' }\n]\n\nlump = Matter()\nmachine = Machine(model=lump, states=states, transitions=transitions, initial='solid')\n\nprint(f\"Initial state: {lump.state}\")\nlump.melt()\nprint(f\"Current state: {lump.state}\")\nlump.evaporate()\nprint(f\"Current state: {lump.state}\")\n","lang":"python","description":"This quickstart demonstrates creating a simple state machine with a model, defining states and transitions, and triggering state changes. Callbacks can be attached to transitions (e.g., `before`, `after`) to execute logic."},"warnings":[{"fix":"Refactor state machine definitions to use the modern hierarchical state features provided by the main `Machine` class and `NestedState` objects. Review the official documentation for nested state examples.","message":"The legacy `HierarchicalMachine` implementation was removed in version 0.9.0. Users should migrate to the `NestedState` and `HierarchicalMachine` features available directly via the standard `Machine` class or its `HierarchicalMachine` extension.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Carefully order your `add_transition` calls. Place more specific or restrictive conditions before more general ones to ensure the desired transition takes precedence. Consider using the `conditions` argument within a single transition if multiple checks are needed for the same outcome.","message":"When using `add_transition` with multiple conditional transitions for the same trigger/source, the order in which transitions are added matters. Transitions are evaluated in the order they were added, and the first one whose conditions evaluate to `True` will be executed.","severity":"gotcha","affected_versions":"All"},{"fix":"When working with `queued=True`, do not rely on the return value of trigger methods to indicate immediate success. Instead, rely on callbacks (`on_enter`, `on_exit`, `after`) or monitor the model's state for eventual completion.","message":"When `queued=True` is enabled for a `Machine`, trigger calls will always return `True` immediately, as there is no way to determine at queuing time if a transition will ultimately complete successfully after processing the queue.","severity":"gotcha","affected_versions":"All (when `queued=True`)"},{"fix":"Ensure all callbacks associated with a transition's event are designed to accept the same set of arguments or use `*args` and `**kwargs` to accept arbitrary parameters. Alternatively, create wrapper functions that adapt the arguments for specific callbacks.","message":"Methods assigned as callbacks (e.g., `before`, `after`, `on_enter`, `on_exit`, `conditions`) must be able to handle all arguments that the triggering event passes. This can be problematic if different callbacks expect different data.","severity":"gotcha","affected_versions":"All"},{"fix":"If you explicitly passed `model='self'` to `Machine` and relied on a custom object also named 'self', this might break. It is recommended to either pass the actual instance of the object as the model or use `Machine.self_literal` for custom identity checks if you need to override the default behavior.","message":"In version 0.8.10, the literal string 'self' (the default model parameter of `Machine`) changed from a value check to an identity check. This affects how `Machine` determines if it should act as its own model.","severity":"breaking","affected_versions":">=0.8.10"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}