You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://github.com/fgmacedo/python-statemachine/compare/main...develop)
9
9
10
10
11
11
Python [finite-state machines](https://en.wikipedia.org/wiki/Finite-state_machine) made easy.
Welcome to python-statemachine, an intuitive and powerful state machine framework designed for a
19
-
great developer experience.
20
-
21
-
🚀 With StateMachine, you can easily create complex, dynamic systems with clean, readable code.
22
-
23
-
💡 Our framework makes it easy to understand and reason about the different states, events and
24
-
transitions in your system, so you can focus on building great products.
25
-
26
-
🔒 python-statemachine also provides robust error handling and ensures that your system stays
27
-
in a valid state at all times.
28
-
29
-
30
-
A few reasons why you may consider using it:
31
-
32
-
* 📈 python-statemachine is designed to help you build scalable,
33
-
maintainable systems that can handle any complexity.
34
-
* 💪 You can easily create and manage multiple state machines within a single application.
35
-
* 🚫 Prevents common mistakes and ensures that your system stays in a valid state at all times.
36
-
37
-
38
-
## Getting started
39
-
20
+
great developer experience. We provide an _pythonic_ and expressive API for implementing state
21
+
machines in sync or asynchonous Python codebases.
22
+
23
+
## Features
24
+
25
+
- ✨ **Basic components**: Easily define **States**, **Events**, and **Transitions** to model your logic.
26
+
- ⚙️ **Actions and handlers**: Attach actions and handlers to states, events, and transitions to control behavior dynamically.
27
+
- 🛡️ **Conditional transitions**: Implement **Guards** and **Validators** to conditionally control transitions, ensuring they only occur when specific conditions are met.
28
+
- 🚀 **Full async support**: Enjoy full asynchronous support. Await events, and dispatch callbacks asynchronously for seamless integration with async codebases.
29
+
- 🔄 **Full sync support**: Use the same state machine from synchronous codebases without any modifications.
30
+
- 🎨 **Declarative and simple API**: Utilize a clean, elegant, and readable API to define your state machine, making it easy to maintain and understand.
31
+
- 👀 **Observer pattern support**: Register external and generic objects to watch events and register callbacks.
32
+
- 🔍 **Decoupled design**: Separate concerns with a decoupled "state machine" and "model" design, promoting cleaner architecture and easier maintenance.
33
+
- ✅ **Correctness guarantees**: Ensured correctness with validations at class definition time:
34
+
- Ensures exactly one `initial` state.
35
+
- Disallows transitions from `final` states.
36
+
- Requires ongoing transitions for all non-final states.
37
+
- Guarantees all non-final states have at least one path to a final state if final states are declared.
38
+
- Validates the state machine graph representation has a single component.
39
+
- 📦 **Flexible event dispatching**: Dispatch events with any extra data, making it available to all callbacks, including actions and guards.
40
+
- 🔧 **Dependency injection**: Needed parameters are injected into callbacks.
41
+
- 📊 **Graphical representation**: Generate and output graphical representations of state machines. Create diagrams from the command line, at runtime, or even in Jupyter notebooks.
42
+
- 🌍 **Internationalization support**: Provides error messages in different languages, making the library accessible to a global audience.
43
+
- 🛡️ **Robust testing**: Ensured reliability with a codebase that is 100% covered by automated tests, including all docs examples. Releases follow semantic versioning for predictable releases.
44
+
- 🏛️ **Domain model integration**: Seamlessly integrate with domain models using Mixins.
45
+
- 🔧 **Django integration**: Automatically discover state machines in Django applications.
46
+
47
+
48
+
49
+
## Installing
40
50
41
51
To install Python State Machine, run this command in your terminal:
42
52
@@ -48,6 +58,8 @@ our docs for more details.
48
58
49
59
pip install python-statemachine[diagrams]
50
60
61
+
## First example
62
+
51
63
Define your state machine:
52
64
53
65
```py
@@ -108,7 +120,27 @@ Then start sending events to your new state machine:
108
120
109
121
```
110
122
111
-
That's it. This is all an external object needs to know about your state machine: How to send events.
123
+
You can use the exactly same state machine from an async codebase:
124
+
125
+
126
+
```py
127
+
>>>asyncdefrun_sm():
128
+
... asm = TrafficLightMachine()
129
+
... results = []
130
+
...for _i inrange(4):
131
+
... result =await asm.send("cycle")
132
+
... results.append(result)
133
+
...return results
134
+
135
+
>>> asyncio.run(run_sm())
136
+
Don't move.
137
+
Go ahead!
138
+
['Running cycle from green to yellow', 'Running cycle from yellow to red', ...
139
+
140
+
```
141
+
142
+
143
+
**That's it.** This is all an external object needs to know about your state machine: How to send events.
112
144
Ideally, all states, transitions, and actions should be kept internally andnot checked externally to avoid unnecessary coupling.
113
145
114
146
But if your use case needs, you can inspect state machine properties, like the current state:
Copy file name to clipboardExpand all lines: docs/releases/2.3.0.md
+7-22Lines changed: 7 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,14 @@
4
4
5
5
## What's new in 2.3.0
6
6
7
-
In this release, we conducted a significant update focusing on adding asynchronous support, and enhancing overall functionality. In fact, the approach we took was to go all the way down changing the internals of the library to be fully async, keeping only the current external API as a thin sync wrapper.
7
+
This release has a high expected feature, we're adding [asynchronous support](../async.md), and enhancing overall functionality. In fact, the approach we took was to go all the way down changing the internals of the library to be fully async, keeping only the current external API as a thin sync/async adapter.
0 commit comments