State: behaviour that changes with state

State is a behavioural design pattern for an object whose behaviour depends on the situation it is in. Instead of checking a status flag in every method, the object keeps a current state, and each state decides what every event does: which events it accepts, which it refuses and which state comes next. When an event moves the object to a new state, its behaviour changes with it, so from the outside the object seems to change its class. Vending machines, order lifecycles, network connections, document workflows and the modes of an editor are all state machines.

How State works

A vending machine shows the problem. It can be idle, holding money, dispensing or sold out, and the same coin means different things in each: it starts a purchase when idle and must be refused while an item is being dispensed. Code that stores a status string and checks it with if statements in every method spreads each state across all the methods, so adding a state means editing every one of them, and a forgotten check silently accepts an event that should have been refused.

The State pattern puts each state’s behaviour in one place and makes every transition explicit. The machine’s states and transitions, drawn straight from its transition table:

The shortest correct implementation is that table, as data. The machine looks up its current state and the event; an entry gives the next state, and a missing entry means the event is refused in that state:

"""State as a transition table: the machine's current state decides what each event does, and an event the table
has no entry for is refused."""

# (state, event) -> next state, or a function of the machine when the next state depends on its data (a guard)
TRANSITIONS = {
    ("idle", "coin"): "has money",
    ("idle", "restock"): "idle",
    ("has money", "refund"): "idle",
    ("has money", "choose"): "dispensing",
    ("dispensing", "done"): lambda machine: "idle" if machine.stock else "sold out",
    ("sold out", "restock"): "idle",
}


class VendingMachine:
    def __init__(self, stock):
        self.state = "idle"
        self.stock = stock

    def handle(self, event):
        target = TRANSITIONS.get((self.state, event))
        if target is None:
            return f"{event:8} refused in {self.state}"
        if event == "choose":
            self.stock -= 1
        elif event == "restock":
            self.stock += 3
        before, self.state = self.state, target(self) if callable(target) else target
        return f"{event:8} {before} -> {self.state} (stock {self.stock})"


machine = VendingMachine(stock=1)
for event in ["choose", "coin", "choose", "coin", "done", "coin", "restock", "coin", "refund"]:
    print(machine.handle(event))

choose   refused in idle
coin     idle -> has money (stock 1)
choose   has money -> dispensing (stock 0)
coin     refused in dispensing
done     dispensing -> sold out (stock 0)
coin     refused in sold out
restock  sold out -> idle (stock 3)
coin     idle -> has money (stock 3)
refund   has money -> idle (stock 3)

The first “choose” is refused because nothing has been paid. After the only item is sold, “done” leads to sold out instead of idle: that entry is a guard, a condition on the machine’s data that decides between two next states. In sold out every coin is refused until a restock.

State machines are written in a few standard ways, and each has a name:

• State classes give each state its own class with a method per event, the form in the Gang of Four catalogue.
• An enum with match keeps the states as values and handles every state and event in one function.
• A transition table lists each state and event with its next state, as data that is easy to draw and test.
• Typestate gives each state its own type, so that an illegal transition does not even compile.
• Statecharts add nested and parallel states to machines whose flat diagrams would explode.

Three implementations, tested by one matrix Pro: opens with a Pro, Premium or Ultimate pass