Getting started

This tutorial takes a small order lifecycle from Sismic YAML to an importable python-statemachine class.

1. Install the project

From the project root:

uv sync --extra test --extra docs

The docs extra is not required to run State Mate, but installing it now also gives you MkDocs for later documentation work.

2. Create a Sismic statechart

Create order.yaml:

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

The statechart has one compound root, one initial child, several basic states, two final states, and event-driven external transitions.

3. Generate Python source

Run:

uv run state-mate order.yaml --output order_machine.py

State Mate loads the YAML through Sismic, verifies that the statechart belongs to the supported subset, then renders the Python module.

The generated module contains an Enum for the states and a StateMachine declaration whose transitions are grouped by event. Repeated events become compound transition expressions, for example:

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

4. Inspect output on stdout

The output file is optional. To inspect generated source directly:

uv run state-mate order.yaml

5. Use the generated machine

Install python-statemachine in the application that consumes the generated module, then import the generated class:

from order_machine import OrderStateMachine

machine = OrderStateMachine()
machine.order()
machine.process()
machine.ship()
machine.succeed()

At this point you have completed the full State Mate workflow: declarative Sismic YAML in, generated Python state machine out.

Next steps