state-mate

Generate a python-statemachine implementation directly from a constrained Sismic YAML statechart using Jinja2.

Sismic is the authoritative parser and in-memory model. The generator deliberately does not redefine states, transitions, or the state machine in its own domain model.

Input

statechart:
  name: Order
  root state:
    name: lifecycle
    initial: orderable
    states:
      - name: orderable
        transitions:
          - event: order
            target: ordered

      - name: ordered
        transitions:
          - event: process
            target: pending

      - name: pending
        transitions:
          - event: ship
            target: shipping
          - event: cancel
            target: canceled
          - event: fail
            target: failed

      - name: shipping
        transitions:
          - event: succeed
            target: succeeded
          - event: cancel
            target: canceled
          - event: fail
            target: failed

      - name: succeeded
        type: final

      - name: canceled
        type: final

      - name: failed
        transitions:
          - event: retry
            target: ordered

load_statechart() calls sismic.io.import_from_yaml(filepath=...). Sismic therefore performs its normal YAML-schema and statechart validation first.

Architecture

Sismic YAML
    |
    v
sismic.io.import_from_yaml()
    |
    v
sismic.model.Statechart
    |
    +--> validate_supported_subset()
    |
    v
Jinja2 + small rendering helpers
    |
    v
python-statemachine source

There is no secondary Machine, State, or Transition model. Sismic objects are passed directly to the renderer and template.

The only derived rendering structure is a grouping of Sismic Transition objects by event. This is needed to generate combined python-statemachine event declarations such as:

cancel = (
    states.PENDING.to(states.CANCELED)
    | states.SHIPPING.to(states.CANCELED)
)

Supported subset

The generator intentionally targets a flat finite-state-machine subset:

• one compound root state;
• basic and final states directly below the root;
• one initial child state;
• external transitions with one event and one target;
• repeated event names across source states.

The following Sismic features are rejected explicitly because the current python-statemachine output cannot preserve their semantics faithfully:

• nested compound states;
• parallel states;
• history states;
• eventless transitions;
• internal transitions;
• guards;
• transition actions;
• priorities;
• state entry/exit actions;
• state and transition contracts.

Source layout

src/state_mate/
├── __init__.py
├── cli.py
├── loader.py
├── render.py
└── templates/
    └── machine.py.j2

loader.py is intentionally limited to loading and subset validation. render.py contains only Python naming helpers, event grouping, and Jinja2 setup.

Install and run

uv sync --extra test

Generate a Python state machine:

uv run state-mate examples/order.yaml \
  --output build/order_machine.py

Without --output, generated source is written to stdout:

uv run state-mate examples/order.yaml

Run the tests:

uv run pytest

PlantUML

PlantUML output is intentionally outside this project because Sismic already provides it directly:

uv run sismic-plantuml examples/order.yaml

or programmatically with sismic.io.export_to_plantuml().

Documentation

The project documentation is organized according to Diátaxis and built with MkDocs using the built-in Read the Docs theme.

License