Skip to content

API Reference

Generated reference pages use mkdocstrings (Google-style docstrings in source). Install pystator[api] so Python can import SQLAlchemy-backed stores and the full dependency tree, then from the repo root run mkdocs serve or pystator docs serve.

Module map

pystator (top-level re-exports)
├── StateMachine, StateMachineBuilder     # FSM runtime definition
├── EntitySession                         # Per-entity state in memory
├── MachineDefinition, parse_machine_file # Via machine_parser (also on root)
├── build_machine, MachineStoreClient     # Via machine_builder / machine_store
├── GuardRegistry, ActionRegistry, ActionExecutor
├── Orchestrator                          # Load → process → persist → act
├── stores: InMemoryStateStore, StateStoreClient, …  # Entity state (optional drivers)
├── discovery: InferenceEngine, …        # Inferred FSMs (see Discovery page)
├── worker (subpackage): Worker, submit_event       # Background queue processor
├── pystator.hooks                       # TransitionHook, MetricsCollector, …
├── pystator.visualization               # to_mermaid, to_dot, get_statistics
├── pystator.context                     # TransitionContext
├── pystator.sinks                       # EventSink, MetricSink, …
├── pystator.lint                        # lint(), LintWarning
└── errors                               # FSMError hierarchy

Facades (optional namespaces)
├── pystator.core                        # Machine + session + core types
├── pystator.behavior                    # Guards, actions, checks, effects, sinks
└── pystator.observability               # Hooks, lint, visualization
Topic Description
Condensed reference Hand-maintained list of main methods (no docstring expansion)
State Machine StateMachine, from_yaml, from_dict, process, aprocess, parallel states
EntitySession EntitySession, EventRecorder, snapshots
Orchestrator process_event, async_process_event, state store, schedulers
Machine definitions MachineDefinition, parser, MachineStoreClient, build_machine
Worker (Python) Worker, WorkerConfig, submit_event
Discovery InferenceEngine, stores, classification
Guards GuardRegistry, builtins (equals, greater_than, …)
Actions ActionRegistry, ActionExecutor, execution modes
Stores StateStoreClient, InMemoryStateStore, SQL/Redis/Mongo adapters
Hooks TransitionHook, LoggingHook, MetricsCollector
Visualization to_mermaid, to_dot, to_scxml, get_statistics
Context & Sinks TransitionContext, EventSink, MetricSink
Lint lint(), LintWarning, LintSeverity
Errors FSMError, ConfigurationError, InvalidTransitionError, …
REST API OpenAPI / in-app Playground

Import patterns

# Core runtime (typical app code)
from pystator import StateMachine, EntitySession, Orchestrator

# Machine definition pipeline (DB-backed definitions, CI, API)
from pystator import (
    MachineDefinition,
    parse_machine_file,
    build_machine,
    build_machine_from_store,
    MachineStoreClient,
    InMemoryMachineStore,
)

# Guards and actions
from pystator import GuardRegistry, ActionRegistry, ActionExecutor

# Entity state stores (adapters may need optional drivers)
from pystator import InMemoryStateStore, StateStoreClient

# Worker queue (install pystator[worker])
from pystator.worker import Worker, submit_event, submit_event_sync

# Discovery
from pystator.discovery import InferenceEngine, create_discovery_store, StateClassifier

# Facades
from pystator.core import StateMachine, EntitySession
from pystator.behavior import GuardRegistry, ActionRegistry
from pystator.observability import lint, to_mermaid

# Errors, lint, visualization (module paths)
from pystator import FSMError, InvalidTransitionError, GuardRejectedError
from pystator import lint, LintWarning
from pystator.visualization import to_mermaid, to_dot, get_statistics
from pystator.hooks import LoggingHook, MetricsCollector
from pystator.context import TransitionContext
from pystator.sinks import configure_event_sink, configure_metric_sink
from pystator.instance import EventRecorder, RecordedEvent