Tutorial
Note
Automat 24.8 is a major change to the public API - effectively a whole new
library. For ease of migration, the code and API documentation still
contains MethodicalMachine
, effectively the previous version of the
library. However, for readability, the narrative documentation now only
documents TypeMachineBuilder
. If you need documentation for that
earlier version, you can find it as v22.10.0 on readthedocs.
The Basics: a Garage Door Opener
Describing the State Machine
Let’s consider the garage door example from the introduction.
Automat takes great care to present a state machine as a collection of regular
methods. So we define what those methods are with a
typing.Protocol
that describes them.
class GarageController(typing.Protocol):
def pushButton(self) -> None:
"Push the button to open or close the door"
def openSensor(self) -> None:
"The 'open' sensor activated; the door is fully open."
def closeSensor(self) -> None:
"The 'close' sensor activated; the door is fully closed."
This protocol tells us that only 3 things can happen to our controller from the outside world (its inputs): the user can push the button, the “door is all the way up” sensor can emit a signal, or the “door is all the way down” sensor can emit a signal. So those are our inputs.
However, our state machine also needs to be able to affect things in the world (its outputs). As we are writing a program in Python, these come in the form of a Python object that can be shared between all the states that implement our controller, and for this purpose we define a simple shared-data class:
@dataclasses.dataclass
class DoorDevices:
motor: Motor
alarm: Alarm
Here we have a reference to a Motor
that can open and close the door, and
an Alarm
that can beep to alert people that the door is closing.
Next we need to combine those together, using a
automat.TypeMachineBuilder
.
builder = TypeMachineBuilder(GarageController, DoorDevices)
Next we have to define our states. Let’s start with four simple ones:
closed - the door is closed and idle
opening - the door is actively opening
opened - the door is open and idle
closing - the door is actively closing
closed = builder.state("closed")
opening = builder.state("opening")
opened = builder.state("opened")
closing = builder.state("closing")
To describe the state machine, we define a series of transitions, using the
method .upon()
:
@closed.upon(GarageController.pushButton).to(opening)
def startOpening(controller: GarageController, devices: DoorDevices) -> None:
devices.motor.up()
@opening.upon(GarageController.openSensor).to(opened)
def finishedOpening(controller: GarageController, devices: DoorDevices):
devices.motor.stop()
@opened.upon(GarageController.pushButton).to(closing)
def startClosing(controller: GarageController, devices: DoorDevices) -> None:
devices.alarm.beep()
devices.motor.down()
@closing.upon(GarageController.closeSensor).to(closed)
def finishedClosing(controller: GarageController, devices: DoorDevices):
devices.motor.stop()
Building and using the state machine
Now that we have described all the inputs, states, and output behaviors, it’s time to actually build the state machine:
machineFactory = builder.build()
The automat.TypeMachineBuilder.build()
method creates a callable that
takes an instance of its state core (DoorDevices
) and returns an object
that conforms to its inputs protocol (GarageController
). We can then take
this machineFactory
and call it, like so:
machine = machineFactory(DoorDevices(Motor(), Alarm()))
Because we defined closed
as our first state above, the machine begins in
that state by default. So the first thing we’ll do is to open the door:
machine.pushButton()
If we run this, we will then see some output, indicating that the motor is running:
motor running up
If we press the button again, rather than silently double-starting the motor, we will get an error, since we haven’t yet defined a state transition for this state yet. The traceback looks like this:
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
machine.pushButton()
File ".../automat/_typed.py", line 419, in implementation
[outputs, tracer] = transitioner.transition(methodInput)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File ".../automat/_core.py", line 196, in transition
outState, outputSymbols = self._automaton.outputForInput(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File ".../automat/_core.py", line 169, in outputForInput
raise NoTransition(state=inState, symbol=inputSymbol)
automat._core.NoTransition: no transition for pushButton in TypedState(name='opening')
At first, this might seem like it’s making more work for you. If you don’t want to crash the code that calls your methods, you need to provide many more implementations of the same method for each different state. But, in this case, by causing this exception before running any of your code, Automat is protecting your internal state: although client code will get an exception, the internal state of your garage door controller will remain consistent.
If you did not explicitly take a specific state into consideration while implementing some behavior, that behavior will never be invoked. Therefore, it cannot do something potentially harmful like double-starting the motor.
If we trigger the open sensor so that the door completes its transition to the ‘open’ state, then push the button again, the buzzer will sound and the door will descend:
machine.openSensor()
machine.pushButton()
motor stopped
beep beep beep
motor running down
Try these exercises to get to to know Automat a little bit better:
When the button is pushed while the door is opening, the motor should stop, and if it’s pressed again, the door should go in the reverse direction; for exmaple, if it’s opening, it should pause and then close again, and if it’s closing, it should pause and then open again. Make it do this rather than raise an exception.
Add a ‘safety sensor’ input, that refuses to close the door while it is tripped.
Taking, Storing, and Returning Data
Any method defined by the input protocol can take arguments and return values, just like any Python method. In order to facilitate this, all transition behavior methods must be able to accept any signature that their input can.
To demonstrate this, let’s add a feature to our door. Instead of a single
button, let’s add the ability to pair multiple remotes to open the door, so we
can note which remote was used in a security log. For starters, we will need
to modify our pushButton
method to accept a remoteID
argument, which we
can print out.
def pushButton(self, remoteID: str) -> None:
"Push the button to open or close the door"
If you’re using mypy
, you will immediately see a type error when making
this change, as all the calls to <state>.upon(GarageController.pushButton)
now complain something like this:
garage_door_security.py:75:2: error: Argument 1 to "__call__" of "TransitionRegistrar"
has incompatible type "Callable[[GarageController, DoorDevices], None]";
expected "Callable[[GarageController, DoorDevices, str], None]" [arg-type]
The TransitionRegistrar
object is the result of calling .to(...)
, so
what this is saying is that your function that is decorated with, say,
@closed.upon(GarageController.pushButton).to(opening)
, takes your input
protocol and your shared core object (as all transition behavior functions
must), but does not take the str
argument that pushButton
takes. To
fix it, we can add that parameter everywhere, and print it out, like so:
@closed.upon(GarageController.pushButton).to(opening)
def startOpening(controller: GarageController, devices: DoorDevices, remoteID: str) -> None:
print(f"opened by {remoteID}")
devices.motor.up()
Obviously, mypy will also complain that our test callers are missing the
remoteID
argument as well, so if we change them to pass along some value
like so:
machine.pushButton()
Then we will see it in our output:
opened by alice
Return values are treated in the same way as parameters. If your input protocol specifies a return type, then all behavior methods must also return that type. Your type checker will help ensure that these all line up for you as well.
You can download the full examples here:
More Advanced Usage: a Membership Card Automat Restaurant
Setting Up the Example
We will have to shift to a slightly more complex example to demonstrate Automat’s more sophisticated features. Rather than opening the single door on our garage, let’s implement the payment machine for an Automat - a food vending machine.
Our automat operates on a membership system. You buy an AutoBux card, load it up, and then once you are at the machine, you swipe your card, make a selection, your account is debited, and your food is dispensed.
State-specific Data
One of the coolest feature of Automat is not merely enforcing state transitions, but ensuring that the right data is always available in the right state. For our membership-card example, will start in an “idle” state, but when a customer swipes their card and starts to make their food selection, we have now entered the “choosing” state, it is crucial that if we are in the choosing state, then we must know which customer’s card we will charge.
We set up the state machine in much the same way as before: a state core:
@dataclass
class AutomatCore:
payments: PaymentBackend
foods: dict[int, Food] # mapping door-number to food
doors: Doors
And an inputs protocol:
class Automat(Protocol):
def swipeCard(self, accountID: str) -> None:
"Swipe a payment card with the given account ID."
def selectFood(self, doorNumber: int) -> None:
"Select a food."
def _dispenseFood(self, doorNumber: int) -> None:
"Open a door and dispense the food."
It may jump out at you that the _dispenseFood
method is private. That’s a
bit unusual for a Protocol
, which is usually used to describe a
publicly-facing API. Indeed, you might even want a second Protocol
to
hide this away from your public documentation. But for Automat, this is
important because it’s what lets us implement a conditional state transition,
something commonly associated with state-specific data.
We will get to that in a moment, but first, let’s define that data. We’ll
begin with a function that, like transition behavior functions, takes our input
protocol and core type. Its job will be to build our state-specific data for
the “choosing” state, i.e. payment details. Entering this state requires an
accountID
as supplied by our swipeCard
input, so we will require that
as a parameter as well:
def rememberAccount(
inputs: Automat, core: AutomatCore, accountID: str
) -> PaymentDetails:
print(f"remembering {accountID=}")
return PaymentDetails(accountID)
Next, let’s actually build the machine. We will use rememberAccount
as the
second parameter to TypeMachineBuilder.state()
, which defines choosing
as a data state:
builder = TypeMachineBuilder(Automat, AutomatCore)
idle = builder.state("idle")
choosing = builder.state("choosing", rememberAccount)
idle.upon(Automat.swipeCard).to(choosing).returns(None)
Note
Here, because swipeCard doesn’t need any behavior and returns a static,
immutable type (None), we define the transition with .returns(None)
rather than giving it a behavior function. This is the same as using
@idle.upon(Automat.swipeCard).to(choosing)
as a decorator on an empty
function, but a lot faster to type and to read.
The fact that choosing
is a data state adds two new requirements to its
transitions:x
First, for every transition defined to the
choosing
state, the data factory function –rememberAccount
– must be callable with whatever parameters defined in the input. If you want to make a lenient data factory that supports multiple signatures, you can always add*args: object, **kwargs: object
to its signature, but any parameters it requires (in this case,accountID
) must be present in any input protocol methods that transition tochoosing
so that they can be passed along to the factory.Second, for every transition defined from the
choosing
state, behavior functions will accept an additional parameter, of the same type returned by their state-specific data factory function. In other words, we will build aPaymentDetails
object on every transition tochoosing
, and then remember and pass that object to every behavior function as long as the machine remains in that state.
Conditional State Transitions
Formally, in a deterministic finite-state automaton, an input in one state must result in the same transition to the same output state. When you define transitions statically, Automat adheres to this rule. However, in many real-world cases, which state you end up in after a particular event depends on things like the input data or internal state. In this example, if the user’s AutoBux™ account balance is too low, then the food should not be dispensed; it should prompt the user to make another selection.
Because it must be static, this means that the transition we will define from
the choosing
state upon selectFood
will actually be a .loop()
– in
other words, back to choosing
– rather than .to(idle)
. Within the
behavior function of that transition, if we have determined that the user’s
card has been charged properly, we will call back into the Automat
protocol via the _dispenseFood
private input, like so:
@choosing.upon(Automat.selectFood).loop()
def selected(
inputs: Automat, core: AutomatCore, details: PaymentDetails, doorNumber: int
) -> None:
food = core.foods[doorNumber]
try:
core.payments.deduct(details.accountID, core.foods[doorNumber].price)
except ValueError as ve:
print(ve)
else:
inputs._dispenseFood(doorNumber)
And since we want that input to transition us back to idle
once the food
has been dispensed, once again, we register a static transition, and this one’s
behavior is much simpler:
@choosing.upon(Automat._dispenseFood).to(idle)
def doOpen(
inputs: Automat, core: AutomatCore, details: PaymentDetails, doorNumber: int
) -> None:
core.doors.openDoor(doorNumber)
You can download the full example here:
Reentrancy
Observant readers may have noticed a slightly odd detail in the previous section.
If our selected
behavior function can cause a transition to another state
before it’s completed, but that other state’s behaviors may require invariants
that are maintained by previous behavior (i.e. selected
itself) having
completed, doesn’t that create a paradox? How can we just invoke
inputs._dispenseFood
and have it work?
In fact, you can’t. This is an unresolvable paradox, and automat does a little trick to allow this convenient illusion, but it only works in some cases.
Problems that lend themselves to state machines often involve setting up state
to generate inputs back to the state machine in the future. For example, in
the garage door example above, we implicitly registered sensors to call the
openSensor
and closeSensor
methods. A more complete implementation in
the behavior might need to set a timeout with an event loop, to automatically
close the door after a certain amount of time. Being able to treat the state
machines inputs as regular bound methods that can be used in callbacks is
extremely convenient for this sort of thing. For those use cases, there are no
particular limits on what can be called; once the behavior itself is finished
and it’s no longer on the stack, the object will behave exactly as its
Protocol
describes.
One constraint is that any method you invoke in this way cannot return any value except None. This very simple machine, for example, that attempts to invoke a behavior that returns an integer:
class Inputs(typing.Protocol):
def compute(self) -> int: ...
def behavior(self) -> None: ...
class Nothing: ...
builder = TypeMachineBuilder(Inputs, Nothing)
start = builder.state("start")
@start.upon(Inputs.compute).loop()
def three(inputs: Inputs, core: Nothing) -> int:
return 3
@start.upon(Inputs.behavior).loop()
def behave(inputs: Inputs, core: Nothing) -> None:
print("computed:", inputs.compute())
will result in a traceback like so:
File "feedback_errors.py", line 24, in behave
print("computed:", inputs.compute())
^^^^^^^^^^^^^^^^
File ".../automat/_typed.py", line 406, in implementation
raise RuntimeError(
RuntimeError: attempting to reentrantly run Inputs.compute
but it wants to return <class 'int'> not None
However, if instead of calling the method immediately, we save the method away to invoke later, it works fine once the current behavior function has completed:
computations = []
@start.upon(Inputs.behavior).loop()
def behave(inputs: Inputs, core: Nothing) -> None:
computations.append(inputs.compute)
machineFactory = builder.build()
machineFactory(Nothing()).behavior()
print(computations[0]())
This simply prints 3
, as expected.
But why is there a constraint on return type? Surely a None
-returning
method with side effects depends on its internal state just as much as
something that returns a value? Running it re-entrantly before finishing the
previous behavior would leave things in an invalid state, so how can it run at
all?
The magic that makes this work is that Automat automatically makes the invocation not reentrant, by re-ordering it for you. It can re-order a second behavior that returns None to run at the end of your current behavior, but it cannot steal a return value from the future, so it raises an exception to avoid confusion.
But there is still the potentially confusing edge-case of re-ordering. A machine that contains these two behaviors:
@start.upon(Inputs.behavior1).loop()
def one(inputs: Inputs, core: Nothing) -> None:
print("starting behavior 1")
inputs.behavior2()
print("ending behavior 1")
@start.upon(Inputs.behavior2).loop()
def two(inputs: Inputs, core: Nothing) -> None:
print("behavior 2")
will, when .behavior1()
is invoked on it, print like so:
starting behavior 1
ending behavior 1
behavior 2
In general, this re-ordering is what you want idiomatically when working with a state machine, but it is important to know that it can happen. If you have code that you do want to invoke side effects in a precise order, put it in a function or into a method on your shared core.
How do I get the current state of a state machine?
Don’t do that.
One major reason for having a state machine is that you want the callers of the state machine to just provide the appropriate input to the machine at the appropriate time, and not have to check themselves what state the machine is in.
The whole point of Automat is to never, ever write code that looks like this, and places the burden on the caller:
if connectionMachine.state == "CONNECTED":
connectionMachine.sendMessage()
else:
print("not connected")
Instead, just make your calling code do this:
connectionMachine.sendMessage()
and then change your state machine to look like this:
class Connector(Protocol):
def sendMessage(self) -> None:
"send a message"
@dataclass
class Core:
_transport: Transport
builder = TypeMachineBuilder(Connector, Core)
disconnected = builder.state("disconnected")
connected = builder.state("connector")
@connected.upon(Connector.sendMessage).loop()
def actuallySend(connector: Connector, core: Core) -> None:
core._transport.send(b"message")
@disconnected.upon(Connector.sendMessage).loop()
def failSend(connector: Connector, core: Core):
print("not connected")
so that the responsibility for knowing which state the state machine is in remains within the state machine itself.
If I can’t get the state of the state machine, how can I save it to (a database, an API response, a file on disk…)
On the serialization side, you can build inputs that return a type that every
state can respond to. For example, here’s a machine that maintains an int
value in its core, and a str
value in a piece of state-specific data. This
really just works like implementing any other return value.
class Inputs(Protocol):
def serialize(self) -> tuple[int, str | None]: ...
def next(self) -> None: ...
def data(self, datum: str) -> None: ...
builder = TypeMachineBuilder(Inputs, Core)
start = builder.state("start")
nodata = builder.state("nodata")
data = builder.state("data", DataObj.create)
nodata.upon(Inputs.data).to(data).returns(None)
start.upon(Inputs.next).to(nodata).returns(None)
@nodata.upon(Inputs.serialize).loop()
def serialize(inputs: Inputs, core: Core) -> tuple[int, None]:
return (core.value, None)
@data.upon(Inputs.serialize).loop()
def serializeData(inputs: Inputs, core: Core, data: DataObj) -> tuple[int, str]:
return (core.value, data.datum)
getting the data out then looks like this:
machineFactory = builder.build()
machine = machineFactory(Core(3))
machine.next()
print(machine.serialize())
machine.data("hi")
print(machine.serialize())
which produces:
(3, None)
(3, DataObj(datum='hi'))
Future versions of automat may include some utility functionaity here to reduce boilerplate, but no additional features are required to address this half of the problem.
However, for *de*serialization, we do need the ability to start in a different
initial state. For non-data states, it’s simple enough; construct an
appropriate shared core, and just pass the state that you want; in our case,
nodata
:
def deserializeWithoutData(serialization: tuple[int, DataObj | None]) -> Inputs:
coreValue, dataValue = serialization
assert dataValue is None, "not handling data yet"
return machineFactory(Core(coreValue), nodata)
Finally, all we need to deserialize a state with state-specific data is to pass
a factory function which takes inputs, core
as arguments, just like
behavior and data-factory functions. Since we are skipping directly to the
data state, we will skip the data factory declared on the state itself, and
call this one:
def deserialize(serialization: tuple[int, str | None]) -> Inputs:
coreValue, dataValue = serialization
if dataValue is None:
return machineFactory(Core(coreValue), nodata)
else:
return machineFactory(
Core(coreValue),
data,
lambda inputs, core: DataObj(dataValue),
)
Note
In this specific deserialization context, since the object isn’t even really
constructed yet, the inputs
argument is in a totally invalid state and
cannot be invoked reentrantly at all; any method will raise an exception if
called during the duration of this special deserialization data factory.
You can only use it to save it away on your state-specific data for future
invocations once the state machine instance is built.
You can download the full example here:
And that’s pretty much all you need to know in order to build type-safe state machines with Automat!