StateDiagram: UML Statecharts, Automata & Transitions

StateDiagram models behavioral state transitions, Finite State Machines (FSM), and UML 2.0 Statecharts. It provides dedicated pseudo-states, internal action compartments (entry, do, exit), and curved arc transitions.

1. Overview & Action Compartments

from drawlib.canvas import save, setup
from drawlib.diagrams.state import InitialState, State, StateDiagram
from drawlib.styles import Styles

setup(width=108, height=34)

sd = StateDiagram(
    node_style=Styles.Neutral,
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.Dark.patch(text_size=10.5),
)

init = sd.add(InitialState(style=Styles.Dark), xy=(6.0, 17.0))
idle = sd.add(State("Idle", shape="box", width=22.0, height=13.0), xy=(28.0, 17.0))
proc = sd.add(
    State(
        "Processing",
        shape="box",
        entry="start_timer()",
        do="calculate()",
        exit="cleanup()",
        width=32.0,
        style=Styles.PrimaryNeutral,
    ),
    xy=(88.0, 17.0),
)

sd.connect(init, idle)
sd.connect(
    idle,
    proc,
    event="event",
    guard="guard",
    action="action",
    bend=-0.30,
    start_side="top_right",
    end_side="top_left",
)
sd.connect(
    proc,
    idle,
    event="failure",
    bend=-0.35,
    start_side="bottom_left",
    end_side="bottom_right",
    text_style=Styles.Dark.patch(text_size=10.5, valign="top"),
)

sd.draw(xy=(0.0, 0.0))
save()

• 5 State Geometric Shapes (shape=...): State supports "box" (rounded rectangle with optional action compartments), "ellipse" (ellipse/capsule), "circle" (classic FSM state), "double_circle" (FSM accepting state), and "text_only" (borderless text node).
• UML Action Compartments: When shape="box", a State card can display internal behavior triggers (entry, do, exit, or custom triggers via state.add_action(kind, action)) below a divider line.
• Pseudo-States (StateNodeBase subclasses):
  • InitialState: Solid circle indicating system start.
  • FinalState: Bullseye concentric circles indicating termination.
  • ChoiceState: Diamond shape for dynamic conditional branching.
  • ForkJoinState: Solid synchronization bar ("horizontal" or "vertical") for concurrent state splits and joins.
• Standard Transition Syntax: Transition labels automatically format as event [guard] / action.
• Bidirectional Arcs (bend) & 8-Direction Anchors: Setting bend=0.3 creates smooth curved arcs, and start_side / end_side / side support all 8 cardinal and diagonal directions ("top", "bottom", "left", "right", "top_left", "top_right", "bottom_left", "bottom_right").

2. Constructor, Core Classes & Parameter Reference

from drawlib.diagrams.state import (
    ChoiceState,
    FinalState,
    ForkJoinState,
    InitialState,
    State,
    StateAction,
    StateDiagram,
    StateNodeBase,
    StateTransition,
)
from drawlib.styles import Styles

sd = StateDiagram(
    node_style=Styles.Neutral,
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.Dark,
    title="Session Lifecycle State Machine",
)

# State with action compartments + custom action
active = sd.add(
    State("Active", shape="box", entry="start_heartbeat()", do="handle_requests()", exit="flush()", style=Styles.PrimaryNeutral),
    xy=(60.0, 40.0),
)
active.add_action("on_timeout", "warn_idle()")

# Transition with guard and action
init = sd.add(InitialState(), xy=(10.0, 40.0))
sd.connect(init, active, event="login", guard="token_valid", action="init_session()")

Parameter Reference Tables

StateDiagram Class

State Class (inherits StateNodeBase)

• state.add_action(kind: str, action: str) -> State: Appends a StateAction(kind=kind, action=action) (rendered as {kind} / {action}) to state.actions and returns self.

Pseudo-State Classes (StateNodeBase Subclasses)

StateTransition & sd.connect(...)

Registration, Sizing & Rendering Methods

• sd.add(item: StateNodeBase, xy=(cx, cy), width=None, height=None, style=None, show=None) -> StateNodeBase: Places a state or pseudo-state centered at (cx, cy) (with optional width, height, style, and show overrides) and returns the mutable element. If show=False, the state and any transitions connected to it are skipped during draw() while diagram bounds stay fixed.
• sd.connect(source, target, *, label="", event="", guard="", action="", side="top", bend=0.0, start_side="auto", end_side="auto", routing="curved", style=None, text_style=None, padding=0.0, loop_width=None, loop_height=None, loop_ratio=0.88, show=True) -> StateTransition (and sd.add_transition(trans) -> StateTransition).
• sd.get_bounds() -> tuple[float, float, float, float]: Returns (min_x, min_y, max_x, max_y) enclosing all states and self-transition loops.
• sd.get_size() -> tuple[float, float]: Returns (width, height) of the diagram (including margin).
• sd.draw(xy=(0.0, 0.0), *, scale: float = 1.0) -> None: Renders the state diagram anchored at bottom-left xy, proportionally scaling state positions, dimensions, curved arcs, and font sizes by scale.

3. Session Lifecycle State Machine (shape="box", ChoiceState & Self-Loop)

The following complete example showcases pseudo-states, choice diamonds, action compartments, a self-loop, and curved return transitions:

from drawlib.canvas import save, setup
from drawlib.diagrams.state import ChoiceState, FinalState, InitialState, State, StateDiagram
from drawlib.styles import Styles

setup(width=128, height=58)

sd = StateDiagram(
    node_style=Styles.Neutral,
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.Dark.patch(text_size=10.5),
    title="User Session Lifecycle State Machine",
    title_style=Styles.BlackBold.patch(text_size=13.5),
)

# 1. Pseudo-states and state nodes
init = sd.add(InitialState(), xy=(8.0, 24.0))
idle = sd.add(
    State("Idle", shape="box", entry="reset()", do="listen()", width=22.0),
    xy=(32.0, 24.0),
)
valid_check = sd.add(ChoiceState(name="Valid?", style=Styles.SecondaryNeutral), xy=(64.0, 24.0))
active = sd.add(
    State(
        "Active",
        shape="box",
        entry="start()",
        do="handle()",
        exit="flush()",
        style=Styles.PrimaryNeutral,
        width=22.0,
    ),
    xy=(95.0, 24.0),
)
final = sd.add(FinalState(), xy=(121.0, 24.0))

# 2. Connect transitions
sd.connect(init, idle)
sd.connect(idle, valid_check, event="login")

# Choice branches (success vs failure)
sd.connect(valid_check, active, guard="valid")
sd.connect(
    valid_check,
    idle,
    guard="invalid",
    bend=-0.35,
    start_side="bottom",
    end_side="bottom",
    text_style=Styles.Dark.patch(text_size=10.5, valign="top"),
)

# Self-transition heartbeat loop
sd.connect(active, active, side="top", event="ping", action="extend()", loop_width=8.0, loop_height=7.0)

# Termination
sd.connect(active, final, event="logout")

sd.draw(xy=(0.0, 0.0))
save()

4. Concurrent Task Synchronization (ForkJoinState)

Use ForkJoinState to represent concurrent parallel threads:

from drawlib.canvas import save, setup
from drawlib.diagrams.state import FinalState, ForkJoinState, InitialState, State, StateDiagram
from drawlib.styles import Styles

setup(width=106, height=56)

sd = StateDiagram(
    node_style=Styles.Neutral,
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.Dark.patch(text_size=10.5),
    title="Concurrent Task Fork and Join",
    title_style=Styles.BlackBold.patch(text_size=13.5),
)

init = sd.add(InitialState(), xy=(7.0, 24.5))
fork = sd.add(ForkJoinState(orientation="vertical", length=22.0), xy=(21.0, 24.5))
job_a = sd.add(State("Compute Analytics", shape="box", width=28.0, style=Styles.PrimaryNeutral), xy=(51.0, 36.0))
job_b = sd.add(State("Index Search", shape="box", width=28.0, style=Styles.SecondaryNeutral), xy=(51.0, 13.0))
join = sd.add(ForkJoinState(orientation="vertical", length=22.0), xy=(81.0, 24.5))
final = sd.add(FinalState(), xy=(99.0, 24.5))

sd.connect(init, fork)
sd.connect(fork, job_a)
sd.connect(fork, job_b)
sd.connect(job_a, join)
sd.connect(job_b, join)
sd.connect(join, final)

sd.draw(xy=(0.0, 0.0))
save()

5. Finite Automaton & All 5 State Geometric Shapes

Beyond UML "box" cards, State supports "text_only" (borderless entry/label nodes), "circle" (standard automaton states), "ellipse" (capsule states), and "double_circle" (accepting states), along with diagonal anchor sides ("top_right", "bottom_left", etc.):

from drawlib.canvas import save, setup
from drawlib.diagrams.state import State, StateDiagram
from drawlib.styles import Styles

setup(width=128, height=58)

sd = StateDiagram(
    node_style=Styles.Neutral,
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.Dark.patch(text_size=10.5),
    title="Lexical Token Automaton (All State Shapes)",
    title_style=Styles.BlackBold.patch(text_size=13.5),
)

# 1. text_only start indicator, circle state, ellipse state, and double_circle accepting state
start_lbl = sd.add(State("start", shape="text_only", width=11.0), xy=(11.0, 26.0))
q0 = sd.add(State("q0", shape="circle", width=15.0, style=Styles.Neutral), xy=(36.0, 26.0))
q1 = sd.add(
    State("Scan Ident", shape="ellipse", width=25.0, height=13.0, style=Styles.PrimaryNeutral),
    xy=(73.0, 26.0),
)
q_accept = sd.add(
    State("ACCEPT", shape="double_circle", width=19.0, style=Styles.SecondaryNeutral),
    xy=(113.0, 26.0),
)

# 2. Transitions with self-loops and diagonal anchors
sd.connect(start_lbl, q0)
sd.connect(q0, q0, side="bottom", label="ws", loop_width=7.0, loop_height=7.0)
sd.connect(q0, q1, label="[a-zA-Z_]")
sd.connect(q1, q1, side="top", label="[a-zA-Z0-9_]", loop_width=8.0, loop_height=7.5)
sd.connect(q1, q_accept, label="delimiter")
sd.connect(
    q_accept,
    q0,
    label="reset",
    bend=-0.32,
    start_side="bottom_left",
    end_side="bottom_right",
    text_style=Styles.Dark.patch(text_size=10.5, valign="top"),
)

sd.draw(xy=(0.0, 0.0))
save()

6. Best Practices & Guidelines

1. Use bend for Opposing Transitions: When two states transition back and forth (e.g. Idle ↔ Active), apply bend=0.25 on one transition and bend=-0.25 on the return so they do not overlap.
2. Standard Label Formatting: Prefer passing event, guard, and action parameters rather than writing label="login [valid] / init". Drawlib guarantees standard UML typography and spacing.
3. Choice Diamond Clarity: Label exit branches from ChoiceState with explicit guard criteria (guard="is_valid" vs guard="is_invalid").