hascii

Convert Graphviz DOT graphs to Unicode box-drawing art

Embed readable flow diagrams in docstrings, source code, and plain-text docs.
No image viewer needed — just Unicode text.

What it does

Takes a Graphviz DOT graph and renders it as ASCII art with box-drawing characters:

  ┌───────┐
  │ Start │◀─┐
  └───────┘  │
      │      │retry
      │      │
      ▼      │
  ┌───────┐  │
  │ Check │──┘
  └───────┘
      │ok
      │
      ▼
  ┌──────┐
  │ Done │
  └──────┘

Back-edges, conditions, and edge labels

    ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
 ┌─▶┆ router_while_simple_flow_while_i_lt_max_iterations ┆
 │  └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
 │                             │p['i'] < p['max_iterations']
 │                             └─────────────────────────────────┐
 │                             │                                 │else
 │                             ▼                                 ▼
 │          ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐     ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┐
 │          ┆ router_while_simple_flow_seq_set_i ┆     ╎ handler_finalize ╎
 │          ┆            p['i'] += 1             ┆     └╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┘
 │          └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
 │           ┌─────────────────┘
 │           ▼
 │  ┏┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┓
 └──┇ handler_process ┇
    ┗┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┛

Subgraph grouping

Cluster subgraphs render as dashed group boxes:

       ┌────────────┐
       │ preprocess │
       └────────────┘
              │
   ┌ validation_stage ╌╌╌┐
   ╎          ▼          ╎
   ╎    ┌──────────┐     ╎
   ╎    │ validate │     ╎
   ╎    └──────────┘     ╎
   ╎          │          ╎
   ╎          ▼          ╎
   ╎     ┌────────┐      ╎
   ╎     │ enrich │      ╎
   ╎     └────────┘      ╎
   └╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┘
              │
              ▼
          ┌───────┐
          │ store │
          └───────┘

Color modes

Node fill colors are conveyed through border styles (B/W) or ANSI colors (terminal):

Quick start

Try without installing (requires uv and Graphviz):

echo 'digraph { A -> B -> C }' | uvx hascii -
uvx hascii flow.dot
uvx hascii - < flow.dot

Install

Graphviz is a required system dependency (hascii uses dot for layout):

sudo apt-get install graphviz   # Debian/Ubuntu
brew install graphviz            # macOS

Python:

pip install hascii

Rust CLI:

cargo install hascii

Python API

import hascii

dot = '''
digraph {
    A [label="Start"]; B [label="End"];
    A -> B;
}
'''

# ANSI colors (default) — for terminal display
print(hascii.render(dot))

# Plain solid borders — for docstrings and source code
print(hascii.render(dot, color=False))

# All options
hascii.render(
    dot_source,
    max_width=72,       # constrain output width
    trim="smart",       # label trimming: end, start, middle, smart
    max_label=30,       # max label length
    color=False,        # True: ANSI colors, False: plain borders
)

# From file
hascii.render_file("flow.dot", color=False)

CLI

hascii [OPTIONS] <FILE>

Arguments:
  <FILE>  Path to a .dot file, or "-" to read from stdin

Options:
      --width <N>          Max output width in characters
      --trim <STRAT>       Label trimming strategy [default: smart]
      --max-label <N>      Max label width in characters
      --no-color           Use hue-based border styles instead of ANSI colors
  -v, --verbose...         Increase verbosity
  -h, --help               Print help

# Render a DOT file (colors on terminal)
hascii flow.dot

# Pipe from stdin
echo 'digraph { A -> B }' | hascii -

# Save to file (hue-based borders, no ANSI)
hascii --no-color flow.dot > flow.txt

# Constrain for docstrings
hascii --width 72 --max-label 25 flow.dot

Rust API

use hascii::{render, RenderOptions};

let dot = r#"digraph { A -> B -> C }"#;
let options = RenderOptions::default();
let ascii = render(dot, &options).expect("render failed");
println!("{ascii}");

Label trimming

Long labels are trimmed with --trim / trim=:

License

Apache-2.0