pytransitions/transitions

Once a Machine is attached to a model, you can trigger transitions in two ways:

1. Automatic methods: transitions automatically attaches methods to your model named after each trigger. Note: If your model already has a method with the same name, transitions will not overwrite it.
2. The trigger method: Use model.trigger('trigger_name') for dynamic triggering where the name is a string.

Warning: Avoid naming your model's existing methods the same as your transition triggers to prevent conflicts.

Transitions uses the standard Python logging module. State changes, transition triggers, and conditional checks are logged at the INFO level. You can configure the log level for the transitions logger specifically.

import logging

# Basic setup to see DEBUG messages
logging.basicConfig(level=logging.DEBUG)

# Set transitions specifically to INFO to hide DEBUG noise
logging.getLogger('transitions').setLevel(logging.INFO)

By default, transitions processes events instantly. If a transition is triggered inside an on_enter callback, it may execute before the after callback of the original transition, leading to unexpected execution orders.

To ensure a transition is fully finished before the next one begins, enable queuing in the Machine initializer by setting queued=True.

Execution Order Comparison:

• Default: prepare $\rightarrow$ before $\rightarrow$ on_enter_B $\rightarrow$ on_enter_C $\rightarrow$ after (if C was triggered from B's enter).
• Queued: prepare $\rightarrow$ before $\rightarrow$ on_enter_B $\rightarrow$ queue(to_C) $\rightarrow$ after $\rightarrow$ on_enter_C.

Note: When using a queue, the trigger call will always return True because the success of a queued transition cannot be determined at the time of queuing.

Once a Machine is bound to a model, you can trigger transitions in two ways:

1. Directly via generated methods: If a transition has a trigger named 'melt', the model will have a method melt().
2. Dynamically via trigger(): Call the trigger(name) method on the model, passing the trigger name as a string.

Example transition definition:

{ 'trigger': 'melt', 'source': 'solid', 'dest': 'liquid' }

You can extend state functionality by decorating a machine class with @add_state_features. This allows you to pass extra keywords in the states definition.

To create your own extension, write a Mixin that overrides __init__, enter, and exit.

Note: Decorated machines cannot be pickled because the dynamically generated CustomState is not picklable. For picklable machines, define a custom state class and assign it to the machine's state_cls attribute.

from transitions import Machine
from transitions.extensions.states import add_state_features, Tags, Timeout

@add_state_features(Tags, Timeout)
class CustomStateMachine(Machine):
    pass

# States can now use 'tags' and 'timeout' keywords
states = [
    {'name': 'preparing', 'tags': ['home', 'busy']},
    {'name': 'waiting', 'timeout': 1, 'on_timeout': 'go'}
]

To avoid using threads for timeouts in an AsyncMachine, use the AsyncTimeout extension from transitions.extensions.asyncio. It is highly recommended to pass queued=True to the constructor to prevent race conditions between timeouts and manual events.

import asyncio
from transitions.extensions.states import add_state_features
from transitions.extensions.asyncio import AsyncTimeout, AsyncMachine

@add_state_features(AsyncTimeout)
class TimeoutMachine(AsyncMachine):
    pass

states = ['A', {'name': 'B', 'timeout': 0.2, 'on_timeout': 'to_C'}, 'C']
m = TimeoutMachine(states=states, initial='A', queued=True)

You can execute code automatically when entering or leaving a state using callbacks.

Ways to define callbacks:

1. In the State constructor: Pass a list of method names to on_enter or on_exit.
2. On the Machine instance: Use dynamically generated methods machine.on_enter_<state_name>(callback_name) or machine.on_exit_<state_name>(callback_name).
3. In the Model class: Define methods named on_enter_<state_name> or on_exit_<state_name> directly on your model class.

Note: on_enter callbacks do not fire during the initial Machine setup if the machine starts in that state. To trigger them, you must transition into the state explicitly.

To use advanced graphing features, you must install the system-level graphviz library and the corresponding Python packages.

System Installation:

• Ubuntu/Debian: sudo apt-get install graphviz graphviz-dev
• MacOS: brew install graphviz
• Conda: conda install graphviz python-graphviz

Python Installation:

• For pygraphviz support: pip install graphviz pygraphviz
• For the diagrams extras: pip install transitions[diagrams]

sudo apt-get install graphviz graphviz-dev  # Ubuntu and Debian
brew install graphviz  # MacOS
conda install graphviz python-graphviz  # (Ana)conda

pip install graphviz pygraphviz  # install graphviz and/or pygraphviz manually...
pip install transitions[diagrams]  # ... or install transitions with 'diagrams' extras

Since version 0.8.0, (Nested)State instances are referenced rather than copied. This allows you to define a HierarchicalMachine for a specific task and embed it as a substate in another machine.

Key behaviors:

• Changes to the embedded machine's states/events will influence the parent machine.
• If you pass a machine via the children keyword, its initial state is assigned to the new parent state. To prevent this, set initial: False in the parent state definition.
• To make an embedded machine 'return' to a super state upon reaching a specific state, use the remap keyword in the parent state definition.