Diagramas Unicode
Dibuja diagramas como texto plano con caracteres Unicode de recuadro, en un estilo homogéneo.
Construye siempre el diagrama con el motor de cuadrícula textdiagram.py que se muestra a continuación. No dibujes a mano:
los diagramas dibujados a mano se desalinean.
Reglas de estilo
- Texto plano en un bloque de código delimitado. Nada de Mermaid, SVG, imágenes ni emojis.
- Ancho: 80 columnas por defecto. Para cambiarlo, pasa
max_widthal constructor, por ejemploD(max_width=100). El motor lanza un error si una línea es más larga. - Todo el texto está en MAYÚSCULAS. El motor hace esto por ti: escribe el texto normal en el script.
Excepción: las unidades cuyo caso cambia el significado se mantienen tal cual, cuando las escribes
exactamente así:
Hz kHz MHz GHz,kB MB GB TB KiB MiB GiB TiB,kb Mb Gb Tb kbps Mbps Gbps,ms µs ns. Otras palabras, como NGINX o K8S, están en mayúsculas. - Caja COMPONENTE (una parte del sistema: servicio, cliente, base de datos, cola, trabajador):
líneas ligeras
┌─┐ │ └─┘más una sombra ligera░, una columna a la derecha y una fila hacia abajo. Para agrupar partes, divide una caja en secciones: divisores ligeros├───┤, un marco, una sombra. - Caja TÍTULO (el título principal del documento, uno por diagrama): líneas dobles
╔═╗ ║ ╚═╝, sin sombra. Un elemento por línea (nombre, tipo de documento, versión), cada línea centrada en la caja. Créala cond.header(...): el motor centra la caja sobre todo el diagrama. Opcional: una caja de metadatos a la izquierda (empresa, RFC, fecha) y una caja de sello a la derecha (estado). Las tres tienen la misma altura; las líneas de relleno de la caja de título tienen un punto centrado·. Ninguna flecha puede comenzar o terminar en una caja de encabezado. - Caja MARCO (encabezado de sección, nota, llamada): líneas ligeras, sin sombra.
Nota / llamada: coloca el nombre en el borde superior, como
┌─ NOTA ───┐. No añadas una leyenda: el estilo es el mismo en todos los diagramas. - Texto libre (
d.annotate): una observación breve sin caja, al lado del diagrama. Úsalo con poca frecuencia. Una línea no debe cruzarlo. - Flecha horizontal: etiqueta dentro de la línea, un espacio a cada lado:
── HTTPS ──▶. Ambos extremos tocan una caja: la línea comienza en la columna de sombra de la caja emisora y la cabeza toca la caja receptora. - Flecha vertical: la línea comienza desde
┬en el borde inferior, termina con▼. La etiqueta va a la derecha de la línea, una fila debajo de la sombra. O inserta la etiqueta en la línea (inline=True): línea, fila en blanco, líneas de etiqueta centradas en la línea, fila en blanco, línea. - Flecha curvada (
d.route): cualquier número de curvas, en cualquier dirección (▲ ▼ ◀ ▶). La etiqueta va dentro de un segmento horizontal, o al lado (o, coninline=True, insertada en) un segmento vertical. Las líneas que se cruzan o unen forman una unión (┼ ├ ┤ ┬ ┴). Una línea nunca atraviesa una caja. - Bus (
d.fan_out): una línea desde una caja que se divide en una flecha por destino. La etiqueta va en la línea compartida. - Cabezas de flecha: rellenas
▶ ◀ ▲ ▼para el flujo principal. Huecas▷ ◁ △ ▽para un segundo tipo de relación (asíncrona, opcional, evento). Usa huecas solo si el diagrama necesita dos tipos, y nombra el significado en una etiqueta o una nota, no en una leyenda. - Etiqueta cada flecha con lo que fluye (protocolo, evento, datos).
- Si no está claro qué rol tiene una caja: COMPONENTE para partes del sistema, TÍTULO para el título principal, MARCO para todo lo demás.
Flujo de trabajo
- Enumera los componentes, marcos y flechas antes de dibujar.
- Escribe el motor en
/tmp/textdiagram/textdiagram.py(código fuente completo al final de este archivo, cópialo exactamente). Escríbelo de nuevo en cada sesión, para que nunca se use una versión antigua. - Escribe un script Python corto que importe el motor y construya el diagrama. Usa las
ayudas de diseño para colocar cajas (no adivines coordenadas):
Diagram.x_right_of(a, label)— x para la siguiente caja a la derecha, con espacio para la etiqueta de la flecha.Diagram.x_left_of(a, lines, label)— x para una nueva caja a la izquierda dea, con espacio para la etiqueta.Diagram.y_below(a)— y para una caja debajo dea. Con etiqueta en línea:Diagram.y_below(a, lines=N).Diagram.x_centered_under(a, lines)— x para que una caja quede centrada debajo dea(necesario paraarrow_v).- Para carriles de ruta, usa los bordes de las cajas:
a.right + 4,a.bottom + 2.
- Ejecútalo. Si lanza
DiagramError, corrige el diseño como indique el mensaje y vuelve a ejecutarlo. - Pega la salida en un bloque de código exactamente como se imprimió. No la edites a mano. Para un cambio, edita el script y vuelve a ejecutarlo.
Ejemplo 1: encabezado, secciones, rutas
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D() # max_width=80 es el valor por defecto
t = d.header(["Plataforma de Pedidos", "Arquitectura"],
left=["Acme Inc", "RFC 9000", "Nov 2026"],
right=["*~~~~~~~~~*", "Análisis Profundo", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Cliente"]) # role="component" es el valor por defecto
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Puerta de Enlace"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2, # secciones: una caja, una sombra
[["Auth"], ["Pedidos"], ["Facturación"]], title="Servicios")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Llamadas") # forma de S
cache = d.box(D.x_left_of(svc, ["Caché"], "Lecturas"), svc.rows[1] - 1, ["Caché"])
d.arrow_h(svc, cache, "Lecturas", row=svc.rows[1]) # conectar a una sección
aud = d.box(svc.right + 9, y, ["Auditoría"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Eventos") # una curva
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2], # bucle: 3 curvas
via=[svc.right + 4, svc.bottom + 2], label="Reintento")
print(d.render())
Salida:
┌────────────┐ ╔══════════════════╗ ┌───────────────┐
│ ACME INC │ ║ PLATAFORMA DE ║ │ *~~~~~~~~~* │
│ RFC 9000 │ ║ PEDIDOS ║ │ ANÁLISIS │
│ NOV 2026 │ ║ ARQUITECTURA ║ │ PROFUNDO │
└────────────┘ ║ · ║ │ *~~~~~~~~~* │
╚══════════════════╝ └───────────────┘
┌──────────┐ ┌───────────┐ ┌─────────┐
│ CLIENTE │── HTTPS ──▶│ PUERTA │░ │ AUDIT. │░
└──────────┘░ │ DE ENLACE│░ └─────────┘░
░░░░░▲░░░░░░ └─────┬─────┘░ ░░░░▲░░░░░░
│ │ │
│ │ │
│ └───── LLAMADAS ─────┐ │
│ │ │
│ ▼ │
│ ┌─ SERVICIOS ───┐ │
│ │ AUTH │─── EVENTOS ───┘
│ ┌─────────┐ ├───────────────┤░
│ │ CACHÉ │◀─ LECT.─│ PEDIDOS │░
│ └─────────┘░ ├───────────────┤░
│ ░░░░░░░░░░░ │ FACTURACIÓN │────┐
│ └───────────────┘░ │
│ ░░░░░░░░░░░░░░░░░ │
│ │
└───────────────────── REINTENTO ───────────────────┘
Ejemplo 2: bus, cabezas huecas, etiqueta en línea, texto libre
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D()
t = d.header(["Bus de Eventos", "Diseño"], left=["Acme Inc", "ADR 12", "Nov 2026"],
right=["*~~~~~~~*", "Borrador", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publicador"])
s1 = d.box(36, y - 2, ["Facturación"])
s2 = d.box(36, y + 4, ["Auditoría"])
s3 = d.box(36, y + 10, ["Búsqueda"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Eventos", head="hollow") # bus, cabezas huecas
arc = d.box(D.x_centered_under(pub, ["Archivo"]), D.y_below(pub, lines=2), ["Archivo"])
d.arrow_v(pub, arc, "Copia\nnocturna", inline=True) # etiqueta insertada en la línea
d.annotate(46, y + 16, ["Al menos una", "entrega"]) # texto libre, sin caja
print(d.render())
Salida:
┌────────────┐ ╔═════════════╗ ┌─────────────┐
│ ACME INC │ ║ BUS DE ║ │ *~~~~~~~* │
│ ADR 12 │ ║ EVENTOS ║ │ BORRADOR │
│ NOV 2026 │ ║ DISEÑO ║ │ *~~~~~~~* │
└────────────┘ ║ · ║ └─────────────┘
╚═════════════╝
┌───────────┐
┌──────▷│ FACTURAC. │░
┌─────────────┐ │ └───────────┘░
│ PUBLICADOR │── EVENTOS ───┤ ░░░░░░░░░░░░░
└──────┬──────┘░ │
░░░░░░│░░░░░░░░ │
│ ┌─────────┐
COPIA ├──────▷│ AUDIT. │░
NOCTURNA │ └─────────┘░
│ ░░░░░░░░░░░
│ │
▼ │
┌───────────┐ │ ┌──────────┐
│ ARCHIVO │░ └──────▷│ BÚSQUEDA │░
└───────────┘░ └──────────┘░
░░░░░░░░░░░░░ ░░░░░░░░░░░░
AL MENOS UNA
ENTREGA
Referencia de la API
D(max_width=80)— crea un diagrama;max_widthes el límite de columnas.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/bottomincluyen la sombra).lineses una lista de líneas, o una lista de secciones (listas de líneas) para dividir la caja.box.rowscontiene la fila de flecha de cada sección.align="center"centra el texto.d.header(title, left=None, right=None, y=0)→ cajaBoxde título. Cada argumento es una lista de líneas. Las cajas obtienen suxfinal en el momento del renderizado. Un encabezado por diagrama.d.arrow_h(a, b, label="", row=None, head="filled")—ayblado a lado; funciona en ambas direcciones.rowselecciona una fila de sección (a.rows[i]).heades"filled"o"hollow".d.arrow_v(a, b, label="", head="filled", inline=False)—bdebajo dea, centrado debajo. Una etiqueta puede tener más de una línea ("\n"). Coninline=True, deja espacio conDiagram.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)— los lados son"left" "right" "top" "bottom". La línea sale dea_sidedeay entra enb_sidedeb. Tienelen(via) + 2segmentos, que alternan entre horizontales y verticales, empezando con la dirección que sale dea_side. Cada valor deviaes el carril de un segmento medio: una x para un segmento vertical, una y para un segmento horizontal.via=[]es una curva, un valor es dos curvas (forma de S o U), dos valores son tres curvas (un bucle).a_row/b_rowseleccionan una fila de sección.label_segselecciona el segmento (desde 0) que lleva la etiqueta.d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False)— un bus.trunkes el carril de la línea compartida: una x para lados izquierdo/derecho, una y para superior/inferior.d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled")— una curva, una forma abreviada deroute.vh: sale de la parte inferior dea, gira hacia el lado deb.hv: sale del lado dea, gira hacia la parte superior deb. La dirección sigue la posición deb.d.annotate(x, y, lines, align="left")→Box(rol"text") — texto libre, en mayúsculas.lineses una cadena ("\n"comienza una nueva línea) o una lista.d.text(x, y, s)— texto sin formato (no en mayúsculas).d.render()— devuelve el diagrama; coloca el encabezado; comprueba el ancho y los caracteres anchos.- El motor lanza
DiagramErroren caso de superposiciones, espacios pequeños, valores de carril incorrectos o líneas que superan el ancho máximo.
Si no hay un shell disponible
Dibuja a mano con las mismas reglas. Luego cuenta las columnas de cada línea y verifica que: la sombra derecha está una columna a la derecha de la caja; la fila de sombra inferior comienza una columna a la derecha del borde izquierdo de la caja y termina en la columna de sombra; todos los bordes de la caja están alineados.
Código fuente del motor: textdiagram.py
"""textdiagram: dibuja diagramas de caja Unicode alineados en una cuadrícula de caracteres.
Estilo:
Todo el texto está en mayúsculas, excepto las unidades en KEEP.
Caja COMPONENTE: líneas ligeras + sombra ligera (░) una columna a la derecha, una fila hacia abajo.
Caja TÍTULO: líneas dobles, sin sombra, centrada sobre el diagrama (colocada en el renderizado).
Caja MARCO: líneas ligeras, sin sombra (nota, llamada).
Encabezado: caja de título con una caja de metadatos opcional (izquierda) y una caja de sello (derecha);
las líneas de relleno de la caja de título tienen un punto centrado.
Secciones: una caja dividida por divisores ligeros, una sombra para toda la caja.
Flecha horizontal: etiqueta dentro de la línea, ambos extremos tocan una caja: ── ETIQUETA ──▶
Flecha vertical: etiqueta a la derecha de la línea, una fila debajo de la sombra.
Ruta: flecha con cualquier número de curvas, establecida por coordenadas de carril (via).
Cabeza: rellena (▶) o hueca (▷). fan_out: una línea que se divide en varias flechas.
Etiqueta en una línea vertical: al lado de la línea, o insertada en ella (inline=True).
annotate: texto libre sin caja.
"""
import re
import unicodedata
SHADOW = "░"
MIN_DASH = 2 # guiones a cada lado de una etiqueta de flecha
HEADER_GAP = 2 # columnas entre las cajas de encabezado
# Unidades cuyo caso cambia el significado (MB = byte, Mb = bit, ms = mili, MS = mega).
# Una palabra se conserva solo si está escrita exactamente como una de estas.
KEEP = {
"Hz", "kHz", "MHz", "GHz",
"kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
"kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
"ms", "µs", "ns",
}
# Caracteres de dibujo de caja como conjuntos de brazos: donde se encuentran dos líneas de flecha, los brazos
# se unen en un carácter de unión (┼, ├, ...).
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
"├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v):
…
[truncado para traducción]