Diagramas Unicode
Desenhe diagramas como texto puro com caracteres Unicode de desenho de caixas, em um estilo único. Sempre construa o diagrama com o motor de grade textdiagram.py abaixo. Não desenhe à mão: diagramas desenhados manualmente perdem o alinhamento.
Regras de estilo
- Texto puro em um bloco de código cercado. Sem Mermaid, SVG, imagens ou emojis.
- Largura: 80 colunas por padrão. Para alterar, passe
max_widthpara o construtor, por exemploD(max_width=100). O motor gera um erro em uma linha mais longa. - Todo texto é em MAIÚSCULAS. O motor faz isso por você: escreva texto normal no script. Exceção: unidades cuja caixa altera o significado permanecem como escritas, quando você as escreve exatamente assim:
Hz kHz MHz GHz,kB MB GB TB KiB MiB GiB TiB,kb Mb Gb Tb kbps Mbps Gbps,ms µs ns. Outras palavras, como NGINX ou K8S, ficam em maiúsculas. - Caixa COMPONENTE (uma parte do sistema: serviço, cliente, banco de dados, fila, trabalhador): linhas leves
┌─┐ │ └─┘mais uma sombra leve░, uma coluna à direita e uma linha abaixo. Para agrupar partes, divida uma caixa em seções: divisores leves├───┤, um quadro, uma sombra. - Caixa TÍTULO (o título principal do documento, um por diagrama): linhas duplas
╔═╗ ║ ╚═╝, sem sombra. Um item por linha (nome, tipo de documento, versão), cada linha centralizada na caixa. Faça comd.header(...): o motor centraliza a caixa sobre todo o diagrama. Opcional: uma caixa de metadados à esquerda (empresa, RFC, data) e uma caixa de selo à direita (status). Todas as três têm a mesma altura; linhas de preenchimento da caixa de título seguram um ponto centralizado·. Nenhuma seta pode começar ou terminar em uma caixa de cabeçalho. - Caixa MOLDURA (cabeçalho de seção, nota, chamada): linhas leves, sem sombra. Nota / chamada: coloque o nome na borda superior, como
┌─ NOTA ───┐. Não adicione legenda: o estilo é o mesmo em todo diagrama. - Texto livre (
d.annotate): um breve comentário sem caixa, ao lado do diagrama. Use raramente. Uma linha não deve cruzá-lo. - Seta horizontal: rótulo dentro da linha, um espaço de cada lado:
── HTTPS ──▶. Ambas as extremidades tocam uma caixa: a linha começa na coluna de sombra da caixa emissora e a cabeça toca a caixa receptora. - Seta vertical: linha começa de
┬na borda inferior, termina com▼. O rótulo vai à direita da linha, uma linha abaixo da sombra. Ou corte o rótulo na linha (inline=True): linha, linha em branco, linhas de rótulo centralizadas na linha, linha em branco, linha. - Seta curvada (
d.route): qualquer número de curvas, em qualquer direção (▲ ▼ ◀ ▶). O rótulo vai dentro de um segmento horizontal, ou ao lado (ou, cominline=True, cortado em) um segmento vertical. Linhas que se cruzam ou juntam formam uma junção (┼ ├ ┤ ┬ ┴). Uma linha nunca passa através de uma caixa. - Barramento (
d.fan_out): uma linha de uma caixa que se divide em uma seta por destino. O rótulo vai na linha compartilhada. - Cabeças de seta: preenchidas
▶ ◀ ▲ ▼para o fluxo principal. Vazadas▷ ◁ △ ▽para um segundo tipo de relação (assíncrona, opcional, evento). Use vazadas apenas se o diagrama precisar de dois tipos, e nomeie o significado em um rótulo ou nota, não em uma legenda. - Rotule cada seta com o que flui (protocolo, evento, dados).
- Se não estiver claro qual função uma caixa tem: COMPONENTE para partes do sistema, TÍTULO para o título principal, MOLDURA para todo o resto.
Fluxo de trabalho
- Liste os componentes, molduras e setas antes de desenhar.
- Escreva o motor em
/tmp/textdiagram/textdiagram.py(código fonte completo no final deste arquivo, copie exatamente). Escreva-o novamente a cada sessão, para que uma versão antiga nunca seja usada. - Escreva um script Python curto que importa o motor e constrói o diagrama. Use os auxiliares de layout para posicionar caixas (não adivinhe coordenadas):
Diagram.x_right_of(a, label)— x para a próxima caixa à direita, com espaço para o rótulo da seta.Diagram.x_left_of(a, lines, label)— x para uma nova caixa à esquerda dea, com espaço para o rótulo.Diagram.y_below(a)— y para uma caixa abaixo dea. Com um rótulo inline:Diagram.y_below(a, lines=N).Diagram.x_centered_under(a, lines)— x para que uma caixa fique centralizada soba(necessário paraarrow_v).- Para faixas de rota, use as bordas das caixas:
a.right + 4,a.bottom + 2.
- Execute. Se levantar
DiagramError, corrija o layout conforme a mensagem e execute novamente. - Cole a saída em um bloco de código exatamente como impresso. Não edite manualmente. Para uma alteração, edite o script e execute novamente.
Exemplo 1: cabeçalho, seções, rotas
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D() # max_width=80 é o padrão
t = d.header(["Plataforma de Pedidos", "Arquitetura"],
left=["Acme Inc", "RFC 9000", "Nov 2026"],
right=["*~~~~~~~~~*", "Mergulho Profundo", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Cliente"]) # role="component" é padrão
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, # seções: uma caixa, uma sombra
[["Auth"], ["Pedidos"], ["Cobrança"]], title="Serviços")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Chamadas") # Forma S
cache = d.box(D.x_left_of(svc, ["Cache"], "Leituras"), svc.rows[1] - 1, ["Cache"])
d.arrow_h(svc, cache, "Leituras", row=svc.rows[1]) # anexar a uma seção
aud = d.box(svc.right + 9, y, ["Auditoria"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Eventos") # uma curva
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2], # laço: 3 curvas
via=[svc.right + 4, svc.bottom + 2], label="Reenvio")
print(d.render())
Saída:
┌────────────┐ ╔══════════════════╗ ┌───────────────┐
│ ACME INC │ ║ PLATAFORMA DE ║ │ *~~~~~~~~~* │
│ RFC 9000 │ ║ PEDIDOS ║ │ MERGULHO │
│ NOV 2026 │ ║ ARQUITETURA ║ │ PROFUNDO │
└────────────┘ ║ · ║ │ *~~~~~~~~~* │
╚══════════════════╝ └───────────────┘
┌──────────┐ ┌───────────┐ ┌─────────┐
│ CLIENTE │── HTTPS ──▶│ GATEWAY │░ │AUDITORIA│░
└──────────┘░ └─────┬─────┘░ └─────────┘░
░░░░░▲░░░░░░ ░░░░░│░░░░░░░ ░░░░▲░░░░░░
│ │ │
│ │ │
│ └── CHAMADAS ──┐ │
│ │ │
│ ▼ │
│ ┌─ SERVIÇOS ───┐ │
│ │ AUTH │── EVENTOS ──┘
│ ┌─────────┐ ├───────────────┤░
│ │ CACHE │◀─ LEITURAS─│ PEDIDOS │░
│ └─────────┘░ ├───────────────┤░
│ ░░░░░░░░░░░ │ COBRANÇA │────┐
│ └───────────────┘░ │
│ ░░░░░░░░░░░░░░░░░ │
│ │
└─────────────────────── REENVIO ──────────────────────┘
Exemplo 2: barramento, cabeças vazadas, rótulo inline, texto livre
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D()
t = d.header(["Barramento de Eventos", "Design"], left=["Acme Inc", "ADR 12", "Nov 2026"],
right=["*~~~~~~~*", "Rascunho", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publicador"])
s1 = d.box(36, y - 2, ["Cobrança"])
s2 = d.box(36, y + 4, ["Auditoria"])
s3 = d.box(36, y + 10, ["Pesquisa"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Eventos", head="hollow") # barramento, cabeças vazadas
arc = d.box(D.x_centered_under(pub, ["Arquivo"]), D.y_below(pub, lines=2), ["Arquivo"])
d.arrow_v(pub, arc, "Cópia\nnoturna", inline=True) # rótulo cortado na linha
d.annotate(46, y + 16, ["Entrega pelo", "menos uma vez"]) # texto livre, sem caixa
print(d.render())
Saída:
┌────────────┐ ╔════════════════╗ ┌─────────────┐
│ ACME INC │ ║ BARRAMENTO DE ║ │ *~~~~~~~* │
│ ADR 12 │ ║ EVENTOS ║ │ RASCUNHO │
│ NOV 2026 │ ║ DESIGN ║ │ *~~~~~~~* │
└────────────┘ ║ · ║ └─────────────┘
╚════════════════╝
┌───────────┐
┌──────▷│ COBRANÇA │░
┌─────────────┐ │ └───────────┘░
│ PUBLICADOR │── EVENTOS ──┤ ░░░░░░░░░░░░░
└──────┬──────┘░ │
░░░░░░│░░░░░░░░ │
│ ┌─────────┐
CÓPIA ├──────▷│AUDITORIA│░
NOTURNA │ └─────────┘░
│ ░░░░░░░░░░░
│ │
▼ │
┌───────────┐ │ ┌──────────┐
│ ARQUIVO │░ └──────▷│ PESQUISA │░
└───────────┘░ └──────────┘░
░░░░░░░░░░░░░ ░░░░░░░░░░░░
ENTREGA PELO
MENOS UMA VEZ
Referência da API
D(max_width=80)— cria um diagrama;max_widthé o limite de colunas.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/bottomincluem a sombra).linesé uma lista de linhas, ou uma lista de seções (listas de linhas) para dividir a caixa.box.rowscontém a linha de seta de cada seção.align="center"centraliza o texto.d.header(title, left=None, right=None, y=0)→ caixa de títuloBox. Cada argumento é uma lista de linhas. As caixas obtêm seuxfinal no momento da renderização. Um cabeçalho por diagrama.d.arrow_h(a, b, label="", row=None, head="filled")—aeblado a lado; funciona em ambas as direções.rowseleciona uma linha de seção (a.rows[i]).headé"filled"ou"hollow".d.arrow_v(a, b, label="", head="filled", inline=False)—babaixo dea, centralizado sob ela. Um rótulo pode ter mais de uma linha ("\n"). Cominline=True, deixe espaço comDiagram.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)— lados são"left" "right" "top" "bottom". A linha sai dea_sidedeae entra emb_sidedeb. Temlen(via) + 2segmentos, que alternam entre horizontais e verticais, começando com a direção que sai dea_side. Cada valor deviaé a faixa de um segmento do meio: um x para um segmento vertical, um y para um segmento horizontal.via=[]é uma curva, um valor são duas curvas (forma S ou U), dois valores são três curvas (um laço).a_row/b_rowselecionam uma linha de seção.label_segseleciona o segmento (de 0) que carrega o rótulo.d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False)— um barramento.trunké a faixa da linha compartilhada: um x para lados esquerdo/direito, um y para topo/base.d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled")— uma curva, uma forma curta deroute.vh: sai da base dea, vira para o lado deb.hv: sai do lado dea, vira para baixo no topo deb. A direção segue a posição deb.d.annotate(x, y, lines, align="left")→Box(role"text") — texto livre, em maiúsculas.linesé uma string ("\n"começa uma nova linha) ou uma lista.d.text(x, y, s)— texto bruto (não em maiúsculas).d.render()— retorna o diagrama; posiciona o cabeçalho; verifica largura e caracteres largos.- O motor levanta
DiagramErrorem sobreposições, lacunas pequenas, valores de faixa errados ou linhas acima da largura máxima.
Se nenhum shell estiver disponível
Desenhe à mão com as mesmas regras. Em seguida, conte as colunas em cada linha e verifique se: a sombra direita está uma coluna à direita da caixa; a linha de sombra inferior começa uma coluna à direita da borda esquerda da caixa e termina na coluna de sombra; todas as bordas da caixa se alinham.
Código fonte do motor: textdiagram.py
"""textdiagram: desenhe diagramas de caixa Unicode alinhados em uma grade de caracteres.
Estilo:
Todo texto é em maiúsculas, exceto as unidades em KEEP.
Caixa COMPONENTE: linhas leves + sombra leve (░) uma coluna à direita, uma linha abaixo.
Caixa TÍTULO: linhas duplas, sem sombra, centralizada sobre o diagrama (posicionada na renderização).
Caixa MOLDURA: linhas leves, sem sombra (nota, chamada).
Cabeçalho: caixa de título com uma caixa de metadados opcional (esquerda) e caixa de selo (direita);
linhas de preenchimento da caixa de título seguram um ponto centralizado.
Seções: uma caixa dividida por divisores leves, uma sombra para toda a caixa.
Seta horizontal: rótulo dentro da linha, ambas as extremidades tocam uma caixa: ── RÓTULO ──▶
Seta vertical: rótulo à direita da linha, uma linha abaixo da sombra.
Rota: seta com qualquer número de curvas, definidas por coordenadas de faixa (via).
Cabeça: preenchida (▶) ou vazada (▷). fan_out: uma linha que se divide em várias setas.
Rótulo em uma linha vertical: ao lado da linha, ou cortado nela (inline=True).
annotate: texto livre sem caixa.
"""
import re
import unicodedata
SHADOW = "░"
MIN_DASH = 2 # traços de cada lado de um rótulo de seta
HEADER_GAP = 2 # colunas entre as caixas do cabeçalho
# Unidades cuja caixa altera o significado (MB = byte, Mb = bit, ms = mili, MS = mega).
# Uma palavra é mantida apenas se escrita exatamente como uma destas.
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 desenho de caixa como conjuntos de braços: onde duas linhas de seta se encontram,
# os braços são unidos em um caractere de junção (┼, ├, ...).
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
"├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v): k for k, v in ARMS.items()}
# ... [código truncado para tradução]