Skip to content

Package structure: core vs optional

PyStator is split into a core FSM library and optional layers (REST API, DB, UI, schedulers). You can use the core alone; add extras when you need them.

Core (always installed)

The core is the state machine library. Everything you need to define and run FSMs lives here.

Area Modules / components Purpose
Machine & instance StateMachine, StateMachineBuilder, EntitySession Load FSM from YAML/dict or build in code; process() / send().
Events & types Event, State, Transition, TransitionResult, GuardSpec, ActionSpec, CheckSpec, etc. Events and immutable FSM value types.
Guards & actions GuardRegistry, GuardEvaluator, ActionRegistry, ActionExecutor Register and run guards and actions by name.
Declarative checks.evaluate_check, effects.apply_effect YAML check: guards and set / timestamp / … effects without Python.
Config config.loader, config.models, config.converter, config.validator Load/validate YAML or dict and convert to internal types.
Stores StateStore, AsyncStateStore, InMemoryStateStore, PostgresStateStore, RedisStateStore, … Persistence adapters (some require optional deps).
Orchestrator Orchestrator Sandwich loop: load state by entity ID → process → persist → run actions (optional scheduler).
Hooks TransitionObserver, LoggingHook, MetricsCollector, StructuredLoggingHook Observability and metrics.
Sinks pystator.sinks Event/metric sinks for actions and tooling.
Lint pystator.lint.lint Static warnings over FSM config.
Builtins pystator.builtins Optional pre-registered guard/action packs.
Visualization to_mermaid, to_dot, etc. Generate diagrams from FSM config.
Errors FSMError, ConfigurationError, InvalidTransitionError, etc. Exception hierarchy.

Internal implementation details (not part of the public API) live in modules prefixed with _: _types, _engine, _hierarchy, _parallel. You typically use the public classes and functions only.

Install: pip install pystator (core is always present).

Optional (extras)

These components build on the core and are optional. Install them only if you need REST API, DB persistence, web UI, or specific schedulers.

Extra Install What it adds
API pip install pystator[api] REST API (pystator api), DB/migrations (Alembic/SQLAlchemy), PostgreSQL and MongoDB drivers, Pydantic validation, inline expr: guards (simpleeval), and the local docs site (pystator docs serve, MkDocs).
Worker pip install pystator[worker] SQLAlchemy/Alembic + Redis/Celery + PostgreSQL driver for pystator worker, worker_events, and submit_event(). Requires PYSTATOR_DATABASE_URL at runtime. See Worker.
UI pip install pystator[ui] (often with [api]) Static/UI dev server; pystator ui serve / pystator ui dev.
All (runtime) pip install pystator[all] api + worker + ui in one install (no dev-only tools).
Schedulers Core code in package; Redis/Celery via [worker] / env AsyncioScheduler, RedisScheduler, CeleryScheduler for after: transitions with the Orchestrator.
Dev pip install pystator[dev] api + worker + ui plus pytest, ruff, mypy, notebooks, etc.

Directory layout in the source tree:

  • Core: machine.py, instance.py, event.py, errors.py, guards.py, actions.py, checks.py, effects.py, hooks.py, lint.py, orchestrator.py, visualization.py, builtins/, sinks.py, _types.py, _engine.py, _hierarchy.py, _parallel.py, config/, stores/.
  • Optional: api/ (REST API), worker/ (event-processing service, worker_events, submit_event), db/ (migrations, models), ui/ (frontend), scheduler/ (scheduler adapters; code is in base install but you only need it for delayed transitions).

When to use what

  • Only core: Define FSMs in YAML, use StateMachine.from_yaml() and either machine.process() (stateless) or machine.create() → EntitySession.send() (stateful in memory). Add a StateStore and Orchestrator when you need persistence by entity ID.
  • Core + API: Run pystator api to expose validate/process and optional machine CRUD over HTTP. Requires pystator[api].
  • Core + Worker: pip install pystator[worker], run pystator worker, enqueue with submit_event(). Requires a database (pystator db upgrade). See Worker.
  • Core + schedulers: Use an Orchestrator with AsyncioScheduler, RedisScheduler, or CeleryScheduler for delayed transitions. Scheduler code is in the base package; Redis/Celery may need extra dependencies.

See Concepts for the three ways to run a machine (EntitySession, stateless process, Orchestrator).