Statomata

Statomata is a strictly typed, flexible library for building and running finite state machines (FSMs) and automata in Python. It provides core automata implementations out of the box and lets you define custom states and state management logic.

Features

• 🧠 State Interface & Context: Follow the state machine OOP pattern with clear, isolated state definitions.
• ⏸️ Defer & Recall: States can defer incoming messages and recall them later, enabling complex multi-step workflows.
• ⚡ Built-in Automata: feel free to use one of the predefined automata classes from SDK (sync / async; unary / iterable)
• 🏗 Custom Automata Support: Build your own automata with custom state management logic. You can choose declarative style or built custom automata using provided interfaces.
• ✅ Strict Typing: Designed for type safety and clarity with full type hints.

Installation

pip install statomata

Quick Start

Use high-level declarative style:

from statomata.declarative import DeclarativeStateMachine, State


class OpenCloseExample(DeclarativeStateMachine):
    closed = State(initial=True)
    opened = State()

    @closed.to(opened)
    def open(self) -> str:
        return "Opened"

    @opened.to(closed)
    def close(self) -> str:
        return "Closed"

Run the state machine:

from contextlib import suppress
from statomata.exception import InvalidStateError

sm = OpenCloseExample()

print(sm.open())  # Output: Opened
print(sm.close())  # Output: Closed

with suppress(InvalidStateError):
    sm.close()

Or you can use low-level style:

from statomata.abc import State, Context
from statomata.exception import InvalidStateError


class OpenState(State[str, str]):
    def handle(self, income: str, context: Context[State[str, str]]) -> str:
        if income != "close":
            raise InvalidStateError(self, message="already opened")

        context.set_state(ClosedState())
        return "Closed"


class ClosedState(State[str, str]):
    def handle(self, income: str, context: Context[State[str, str]]) -> str:
        if income != "open":
            raise InvalidStateError(self, message="already closed")

        context.set_state(OpenState())
        return "Opened"

Run the state machine:

from contextlib import suppress

from statomata.exception import InvalidStateError
from statomata.sdk import create_unary_sm

sm = create_unary_sm(ClosedState())

print(sm.run("open"))  # Output: Opened
print(sm.run("close"))  # Output: Closed

with suppress(InvalidStateError):
    sm.run("close")

Examples

• order control
  • low level
  • high level
• positive number store
• traffic light
• defer and recall
• transition cases
• condition cases
• outcome cases
• iterable low level
• anyio cases