0
# Transitions
1

2
A lightweight, object-oriented Python state machine implementation with many extensions. Transitions provides a comprehensive and flexible API for defining states, transitions, and events with support for callbacks, conditional transitions, queued transitions, and automatic transitions. The library includes advanced features such as hierarchical state machines, diagram generation, async support, and integration with various Python frameworks.
3

4
## Package Information
5

6
- **Package Name**: transitions
7
- **Language**: Python  
8
- **Installation**: `pip install transitions`
9

10
## Core Imports
11

12
```python
13
from transitions import Machine, State, Transition, Event, EventData, MachineError
14
```
15

16
For specific functionality:
17

18
```python
19
# Core state machine
20
from transitions import Machine
21

22
# State machine with extensions
23
from transitions.extensions import GraphMachine, HierarchicalMachine, LockedMachine
24
from transitions.extensions import AsyncMachine, MachineFactory
25

26
# Individual components if needed
27
from transitions import State, Transition, Event
28
```
29

30
## Basic Usage
31

32
```python
33
from transitions import Machine
34

35
# Define states and transitions
36
states = ['sleeping', 'awake', 'eating', 'playing']
37

38
transitions = [
39
    {'trigger': 'wake_up', 'source': 'sleeping', 'dest': 'awake'},
40
    {'trigger': 'eat', 'source': 'awake', 'dest': 'eating'},
41
    {'trigger': 'play', 'source': 'eating', 'dest': 'playing'},
42
    {'trigger': 'sleep', 'source': ['awake', 'eating', 'playing'], 'dest': 'sleeping'}
43
]
44

45
# Create a simple model
46
class Pet:
47
    def __init__(self):
48
        self.name = "Fluffy"
49

50
# Initialize the machine
51
pet = Pet()
52
machine = Machine(model=pet, states=states, transitions=transitions, initial='sleeping')
53

54
# Use the state machine
55
print(pet.state)  # 'sleeping'
56
pet.wake_up()
57
print(pet.state)  # 'awake'
58
pet.eat()
59
print(pet.state)  # 'eating'
60
```
61

62
## Architecture
63

64
Transitions follows a modular architecture with core components and extensions:
65

66
- **Core Components**: Machine, State, Transition, Event, EventData provide the fundamental state machine functionality
67
- **Extensions**: Modular enhancements for specialized needs (hierarchical states, threading, async operations, diagram generation)
68
- **Factory Pattern**: MachineFactory provides convenient access to pre-configured machine combinations
69

70
The design enables incremental adoption - start with basic Machine functionality and add extensions as needed for complex requirements.
71

72
## Capabilities
73

74
### Core State Machine
75

76
Fundamental state machine functionality including state management, transitions, callbacks, and event handling. Provides the foundation for all state machine operations.
77

78
```python { .api }
79
class Machine:
80
    def __init__(self, model='self', states=None, initial='initial', transitions=None, **kwargs): ...
81
    def add_state(self, states, **kwargs): ...
82
    def add_transition(self, trigger, source, dest, **kwargs): ...
83
    def get_state(self, state): ...
84
    def is_state(self, state, model): ...
85
```
86

87
[Core State Machine](./core.md)
88

89
### Extensions and Specialized Machines
90

91
Enhanced state machines with additional capabilities including hierarchical states, thread safety, asynchronous operations, and diagram generation.
92

93
```python { .api }
94
class GraphMachine(Machine): ...
95
class HierarchicalMachine(Machine): ...
96
class LockedMachine(Machine): ...
97
class AsyncMachine(Machine): ...
98
class MachineFactory:
99
    def get_predefined(self, graph=False, nested=False, locked=False, asyncio=False): ...
100
```
101

102
[Extensions](./extensions.md)
103

104
### State and Transition Components
105

106
Individual components for states, transitions, events, and conditions that can be used to build custom state machine configurations.
107

108
```python { .api }
109
class State:
110
    def __init__(self, name, on_enter=None, on_exit=None, **kwargs): ...
111
    def enter(self, event_data): ...
112
    def exit(self, event_data): ...
113

114
class Transition:
115
    def __init__(self, source, dest, conditions=None, **kwargs): ...
116
    def execute(self, event_data): ...
117
```
118

119
[Components](./components.md)