graph-easy

A Python port of Graph::Easy, the Perl tool that lays out directed/undirected graphs and renders them as ASCII art (box-and-wire diagrams rendered in the terminal).

This project faithfully translates the original Perl implementation to Python, in order to provide the same functionality to Python users / as a native Python library and command-line tool.

Provenance & License

• Original: Graph::Easy, Copyright (C) 2004 - 2008 by Tels (http://bloodgate.com/).
• Upstream repository: https://github.com/ironcamel/Graph-Easy
• This port is licensed under the GNU General Public License, version 2 or (at your option) any later version — the same license as the original Graph::Easy, because a port is a derivative work.

See LICENSE for the full GPL text.

Third-party color schemes

This product includes color specifications and designs developed by Cynthia Brewer (http://colorbrewer.org/), used under the Apache-Style Software License for ColorBrewer Color Schemes v1.1, © 2002 Cynthia Brewer, Mark Harrower, and The Pennsylvania State University. See the header of the original Graph::Easy::Attributes for the full notice.

Status

Actively-developed port. Currently implemented:

• DSL parser: [ label ]/bare nodes, --> <-- <--> -- arrows, labelled edges (-- label --> and -- { label: x; } -->), multiline labels (\n), node attribute blocks ({ shape: diamond; }), groups (( name [ A ] --> [ B ] )), comments
• Layout engine: longest-path layering with barycenter reordering and orthogonal edge routing — chains, branches, merges, layer-spanning edges, back edges (cycles) and self-loops all render without clobbering boxes (long edges are routed through detour rows); independent components stack as separate diagrams
• Edge line styles (faithful to upstream Parser::_edge_style): -- solid, .. dotted, == double, ~~ wave, ## bold, .-/..- dot-dash
• Edge labels float in the box-free region next to the line (truncated to fit)
• Two output charsets: Unicode box-drawing by default (┌──┐ ──▶ ══ ║ ·), plain ASCII via --ascii
• Colours (on by default; --no-color / --color auto to control): fill (background) and color (foreground) for the label, border-color for the frame, and a ColourBrewer palette via color: <n>; scheme: <name>. Values accept named colours, #RGB / #RRGGBB true-colour, or a palette index (e.g. color: 3; scheme: blues5).
• Node shapes: normal/box (rectangle), rounded/ellipse/circle/ oval, diamond, and hexagon, set via shape: <name>.
• Graphviz export: --dot (or --format dot) emits Graphviz DOT; --format svg|png renders via the dot binary when available.

Limitations: labels are clipped to the free space beside an edge; very dense graphs may need manual attribute tuning. The heavier automatic layout engine (Graph::Easy::Layout grid solver) is a follow-up milestone.

Usage

$ printf '[ Bonn ] --> [ Berlin ] --> [ Hamburg ]\n' | graph-easy
┌──────┐     ┌────────┐     ┌─────────┐
│ Bonn │────▶│ Berlin │────▶│ Hamburg │
└──────┘     └────────┘     └─────────┘

Colours from fill/color attributes are on by default; use --no-color to disable, or --color auto to enable only on a TTY.

# plain-ASCII output
$ printf '[ A ] ..> [ B ]\n' | graph-easy --ascii
+---+     +---+
| A |....>| B |
+---+     +---+

Development

$ python -m venv .venv && source .venv/bin/activate
$ pip install -e '.[dev]'
$ ruff check .
$ mypy src
$ pytest

Acknowledgments

Thanks to Tels and the Graph::Easy contributors whose careful layout and rendering work this port builds upon.