Declarative checks, effects, and tooling¶

PyStator supports config-only guard checks and context mutations (no Python functions), plus built-in guard/action packs, sinks for observability, and lint for static review.

Declarative checks (`check:`)¶

Use structured checks in transition guards instead of named Python guards. Evaluated by pystator.checks.evaluate_check.

Supported operators on a context field:

Operator	Meaning
`eq`, `neq`	Equality / inequality
`gt`, `gte`, `lt`, `lte`	Numeric / comparable ordering
`in`, `not_in`	Membership in a list
`is_set`, `is_null`	Field present / absent

Example in YAML (illustrative):

transitions:
  - trigger: submit
    source: draft
    dest: submitted
    guards:
      - check:
          field: amount
          op: gt
          value: 0

Combine with named guards as needed. See the FSM config reference for the full CheckSpec shape.

Declarative effects (`set`, `timestamp`, …)¶

Effects mutate context during transitions (action-side counterpart to checks). Applied via pystator.effects.apply_effect:

Effect	Role
`set`	`ctx.update(...)` from params
`timestamp`	Set a field to current UTC ISO time
`increment` / `decrement`	Numeric field
`append`	Append to a list field
`clear`	Remove a key from context

In YAML these often appear as on_enter / transition entries using the declarative action form (e.g. { set: { phase: running } } or { timestamp: started_at }). See Context and sinks and the FSM reference for your schema version.

Inline guard expressions (`expr`)¶

For arithmetic / boolean expressions over context, use expr: "fill_qty >= order_qty" in YAML. Requires:

pip install pystator[api]

(simpleeval evaluates expressions; keep configs trusted.)

Builtins¶

pystator.builtins provides register_builtins and builtin_registries to attach common guard/action implementations by name. Use when you want starter implementations without writing every callback from scratch.

Sinks (events and metrics)¶

pystator.sinks defines event and metric sinks (e.g. LoggingEventSink, LoggingMetricSink, configure_event_sink, create_publish_action) so actions can emit structured telemetry without ad-hoc print calls.

Lint¶

Static analysis over FSM config:

from pystator.lint import lint, LintWarning

warnings: list[LintWarning] = lint(config_dict)

See Linting for severity levels and CI usage.

Programmatic machine building¶

For code-first construction, use StateMachineBuilder (from pystator import StateMachineBuilder) to add states and transitions fluently before calling .build().

See also: Concepts · Package structure · FSM config reference