Unicode Diagrams
Unicode箱描画文字を使い、一貫性のある自社スタイルで図をプレーンテキストとして描きます。
常に以下の textdiagram.py グリッドエンジンを使って図を構築すること。手描きは禁止:
手描きの図は位置がずれます。
スタイルルール
- プレーンテキストをフェンスドコードブロックで記述します。Mermaid、SVG、画像、絵文字は使用しません。
- 幅:デフォルト80カラム。変更するにはコンストラクタに
max_widthを渡します。 例:D(max_width=100)。エンジンは長い行があるとエラーを発生します。 - すべてのテキストは大文字です。エンジンが自動的に行います:スクリプトには通常のテキストを書いてください。
例外:意味が変わる単位は、以下のように正確に記述した場合にそのまま保持されます:
Hz kHz MHz GHz、kB MB GB TB KiB MiB GiB TiB、kb Mb Gb Tb kbps Mbps Gbps、ms µs ns。NGINXやK8Sなどの単語は大文字になります。 - コンポーネントボックス(システムの一部:サービス、クライアント、データベース、キュー、ワーカー):
細線
┌─┐ │ └─┘と、右1カラム・下1行に薄い影░を付けます。 パーツをグループ化するには、1つのボックスをセクションに分割します:細い区切り線├───┤、1つの枠、1つの影。 - タイトルボックス(ドキュメントのメインタイトル、図に1つ):二重線
╔═╗ ║ ╚═╝、影なし。 1行に1アイテム(名前、ドキュメント種別、バージョン)、各行はボックス内で中央揃え。d.header(...)で作成:エンジンが図全体に対してボックスを中央揃えに配置します。 オプション:左にメタボックス(会社、RFC、日付)、右にスタンプボックス(ステータス)。3つすべての高さは同じになります。 タイトルボックスのパディング行には中央にドット·を配置します。 ヘッダーボックスから矢印を開始・終了することはできません。 - フレームボックス(セクションヘッダー、注釈、注意書き):細線、影なし。
注釈/注意書き:名前を上枠に配置します(例:
┌─ NOTE ───┐)。 凡例は追加しないでください:すべての図でスタイルは同じです。 - フリーテキスト(
d.annotate):ボックスのない短いコメント、図の横に配置。使用は控えめに。行が交差してはいけません。 - 水平矢印:ラベルは線の内側に、両側に1スペースずつ:
── HTTPS ──▶。 両端がボックスに接します:線は送信ボックスの影のカラムから始まり、矢印の先が受信ボックスに接します。 - 垂直矢印:線は下枠の
┬から始まり、▼で終わります。ラベルは線の右側、影の1行下に配置されます。 またはラベルを線に埋め込む(inline=True):線、空白行、ラベル行(線に中央揃え)、空白行、線。 - 屈折矢印(
d.route):任意の数の屈折、任意の方向(▲ ▼ ◀ ▶)。ラベルは横断セグメント内側、 または上下セグメントの横(もしくはinline=Trueで埋め込み)に配置。 線が交差または結合する場所には交差点文字(┼ ├ ┤ ┬ ┴)を配置。線がボックスを通過することはありません。 - バス(
d.fan_out):1つのボックスから出て各ターゲットごとに1本の矢印に分岐する線。 ラベルは共有線に配置。 - 矢印の先:主なフローには塗りつぶし
▶ ◀ ▲ ▼。別の種類の関係(非同期、オプション、イベント)には中抜き▷ ◁ △ ▽。 図に2種類の関係が必要な場合のみ中抜きを使用し、凡例ではなくラベルや注釈で意味を明記します。 - すべての矢印に、何が流れるか(プロトコル、イベント、データ)をラベル付けします。
- どのボックスがどの役割か不明な場合:システムパーツはコンポーネント、メインタイトルはタイトル、その他はすべてフレーム。
ワークフロー
- 描画する前に、コンポーネント、フレーム、矢印をリストアップします。
- エンジンを
/tmp/textdiagram/textdiagram.pyに書き出します(このファイルの最後に完全なソースがあります。 正確にコピーしてください)。毎セッションごとに再度書き出すことで、古いバージョンが使われないようにします。 - エンジンをインポートして図を構築する短いPythonスクリプトを記述します。レイアウトヘルパーを使って
ボックスを配置します(座標は推測しないこと):
Diagram.x_right_of(a, label)— ボックスaの右に次のボックスを配置するためのx座標(矢印ラベルのスペースを含む)。Diagram.x_left_of(a, lines, label)— ボックスaの左に新しいボックスを配置するためのx座標(ラベルのスペースを含む)。Diagram.y_below(a)— ボックスaの下にボックスを配置するためのy座標。インラインラベルあり:Diagram.y_below(a, lines=N)。Diagram.x_centered_under(a, lines)— ボックスaの下に中央揃えでボックスを配置するためのx座標(arrow_vに必要)。- ルートレーンには、ボックスの端を使用:
a.right + 4、a.bottom + 2。
- スクリプトを実行します。
DiagramErrorが発生した場合は、メッセージに従ってレイアウトを修正し、再実行します。 - 出力をコードブロックに 印刷されたとおり正確に 貼り付けます。手動で編集しないでください。 変更するには、スクリプトを編集して再実行します。
例1:ヘッダー、セクション、ルート
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D() # max_width=80 がデフォルト
t = d.header(["Order Platform", "Architecture"],
left=["Acme Inc", "RFC 9000", "Nov 2026"],
right=["*~~~~~~~~~*", "Deep Dive", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Client"]) # role="component" がデフォルト
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Gateway"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2, # セクション:1つのボックス、1つの影
[["Auth"], ["Orders"], ["Billing"]], title="Services")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Calls") # S字
d.arrow_h(svc, cache, "Reads", row=svc.rows[1]) # 1つのセクションに接続
cache = d.box(D.x_left_of(svc, ["Cache"], "Reads"), svc.rows[1] - 1, ["Cache"])
aud = d.box(svc.right + 9, y, ["Audit"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Events") # 1回屈折
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2], # ループ:3回屈折
via=[svc.right + 4, svc.bottom + 2], label="Retry")
print(d.render())
出力:
┌────────────┐ ╔══════════════════╗ ┌───────────────┐
│ ACME INC │ ║ ORDER PLATFORM ║ │ *~~~~~~~~~* │
│ RFC 9000 │ ║ ARCHITECTURE ║ │ DEEP DIVE │
│ NOV 2026 │ ║ · ║ │ *~~~~~~~~~* │
└────────────┘ ╚══════════════════╝ └───────────────┘
┌──────────┐ ┌───────────┐ ┌─────────┐
│ CLIENT │── HTTPS ──▶│ GATEWAY │░ │ AUDIT │░
└──────────┘░ └─────┬─────┘░ └─────────┘░
░░░░░▲░░░░░░ ░░░░░│░░░░░░░ ░░░░▲░░░░░░
│ │ │
│ │ │
│ └───── CALLS ─────┐ │
│ │ │
│ ▼ │
│ ┌─ SERVICES ────┐ │
│ │ AUTH │─── EVENTS ───┘
│ ┌─────────┐ ├───────────────┤░
│ │ CACHE │◀─ READS ───│ ORDERS │░
│ └─────────┘░ ├───────────────┤░
│ ░░░░░░░░░░░ │ BILLING │────┐
│ └───────────────┘░ │
│ ░░░░░░░░░░░░░░░░░ │
│ │
└─────────────────────── RETRY ────────────────────────┘
例2:バス、中抜き矢印、インラインラベル、フリーテキスト
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D()
t = d.header(["Event Bus", "Design"], left=["Acme Inc", "ADR 12", "Nov 2026"],
right=["*~~~~~~~*", "Draft", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publisher"])
s1 = d.box(36, y - 2, ["Billing"])
s2 = d.box(36, y + 4, ["Audit"])
s3 = d.box(36, y + 10, ["Search"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Events", head="hollow") # バス、中抜き矢印
arc = d.box(D.x_centered_under(pub, ["Archive"]), D.y_below(pub, lines=2), ["Archive"])
d.arrow_v(pub, arc, "Nightly\nbackup", inline=True) # ラベルを線に埋め込み
d.annotate(46, y + 16, ["At-least-once", "delivery"]) # フリーテキスト、ボックスなし
print(d.render())
出力:
┌────────────┐ ╔═════════════╗ ┌─────────────┐
│ ACME INC │ ║ EVENT BUS ║ │ *~~~~~~~* │
│ ADR 12 │ ║ DESIGN ║ │ DRAFT │
│ NOV 2026 │ ║ · ║ │ *~~~~~~~* │
└────────────┘ ╚═════════════╝ └─────────────┘
┌───────────┐
┌──────▷│ BILLING │░
┌─────────────┐ │ └───────────┘░
│ PUBLISHER │── EVENTS ───┤ ░░░░░░░░░░░░░
└──────┬──────┘░ │
░░░░░░│░░░░░░░░ │
│ ┌─────────┐
NIGHTLY ├──────▷│ AUDIT │░
BACKUP │ └─────────┘░
│ ░░░░░░░░░░░
│ │
▼ │
┌───────────┐ │ ┌──────────┐
│ ARCHIVE │░ └──────▷│ SEARCH │░
└───────────┘░ └──────────┘░
░░░░░░░░░░░░░ ░░░░░░░░░░░░
AT-LEAST-ONCE
DELIVERY
API リファレンス
D(max_width=80)— 図を作成します。max_widthはカラム数の上限です。d.box(x, y, lines, role="component"|"frame"|"title", title=None, w=None, align="left")→Box(.x .y .w .h .right .bottom .cx .rows;right/bottomは影を含みます)。linesは行のリスト、またはボックスを分割するためのセクション(行のリスト)のリストです。box.rowsは各セクションの矢印行を保持します。align="center"でテキストを中央揃えにします。d.header(title, left=None, right=None, y=0)→ タイトルBox。各引数は行のリストです。 ボックスの最終的なx座標はレンダリング時に決定されます。図に1つのヘッダーのみ。d.arrow_h(a, b, label="", row=None, head="filled")—aとbが横に並んでいる場合に使用。両方向で動作します。rowでセクション行(a.rows[i])を選択します。headは"filled"または"hollow"。d.arrow_v(a, b, label="", head="filled", inline=False)—bはaの下、その中央に配置されます。 ラベルは複数行("\n")にできます。inline=Trueの場合は、Diagram.y_below(a, lines=N)でスペースを確保します。d.route(a, a_side, b, b_side, via=(), label="", label_seg=None, a_row=None, b_row=None, head="filled", inline=False)— 辺は"left" "right" "top" "bottom"。線はaのa_sideから出てbのb_sideに入ります。len(via) + 2のセグメントを持ち、横方向と上下方向が交互に並び、a_sideから出る方向で始まります。 各via値は1つの中間セグメントのレーンで、上下セグメントの場合はx座標、横セグメントの場合はy座標です。via=[]は1回屈折、1つの値は2回屈折(S字またはU字)、2つの値は3回屈折(ループ)です。a_row/b_rowでセクション行を選択します。label_segでラベルを配置するセグメント(0から開始)を選択します。d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False)— バス。trunkは共有線のレーン:左右の辺の場合はx座標、上下の辺の場合はy座標。d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled")— 1回屈折、routeの簡易形式。vh:aの下辺から出て、bの側面に入ります。hv:aの側面から出て、bの上辺に降りて入ります。 方向はbの位置に従います。d.annotate(x, y, lines, align="left")→Box(role"text") — フリーテキスト、大文字化されます。linesはstr("\n"で改行)またはリスト。d.text(x, y, s)— 生テキスト(大文字化されません)。d.render()— 図を返します。ヘッダーを配置し、幅とワイド文字をチェックします。- エンジンは、重なり、小さな隙間、不正なレーン値、最大幅を超える行に対して
DiagramErrorを発生します。
シェルが利用できない場合
同じルールで手描きします。その後、各行のカラム数を数えて以下を確認します: 右の影はボックスの右に1カラム;下の影行はボックスの左端から1カラム右に始まり、影のカラムで終わる; すべてのボックスの端が揃っている。
エンジンソース:textdiagram.py
"""textdiagram: 文字グリッド上に整列されたUnicode箱図を描画します。
スタイル:
すべてのテキストは大文字ですが、KEEP 内の単位は例外です。
コンポーネントボックス:細線 + 右1カラム・下1行に薄い影 (░)。
タイトルボックス:二重線、影なし、図全体に対して中央揃え(レンダリング時に配置)。
フレームボックス:細線、影なし(注釈、注意書き)。
ヘッダー:タイトルボックスと、オプションのメタボックス(左)およびスタンプボックス(右)。
タイトルボックスのパディング行には中央にドットを配置。
セクション:細い区切り線で分割された1つのボックス、ボックス全体に1つの影。
水平矢印:ラベルは線の内側、両端はボックスに接します: ── ラベル ──▶
垂直矢印:ラベルは線の右側、影の1行下。
ルート:レーン座標(via)で設定された任意の数の屈折を持つ矢印。
矢印の先:塗りつぶし (▶) または中抜き (▷)。fan_out:1本の線から複数の矢印に分岐。
上下線上のラベル:線の横、または線に埋め込まれます(inline=True)。
annotate:ボックスなしのフリーテキスト。
"""
import re
import unicodedata
SHADOW = "░"
MIN_DASH = 2 # 矢印ラベルの両側のダッシュ数
HEADER_GAP = 2 # ヘッダーボックス間のカラム数
# 意味が変わる単位(MB=バイト、Mb=ビット、ms=ミリ秒、MS=メガ秒)。
# 単語は、以下のいずれかと完全に一致する場合にのみ保持されます。
KEEP = {
"Hz", "kHz", "MHz", "GHz",
"kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
"kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
"ms", "µs", "ns",
}
# 箱描画文字を腕の集合として定義:2本の矢印線が出会う場所では、
# 腕が1つの交差点文字(┼、├、...)に結合されます。
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
"├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v):
…
[翻訳のため省略]