Was macht Unicode-Diagramme?
Zeichne Diagramme als Klartext mit Unicode-Box-Zeichen, in einem einheitlichen Stil.
Erstelle das Diagramm immer mit der untenstehenden textdiagram.py-Raster-Engine. Zeichne nicht von Hand:
Handgezeichnete Diagramme geraten aus der Ausrichtung.
Stilregeln
- Klartext in einem umschlossenen Code-Block. Kein Mermaid, SVG, Bilder oder Emojis.
- Breite: Standardmäßig 80 Spalten. Um sie zu ändern, übergib
max_widthan den Konstruktor, z. B.D(max_width=100). Die Engine gibt einen Fehler bei einer längeren Zeile aus. - Alles in GROSSBUCHSTABEN. Die Engine erledigt das für dich: Schreibe normalen Text im Skript.
Ausnahme: Einheiten, deren Groß-/Kleinschreibung die Bedeutung ändert, bleiben so stehen, wie sie
geschrieben sind, wenn du sie exakt so schreibst:
Hz kHz MHz GHz,kB MB GB TB KiB MiB GiB TiB,kb Mb Gb Tb kbps Mbps Gbps,ms µs ns. Andere Wörter, wie NGINX oder K8S, sind in Großbuchstaben. - KOMPONENTEN-Box (ein Teil des Systems: Dienst, Client, Datenbank, Warteschlange, Worker):
helle Linien
┌─┐ │ └─┘plus ein heller░Schatten, eine Spalte rechts und eine Zeile darunter. Um Teile zu gruppieren, teile eine Box in Abschnitte auf: helle Trennlinien├───┤, ein Rahmen, ein Schatten. - TITEL-Box (der Haupttitel des Dokuments, eines pro Diagramm): doppelte Linien
╔═╗ ║ ╚═╝, kein Schatten. Ein Eintrag pro Zeile (Name, Dokumenttyp, Version), jede Zeile in der Box zentriert. Erstelle sie mitd.header(...): Die Engine zentriert die Box über dem gesamten Diagramm. Optional: eine Meta-Box links (Firma, RFC, Datum) und eine Stempel-Box rechts (Status). Alle drei erhalten die gleiche Höhe; Füllzeilen der Titelbox enthalten einen zentrierten Punkt·. Kein Pfeil darf an einer Header-Box beginnen oder enden. - RAHMEN-Box (Abschnittsüberschrift, Notiz, Hinweis): helle Linien, kein Schatten.
Notiz / Hinweis: setze den Namen in den oberen Rand, wie
┌─ HINWEIS ───┐. Füge keine Legende hinzu: Der Stil ist in jedem Diagramm gleich. - Freier Text (
d.annotate): eine kurze Bemerkung ohne Box, neben dem Diagramm. Verwende es selten. Eine Linie darf ihn nicht kreuzen. - Horizontaler Pfeil: Beschriftung innerhalb der Linie, je ein Leerzeichen auf jeder Seite:
── HTTPS ──▶. Beide Enden berühren eine Box: Die Linie beginnt in der Schattenspalte der sendenden Box und die Spitze berührt die empfangende Box. - Vertikaler Pfeil: Linie beginnt mit
┬am unteren Rand, endet mit▼. Die Beschriftung geht rechts von der Linie, eine Zeile unter dem Schatten. Oder schneide die Beschriftung in die Linie (inline=True): Linie, leere Zeile, Beschriftungszeilen zentriert auf der Linie, leere Zeile, Linie. - Abgewinkelter Pfeil (
d.route): beliebig viele Biegungen, in jede Richtung (▲ ▼ ◀ ▶). Die Beschriftung geht in ein horizontales Segment, oder neben (oder, mitinline=True, in) ein vertikales Segment. Linien, die sich kreuzen oder treffen, bilden eine Kreuzung (┼ ├ ┤ ┬ ┴). Eine Linie verläuft niemals durch eine Box. - Bus (
d.fan_out): eine Linie von einer Box, die sich in einen Pfeil pro Ziel aufteilt. Die Beschriftung steht auf der gemeinsamen Linie. - Pfeilspitzen: gefüllte
▶ ◀ ▲ ▼für den Hauptfluss. Hohle▷ ◁ △ ▽für eine zweite Art von Beziehung (asynchron, optional, Ereignis). Verwende hohle Spitzen nur, wenn das Diagramm zwei Arten benötigt, und benenne die Bedeutung in einer Beschriftung oder einer Notiz, nicht in einer Legende. - Beschrifte jeden Pfeil mit dem, was fließt (Protokoll, Ereignis, Daten).
- Wenn nicht klar ist, welche Rolle eine Box hat: KOMPONENTE für Systemteile, TITEL für den Haupttitel, RAHMEN für alles andere.
Arbeitsablauf
- Liste die Komponenten, Rahmen und Pfeile auf, bevor du zeichnest.
- Schreibe die Engine nach
/tmp/textdiagram/textdiagram.py(vollständiger Quellcode am Ende dieser Datei, kopiere ihn genau). Schreibe sie bei jeder Sitzung neu, damit nie eine alte Version verwendet wird. - Schreibe ein kurzes Python-Skript, das die Engine importiert und das Diagramm erstellt. Verwende die
Layout-Hilfsfunktionen, um Boxen zu platzieren (rate keine Koordinaten):
Diagram.x_right_of(a, label)— x für die nächste Box rechts vona, mit Platz für die Pfeilbeschriftung.Diagram.x_left_of(a, lines, label)— x für eine neue Box links vona, mit Platz für die Beschriftung.Diagram.y_below(a)— y für eine Box untera. Mit einer Inline-Beschriftung:Diagram.y_below(a, lines=N).Diagram.x_centered_under(a, lines)— x, damit eine Box zentriert unterasitzt (erforderlich fürarrow_v).- Für Routen-Spuren verwende die Kanten der Boxen:
a.right + 4,a.bottom + 2.
- Führe es aus. Wenn es
DiagramErrorauslöst, korrigiere das Layout gemäß der Meldung und führe es erneut aus. - Füge die Ausgabe genau so in einen Code-Block ein, wie sie gedruckt wurde. Bearbeite sie nicht von Hand. Für eine Änderung bearbeite das Skript und führe es erneut aus.
Beispiel 1: Kopfzeile, Abschnitte, Routen
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D() # max_width=80 ist der Standard
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" ist der Standard
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, # Abschnitte: eine Box, ein Schatten
[["Auth"], ["Orders"], ["Billing"]], title="Services")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Calls") # S-Form
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]) # an einem Abschnitt befestigen
aud = d.box(svc.right + 9, y, ["Audit"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Events") # eine Biegung
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2], # Schleife: 3 Biegungen
via=[svc.right + 4, svc.bottom + 2], label="Retry")
print(d.render())
Ausgabe:
┌────────────┐ ╔══════════════════╗ ┌───────────────┐
│ ACME INC │ ║ ORDER PLATFORM ║ │ *~~~~~~~~~* │
│ RFC 9000 │ ║ ARCHITECTURE ║ │ DEEP DIVE │
│ NOV 2026 │ ║ · ║ │ *~~~~~~~~~* │
└────────────┘ ╚══════════════════╝ └───────────────┘
┌──────────┐ ┌───────────┐ ┌─────────┐
│ CLIENT │── HTTPS ──▶│ GATEWAY │░ │ AUDIT │░
└──────────┘░ └─────┬─────┘░ └─────────┘░
░░░░░▲░░░░░░ ░░░░░│░░░░░░░ ░░░░▲░░░░░░
│ │ │
│ │ │
│ └───── CALLS ─────┐ │
│ │ │
│ ▼ │
│ ┌─ SERVICES ────┐ │
│ │ AUTH │─── EVENTS ───┘
│ ┌─────────┐ ├───────────────┤░
│ │ CACHE │◀─ READS ───│ ORDERS │░
│ └─────────┘░ ├───────────────┤░
│ ░░░░░░░░░░░ │ BILLING │────┐
│ └───────────────┘░ │
│ ░░░░░░░░░░░░░░░░░ │
│ │
└─────────────────────── RETRY ────────────────────────┘
Beispiel 2: Bus, hohle Spitzen, Inline-Beschriftung, freier Text
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") # bus, hohle Spitzen
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) # Beschriftung in die Linie geschnitten
d.annotate(46, y + 16, ["At-least-once", "delivery"]) # freier Text, keine Box
print(d.render())
Ausgabe:
┌────────────┐ ╔═════════════╗ ┌─────────────┐
│ ACME INC │ ║ EVENT BUS ║ │ *~~~~~~~* │
│ ADR 12 │ ║ DESIGN ║ │ DRAFT │
│ NOV 2026 │ ║ · ║ │ *~~~~~~~* │
└────────────┘ ╚═════════════╝ └─────────────┘
┌───────────┐
┌──────▷│ BILLING │░
┌─────────────┐ │ └───────────┘░
│ PUBLISHER │── EVENTS ───┤ ░░░░░░░░░░░░░
└──────┬──────┘░ │
░░░░░░│░░░░░░░░ │
│ ┌─────────┐
NIGHTLY ├──────▷│ AUDIT │░
BACKUP │ └─────────┘░
│ ░░░░░░░░░░░
│ │
▼ │
┌───────────┐ │ ┌──────────┐
│ ARCHIVE │░ └──────▷│ SEARCH │░
└───────────┘░ └──────────┘░
░░░░░░░░░░░░░ ░░░░░░░░░░░░
AT-LEAST-ONCE
DELIVERY
API-Referenz
D(max_width=80)— Erstelle ein Diagramm;max_widthist das Spaltenlimit.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/bottominklusive Schatten).linesist eine Liste von Zeilen oder eine Liste von Abschnitten (Listen von Zeilen), um die Box zu teilen.box.rowsenthält die Pfeilzeile jedes Abschnitts.align="center"zentriert den Text.d.header(title, left=None, right=None, y=0)→ Titel-Box. Jedes Argument ist eine Liste von Zeilen. Die Boxen erhalten ihre endgültigex-Position beim Rendern. Ein Header pro Diagramm.d.arrow_h(a, b, label="", row=None, head="filled")—aundbnebeneinander; funktioniert in beide Richtungen.rowwählt eine Abschnittszeile (a.rows[i]).headist"filled"oder"hollow".d.arrow_v(a, b, label="", head="filled", inline=False)—buntera, zentriert darunter. Eine Beschriftung kann mehr als eine Zeile haben (" "). Mitinline=True, lasse Platz mitDiagram.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)— Seiten sind"left" "right" "top" "bottom". Die Linie verlässta_sidevonaund tritt inb_sidevonbein. Sie hatlen(via) + 2Segmente, die sich horizontal und vertikal abwechseln, beginnend mit der Richtung, diea_sideverlässt. Jedervia-Wert ist die Spur eines mittleren Segments: ein x für ein vertikales Segment, ein y für ein horizontales Segment.via=[]ist eine Biegung, ein Wert ist zwei Biegungen (S- oder U-Form), zwei Werte sind drei Biegungen (eine Schleife).a_row/b_rowwählen eine Abschnittszeile.label_segwählt das Segment (von 0), das die Beschriftung trägt.d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False)— ein Bus.trunkist die Spur der gemeinsamen Linie: ein x für linke/rechte Seiten, ein y für obere/untere.d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled")— eine Biegung, eine Kurzform vonroute.vh: Verlasse den Boden vona, biege in die Seite vonbein.hv: Verlasse die Seite vona, biege nach unten in die Oberseite vonbein. Die Richtung folgt der Position vonb.d.annotate(x, y, lines, align="left")→Box(Rolle"text") — freier Text, in Großbuchstaben.linesist ein str (" "beginnt eine neue Zeile) oder eine Liste.d.text(x, y, s)— roher Text (nicht in Großbuchstaben).d.render()— gibt das Diagramm zurück; platziert den Header; überprüft die Breite und breite Zeichen.- Die Engine gibt
DiagramErrorbei Überlappungen, kleinen Lücken, falschen Spurwerten oder Zeilen über der maximalen Breite aus.
Wenn keine Shell verfügbar ist
Zeichne von Hand mit denselben Regeln. Zähle dann die Spalten in jeder Zeile und überprüfe, dass: der rechte Schatten eine Spalte rechts von der Box ist; die untere Schattenzeile eine Spalte rechts vom linken Rand der Box beginnt und in der Schattenspalte endet; alle Boxkanten ausgerichtet sind.
Engine-Quellcode: textdiagram.py
"""textdiagram: Zeichne ausgerichtete Unicode-Boxdiagramme auf einem Zeichenraster.
Stil:
Alles in Großbuchstaben, außer den Einheiten in KEEP.
KOMPONENTEN-Box: helle Linien + heller Schatten (░) eine Spalte rechts, eine Zeile darunter.
TITEL-Box: doppelte Linien, kein Schatten, zentriert über dem Diagramm (wird beim Rendern platziert).
RAHMEN-Box: helle Linien, kein Schatten (Notiz, Hinweis).
Header: Titelbox mit optionaler Meta-Box (links) und Stempel-Box (rechts);
Füllzeilen der Titelbox enthalten einen zentrierten Punkt.
Abschnitte: Eine Box geteilt durch helle Trennlinien, ein Schatten für die gesamte Box.
Horizontaler Pfeil: Beschriftung innerhalb der Linie, beide Enden berühren eine Box: ── BESCHRIFTUNG ──▶
Vertikaler Pfeil: Beschriftung rechts von der Linie, eine Zeile unter dem Schatten.
Route: Pfeil mit beliebig vielen Biegungen, festgelegt durch Spurenkoordinaten (via).
Spitze: gefüllt (▶) oder hohl (▷). fan_out: eine Linie, die sich in mehrere Pfeile aufteilt.
Beschriftung auf einer vertikalen Linie: neben der Linie oder in sie geschnitten (inline=True).
annotate: freier Text ohne Box.
"""
import re
import unicodedata
SHADOW = "░"
MIN_DASH = 2 # Striche auf jeder Seite einer Pfeilbeschriftung
HEADER_GAP = 2 # Spalten zwischen den Header-Boxen
# Einheiten, deren Groß-/Kleinschreibung die Bedeutung ändert (MB = Byte, Mb = Bit, ms = Milli, MS = Mega).
# Ein Wort wird nur beibehalten, wenn es genau wie eines dieser Wörter geschrieben ist.
KEEP = {
"Hz", "kHz", "MHz", "GHz",
"kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
"kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
"ms", "µs", "ns",
}
# Box-Zeichen als Sätze von Armen: Wo zwei Pfeillinien aufeinandertreffen, werden die Arme
# zu einem Kreuzungszeichen zusammengefügt (┼, ├, ...).
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
"├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v):
…
[nach Kürzung für die Übersetzung]“
}