Transitions

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• pip install transitions Install stable version

Imports

• Machine

  from transitions import Machine

• State

  from transitions import State

  While `State` might be in `transitions.core`, the public API exposes it directly from `transitions` for easier access.

Quickstart

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.

from transitions import Machine

class Matter(object):
    def __init__(self):
        self.state = None # Machine will manage this

    def make_hissing_noises(self):
        print("HISSSSSSSSSSSSSSSS")

    def disappear(self):
        print("where'd all the liquid go?")

states = ['solid', 'liquid', 'gas', 'plasma']
transitions = [
    { 'trigger': 'melt', 'source': 'solid', 'dest': 'liquid', 'before': 'make_hissing_noises' },
    { 'trigger': 'evaporate', 'source': 'liquid', 'dest': 'gas', 'after': 'disappear' },
    { 'trigger': 'sublimate', 'source': 'solid', 'dest': 'gas' },
    { 'trigger': 'ionize', 'source': 'gas', 'dest': 'plasma' }
]

lump = Matter()
machine = Machine(model=lump, states=states, transitions=transitions, initial='solid')

print(f"Initial state: {lump.state}")
lump.melt()
print(f"Current state: {lump.state}")
lump.evaporate()
print(f"Current state: {lump.state}")