Diagrammes Unicode
Dessinez des diagrammes sous forme de texte brut avec des caractères Unicode de traçage de boîtes, dans un style de maison unique.
Construisez toujours le diagramme avec le moteur de grille textdiagram.py ci-dessous. Ne dessinez pas à la main :
les diagrammes dessinés à la main dérivent de leur alignement.
Règles de style
- Texte brut dans un bloc de code délimité. Pas de Mermaid, SVG, images ou emoji.
- Largeur : 80 colonnes par défaut. Pour la modifier, passez
max_widthau constructeur, par exempleD(max_width=100). Le moteur lève une erreur si une ligne est plus longue. - Tout le texte est EN MAJUSCULES. Le moteur le fait pour vous : écrivez du texte normal dans le script.
Exception : les unités dont la casse change le sens restent telles qu'écrites, lorsque vous les écrivez
exactement comme ceci :
Hz kHz MHz GHz,kB MB GB TB KiB MiB GiB TiB,kb Mb Gb Tb kbps Mbps Gbps,ms µs ns. D'autres mots, comme NGINX ou K8S, sont en majuscules. - Boîte COMPOSANT (une partie du système : service, client, base de données, file d'attente, worker) :
traits fins
┌─┐ │ └─┘plus une ombre légère░, une colonne à droite et une ligne en dessous. Pour grouper des parties, divisez une boîte en sections : séparateurs fins├───┤, un cadre, une ombre. - Boîte TITRE (le titre principal du document, un par diagramme) : traits doubles
╔═╗ ║ ╚═╝, pas d'ombre. Un élément par ligne (nom, type de document, version), chaque ligne centrée dans la boîte. Faites-la avecd.header(...): le moteur centre la boîte sur l'ensemble du diagramme. Optionnel : une boîte méta à gauche (entreprise, RFC, date) et une boîte tampon à droite (statut). Les trois ont la même hauteur ; les lignes de padding de la boîte titre contiennent un point centré·. Aucune flèche ne peut commencer ou se terminer sur une boîte d'en-tête. - Boîte CADRE (en-tête de section, note, callout) : traits fins, pas d'ombre.
Note / callout : mettez le nom dans la bordure supérieure, comme
┌─ NOTE ───┐. N'ajoutez pas de légende : le style est le même dans chaque diagramme. - Texte libre (
d.annotate) : une brève remarque sans boîte, à côté du diagramme. Utilisez-le rarement. Une ligne ne doit pas le traverser. - Flèche horizontale : étiquette à l'intérieur de la ligne, un espace de chaque côté :
── HTTPS ──▶. Les deux extrémités touchent une boîte : la ligne commence sur la colonne d'ombre de la boîte émettrice et la tête touche la boîte réceptrice. - Flèche verticale : la ligne part de
┬sur la bordure inférieure, se termine par▼. L'étiquette va à droite de la ligne, une ligne en dessous de l'ombre. Ou coupez l'étiquette dans la ligne (inline=True) : ligne, ligne vide, lignes d'étiquette centrées sur la ligne, ligne vide, ligne. - Flèche coudée (
d.route) : n'importe quel nombre de coudes, dans n'importe quelle direction (▲ ▼ ◀ ▶). L'étiquette va dans un segment transversal, ou à côté (ou, avecinline=True, coupée dans) un segment vertical. Les lignes qui se croisent ou se rejoignent font une jonction (┼ ├ ┤ ┬ ┴). Une ligne ne passe jamais à travers une boîte. - Bus (
d.fan_out) : une ligne d'une boîte qui se divise en une flèche par cible. L'étiquette va sur la ligne partagée. - Têtes de flèche : pleines
▶ ◀ ▲ ▼pour le flux principal. Creuses▷ ◁ △ ▽pour un second type de relation (asynchrone, optionnelle, événement). Utilisez les creuses uniquement si le diagramme a besoin de deux types, et nommez la signification dans une étiquette ou une note, pas dans une légende. - Étiquetez chaque flèche avec ce qui circule (protocole, événement, données).
- S'il n'est pas clair quel rôle une boîte a : COMPOSANT pour les parties du système, TITRE pour le titre principal, CADRE pour tout le reste.
Flux de travail
- Listez les composants, les cadres et les flèches avant de dessiner.
- Écrivez le moteur dans
/tmp/textdiagram/textdiagram.py(source complète à la fin de ce fichier, copiez-le exactement). Écrivez-le à nouveau à chaque session, afin qu'une ancienne version ne soit jamais utilisée. - Écrivez un court script Python qui importe le moteur et construit le diagramme. Utilisez les
aides de disposition pour placer les boîtes (ne devinez pas les coordonnées) :
Diagram.x_right_of(a, label)— x pour la prochaine boîte à droite, avec de la place pour l'étiquette de la flèche.Diagram.x_left_of(a, lines, label)— x pour une nouvelle boîte à gauche dea, avec de la place pour l'étiquette.Diagram.y_below(a)— y pour une boîte en dessous dea. Avec une étiquette en ligne :Diagram.y_below(a, lines=N).Diagram.x_centered_under(a, lines)— x pour qu'une boîte soit centrée sousa(nécessaire pourarrow_v).- Pour les voies de routage, utilisez les bords des boîtes :
a.right + 4,a.bottom + 2.
- Exécutez-le. Si cela lève
DiagramError, corrigez la disposition comme le message le dit et réexécutez. - Collez la sortie dans un bloc de code exactement comme imprimée. Ne la modifiez pas à la main. Pour une modification, éditez le script et exécutez-le à nouveau.
Exemple 1 : en-tête, sections, routes
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D() # max_width=80 est la valeur par défaut
t = d.header(["Plateforme de Commandes", "Architecture"],
left=["Acme Inc", "RFC 9000", "Nov 2026"],
right=["*~~~~~~~~~*", "Plongée Profonde", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Client"]) # role="component" est la valeur par défaut
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Passerelle"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2, # sections : une boîte, une ombre
[["Auth"], ["Commandes"], ["Facturation"]], title="Services")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Appels") # Forme de S
cache = d.box(D.x_left_of(svc, ["Cache"], "Lectures"), svc.rows[1] - 1, ["Cache"])
d.arrow_h(svc, cache, "Lectures", row=svc.rows[1]) # attacher à une section
aud = d.box(svc.right + 9, y, ["Audit"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Événements") # un coude
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2], # boucle : 3 coudes
via=[svc.right + 4, svc.bottom + 2], label="Réessayer")
print(d.render())
Sortie :
┌────────────┐ ╔══════════════════╗ ┌───────────────┐
│ ACME INC │ ║ PLATEFORME DE ║ │ *~~~~~~~~~* │
│ RFC 9000 │ ║ COMMANDES ║ │ PLONGÉE │
│ NOV 2026 │ ║ ARCHITECTURE ║ │ PROFONDE │
└────────────┘ ║ · ║ │ *~~~~~~~~~* │
╚══════════════════╝ └───────────────┘
┌──────────┐ ┌───────────┐ ┌─────────┐
│ CLIENT │── HTTPS ──▶│PASSERELLE│░ │ AUDIT │░
└──────────┘░ └─────┬─────┘░ └─────────┘░
░░░░░▲░░░░░░ ░░░░░│░░░░░░░ ░░░░▲░░░░░░
│ │ │
│ │ │
│ └───── APPELS ────┐ │
│ │ │
│ ▼ │
│ ┌─ SERVICES ────┐ │
│ │ AUTH │─── ÉVÉNEMENTS ──┘
│ ┌─────────┐ ├───────────────┤░
│ │ CACHE │◀─ LECTURES─│ COMMANDES │░
│ └─────────┘░ ├───────────────┤░
│ ░░░░░░░░░░░ │ FACTURATION │────┐
│ └───────────────┘░ │
│ ░░░░░░░░░░░░░░░░░ │
│ │
└─────────────────────── RÉESSAYER ─────────────────────┘
Exemple 2 : bus, têtes creuses, étiquette en ligne, texte libre
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D()
t = d.header(["Bus d'Événements", "Conception"], left=["Acme Inc", "ADR 12", "Nov 2026"],
right=["*~~~~~~~*", "Brouillon", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Éditeur"])
s1 = d.box(36, y - 2, ["Facturation"])
s2 = d.box(36, y + 4, ["Audit"])
s3 = d.box(36, y + 10, ["Recherche"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Événements", head="hollow") # bus, têtes creuses
arc = d.box(D.x_centered_under(pub, ["Archive"]), D.y_below(pub, lines=2), ["Archive"])
d.arrow_v(pub, arc, "Sauvegarde\nnocturne", inline=True) # étiquette coupée dans la ligne
d.annotate(46, y + 16, ["Livraison", "au moins une fois"]) # texte libre, pas de boîte
print(d.render())
Sortie :
┌────────────┐ ╔════════════════╗ ┌─────────────┐
│ ACME INC │ ║ BUS ║ │ *~~~~~~~* │
│ ADR 12 │ ║ D'ÉVÉNEMENTS ║ │ BROUILLON │
│ NOV 2026 │ ║ CONCEPTION ║ │ *~~~~~~~* │
└────────────┘ ║ · ║ └─────────────┘
╚════════════════╝
┌───────────┐
┌──────▷│FACTURATION│░
┌─────────────┐ │ └───────────┘░
│ ÉDITEUR │── ÉVÉNEMENTS──┤ ░░░░░░░░░░░░░
└──────┬──────┘░ │
░░░░░░│░░░░░░░░ │
│ ┌─────────┐
SAUVEGARDE ├──────▷│ AUDIT │░
NOCTURNE │ └─────────┘░
│ ░░░░░░░░░░░
│ │
▼ │
┌───────────┐ │ ┌──────────┐
│ ARCHIVE │░ └──────▷│RECHERCHE │░
└───────────┘░ └──────────┘░
░░░░░░░░░░░░░ ░░░░░░░░░░░░
LIVRAISON AU
MOINS UNE FOIS
Référence de l'API
D(max_width=80)— crée un diagramme ;max_widthest la limite de colonnes.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/bottomincluent l'ombre).linesest une liste de lignes, ou une liste de sections (listes de lignes) pour diviser la boîte.box.rowscontient la ligne de flèche de chaque section.align="center"centre le texte.d.header(title, left=None, right=None, y=0)→ boîteBoxde titre. Chaque argument est une liste de lignes. Les boîtes obtiennent leurxfinal au moment du rendu. Un en-tête par diagramme.d.arrow_h(a, b, label="", row=None, head="filled")—aetbcôte à côte ; fonctionne dans les deux directions.rowchoisit une ligne de section (a.rows[i]).headest"filled"ou"hollow".d.arrow_v(a, b, label="", head="filled", inline=False)—ben dessous dea, centré sous celui-ci. Une étiquette peut avoir plus d'une ligne ("\n"). Avecinline=True, laissez de l'espace avecDiagram.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)— les côtés sont"left" "right" "top" "bottom". La ligne quittea_sidedeaet entre dansb_sidedeb. Elle alen(via) + 2segments, qui alternent entre transversaux et verticaux, en commençant par la direction qui quittea_side. Chaque valeurviaest la voie d'un segment intermédiaire : un x pour un segment vertical, un y pour un segment transversal.via=[]est un coude, une valeur est deux coudes (forme en S ou U), deux valeurs sont trois coudes (une boucle).a_row/b_rowchoisissent une ligne de section.label_segchoisit le segment (à partir de 0) qui porte l'étiquette.d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False)— un bus.trunkest la voie de la ligne partagée : un x pour les côtés gauche/droit, un y pour haut/bas.d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled")— un coude, une forme courte deroute.vh: quitte le bas dea, tourne dans le côté deb.hv: quitte le côté dea, tourne vers le bas dans le haut deb. La direction suit la position deb.d.annotate(x, y, lines, align="left")→Box(rôle"text") — texte libre, en majuscules.linesest une chaîne ("\n"commence une nouvelle ligne) ou une liste.d.text(x, y, s)— texte brut (non mis en majuscules).d.render()— retourne le diagramme ; place l'en-tête ; vérifie la largeur et les caractères larges.- Le moteur lève
DiagramErroren cas de chevauchements, de petits écarts, de valeurs de voie incorrectes ou de lignes dépassant la largeur maximale.
Si aucun shell n'est disponible
Dessinez à la main avec les mêmes règles. Comptez ensuite les colonnes sur chaque ligne et vérifiez que : l'ombre droite est une colonne à droite de la boîte ; la ligne d'ombre inférieure commence une colonne à droite du bord gauche de la boîte et se termine dans la colonne d'ombre ; tous les bords de la boîte s'alignent.
Source du moteur : textdiagram.py
"""textdiagram : dessinez des diagrammes en boîte Unicode alignés sur une grille de caractères.
Style :
Tout le texte est en majuscules, sauf les unités dans KEEP.
Boîte COMPOSANT : traits fins + ombre légère (░) une colonne à droite, une ligne en dessous.
Boîte TITRE : traits doubles, pas d'ombre, centrée sur le diagramme (placée au rendu).
Boîte CADRE : traits fins, pas d'ombre (note, callout).
En-tête : boîte titre avec une boîte méta optionnelle (gauche) et une boîte tampon (droite) ;
les lignes de padding de la boîte titre contiennent un point centré.
Sections : une boîte divisée par des séparateurs fins, une ombre pour toute la boîte.
Flèche horizontale : étiquette à l'intérieur de la ligne, les deux extrémités touchent une boîte : ── ÉTIQUETTE ──▶
Flèche verticale : étiquette à droite de la ligne, une ligne en dessous de l'ombre.
Route : flèche avec n'importe quel nombre de coudes, définis par des coordonnées de voie (via).
Tête : pleine (▶) ou creuse (▷). fan_out : une ligne qui se divise en plusieurs flèches.
Étiquette sur une ligne verticale : à côté de la ligne, ou coupée dedans (inline=True).
annotate : texte libre sans boîte.
"""
import re
import unicodedata
SHADOW = "░"
MIN_DASH = 2 # tirets de chaque côté d'une étiquette de flèche
HEADER_GAP = 2 # colonnes entre les boîtes d'en-tête
# Unités dont la casse change le sens (MB = byte, Mb = bit, ms = milli, MS = mega).
# Un mot n'est conservé que s'il est écrit exactement comme l'un de ceux-ci.
KEEP = {
"Hz", "kHz", "MHz", "GHz",
"kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
"kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
"ms", "µs", "ns",
}
# Caractères de traçage de boîtes en tant qu'ensembles de bras : lorsque deux lignes de flèche se rencontrent, les bras
# sont joints en un seul caractère de jonction (┼, ├, ...).
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
"├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v):
…
[tronqué pour la traduction]