유니코드 다이어그램은(는) 무엇을 하나요?
유니코드 상자 그리기 문자를 사용하여 일반 텍스트로 다이어그램을 그립니다. 하나의 일관된 스타일을 사용합니다.
항상 아래 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 같은 다른 단어는 대문자로 표시됩니다. - 컴포넌트 상자(시스템의 일부: 서비스, 클라이언트, 데이터베이스, 큐, 워커):
가는 선
┌─┐ │ └─┘에 오른쪽 한 열, 아래 한 행의 가는░그림자 추가. 부분을 그룹화하려면 상자를 여러 섹션으로 나눕니다: 가는 구분선├───┤, 하나의 프레임, 하나의 그림자. - 제목 상자(문서의 주요 제목, 다이어그램당 하나): 이중선
╔═╗ ║ ╚═╝, 그림자 없음. 한 줄에 하나의 항목(이름, 문서 유형, 버전), 각 줄은 상자 중앙에 정렬.d.header(...)로 생성: 엔진이 상자를 전체 다이어그램 위에 가운데 정렬합니다. 선택 사항: 왼쪽에 메타 상자(회사, RFC, 날짜)와 오른쪽에 스탬프 상자(상태). 세 상자 모두 같은 높이를 가집니다. 제목 상자의 패딩 줄은 중앙 점·을 포함합니다. 헤더 상자에서 시작하거나 끝나는 화살표는 없습니다. - 프레임 상자(섹션 헤더, 메모, 콜아웃): 가는 선, 그림자 없음.
메모/콜아웃: 상단 테두리에 이름을 넣습니다. 예:
┌─ NOTE ───┐. 범례를 추가하지 마세요: 모든 다이어그램에서 스타일이 동일합니다. - 자유 텍스트(
d.annotate): 상자 없는 짧은 설명, 다이어그램 옆에 위치. 드물게 사용합니다. 줄이 자유 텍스트를 가로지르면 안 됩니다. - 수평 화살표: 선 안에 레이블, 양쪽에 공백 하나씩:
── HTTPS ──▶. 양쪽 끝이 상자에 닿음: 선은 보내는 상자의 그림자 열에서 시작하고 머리는 받는 상자에 닿습니다. - 수직 화살표: 선은 하단 테두리의
┬에서 시작,▼로 끝남. 레이블은 선 오른쪽, 그림자 아래 한 행에 위치. 또는 레이블을 선에 삽입(inline=True): 선, 빈 행, 선에 가운데 정렬된 레이블 행, 빈 행, 선. - 꺾인 화살표(
d.route): 여러 번 꺾일 수 있음, 모든 방향 가능(▲ ▼ ◀ ▶). 레이블은 가로 세그먼트 내부에, 또는 세로 세그먼트 옆에(또는inline=True로 세로 세그먼트에 삽입) 위치. 교차하거나 합류하는 선은 접합 문자(┼ ├ ┤ ┬ ┴)를 생성. 선은 절대 상자를 통과하지 않습니다. - 버스(
d.fan_out): 하나의 상자에서 나와 대상당 하나의 화살표로 분기. 레이블은 공유 선에 위치. - 화살표 머리: 채워짐
▶ ◀ ▲ ▼은 주요 흐름. 빔▷ ◁ △ ▽은 두 번째 관계 유형(비동기, 선택, 이벤트). 다이어그램에 두 가지 유형이 필요한 경우에만 빈 머리를 사용하고, 레이블이나 메모에 의미를 명시하세요(범례는 사용하지 않음). - 모든 화살표에 무엇이 흐르는지(프로토콜, 이벤트, 데이터) 레이블을 붙입니다.
- 상자의 역할이 명확하지 않은 경우: 시스템 부분은 COMPONENT, 주요 제목은 TITLE, 나머지는 FRAME을 사용하세요.
워크플로우
- 그리기 전에 컴포넌트, 프레임 및 화살표를 나열합니다.
- 엔진을
/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, # 섹션: 하나의 상자, 하나의 그림자
[["Auth"], ["Orders"], ["Billing"]], title="Services")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Calls") # S자 형태
cache = d.box(D.x_left_of(svc, ["Cache"], "Reads"), svc.rows[1] - 1, ["Cache"])
d.arrow_h(svc, cache, "Reads", row=svc.rows[1]) # 하나의 섹션에 연결
aud = d.box(svc.right + 9, y, ["Audit"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Events") # 한 번 꺾음
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2], # 루프: 세 번 꺾음
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)→ titleBox. 각 인수는 문자열 리스트입니다. 상자는 렌더링 시 최종x를 얻습니다. 다이어그램당 하나의 헤더.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)— sides는"left" "right" "top" "bottom". 선은a의a_side에서 나와b의b_side로 들어갑니다.len(via) + 2개의 세그먼트를 가지며, 가로와 세로가 번갈아 나타나고a_side에서 나가는 방향으로 시작합니다. 각via값은 중간 세그먼트 하나의 레인입니다: 세로 세그먼트의 x, 가로 세그먼트의 y.via=[]은 한 번 꺾음, 하나의 값은 두 번 꺾음(S 또는 U자 형태), 두 개의 값은 세 번 꺾음(루프).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")— 한 번 꺾음,route의 짧은 형태.vh:a의 하단을 나와b의 측면으로 회전.hv:a의 측면을 나와b의 상단으로 회전. 방향은b의 위치를 따릅니다.d.annotate(x, y, lines, align="left")→Box(역할"text") — 자유 텍스트, 대문자화됨.lines는 문자열("\n"은 새 줄 시작) 또는 리스트.d.text(x, y, s)— 원시 텍스트(대문자화되지 않음).d.render()— 다이어그램 반환; 헤더 배치; 너비 및 와이드 문자 확인.- 엔진은 겹침, 작은 간격, 잘못된 레인 값 또는 최대 너비 초과 시
DiagramError를 발생시킵니다.
셸을 사용할 수 없는 경우
동일한 규칙으로 직접 그리십시오. 그런 다음 각 줄의 열을 세고 다음을 확인하십시오: 오른쪽 그림자는 상자 오른쪽 한 열; 아래쪽 그림자 행은 상자 왼쪽 가장자리에서 한 열 오른쪽에서 시작하여 그림자 열에서 끝남; 모든 상자 가장자리가 정렬됩니다.
엔진 소스: textdiagram.py
"""textdiagram: 문자 그리드에 정렬된 유니코드 상자 다이어그램을 그립니다.
스타일:
모든 텍스트는 KEEP의 단위를 제외하고 대문자입니다.
COMPONENT 상자: 가는 선 + 오른쪽 한 열, 아래 한 행의 가는 그림자(░).
TITLE 상자: 이중선, 그림자 없음, 다이어그램 위에 가운데 정렬(렌더링 시 배치).
FRAME 상자: 가는 선, 그림자 없음(메모, 콜아웃).
헤더: 제목 상자와 선택적 메타 상자(왼쪽) 및 스탬프 상자(오른쪽);
제목 상자의 패딩 줄은 가운데 점을 포함합니다.
섹션: 가는 구분선으로 분할된 하나의 상자, 전체 상자에 대해 하나의 그림자.
수평 화살표: 선 안의 레이블, 양쪽 끝이 상자에 닿음: ── LABEL ──▶
수직 화살표: 선 오른쪽의 레이블, 그림자 아래 한 행.
경로: 레인 좌표(via)로 설정된 여러 번 꺾인 화살표.
머리: 채워짐(▶) 또는 빔(▷). fan_out: 하나의 선이 여러 화살표로 분할.
위/아래 선의 레이블: 선 옆, 또는 선에 삽입(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",
}
# 상자 그리기 문자를 팔 집합으로: 두 개의 화살표 선이 만나는 곳에서 팔이
# 하나의 접합 문자(┼, ├, ...)로 결합됩니다.
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
"├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v):