PyStator Documentation¶
PyStator is a configuration-driven, stateless finite state machine library for Python. Define behavior in YAML or JSON; compute transitions from (current state + event + context); run guards and actions. Optional REST API, worker queue, and UI use the same model.
Documentation map¶
| Section | Description |
|---|---|
| Getting started | Install, first FSM, process(), EntitySession, API pointers |
| Concepts | States, transitions, guards, actions, Orchestrator, hierarchical and parallel |
| Naming rules | Valid identifiers for states, triggers, guards, actions |
| Package structure | Core vs extras ([api], [worker], [ui], [all], [dev]) |
| Declarative features | YAML check: / effects, builtins, sinks, lint, StateMachineBuilder |
| Architecture | Design goals, sandwich pattern, components |
| Schedulers | Delayed transitions (after), Asyncio / Redis / Celery |
| Configuration | pystator.cfg, environment, database |
| Discovery | Inferred FSM candidates, shadow-mode comparison, discovery APIs |
| Worker | pystator worker, submit_event, worker_events, scaling |
| State stores | In-memory, Postgres, Redis, MongoDB, custom |
| Tutorials | Order workflow, API & UI |
| Examples | Runnable examples |
| Reference | FSM config schema |
| API reference | Condensed Python API; generated pages under api/ |
Quick links¶
- I want to run something in 2 minutes → Repository README (Quick start) or Getting started
- I want to understand states and transitions → Concepts
- I want to know what's core vs optional → Package structure
- I want to understand how to run / scale → Concepts: Running a machine, Schedulers
- I want a continuous service that processes events from a queue → Worker
- I want to build an order workflow → Tutorial: Order workflow
- I want to use the REST API and UI → Tutorial: API and UI
- I want to see full code examples → Examples and the
examples/tree on GitHub - I want valid names for states and triggers → Naming rules
- I want the full YAML/config schema → FSM configuration reference
- I want to understand design and architecture → Architecture
Prerequisites¶
- Python 3.11+
- Core:
pip install pystator - REST API, DB drivers, migrations, Pydantic validation, inline
expr:guards, local docs site:pip install pystator[api] - Full runtime stack (API + worker + UI):
pip install pystator[all] - Worker +
submit_event:pip install pystator[worker]and a database (PYSTATOR_DATABASE_URL)