drawlib.diagrams.state(ステートマシン図)
entry /・do /・exit / 内部アクション区画、開始・終了・選択分岐(Choice)・並行同期バー(Fork/Join)疑似状態、自己遷移ループ、および曲線ガード遷移を備えた有限オートマトン(FSM)・UML 2.x ステートマシン図モジュールです。標準インポート: from drawlib.diagrams.state import ChoiceState, FinalState, InitialState, State, StateDiagram。
内部アクション区画・Choice 分岐ひし形・曲線リトライ遷移を用いた接続ステートマシン図
Source Code
from drawlib.canvas import save, setup
from drawlib.diagrams.state import ChoiceState, FinalState, InitialState, State, StateDiagram
from drawlib.styles import Colors, Styles
setup(width=120, height=54)
sd = StateDiagram(
node_style=Styles.Neutral.patch(text_size=10.5),
edge_style=Styles.DarkBold,
edge_text_style=Styles.Dark.patch(text_size=10.0),
margin=4.0,
)
init = sd.add(InitialState(), xy=(6.0, 34.0))
idle = sd.add(State("Idle", width=17, height=11), xy=(21.0, 34.0))
connecting = sd.add(
State(
"Connecting",
entry="openSocket()",
do="handshake()",
width=29,
style=Styles.PrimaryNeutral.patch(text_size=10.5),
),
xy=(54.0, 34.0),
)
choice = sd.add(ChoiceState(style=Styles.SecondaryNeutral), xy=(80.0, 34.0))
connected = sd.add(
State(
"Connected",
width=21,
height=11,
style=Styles.PrimaryFlat.patch(text_color=Colors.White, text_size=10.5),
),
xy=(103.5, 34.0),
)
final = sd.add(FinalState(), xy=(103.5, 11.0))
sd.connect(init, idle, routing="direct", padding=0.8)
sd.connect(idle, connecting, event="connect", start_side="right", end_side="left", routing="direct", padding=0.8)
sd.connect(connecting, choice, event="done", start_side="right", end_side="left", routing="direct", padding=0.8)
sd.connect(choice, connected, guard="ok", start_side="right", end_side="left", routing="direct", padding=0.8)
sd.connect(choice, idle, guard="retry", start_side="bottom", end_side="bottom", bend=-0.26, padding=0.8)
sd.connect(
connected,
final,
event="close",
start_side="bottom",
end_side="top",
routing="direct",
padding=0.8,
text_style=Styles.Dark.patch(text_size=10.0, halign="left"),
)
sd.draw(xy=(60.0, 27.0), align="center")
save()
classChoiceState
ひし形(ダイヤモンド)として描画される UML 2.x の動的条件分岐(Choice)疑似状態です。StateNodeBase のサブクラスです。
ChoiceState(
name: str = "",
size: float = 4.5,
style: Style | None = None,
show: bool = True,
) -> None
- 座標アンカー:
sd.add(choice, xy=(cx, cy)) で登録する際の中心座標 (cx, cy)。
コンストラクタ引数
| 引数 |
型 |
デフォルト |
説明 |
name |
str |
"" |
分岐疑似状態の任意の識別子。 |
size |
float |
4.5 |
ひし形の幅および高さ(ローカル単位)。 |
style |
Style | None |
None |
塗り・枠線のスタイル上書き(未指定時は sd.node_style)。 |
show |
bool |
True |
表示フラグ(False の場合、ひし形と接続遷移を非表示化)。 |
パブリックメソッド・プロパティ
| メンバー |
種別 |
シグネチャ |
説明 |
center |
property |
-> tuple[float, float] |
ひし形の相対中心座標 (cx, cy)。 |
effective_height |
property |
-> float |
実効描画高さ(size)。 |
effective_width |
property |
-> float |
実効描画幅(size)。 |
get_anchor |
method |
(self, side: Side) -> tuple[float, float] |
指定した side のひし形頂点/外周アンカー座標を返します。 |
get_bounds |
method |
(self) -> tuple[float, float, float, float] |
中心 (0, 0) 基準のローカル境界 (-size/2, -size/2, size/2, size/2) を返します。 |
xy |
property |
-> tuple[float, float] |
相対中心座標 (cx, cy) を返すエイリアス。 |
classFinalState
外周リングと黒塗り内円からなる二重丸(ブルズアイ)として描画される UML 2.x 終了状態です。StateNodeBase のサブクラスです。
FinalState(
name: str = "",
radius: float = 2.2,
style: Style | None = None,
show: bool = True,
) -> None
- 座標アンカー:
sd.add(final, xy=(cx, cy)) で登録する際の中心座標 (cx, cy)。
コンストラクタ引数
| 引数 |
型 |
デフォルト |
説明 |
name |
str |
"" |
終了状態の任意の識別子。 |
radius |
float |
2.2 |
外周リングの半径(ローカル単位、全体の直径は 2 * radius)。 |
style |
Style | None |
None |
リングおよび内円の線・塗り色スタイル上書き。 |
show |
bool |
True |
表示フラグ(False の場合、このノードと接続遷移を非表示化)。 |
パブリックメソッド・プロパティ
| メンバー |
種別 |
シグネチャ |
説明 |
center |
property |
-> tuple[float, float] |
二重丸の相対中心座標 (cx, cy)。 |
effective_height |
property |
-> float |
実効描画直径(2 * radius)。 |
effective_width |
property |
-> float |
実効描画直径(2 * radius)。 |
get_anchor |
method |
(self, side: Side) -> tuple[float, float] |
指定した side の外周リング境界座標を返します。 |
get_bounds |
method |
(self) -> tuple[float, float, float, float] |
中心 (0, 0) 基準のローカル境界 (-radius, -radius, radius, radius) を返します。 |
xy |
property |
-> tuple[float, float] |
相対中心座標 (cx, cy) を返すエイリアス。 |
classForkJoinState
単一遷移を複数の並行リージョンへ分岐(fork)または複数の並行リージョンを同期合流(join)させる UML 2.x の太線バー要素です。StateNodeBase のサブクラスです。
ForkJoinState(
name: str = "",
orientation: Literal["horizontal", "vertical"] = "horizontal",
length: float = 16.0,
thickness: float = 1.8,
style: Style | None = None,
show: bool = True,
) -> None
- 座標アンカー:
sd.add(bar, xy=(cx, cy)) で登録する際の中心座標 (cx, cy)。
コンストラクタ引数
| 引数 |
型 |
デフォルト |
説明 |
name |
str |
"" |
Fork/Join バーの任意の識別子。 |
orientation |
Literal["horizontal", "vertical"] |
"horizontal" |
バーの向き(上下フロー向けの横長バー "horizontal"、左右フロー向けの縦長バー "vertical")。 |
length |
float |
16.0 |
orientation 軸方向のバー長(ローカル単位)。 |
thickness |
float |
1.8 |
直交軸方向のバーの厚み(ローカル単位)。 |
style |
Style | None |
None |
バーの塗りつぶしスタイル上書き。 |
show |
bool |
True |
表示フラグ(False の場合、バーと接続遷移を非表示化)。 |
パブリックメソッド・プロパティ
| メンバー |
種別 |
シグネチャ |
説明 |
center |
property |
-> tuple[float, float] |
同期バーの相対中心座標 (cx, cy)。 |
effective_height |
property |
-> float |
描画高さ("horizontal" 時は thickness、"vertical" 時は length)。 |
effective_width |
property |
-> float |
描画幅("horizontal" 時は length、"vertical" 時は thickness)。 |
get_anchor |
method |
(self, side: Side) -> tuple[float, float] |
指定した side の境界座標を返します。 |
get_bounds |
method |
(self) -> tuple[float, float, float, float] |
中心 (0, 0) 基準のローカル境界 (min_x, min_y, max_x, max_y) を返します。 |
xy |
property |
-> tuple[float, float] |
相対中心座標 (cx, cy) を返すエイリアス。 |
classInitialState
ステートマシンの開始点を示す塗りつぶし黒丸の UML 2.x 開始疑似状態です。StateNodeBase のサブクラスです。
InitialState(
name: str = "",
radius: float = 1.75,
style: Style | None = None,
show: bool = True,
) -> None
- 座標アンカー:
sd.add(init, xy=(cx, cy)) で登録する際の中心座標 (cx, cy)。
コンストラクタ引数
| 引数 |
型 |
デフォルト |
説明 |
name |
str |
"" |
開始疑似状態の任意の識別子。 |
radius |
float |
1.75 |
塗りつぶし円の半径(ローカル単位、直径は 3.5)。 |
style |
Style | None |
None |
塗りつぶし色のスタイル上書き。 |
show |
bool |
True |
表示フラグ(False の場合、このノードと出力遷移を非表示化)。 |
パブリックメソッド・プロパティ
| メンバー |
種別 |
シグネチャ |
説明 |
center |
property |
-> tuple[float, float] |
円の相対中心座標 (cx, cy)。 |
effective_height |
property |
-> float |
実効描画直径(2 * radius)。 |
effective_width |
property |
-> float |
実効描画直径(2 * radius)。 |
get_anchor |
method |
(self, side: Side) -> tuple[float, float] |
指定した side の外周アンカー座標を返します。 |
get_bounds |
method |
(self) -> tuple[float, float, float, float] |
中心 (0, 0) 基準のローカル境界 (-radius, -radius, radius, radius) を返します。 |
xy |
property |
-> tuple[float, float] |
相対中心座標 (cx, cy) を返すエイリアス。 |
typePaddingType
StateTransition 矢印の両端に設けるクリアランス余白距離を表す Union 型エイリアスです。
PaddingType = float | tuple[float, float]
- 座標アンカー:
start と end の状態ノード外周から遷移矢印の端点を外側に離す距離を指定します(対称な float または (start_pad, end_pad) タプル)。
typeRoutingType
StateTransition コネクタの曲線/折れ線ジオメトリを制御する Literal 型です。
RoutingType = Literal["curved", "orthogonal", "direct"]
- 座標アンカー: 解決された
start と end の境界アンカー間の補間経路を制御します。
| リテラル値 |
経路ジオメトリ |
"curved" |
bend で曲率を制御する滑らかな二次曲線アーク(デフォルト。双方向 A <-> B 遷移の分離に最適)。 |
"orthogonal" |
水平・垂直の直角マンハッタン折れ線セグメント。 |
"direct" |
解決されたアンカー間を直線で結ぶユークリッド線分。 |
typeShapeType
State ノードの外形図形を選択する Literal 型です。
ShapeType = Literal["box", "ellipse", "circle", "double_circle", "text_only"]
- 座標アンカー: すべての状態図形は
(cx, cy) を中心として描画されます。
| リテラル値 |
描画形状 |
主な用途 |
"box" |
角丸長方形(内部アクション指定時は区切り線付き 2 区画) |
UML 2.x 標準のステートチャート状態(デフォルト)。 |
"ellipse" |
楕円 |
概念的な状態遷移図や Moore/Mealy マシン。 |
"circle" |
一重円 |
形式言語・オートマトン理論の DFA / NFA 状態頂点(q0、q1)。 |
"double_circle" |
同心二重円 |
DFA / NFA の受理状態(Accepting State)。 |
"text_only" |
枠線なしのテキストラベル |
最小構成のテキスト状態表現。 |
typeSide
StateNodeBase ノード上の接続ポート位置(四隅の対角方向を含む)を指定する Literal 型です。
Side = Literal[
"left",
"right",
"top",
"bottom",
"auto",
"top_right",
"top_left",
"bottom_right",
"bottom_left",
]
- 座標アンカー: 角丸長方形、円、楕円、ひし形の外周境界上の座標に解決されます(
"auto" は対向する最近傍の位置を自動選択)。
classState
UML 2.x の角丸ボックス状態(entry /・do /・exit / 内部振る舞い区画に対応)および形式オートマトンの円・二重円状態を表現する主要状態クラスです。StateNodeBase のサブクラスです。
State(
name: str,
shape: ShapeType = "box",
entry: str = "",
do: str = "",
exit: str = "",
width: float | None = None,
height: float | None = None,
style: Style | None = None,
show: bool = True,
) -> None
- 座標アンカー:
sd.add(state, xy=(cx, cy)) で登録する際の中心座標 (cx, cy)。
コンストラクタ引数
| 引数 |
型 |
デフォルト |
説明 |
name |
str |
(必須) |
メイン区画(内部アクションがある場合は上段ヘッダー)に描画される状態名。 |
shape |
ShapeType |
"box" |
ノード図形種別("box"、"ellipse"、"circle"、"double_circle"、"text_only")。 |
entry |
str |
"" |
"box" 状態で entry / <entry> として整形表示される入場アクション。 |
do |
str |
"" |
"box" 状態で do / <do> として整形表示される継続アクティビティ。 |
exit |
str |
"" |
"box" 状態で exit / <exit> として整形表示される退場アクション。 |
width |
float | None |
None |
明示的な固定幅(None の場合は状態名およびアクション文字列長から自動算出)。 |
height |
float | None |
None |
明示的な固定高さ(None の場合はヘッダー+アクション行数から自動算出)。 |
style |
Style | None |
None |
塗り・枠線・文字スタイルの任意上書き(未指定時は sd.node_style)。 |
show |
bool |
True |
表示フラグ(False の場合、この状態と接続遷移を非表示化)。 |
パブリックメソッド・プロパティ
| メンバー |
種別 |
シグネチャ |
説明 |
add_action |
method |
(self, kind: str, action: str) -> State |
内部区画にカスタム StateAction 行("{kind} / {action}")を追加し、self を返します。 |
center |
property |
-> tuple[float, float] |
状態ノードの相対中心座標 (cx, cy)。 |
effective_height |
property |
-> float |
算出された実効描画高さ。 |
effective_width |
property |
-> float |
算出された実効描画幅。 |
get_anchor |
method |
(self, side: Side) -> tuple[float, float] |
指定した side の外周アンカー座標を返します。 |
get_bounds |
method |
(self) -> tuple[float, float, float, float] |
中心 (0, 0) 基準のローカル境界 (-effective_width/2, -effective_height/2, ...) を返します。 |
xy |
property |
-> tuple[float, float] |
相対中心座標 (cx, cy) を返すエイリアス。 |
classStateAction
State ボックス内の内部アクティビティ 1 行(entry /、do /、exit /、または任意の内部イベントトリガー)を表すバリデーション付き Pydantic データモデルです。通常は State(..., entry=..., do=..., exit=...) または state.add_action(kind, action) から登録します。
StateAction(
*,
kind: str,
action: str,
) -> None
- 座標アンカー:
"box" 形状の State の下段区画内に左揃えで描画されます。
コンストラクタ引数・フィールド
| 引数 |
型 |
デフォルト |
説明 |
kind |
str |
(必須) |
"entry"、"do"、"exit"、または内部イベント名などのトリガー種別(キーワード専用)。 |
action |
str |
(必須) |
実行される振る舞い式または関数シグネチャ文字列(キーワード専用)。 |
パブリックメソッド・プロパティ
| メンバー |
種別 |
シグネチャ |
説明 |
display_text |
property |
-> str |
フォーマット済みの UML 内部アクション文字列("{kind} / {action}")。 |
model_copy |
method |
(self, *, update: Mapping[str, Any] | None = None, deep: bool = False) -> Self |
任意のフィールド更新を伴う浅い/深いコピーを生成します(pydantic.BaseModel)。 |
model_dump |
method |
(self, *, mode: str = "python", ...) -> dict[str, Any] |
フィールドを Python 辞書へシリアライズします(pydantic.BaseModel)。 |
model_dump_json |
method |
(self, *, indent: int | None = None, ...) -> str |
フィールドを JSON 文字列へシリアライズします(pydantic.BaseModel)。 |
model_validate |
classmethod |
(obj: Any, *, strict: bool | None = None, ...) -> Self |
任意の辞書やオブジェクトを検証して StateAction を生成します。 |
model_validate_json |
classmethod |
(json_data: str | bytes | bytearray, ...) -> Self |
JSON データをパース・検証して StateAction を生成します。 |
model_validate_strings |
classmethod |
(obj: Any, ...) -> Self |
文字列値辞書を検証して StateAction を生成します。 |
model_construct |
classmethod |
(_fields_set: set[str] | None = None, **values: Any) -> Self |
バリデーションを省略してフィールド値から直接インスタンスを構築します。 |
model_json_schema |
classmethod |
(by_alias: bool = True, ...) -> dict[str, Any] |
StateAction の JSON Schema 辞書を生成します。 |
(このほか pydantic.BaseModel 標準の互換メンバー model_extra、model_fields_set、model_parametrized_name、model_post_init、model_rebuild、construct、copy、dict、from_orm、json、parse_file、parse_obj、parse_raw、schema、schema_json、update_forward_refs、validate を継承します。)
classStateDiagram
状態ノード、疑似状態、状態遷移エッジ、および全体のバウンディングボックス配置を統合管理する UML ステートチャート・FSM 図のトップレベルコンテナです。
StateDiagram(
*,
node_style: Style,
edge_style: Style,
edge_text_style: Style,
title: str = "",
title_style: Style | None = None,
style: Style | None = None,
width: float | None = None,
height: float | None = None,
margin: float = 5.0,
) -> None
- 座標アンカー:
draw(xy=(0.0, 0.0), align="bottom_left") はローカル座標を xy 分シフトして描画します(align="center" の場合は get_bounds() の包含中心を xy に配置)。
コンストラクタ引数
| 引数 |
型 |
デフォルト |
説明 |
node_style |
Style |
(必須) |
状態ノードおよび疑似状態に適用される基本スタイル(キーワード専用)。 |
edge_style |
Style |
(必須) |
StateTransition 遷移線の基本ストローク・矢印スタイル(キーワード専用)。 |
edge_text_style |
Style |
(必須) |
遷移ラベル event [guard] / action の基本テキストスタイル(キーワード専用)。 |
title |
str |
"" |
図の上部中央に描画される任意のタイトル。 |
title_style |
Style | None |
None |
title 用の任意のテキストスタイル上書き。 |
style |
Style | None |
None |
図全体を囲む外枠カードの任意の背景・枠線スタイル。 |
width |
float | None |
None |
固定幅の任意上書き(None の場合は get_bounds() + margin から自動算出)。 |
height |
float | None |
None |
固定高さの任意上書き(None の場合は get_bounds() + margin から自動算出)。 |
margin |
float |
5.0 |
全状態および自己遷移ループ周囲の外側マージン余白。 |
パブリックメソッド・プロパティ
| メンバー |
種別 |
シグネチャ |
説明 |
add |
method |
(self, item: NodeT, xy: tuple[float, float] = (0.0, 0.0), width: float | None = None, height: float | None = None, style: Style | None = None, show: bool | None = None) -> NodeT |
座標 xy を中心として State または疑似状態を登録し(サイズ・スタイルのその場上書きに対応)、返します。 |
add_transition |
method |
(self, trans: StateTransition) -> StateTransition |
構築済みの StateTransition をこの図に登録します。 |
connect |
method |
(self, source: StateNodeBase, target: StateNodeBase, *, label: str = "", event: str = "", guard: str = "", action: str = "", side: LoopSide = "top", bend: float = 0.0, start_side: Side = "auto", end_side: Side = "auto", routing: RoutingType = "curved", style: Style | None = None, text_style: Style | None = None, padding: PaddingType = 0.0, loop_width: float | None = None, loop_height: float | None = None, loop_ratio: float = 0.88, show: bool = True) -> StateTransition |
StateTransition(source is target の場合は自己遷移ループ)を生成・登録します。 |
draw |
method |
(self, xy: tuple[float, float] = (0.0, 0.0), *, align: Literal["bottom_left", "center"] = "bottom_left", scale: PosFloat = 1.0) -> None |
アクティブなキャンバス上のアンカー xy にステートマシン図を描画します。 |
get_bounds |
method |
(self) -> tuple[float, float, float, float] |
全状態ノードおよび自己遷移ループを囲む (min_x, min_y, max_x, max_y) を算出します。 |
get_size |
method |
(self) -> tuple[float, float] |
margin を含めた図全体の (width, height) を算出します。 |
classStateNodeBase
State、InitialState、FinalState、ChoiceState、および ForkJoinState が共有する基底状態ノードクラスです。
StateNodeBase(
name: str = "",
width: float = 20.0,
height: float = 12.0,
style: Style | None = None,
show: bool = True,
) -> None
コンストラクタ引数
| 引数 |
型 |
デフォルト |
説明 |
name |
str |
"" |
状態ノードの識別子またはラベル文字列。 |
width |
float |
20.0 |
基本バウンディング幅(ローカル単位)。 |
height |
float |
12.0 |
基本バウンディング高さ(ローカル単位)。 |
style |
Style | None |
None |
任意の Style 上書き。 |
show |
bool |
True |
この状態ノードの表示フラグ。 |
パブリックメソッド・プロパティ
| メンバー |
種別 |
シグネチャ |
説明 |
center |
property |
-> tuple[float, float] |
状態ノードの相対中心座標 (cx, cy)。 |
effective_height |
property |
-> float |
状態ノードの実効描画高さ。 |
effective_width |
property |
-> float |
状態ノードの実効描画幅。 |
get_anchor |
method |
(self, side: Side) -> tuple[float, float] |
指定した side の境界アンカー座標を返します。 |
get_bounds |
method |
(self) -> tuple[float, float, float, float] |
中心 (0, 0) 基準のローカル境界 (min_x, min_y, max_x, max_y) を返します。 |
xy |
property |
-> tuple[float, float] |
相対中心座標 (cx, cy) を返すエイリアス。 |
classStateTransition
UML 標準の "event [guard] / action" ラベル自動整形を備えた、2 つの StateNodeBase 間を結ぶ有向状態遷移エッジ(または自己遷移楕円ループ)です。
StateTransition(
start: StateNodeBase,
end: StateNodeBase,
label: str = "",
event: str = "",
guard: str = "",
action: str = "",
bend: float = 0.0,
start_side: Side = "auto",
end_side: Side = "auto",
routing: RoutingType = "curved",
style: Style | None = None,
text_style: Style | None = None,
padding: PaddingType = 0.0,
loop_side: LoopSide = "top",
loop_width: float | None = None,
loop_height: float | None = None,
loop_ratio: float = 0.88,
is_loop: bool = False,
show: bool = True,
) -> None
- 座標アンカー:
start の start_side から end の end_side へ接続されます(start is end の場合は loop_side に自己遷移ループ円弧を描画)。
コンストラクタ引数
| 引数 |
型 |
デフォルト |
説明 |
start |
StateNodeBase |
(必須) |
遷移元の状態または疑似状態。 |
end |
StateNodeBase |
(必須) |
遷移先の状態または疑似状態(自己遷移の場合は start と同一)。 |
label |
str |
"" |
明示的な完全遷移ラベル(非空の場合は event/guard/action の自動整形より優先)。 |
event |
str |
"" |
"event [guard] / action" の先頭に配置されるトリガーイベント名。 |
guard |
str |
"" |
自動的に角括弧 [guard] で囲まれるガード条件式。 |
action |
str |
"" |
自動的に / action 形式で付加される遷移時アクション。 |
bend |
float |
0.0 |
"curved" ルーティング時の弧のたわみ量(0.0 で直線、0.25〜0.45 で往復遷移の分離に有効)。 |
start_side |
Side |
"auto" |
start 側の出発アンカー位置。 |
end_side |
Side |
"auto" |
end 側の到着アンカー位置。 |
routing |
RoutingType |
"curved" |
経路ルーティング方式("curved"、"orthogonal"、"direct")。 |
style |
Style | None |
None |
遷移線スタイルの任意上書き(未指定時は sd.edge_style)。 |
text_style |
Style | None |
None |
ラベル文字スタイルの任意上書き(未指定時は sd.edge_text_style)。 |
padding |
PaddingType |
0.0 |
状態境界と遷移矢印端点間のクリアランス余白。 |
loop_side |
Literal["top", "bottom", "left", "right", ...] |
"top" |
自己遷移ループの配置辺(sd.connect(..., side=...) から転送)。 |
loop_width |
float | None |
None |
自己遷移ループ楕円のカスタム幅。 |
loop_height |
float | None |
None |
自己遷移ループ楕円のカスタム高さ。 |
loop_ratio |
float |
0.88 |
自己遷移ループ楕円を描画する円周比率(0.0〜1.0)。 |
is_loop |
bool |
False |
明示的な自己遷移フラグ(start is end の場合は自動的に True)。 |
show |
bool |
True |
この遷移を描画するかどうか。 |
パブリックメソッド・プロパティ
| メンバー |
種別 |
シグネチャ |
説明 |
effective_label |
property |
-> str |
解決された遷移ラベル文字列(label が非空ならその値、それ以外は "event [guard] / action" 整形結果)。 |
is_self_transition |
property |
-> bool |
同一状態へ戻る自己遷移(is_loop または start is end)の場合に True。 |