Domain models

If you need to use any other object to persist the current state, or you’re using the state machine to control the flow of another object, you can pass this object to the StateChart constructor.

If you don’t pass an explicit model instance, this simple Model will be used:

class Model:
    def __init__(self):
        self.state = None
        """Holds the current :ref:`state` value of the :ref:`StateMachine`."""

    def __repr__(self):
        return f"Model(state={self.state})"

See also

See the Order control machine (rich model) as example of using a domain object to hold attributes and methods to be used on the StateChart definition.

Hint

Domain models are registered as Listeners, so you can have the same level of functionalities provided to the built-in StateChart, such as implementing all Actions and Conditions on your domain model and keeping only the definition of States and Transitions on the StateChart.

Typed models

StateChart supports a generic type parameter so that type checkers (mypy, pyright) and IDEs can infer the type of sm.model and provide code completion.

Declare your model class and pass it as a type parameter to StateChart:

>>> from statemachine import State, StateChart

>>> class OrderModel:
...     order_id: str = ""
...     total: float = 0.0
...     def confirm(self):
...         return f"Order {self.order_id} confirmed: ${self.total}"

>>> class OrderWorkflow(StateChart["OrderModel"]):
...     draft = State(initial=True)
...     confirmed = State(final=True)
...     confirm = draft.to(confirmed, on="on_confirm")
...     def on_confirm(self):
...         return self.model.confirm()

>>> model = OrderModel()
>>> model.order_id = "A-123"
>>> model.total = 49.90
>>> sm = OrderWorkflow(model=model)

>>> sm.send("confirm")
'Order A-123 confirmed: $49.9'

With this declaration, sm.model is typed as OrderModel instead of Any, so sm.model.order_id, sm.model.total, and sm.model.confirm() all get full autocompletion and type checking in your IDE.

Note

When no type parameter is given (e.g. class MySM(StateChart)), the model defaults to Any, preserving full backward compatibility.